class Poco::URI

Overview

A Uniform Resource Identifier, as specified in RFC 3986. More…

#include <URI.h>

class URI
{
public:
    // typedefs

    typedef std::vector<std::pair<std::string, std::string>> QueryParameters;

    // construction

    URI();
    URI(const std::string& uri);
    URI(const char* uri);

    URI(
        const std::string& scheme,
        const std::string& pathEtc
        );

    URI(
        const std::string& scheme,
        const std::string& authority,
        const std::string& pathEtc
        );

    URI(
        const std::string& scheme,
        const std::string& authority,
        const std::string& path,
        const std::string& query
        );

    URI(
        const std::string& scheme,
        const std::string& authority,
        const std::string& path,
        const std::string& query,
        const std::string& fragment
        );

    URI(const URI& uri);

    URI(
        const URI& baseURI,
        const std::string& relativeURI
        );

    URI(const Path& path);

    // methods

    URI&
    operator=(const URI& uri);

    URI&
    operator=(const std::string& uri);

    URI&
    operator=(const char* uri);

    void
    swap(URI& uri);

    void
    clear();

    std::string
    toString() const;

    const std::string&
    getScheme() const;

    void
    setScheme(const std::string& scheme);

    const std::string&
    getUserInfo() const;

    void
    setUserInfo(const std::string& userInfo);

    const std::string&
    getHost() const;

    void
    setHost(const std::string& host);

    unsigned short
    getPort() const;

    void
    setPort(unsigned short port);

    std::string
    getAuthority() const;

    void
    setAuthority(const std::string& authority);

    const std::string&
    getPath() const;

    void
    setPath(const std::string& path);

    std::string
    getQuery() const;

    void
    setQuery(const std::string& query);

    void
    addQueryParameter(
        const std::string& param,
        const std::string& val = ""
        );

    const std::string&
    getRawQuery() const;

    void
    setRawQuery(const std::string& query);

    QueryParameters
    getQueryParameters() const;

    void
    setQueryParameters(const QueryParameters& params);

    const std::string&
    getFragment() const;

    void
    setFragment(const std::string& fragment);

    void
    setPathEtc(const std::string& pathEtc);

    std::string
    getPathEtc() const;

    std::string
    getPathAndQuery() const;

    void
    resolve(const std::string& relativeURI);

    void
    resolve(const URI& relativeURI);

    bool
    isRelative() const;

    bool
    empty() const;

    bool
    operator==(const URI& uri) const;

    bool
    operator==(const std::string& uri) const;

    bool
    operator!=(const URI& uri) const;

    bool
    operator!=(const std::string& uri) const;

    void
    normalize();

    void
    getPathSegments(std::vector<std::string>& segments);

    static
    void
    encode(
        const std::string& str,
        const std::string& reserved,
        std::string& encodedStr
        );

    static
    void
    decode(
        const std::string& str,
        std::string& decodedStr,
        bool plusAsSpace = false
        );

protected:
    // fields

    static const std::string RESERVED_PATH;
    static const std::string RESERVED_QUERY;
    static const std::string RESERVED_QUERY_PARAM;
    static const std::string RESERVED_FRAGMENT;
    static const std::string ILLEGAL;

    // methods

    bool
    equals(const URI& uri) const;

    bool
    isWellKnownPort() const;

    unsigned short
    getWellKnownPort() const;

    void
    parse(const std::string& uri);

    void
    parseAuthority(
        std::string::const_iterator& it,
        const std::string::const_iterator& end
        );

    void
    parseHostAndPort(
        std::string::const_iterator& it,
        const std::string::const_iterator& end
        );

    void
    parsePath(
        std::string::const_iterator& it,
        const std::string::const_iterator& end
        );

    void
    parsePathEtc(
        std::string::const_iterator& it,
        const std::string::const_iterator& end
        );

    void
    parseQuery(
        std::string::const_iterator& it,
        const std::string::const_iterator& end
        );

    void
    parseFragment(
        std::string::const_iterator& it,
        const std::string::const_iterator& end
        );

    void
    mergePath(const std::string& path);

    void
    removeDotSegments(bool removeLeading = true);

    void
    buildPath(
        const std::vector<std::string>& segments,
        bool leadingSlash,
        bool trailingSlash
        );

    static
    void
    getPathSegments(
        const std::string& path,
        std::vector<std::string>& segments
        );
};

Detailed Documentation

A Uniform Resource Identifier, as specified in RFC 3986.

The URI class provides methods for building URIs from their parts, as well as for splitting URIs into their parts. Furthermore, the class provides methods for resolving relative URIs against base URIs.

The class automatically performs a few normalizations on all URIs and URI parts passed to it:

