libcamgm
Public Types | Public Member Functions | Static Public Member Functions | Private Attributes | Friends | List of all members
ca_mgm::url::Url Class Reference

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...
 
Urloperator= (const std::string &urlString)
 Assigns parsed percent-encoded URL string to the object. More...
 
Urloperator= (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 &param, 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 &param, 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 &params)
 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 &param, 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 &param, 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)
 

Detailed Description

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.

RFC3986, Syntax Components:

The generic URI syntax consists of a hierarchical sequence of components referred to as the scheme, authority, path, query, and fragment.

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
hier-part = "//" authority path-abempty
/ path-absolute
/ path-rootless
/ path-empty

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:

foo://example.com:8042/over/there?name=ferret#nose
\_/ \______________/\_________/ \_________/ \__/
| | | | |
scheme authority path query fragment
| _____________________|__
/ \ / \
urn:example:animal:ferret:nose

Member Typedef Documentation

Encoding flags.

View options.

Constructor & Destructor Documentation

ca_mgm::url::Url::~Url ( )
ca_mgm::url::Url::Url ( )
ca_mgm::url::Url::Url ( const Url url)

Create a new Url object as shared copy of the given one.

Upon return, both objects will point to the same underlying object. This state will remain until one of the object is modified.

Parameters
urlThe Url object to make a copy of.
Exceptions
url::UrlExceptionif copy fails (should not happen).
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.

Parameters
urlThe URL implementation reference to make a copy of.
Exceptions
url::UrlExceptionif 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.

Parameters
urlStringA percent-encoded URL string.
Exceptions
url::UrlParsingExceptionif parsing of the url fails and may also contain an sub-exception - see parseUrl().

Member Function Documentation

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.

Returns
The encoded authority component string.
std::string ca_mgm::url::Url::getFragment ( EEncoding  eflag = ca_mgm::url::E_DECODED) const

Returns the encoded fragment component of the URL.

Parameters
eflagFlag if the fragment should be percent-decoded or not.
Returns
The encoded fragment component of the URL.
Exceptions
url::UrlDecodingExceptionif 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.

Parameters
eflagFlag if the host should be percent-decoded or not.
Returns
The host sub-component from the URL authority.
Exceptions
url::UrlDecodingExceptionif 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.

Returns
An array with scheme names known by this object.
std::string ca_mgm::url::Url::getPassword ( EEncoding  eflag = ca_mgm::url::E_DECODED) const

Returns the password from the URL authority.

Parameters
eflagFlag if the password should be percent-decoded or not.
Returns
The password sub-component from the URL authority.
Exceptions
url::UrlDecodingExceptionif 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".

Returns
The encoded path component of the URL.
std::string ca_mgm::url::Url::getPathName ( EEncoding  eflag = ca_mgm::url::E_DECODED) const

Returns the path name from the URL.

Parameters
eflagFlag if the path should be decoded or not.
Returns
The path name sub-component without path parameters from Path-Data component of the URL.
Exceptions
url::UrlDecodingExceptionif 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".

Parameters
paramThe path parameter key.
eflagFlag if the path parameter keys and values should be decoded or not.
Returns
The value for the path parameter key or empty string.
Exceptions
url::UrlNotSupportedExceptionif parameter parsing is not supported for a URL (scheme).
url::UrlDecodingExceptionif the decoded result string would contain a '\0' character.
std::string ca_mgm::url::Url::getPathParams ( ) const

Returns the path parameters from the URL.

Returns
The encoded 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".

Returns
The path parameters splited into an array of substrings.
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.

Parameters
eflagFlag if the path parameter keys and values should be decoded or not.
Returns
The path parameters key and values as a string map.
Exceptions
url::UrlNotSupportedExceptionif parameter parsing is not supported for a URL (scheme).
url::UrlDecodingExceptionif the decoded result string would contain a '\0' character.
std::string ca_mgm::url::Url::getPort ( ) const

Returns the port from the URL authority.

Returns
The port sub-component 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".

Parameters
paramThe query parameter key.
eflagFlag if the query parameter keys and values should be decoded or not.
Returns
The value for the query parameter key or empty string.
Exceptions
url::UrlNotSupportedExceptionif parameter parsing is not supported for a URL (scheme).
url::UrlDecodingExceptionif 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.

Returns
The encoded query string component of the URL.
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".

Returns
The query string splited into an array of substrings.
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".

Parameters
eflagFlag if the query string keys and values should be decoded or not.
Returns
The query string as a key/value string map.
Exceptions
url::UrlNotSupportedExceptionif parameter parsing is not supported for a URL (scheme).
url::UrlDecodingExceptionif the decoded result string would contain a '\0' character.
std::string ca_mgm::url::Url::getScheme ( ) const

Returns the scheme name of the URL.

Returns
Scheme name of the current Url object.
std::string ca_mgm::url::Url::getUsername ( EEncoding  eflag = ca_mgm::url::E_DECODED) const

Returns the username from the URL authority.

Parameters
eflagFlag if the usename should be percent-decoded or not.
Returns
The username sub-component from the URL authority.
Exceptions
url::UrlDecodingExceptionif 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.

Returns
The current view option combination.
bool ca_mgm::url::Url::isValid ( ) const

Verifies the Url.

Verifies if the current object contains a non-empty scheme name. Additional semantical URL checks may be performed by derived UrlBase objects.

