libcamgm
|
Url manipulation class. More...
#include <Url.hpp>
Public Types | |
typedef ca_mgm::url::EEncoding | EEncoding |
typedef ca_mgm::url::ViewOptions | ViewOptions |
Public Member Functions | |
~Url () | |
Url () | |
Url (const Url &url) | |
Url (const ca_mgm::url::UrlRef &url) | |
Url (const std::string &urlString) | |
Construct a Url object from percent-encoded URL string. More... | |
Url & | operator= (const std::string &urlString) |
Assigns parsed percent-encoded URL string to the object. More... | |
Url & | operator= (const Url &url) |
Assign shared copy of url to the current object. More... | |
std::vector< std::string > | getKnownSchemes () const |
Returns scheme names known to this object. More... | |
bool | isValidScheme (const std::string &scheme) const |
Verifies specified scheme name. More... | |
bool | isValid () const |
Verifies the Url. More... | |
std::string | toString () const |
std::string | toString (const ViewOptions &opts) const |
std::string | toCompleteString () const |
std::string | getScheme () const |
std::string | getAuthority () const |
std::string | getUsername (EEncoding eflag=ca_mgm::url::E_DECODED) const |
std::string | getPassword (EEncoding eflag=ca_mgm::url::E_DECODED) const |
std::string | getHost (EEncoding eflag=ca_mgm::url::E_DECODED) const |
std::string | getPort () const |
std::string | getPathData () const |
std::string | getPathName (EEncoding eflag=ca_mgm::url::E_DECODED) const |
std::string | getPathParams () const |
std::vector< std::string > | getPathParamsArray () const |
ca_mgm::url::ParamMap | getPathParamsMap (EEncoding eflag=ca_mgm::url::E_DECODED) const |
std::string | getPathParam (const std::string ¶m, EEncoding eflag=ca_mgm::url::E_DECODED) const |
std::string | getQueryString () const |
std::vector< std::string > | getQueryStringArray () const |
ca_mgm::url::ParamMap | getQueryStringMap (EEncoding eflag=ca_mgm::url::E_DECODED) const |
std::string | getQueryParam (const std::string ¶m, EEncoding eflag=ca_mgm::url::E_DECODED) const |
std::string | getFragment (EEncoding eflag=ca_mgm::url::E_DECODED) const |
void | setScheme (const std::string &scheme) |
Set the scheme name in the URL. More... | |
void | setAuthority (const std::string &authority) |
Set the authority component in the URL. More... | |
void | setUsername (const std::string &user, EEncoding eflag=ca_mgm::url::E_DECODED) |
Set the username in the URL authority. More... | |
void | setPassword (const std::string &pass, EEncoding eflag=ca_mgm::url::E_DECODED) |
Set the password in the URL authority. More... | |
void | setHost (const std::string &host, EEncoding eflag=ca_mgm::url::E_DECODED) |
Set the hostname or IP in the URL authority. More... | |
void | setPort (const std::string &port) |
Set the port number in the URL authority. More... | |
void | setPathData (const std::string &pathdata) |
Set the path data component in the URL. More... | |
void | setPathName (const std::string &path, EEncoding eflag=ca_mgm::url::E_DECODED) |
Set the path name. More... | |
void | setPathParams (const std::string ¶ms) |
Set the path parameters. More... | |
void | setPathParamsArray (const std::vector< std::string > &parray) |
Set the path parameters. More... | |
void | setPathParamsMap (const ca_mgm::url::ParamMap &pmap) |
Set the path parameters. More... | |
void | setPathParam (const std::string ¶m, const std::string &value) |
Set or add value for the specified path parameter. More... | |
void | setQueryString (const std::string &querystr) |
Set the query string in the URL. More... | |
void | setQueryStringArray (const std::vector< std::string > &qarray) |
Set the query parameters. More... | |
void | setQueryStringMap (const ca_mgm::url::ParamMap &qmap) |
Set the query parameters. More... | |
void | setQueryParam (const std::string ¶m, const std::string &value) |
Set or add value for the specified query parameter. More... | |
void | setFragment (const std::string &fragment, EEncoding eflag=ca_mgm::url::E_DECODED) |
Set the fragment string in the URL. More... | |
ViewOptions | getViewOptions () const |
void | setViewOptions (const ViewOptions &vopts) |
Static Public Member Functions | |
static url::UrlRef | parseUrl (const std::string &urlString) |
Parse a percent-encoded URL string. More... | |
Private Attributes | |
url::UrlRef | m_impl |
Friends | |
std::ostream & | operator<< (std::ostream &os, const Url &url) |
Url manipulation class.
The generic URL (URI) syntax and its main components are defined in RFC3986 (http://rfc.net/rfc3986.html) Section 3, "Syntax Components". The scheme specific URL syntax and semantics is defined in the specification of the particular scheme. See also RFC1738 (http://rfc.net/rfc1738.html), that defines specific syntax for several URL schemes.
This class provides methods to access and manipulate generic and common scheme-specific URL components (or using the more general term, URI components). To consider the scheme-specifics of a URL, the Url class contains a reference object pointing to a UrlBase or derived object, that implements the scheme specifics.
Using the Url::registerScheme() method, it is possible to register a preconfigured or derived UrlBase object for a specific scheme name. The registered object will be cloned to handle all URL's containing the specified scheme name.
The generic URI syntax consists of a hierarchical sequence of components referred to as the scheme, authority, path, query, and fragment.
The scheme and path components are required, though the path may be empty (no characters). When authority is present, the path must either be empty or begin with a slash ("/") character. When authority is not present, the path cannot begin with two slash characters ("//"). These restrictions result in five different ABNF rules for a path (Section 3.3), only one of which will match any given URI reference.
The following are two example URIs and their component parts:
Encoding flags.
View options.
ca_mgm::url::Url::~Url | ( | ) |
ca_mgm::url::Url::Url | ( | ) |
ca_mgm::url::Url::Url | ( | const Url & | url | ) |
ca_mgm::url::Url::Url | ( | const ca_mgm::url::UrlRef & | url | ) |
Create a new Url object as shared copy of the given reference.
Upon return, both objects will point to the same underlying object. This state will remain until one of the object is modified.
url | The URL implementation reference to make a copy of. |
url::UrlException | if reference is empty. |
ca_mgm::url::Url::Url | ( | const std::string & | urlString | ) |
Construct a Url object from percent-encoded URL string.
Parses the urlString
string using the parseUrl() method and assings the result to the new created object.
urlString | A percent-encoded URL string. |
url::UrlParsingException | if parsing of the url fails and may also contain an sub-exception - see parseUrl(). |
std::string ca_mgm::url::Url::getAuthority | ( | ) | const |
Returns the encoded authority component of the URL.
The returned authority string does not contain the leading "//" separator characters, but just its "user:pass@host:port" content only.
std::string ca_mgm::url::Url::getFragment | ( | EEncoding | eflag = ca_mgm::url::E_DECODED | ) | const |
Returns the encoded fragment component of the URL.
eflag | Flag if the fragment should be percent-decoded or not. |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
std::string ca_mgm::url::Url::getHost | ( | EEncoding | eflag = ca_mgm::url::E_DECODED | ) | const |
Returns the hostname or IP from the URL authority.
In case the Url contains an IP number, it may be surrounded by "[" and "]" characters, for example "[::1]" for an IPv6 localhost address.
eflag | Flag if the host should be percent-decoded or not. |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
std::vector<std::string> ca_mgm::url::Url::getKnownSchemes | ( | ) | const |
Returns scheme names known to this object.
std::string ca_mgm::url::Url::getPassword | ( | EEncoding | eflag = ca_mgm::url::E_DECODED | ) | const |
Returns the password from the URL authority.
eflag | Flag if the password should be percent-decoded or not. |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
std::string ca_mgm::url::Url::getPathData | ( | ) | const |
Returns the encoded path component of the URL.
The path data contains the path name, optionally followed by path parameters separated with a ";" character, for example "/foo/bar;version=1.1".
std::string ca_mgm::url::Url::getPathName | ( | EEncoding | eflag = ca_mgm::url::E_DECODED | ) | const |
Returns the path name from the URL.
eflag | Flag if the path should be decoded or not. |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
std::string ca_mgm::url::Url::getPathParam | ( | const std::string & | param, |
EEncoding | eflag = ca_mgm::url::E_DECODED |
||
) | const |
Return the value for the specified path parameter.
For example, if the path parameters string is "foo=1,bar=2" the method will return the substring "1" for the param key "foo" and "2" for the param key "bar".
param | The path parameter key. |
eflag | Flag if the path parameter keys and values should be decoded or not. |
url::UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
std::string ca_mgm::url::Url::getPathParams | ( | ) | const |
Returns the path parameters from the URL.
std::vector<std::string> ca_mgm::url::Url::getPathParamsArray | ( | ) | const |
Returns an array with path parameter substrings.
The default path parameter separator is the '
,' character. A schema specific object may overide the default separators.
For example, the path parameters string "foo=1,bar=2" is splited by default into an array containing the substrings "foo=1" and "bar=2".
ca_mgm::url::ParamMap ca_mgm::url::Url::getPathParamsMap | ( | EEncoding | eflag = ca_mgm::url::E_DECODED | ) | const |
Returns a string map with path parameter keys and values.
The default path parameter separator is the '
,' character, the default key/value separator for the path parameters is the '='
character. A schema specific object may overide the default separators.
For example, the path parameters string "foo=1,bar=2" is splited into a map containing "foo" = "1" and "bar" = "2" by default.
eflag | Flag if the path parameter keys and values should be decoded or not. |
url::UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
std::string ca_mgm::url::Url::getPort | ( | ) | const |
Returns the port from the URL authority.
std::string ca_mgm::url::Url::getQueryParam | ( | const std::string & | param, |
EEncoding | eflag = ca_mgm::url::E_DECODED |
||
) | const |
Return the value for the specified query parameter.
For example, if the query string is "foo=1,bar=2" the method will return the substring "1" for the param key "foo" and "2" for the param key "bar".
param | The query parameter key. |
eflag | Flag if the query parameter keys and values should be decoded or not. |
url::UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
std::string ca_mgm::url::Url::getQueryString | ( | ) | const |
Returns the encoded query string component of the URL.
The query string is returned without first "?" (separator) character. Further "?" characters as in e.g. LDAP URL's remains in the returned string.
std::vector<std::string> ca_mgm::url::Url::getQueryStringArray | ( | ) | const |
Returns an array with query string parameter substrings.
The default query string parameter separator is the '&'
character. A schema specific object may overide the default separators.
For example, the query string "foo=1&bar=2" is splited by default into an array containing the substrings "foo=1" and "bar=2".
ca_mgm::url::ParamMap ca_mgm::url::Url::getQueryStringMap | ( | EEncoding | eflag = ca_mgm::url::E_DECODED | ) | const |
Returns a string map with query parameter and their values.
The default query string parameter separator is the '
,' character, the default key/value separator the '='
character. A schema specific object may overide the default separators.
For example, the query string "foo=1&bar=2" is splited by default into a map containing "foo" = "1" and "bar" = "2".
eflag | Flag if the query string keys and values should be decoded or not. |
url::UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
std::string ca_mgm::url::Url::getScheme | ( | ) | const |
Returns the scheme name of the URL.
std::string ca_mgm::url::Url::getUsername | ( | EEncoding | eflag = ca_mgm::url::E_DECODED | ) | const |
Returns the username from the URL authority.
eflag | Flag if the usename should be percent-decoded or not. |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
ViewOptions ca_mgm::url::Url::getViewOptions | ( | ) | const |
Return the view options of the current object.
This method is used to query the view options used by the asString() method.
bool ca_mgm::url::Url::isValid | ( | ) | const |
bool ca_mgm::url::Url::isValidScheme | ( | const std::string & | scheme | ) | const |
Verifies specified scheme name.
Verifies the generic syntax of the specified scheme
name and if it is contained in the current object's list of known schemes (see getKnownSchemes()) if the list is not empty.
The default implementation in the UrlBase class returns an emtpy list of known schemes, causing a check of the generic syntax only.
Url& ca_mgm::url::Url::operator= | ( | const std::string & | urlString | ) |
Assigns parsed percent-encoded URL string to the object.
Parses urlString
string using the parseUrl() method and assigns the result to the current object.
urlString | A percent-encoded URL string. |
url::UrlParsingException | if parsing of the url fails and may also contain an sub-exception - see parseUrl(). |
|
static |
Parse a percent-encoded URL string.
Trys to parses the given string into generic URL components and created a clone of a scheme-specialized object or a new UrlBase object.
urlString | A percent-encoded URL string. |
urlString
string does not match the generic URL syntax. url::UrlParsingException | if parsing of the url fails and may also contain an chained url sub-exception, e.g. url::UrlNotAllowedException, url::UrlBadComponentException, url::UrlNotSupportedException. |
void ca_mgm::url::Url::setAuthority | ( | const std::string & | authority | ) |
Set the authority component in the URL.
The authority
string shoud contain the "user:pass@host:port" sub-components without any leading "//" separator characters.
authority | The encoded authority component string. |
url::UrlNotAllowedException | if the authority has to be empty in for the current scheme. |
url::UrlBadComponentException | if the authority contains an invalid character. |
url::UrlParsingException | if authority parsing fails. |
void ca_mgm::url::Url::setFragment | ( | const std::string & | fragment, |
EEncoding | eflag = ca_mgm::url::E_DECODED |
||
) |
Set the fragment string in the URL.
fragment | The new fragment string. |
eflag | If the fragment is encoded or not. |
url::UrlBadComponentException | if the fragment contains an invalid character. |
void ca_mgm::url::Url::setHost | ( | const std::string & | host, |
EEncoding | eflag = ca_mgm::url::E_DECODED |
||
) |
Set the hostname or IP in the URL authority.
The host
parameter may contain a hostname, an IPv4 address in dotted-decimal form or an IPv6 address literal encapsulated within square brackets (RFC3513, Sect. 2.2).
A hostname may contain national alphanumeric UTF8 characters (letters other than ASCII a-z0-9), that will be encoded. This function allows to specify both, a encoded or decoded hostname.
Other IP literals in "[v ... ]" square bracket format are not supported by the implementation in UrlBase class.
host | The new hostname or IP address. |
url::UrlNotAllowedException | if the host (authority) has to be empty in for the current scheme. |
url::UrlBadComponentException | if the host is invalid. |
void ca_mgm::url::Url::setPassword | ( | const std::string & | pass, |
EEncoding | eflag = ca_mgm::url::E_DECODED |
||
) |
Set the password in the URL authority.
pass | The new password. |
eflag | If the password is encoded or not. |
url::UrlNotAllowedException | if the pass has to be empty in for the current scheme. |
url::UrlBadComponentException | if the pass contains an invalid character. |
void ca_mgm::url::Url::setPathData | ( | const std::string & | pathdata | ) |
Set the path data component in the URL.
By default, the pathdata
string may include path parameters separated by the ";" separator character.
pathdata | The encoded path data component string. |
url::UrlBadComponentException | if the pathdata contains an invalid character. |
void ca_mgm::url::Url::setPathName | ( | const std::string & | path, |
EEncoding | eflag = ca_mgm::url::E_DECODED |
||
) |
Set the path name.
path | The new path name. |
eflag | If the path name is encoded or not. |
url::UrlBadComponentException | if the path name contains an invalid character. |
void ca_mgm::url::Url::setPathParam | ( | const std::string & | param, |
const std::string & | value | ||
) |
Set or add value for the specified path parameter.
param | The decoded path parameter name. |
value | The decoded path parameter value. |
url::UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
void ca_mgm::url::Url::setPathParams | ( | const std::string & | params | ) |
Set the path parameters.
params | The new encoded path parameter string. |
url::UrlBadComponentException | if the path params contains an invalid character. |
void ca_mgm::url::Url::setPathParamsArray | ( | const std::vector< std::string > & | parray | ) |
Set the path parameters.
parray | The array with encoded path parameters. |
url::UrlBadComponentException | if the parray contains an invalid character. |
void ca_mgm::url::Url::setPathParamsMap | ( | const ca_mgm::url::ParamMap & | pmap | ) |
Set the path parameters.
pmap | The map with decoded path parameters. |
url::UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
void ca_mgm::url::Url::setPort | ( | const std::string & | port | ) |
Set the port number in the URL authority.
port | The new port number. |
url::UrlNotAllowedException | if the port (authority) has to be empty in for the current scheme. |
url::UrlBadComponentException | if the port is invalid. |
void ca_mgm::url::Url::setQueryParam | ( | const std::string & | param, |
const std::string & | value | ||
) |
Set or add value for the specified query parameter.
param | The decoded query parameter name. |
value | The decoded query parameter value. |
url::UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
url::UrlDecodingException | if the decoded result string would contain a '\0' character. |
void ca_mgm::url::Url::setQueryString | ( | const std::string & | querystr | ) |
Set the query string in the URL.
querystr | The new encoded query string. |
url::UrlBadComponentException | if the querystr contains an invalid character. |
void ca_mgm::url::Url::setQueryStringArray | ( | const std::vector< std::string > & | qarray | ) |
Set the query parameters.
qarray | The array with encoded query parameters. |
url::UrlBadComponentException | if the qarray contains an invalid character. |
void ca_mgm::url::Url::setQueryStringMap | ( | const ca_mgm::url::ParamMap & | qmap | ) |
Set the query parameters.
qmap | The map with decoded query parameters. |
url::UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
void ca_mgm::url::Url::setScheme | ( | const std::string & | scheme | ) |
Set the scheme name in the URL.
scheme | The new scheme name. |
url::UrlBadComponentException | if the scheme contains an invalid character or is empty. |
void ca_mgm::url::Url::setUsername | ( | const std::string & | user, |
EEncoding | eflag = ca_mgm::url::E_DECODED |
||
) |
Set the username in the URL authority.
user | The new username. |
eflag | If the username is encoded or not. |
url::UrlNotAllowedException | if the user has to be empty in for the current scheme |
url::UrlBadComponentException | if the user contains an invalid character. |
void ca_mgm::url::Url::setViewOptions | ( | const ViewOptions & | vopts | ) |
Change the view options of the current object.
This method is used to change the view options used by the asString() method.
vopts | New view options combination. |
std::string ca_mgm::url::Url::toCompleteString | ( | ) | const |
std::string ca_mgm::url::Url::toString | ( | ) | const |
std::string ca_mgm::url::Url::toString | ( | const ViewOptions & | opts | ) | const |
|
friend |
Stream output operator.
os | The output stream reference. |
url | The Url object. |
The | output stream reference. |
|
private |