* scheme identifiers are converted to lower case
* percent-encoded characters are decoded (except for the query string)
* optionally, dot segments are removed from paths (see normalize())

Note that dealing with query strings requires some precautions, as, internally, query strings are stored in percent-encoded form, while all other parts of the URI are stored in decoded form. While parsing query strings from properly encoded URLs generally works, explicitly setting query strings with setQuery() or extracting query strings with getQuery() may lead to ambiguities. See the descriptions of setQuery(), setRawQuery(), getQuery() and getRawQuery() for more information.

Construction

URI()

Creates an empty URI.

URI(const std::string& uri)

Parses an URI from the given string.

Throws a SyntaxException if the uri is not valid.

URI(const char* uri)

Parses an URI from the given string.

Throws a SyntaxException if the uri is not valid.

URI(
    const std::string& scheme,
    const std::string& pathEtc
    )

Creates an URI from its parts.

URI(
    const std::string& scheme,
    const std::string& authority,
    const std::string& pathEtc
    )

Creates an URI from its parts.

URI(
    const std::string& scheme,
    const std::string& authority,
    const std::string& path,
    const std::string& query
    )

Creates an URI from its parts.

URI(
    const std::string& scheme,
    const std::string& authority,
    const std::string& path,
    const std::string& query,
    const std::string& fragment
    )

Creates an URI from its parts.

URI(const URI& uri)

Copy constructor. Creates an URI from another one.

URI(
    const URI& baseURI,
    const std::string& relativeURI
    )

Creates an URI from a base URI and a relative URI, according to the algorithm in section 5.2 of RFC 3986.

URI(const Path& path)

Creates a URI from a path.

The path will be made absolute, and a file:// URI will be built from it.

Methods

URI&
operator=(const URI& uri)

Assignment operator.

URI&
operator=(const std::string& uri)

Parses and assigns an URI from the given string.

Throws a SyntaxException if the uri is not valid.

URI&
operator=(const char* uri)

Parses and assigns an URI from the given string.

Throws a SyntaxException if the uri is not valid.

void
swap(URI& uri)

Swaps the URI with another one.

void
clear()

Clears all parts of the URI.

std::string
toString() const

Returns a string representation of the URI.

Characters in the path, query and fragment parts will be percent-encoded as necessary.

const std::string&
getScheme() const

Returns the scheme part of the URI.

void
setScheme(const std::string& scheme)

Sets the scheme part of the URI.

The given scheme is converted to lower-case.

A list of registered URI schemes can be found at http://www.iana.org/assignments/uri-schemes.

const std::string&
getUserInfo() const

Returns the user-info part of the URI.

void
setUserInfo(const std::string& userInfo)

Sets the user-info part of the URI.

const std::string&
getHost() const

Returns the host part of the URI.

void
setHost(const std::string& host)

Sets the host part of the URI.

unsigned short
getPort() const

Returns the port number part of the URI.

If no port number (0) has been specified, the well-known port number (e.g., 80 for http) for the given scheme is returned if it is known. Otherwise, 0 is returned.

void
setPort(unsigned short port)

Sets the port number part of the URI.

std::string
getAuthority() const

Returns the authority part (userInfo, host and port) of the URI.

If the port number is a well-known port number for the given scheme (e.g., 80 for http), it is not included in the authority.

void
setAuthority(const std::string& authority)

Parses the given authority part for the URI and sets the user-info, host, port components accordingly.

const std::string&
getPath() const

Returns the decoded path part of the URI.

void
setPath(const std::string& path)

Sets the path part of the URI.

std::string
getQuery() const

Returns the decoded query part of the URI.

Note that encoded ampersand characters (‘&’, “%26”) will be decoded, which could cause ambiguities if the query string contains multiple parameters and a parameter name or value contains an ampersand as well. In such a case it’s better to use getRawQuery() or getQueryParameters().

void
setQuery(const std::string& query)

Sets the query part of the URI.

The query string will be percent-encoded. If the query already contains percent-encoded characters, these will be double-encoded, which is probably not what’s intended by the caller. Furthermore, ampersand (‘&’) characters in the query will not be encoded. This could lead to ambiguity issues if the query string contains multiple name-value parameters separated by ampersand, and if any name or value also contains an ampersand. In such a case, it’s better to use setRawQuery() with a properly percent-encoded query string, or use addQueryParameter() or setQueryParameters(), which take care of appropriate percent encoding of parameter names and values.

void
addQueryParameter(
    const std::string& param,
    const std::string& val = ""
    )

Adds “param=val” to the query; “param” may not be empty.

If val is empty, only ‘=’ is appended to the parameter.

In addition to regular encoding, function also encodes ‘&’ and ‘=’, if found in param or val.

const std::string&
getRawQuery() const

Returns the query string in raw form, which usually means percent encoded.

void
setRawQuery(const std::string& query)

Sets the query part of the URI.

The given query string must be properly percent-encoded.

QueryParameters
getQueryParameters() const

Returns the decoded query string parameters as a vector of name-value pairs.

void
setQueryParameters(const QueryParameters& params)

Sets the query part of the URI from a vector of query parameters.

Calls addQueryParameter() for each parameter name and value.

const std::string&
getFragment() const

Returns the fragment part of the URI.

void
setFragment(const std::string& fragment)

Sets the fragment part of the URI.

void
setPathEtc(const std::string& pathEtc)

Sets the path, query and fragment parts of the URI.

std::string
getPathEtc() const

Returns the encoded path, query and fragment parts of the URI.

std::string
getPathAndQuery() const

Returns the encoded path and query parts of the URI.

void
resolve(const std::string& relativeURI)

Resolves the given relative URI against the base URI.

See section 5.2 of RFC 3986 for the algorithm used.

void
resolve(const URI& relativeURI)

Resolves the given relative URI against the base URI.

See section 5.2 of RFC 3986 for the algorithm used.

bool
isRelative() const

Returns true if the URI is a relative reference, false otherwise.

A relative reference does not contain a scheme identifier. Relative references are usually resolved against an absolute base reference.

bool
empty() const

Returns true if the URI is empty, false otherwise.

bool
operator==(const URI& uri) const

Returns true if both URIs are identical, false otherwise.

Two URIs are identical if their scheme, authority, path, query and fragment part are identical.

bool
operator==(const std::string& uri) const

Parses the given URI and returns true if both URIs are identical, false otherwise.

bool
operator!=(const URI& uri) const

Returns true if both URIs are identical, false otherwise.

bool
operator!=(const std::string& uri) const

Parses the given URI and returns true if both URIs are identical, false otherwise.

void
normalize()

Normalizes the URI by removing all but leading .

and .. segments from the path.

If the first path segment in a relative path contains a colon (:), such as in a Windows path containing a drive letter, a dot segment (./) is prepended in accordance with section 3.3 of RFC 3986.

void
getPathSegments(std::vector<std::string>& segments)

Places the single path segments (delimited by slashes) into the given vector.

static
void
encode(
    const std::string& str,
    const std::string& reserved,
    std::string& encodedStr
    )

URI-encodes the given string by escaping reserved and non-ASCII characters.

The encoded string is appended to encodedStr.

static
void
decode(
    const std::string& str,
    std::string& decodedStr,
    bool plusAsSpace = false
    )

URI-decodes the given string by replacing percent-encoded characters with the actual character.

The decoded string is appended to decodedStr.

When plusAsSpace is true, non-encoded plus signs in the query are decoded as spaces. (http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1)

bool
equals(const URI& uri) const

Returns true if both uri’s are equivalent.

bool
isWellKnownPort() const

Returns true if the URI ‘s port number is a well-known one (for example, 80, if the scheme is http).

unsigned short
getWellKnownPort() const

Returns the well-known port number for the URI ‘s scheme, or 0 if the port number is not known.

void
parse(const std::string& uri)

Parses and assigns an URI from the given string.

Throws a SyntaxException if the uri is not valid.

void
parseAuthority(
    std::string::const_iterator& it,
    const std::string::const_iterator& end
    )

Parses and sets the user-info, host and port from the given data.

void
parseHostAndPort(
    std::string::const_iterator& it,
    const std::string::const_iterator& end
    )

Parses and sets the host and port from the given data.

void
parsePath(
    std::string::const_iterator& it,
    const std::string::const_iterator& end
    )

Parses and sets the path from the given data.

void
parsePathEtc(
    std::string::const_iterator& it,
    const std::string::const_iterator& end
    )

Parses and sets the path, query and fragment from the given data.

void
parseQuery(
    std::string::const_iterator& it,
    const std::string::const_iterator& end
    )

Parses and sets the query from the given data.

void
parseFragment(
    std::string::const_iterator& it,
    const std::string::const_iterator& end
    )

Parses and sets the fragment from the given data.

void
mergePath(const std::string& path)

Appends a path to the URI ‘s path.

void
removeDotSegments(bool removeLeading = true)

Removes all dot segments from the path.

void
buildPath(
    const std::vector<std::string>& segments,
    bool leadingSlash,
    bool trailingSlash
    )

Builds the path from the given segments.

static
void
getPathSegments(
    const std::string& path,
    std::vector<std::string>& segments
    )

Places the single path segments (delimited by slashes) into the given vector.