Returns
True, if the Url seems to be valid.
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.

Returns
True, if generic scheme name syntax is valid and the scheme name is known to the current object.
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.

Parameters
urlStringA percent-encoded URL string.
Returns
A reference to this Url object.
Exceptions
url::UrlParsingExceptionif parsing of the url fails and may also contain an sub-exception - see parseUrl().
Url& ca_mgm::url::Url::operator= ( const Url url)

Assign shared copy of url to the current object.

Upon return, both objects will point to the same underlying object. This state will remain until one of the object is modified.

Parameters
urlThe Url object to make a copy of.
Returns
A reference to this Url object.
static url::UrlRef ca_mgm::url::Url::parseUrl ( const std::string &  urlString)
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.

Parameters
urlStringA percent-encoded URL string.
Returns
A reference to a (derived) UrlBase object or empty reference if the urlString string does not match the generic URL syntax.
Exceptions
url::UrlParsingExceptionif 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.

Parameters
authorityThe encoded authority component string.
Exceptions
url::UrlNotAllowedExceptionif the authority has to be empty in for the current scheme.
url::UrlBadComponentExceptionif the authority contains an invalid character.
url::UrlParsingExceptionif 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.

Parameters
fragmentThe new fragment string.
eflagIf the fragment is encoded or not.
Exceptions
url::UrlBadComponentExceptionif 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.

Parameters
hostThe new hostname or IP address.
Exceptions
url::UrlNotAllowedExceptionif the host (authority) has to be empty in for the current scheme.
url::UrlBadComponentExceptionif 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.

Parameters
passThe new password.
eflagIf the password is encoded or not.
Exceptions
url::UrlNotAllowedExceptionif the pass has to be empty in for the current scheme.
url::UrlBadComponentExceptionif 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.

Parameters
pathdataThe encoded path data component string.
Exceptions
url::UrlBadComponentExceptionif 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.

Parameters
pathThe new path name.
eflagIf the path name is encoded or not.
Exceptions
url::UrlBadComponentExceptionif 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.

Parameters
paramThe decoded path parameter name.
valueThe decoded path parameter value.
Exceptions
url::UrlNotSupportedExceptionif parameter parsing is not supported for a URL (scheme).
url::UrlDecodingExceptionif the decoded result string would contain a '\0' character.
void ca_mgm::url::Url::setPathParams ( const std::string &  params)

Set the path parameters.

Parameters
paramsThe new encoded path parameter string.
Exceptions
url::UrlBadComponentExceptionif the path params contains an invalid character.
void ca_mgm::url::Url::setPathParamsArray ( const std::vector< std::string > &  parray)

Set the path parameters.

Parameters
parrayThe array with encoded path parameters.
Exceptions
url::UrlBadComponentExceptionif the parray contains an invalid character.
void ca_mgm::url::Url::setPathParamsMap ( const ca_mgm::url::ParamMap pmap)

Set the path parameters.

Parameters
pmapThe map with decoded path parameters.
Exceptions
url::UrlNotSupportedExceptionif 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.

Parameters
portThe new port number.
Exceptions
url::UrlNotAllowedExceptionif the port (authority) has to be empty in for the current scheme.
url::UrlBadComponentExceptionif 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.

Parameters
paramThe decoded query parameter name.
valueThe decoded query parameter value.
Exceptions
url::UrlNotSupportedExceptionif parameter parsing is not supported for a URL (scheme).
url::UrlDecodingExceptionif 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.

Parameters
querystrThe new encoded query string.
Exceptions
url::UrlBadComponentExceptionif the querystr contains an invalid character.
void ca_mgm::url::Url::setQueryStringArray ( const std::vector< std::string > &  qarray)

Set the query parameters.

Parameters
qarrayThe array with encoded query parameters.
Exceptions
url::UrlBadComponentExceptionif the qarray contains an invalid character.
void ca_mgm::url::Url::setQueryStringMap ( const ca_mgm::url::ParamMap qmap)

Set the query parameters.

Parameters
qmapThe map with decoded query parameters.
Exceptions
url::UrlNotSupportedExceptionif 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.

Parameters
schemeThe new scheme name.
Exceptions
url::UrlBadComponentExceptionif 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.

Parameters
userThe new username.
eflagIf the username is encoded or not.
Exceptions
url::UrlNotAllowedExceptionif the user has to be empty in for the current scheme
url::UrlBadComponentExceptionif 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.

Parameters
voptsNew view options combination.
std::string ca_mgm::url::Url::toCompleteString ( ) const

Returns a complete string representation of the Url object.

This function ignores the configuration of the view options in the current object (see setViewOption()) and forces to return an string with all URL components included.

Returns
A complete string representation of the Url object.
std::string ca_mgm::url::Url::toString ( ) const

Returns a default string representation of the Url object.

By default, a password in the URL will be hidden.

Returns
A default string representation of the Url object.
std::string ca_mgm::url::Url::toString ( const ViewOptions opts) const

Returns a string representation of the Url object.

To include a password in the resulting Url string, use:

url.toString(url.getViewOptions() +
Parameters
optsA combination of view options.
Returns
A string representation of the Url object.

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  os,
const Url url 
)
friend

Stream output operator.

Parameters
osThe output stream reference.
urlThe Url object.
Theoutput stream reference.

Member Data Documentation

url::UrlRef ca_mgm::url::Url::m_impl
private

The documentation for this class was generated from the following file: