class EE::Network::URI

Overview

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

#include <uri.hpp>

class URI {
public:
    // 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();

    // methods

    URI& operator=(const URI& uri);
    URI& operator=(const std::string& uri);
    URI& operator=(const char* uri);
    bool operator<(const URI& url) const;
    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 getPort(unsigned short port);
    std::string getAuthority() const;
    void setAuthority(const std::string& authority);
    std::string getSchemeAndAuthority() const;
    const std::string& getPath() const;
    std::string getFSPath() const;
    std::string getLastPathSegment() const;
    void setPath(const std::string& path);
    std::string getQuery() const;
    void setQuery(const std::string& query);
    const std::string& getRawQuery() const;
    void setRawQuery(const std::string& query);
    const std::string& getFragment() const;
    void getFragment(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);
    std::string getLastPathSegment();
    std::string getAuthorityAndPath() const;
    static void encode(const std::string& str, const std::string& reserved, std::string& encodedStr);
    static void decode(const std::string& str, std::string& decodedStr);
    static std::string encode(const std::string& str);
    static std::string decode(const std::string& str);
};

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 optionally, dot segments are removed from paths (see Normalize()) Examples of URI structure:

  foo://username:password@example.com:8042/over/there/index.dtb?type=animal&name=narwhal#nose
  \_/   \_______________/ \_________/ \__/            \___/ \_/ \______________________/ \__/
   |           |               |       |                |    |            |                |
   |       userinfo         hostname  port              |    |          query          fragment
   |    \________________________________/\_____________|____|/ \__/        \__/
   |                    |                          |    |    |    |          |
   |                    |                          |    |    |    |          |
scheme              authority                    path   |    |    interpretable as keys
 name   \_______________________________________________|____|/       \____/     \_____/
   |                         |                          |    |          |           |
   |                 hierarchical part                  |    |    interpretable as values
   |                                                    |    |
   |            path               interpretable as filename |
   |   ___________|____________                              |
  / \ /                        \                             |
  urn:example:animal:ferret:nose               interpretable as extension

                path
         _________|________
 scheme /                  \
  name  userinfo  hostname       query
  _|__   ___|__   ____|____   _____|_____
 /    \ /      \ /         \ /           \
 mailto:username@example.com?subject=Topic

This class is based on the Poco library URI class.

Construction

URI()

Creates an empty URI.

URI(const std::string& uri)

Parses an URI from the given string.

URI(const char* uri)

Parses an URI from the given string.

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()

Destroys the URI.

Methods

URI& operator=(const URI& uri)

Assignment operator.

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

Parses and assigns an URI from the given string.

URI& operator=(const char* uri)

Parses and assigns an URI from the given string.

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 getPort(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.

std::string getSchemeAndAuthority() const

Returns:

The scheme and authority of the URI.

const std::string& getPath() const

Returns:

The path part of the URI.

std::string getLastPathSegment() const

Returns:

The last path segment.

void setPath(const std::string& path)

Sets the path part of the URI.

std::string getQuery() const

Returns:

the query part of the URI.

void setQuery(const std::string& query)

Sets the query part of the URI.

const std::string& getRawQuery() const

Returns:

the unencoded query part of the URI.

void setRawQuery(const std::string& query)

Sets the query part of the URI.

const std::string& getFragment() const

Returns:

the fragment part of the URI.

void getFragment(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 path, query and fragment parts of the URI.

std::string getPathAndQuery() const

Returns:

the 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.

std::string getLastPathSegment()

Returns:

The last path segment if any

std::string getAuthorityAndPath() const

Returns:

The authority and path

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)

URI-decodes the given string by replacing percent-encoded characters with the actual character. The decoded string is appended to decodedStr.

static std::string encode(const std::string& str)

URI encodes the string.

static std::string decode(const std::string& str)

URI decodes the string.