libcamgm
|
Generic Url base class. More...
#include <UrlBase.hpp>
Public Member Functions | |
virtual | ~UrlBase () |
UrlBase () | |
UrlBase (const UrlBase &url) | |
UrlBase (const UrlComponents &components) | |
Construct new object and initializes it with specified URL components. More... | |
UrlBase (const std::string &urlString) | |
UrlBase & | operator= (const UrlBase &url) |
Assign shared copy of url to the current object. More... | |
UrlBase & | operator= (const std::string &urlString) |
Assigns parsed percent-encoded URL string to the object. More... | |
virtual void | clear () |
Clears all data in the object. More... | |
virtual UrlBase * | clone () const |
virtual void | init (const UrlComponents &components) |
Initializes current object with new URL components. More... | |
virtual std::vector< std::string > | getKnownSchemes () const |
Returns scheme names known by this object. More... | |
virtual bool | isKnownScheme (const std::string &scheme) const |
Returns if scheme name is known to this object. More... | |
virtual bool | isValidScheme (const std::string &scheme) const |
Verifies specified scheme name. More... | |
virtual bool | isValid () const |
Verifies the Url. More... | |
virtual std::string | toString () const |
virtual std::string | toString (const ca_mgm::url::ViewOptions &opts) const |
virtual std::string | getScheme () const |
virtual std::string | getAuthority () const |
virtual std::string | getUsername (EEncoding eflag) const |
virtual std::string | getPassword (EEncoding eflag) const |
virtual std::string | getHost (EEncoding eflag) const |
virtual std::string | getPort () const |
virtual std::string | getPathData () const |
virtual std::string | getPathName (EEncoding eflag) const |
virtual std::string | getPathParams () const |
virtual std::vector< std::string > | getPathParamsArray () const |
virtual ca_mgm::url::ParamMap | getPathParamsMap (EEncoding eflag) const |
virtual std::string | getPathParam (const std::string ¶m, EEncoding eflag) const |
virtual std::string | getQueryString () const |
virtual std::vector< std::string > | getQueryStringArray () const |
virtual ca_mgm::url::ParamMap | getQueryStringMap (EEncoding eflag) const |
virtual std::string | getQueryParam (const std::string ¶m, EEncoding eflag) const |
virtual std::string | getFragment (EEncoding eflag) const |
virtual void | setScheme (const std::string &scheme) |
Set the scheme name in the URL. More... | |
virtual void | setAuthority (const std::string &authority) |
Set the authority component in the URL. More... | |
virtual void | setUsername (const std::string &user, EEncoding eflag) |
Set the username in the URL authority. More... | |
virtual void | setPassword (const std::string &pass, EEncoding eflag) |
Set the password in the URL authority. More... | |
virtual void | setHost (const std::string &host, EEncoding eflag) |
Set the hostname or IP in the URL authority. More... | |
virtual void | setPort (const std::string &port) |
Set the port number in the URL authority. More... | |
virtual void | setPathData (const std::string &pathdata) |
Set the path data component in the URL. More... | |
virtual void | setPathName (const std::string &path, EEncoding eflag) |
Set the path name. More... | |
virtual void | setPathParams (const std::string ¶ms) |
Set the path parameters. More... | |
virtual void | setPathParamsArray (const std::vector< std::string > &parray) |
Set the path parameters. More... | |
virtual void | setPathParamsMap (const ca_mgm::url::ParamMap &pmap) |
Set the path parameters. More... | |
virtual void | setPathParam (const std::string ¶m, const std::string &value) |
Set or add value for the specified path parameter. More... | |
virtual void | setQueryString (const std::string &querystr) |
Set the query string in the URL. More... | |
virtual void | setQueryStringArray (const std::vector< std::string > &qarray) |
Set the query parameters. More... | |
virtual void | setQueryStringMap (const ca_mgm::url::ParamMap &qmap) |
Set the query parameters. More... | |
virtual void | setQueryParam (const std::string ¶m, const std::string &value) |
Set or add value for the specified query parameter. More... | |
virtual void | setFragment (const std::string &fragment, EEncoding eflag) |
Set the fragment string in the URL. More... | |
virtual void | configure () |
std::string | config (const std::string &opt) const |
void | config (const std::string &opt, const std::string &val) |
ViewOptions | getViewOptions () const |
void | setViewOptions (const ViewOptions &vopts) |
Protected Member Functions | |
virtual std::string | cleanupPathName (const std::string &path, bool authority) const |
virtual std::string | cleanupPathName (const std::string &path) const |
virtual void | checkValidScheme (const std::string &scheme, EEncoding eflag) const |
virtual void | checkValidUser (const std::string &user, EEncoding eflag) const |
virtual void | checkValidPass (const std::string &pass, EEncoding eflag) const |
virtual void | checkValidHost (const std::string &host, EEncoding eflag) const |
Verifies specified host or IP. More... | |
virtual void | checkValidPort (const std::string &port, EEncoding eflag) const |
Verifies if specified port number is in the range 0..65535. More... | |
virtual void | checkValidPathName (const std::string &path, EEncoding eflag) const |
virtual void | checkValidPathParams (const std::string ¶ms, EEncoding eflag) const |
virtual void | checkValidQueryStr (const std::string &querystr, EEncoding eflag) const |
virtual void | checkValidFragment (const std::string &fragment, EEncoding eflag) const |
Private Attributes | |
RWCOW_pointer< UrlBaseData > | m_data |
Generic Url base class.
The UrlBase class implements default behaviour for URL manipulations and a base for implementation of scheme- specialized URL's for the Url class.
|
virtual |
Destroys the current object.
ca_mgm::url::UrlBase::UrlBase | ( | ) |
Create an empty Url object.
ca_mgm::url::UrlBase::UrlBase | ( | const UrlBase & | url | ) |
ca_mgm::url::UrlBase::UrlBase | ( | const UrlComponents & | components | ) |
Construct new object and initializes it with specified URL components.
components | The url main component string to use. |
UrlNotAllowedException | if one of the components is not allowed for the scheme. |
UrlBadComponentException | if one of the components contains an invalid character. |
ca_mgm::url::UrlBase::UrlBase | ( | const std::string & | urlString | ) |
Create a new Url object from from percent-encoded URL string.
urlString | The url string. |
url::UrlParsingException | if parsing of the url fails. |
url::UrlNotAllowedException | if one of the components is not allowed for the scheme. |
url::UrlBadComponentException | if one of the components contains an invalid character. |
|
protectedvirtual |
|
protectedvirtual |
Verifies specified host or IP.
It verifies, if the specified host
parameter contains a hostname, an IPv4 address in dotted-decimal form or an IPv6 address literal encapsulated within square brackets (RFC3513, Sect. 2.2).
A hostname in the host
parameter, may contain national alphanumeric UTF8 characters (letters other than ASCII a-zA-Z) and allows to specify both, a encoded or decoded hostname.
This function does not perform any hostname lookups and supports only IPv6 addresses in "[ ... ]" notation. The "[v ... ]" square bracket format is not supported by this implementation.
host | The host name or IP to verify. |
UrlNotSupportedException | if the hostname is in the unsuported "[v ... ]" square bracket format. |
UrlBadComponentException | if the hostname is invalid. |
|
protectedvirtual |
|
protectedvirtual |
|
protectedvirtual |
|
protectedvirtual |
Verifies if specified port number is in the range 0..65535.
port | The port number to verify. |
UrlBadComponentException | if the port number is invalid. |
|
protectedvirtual |
|
protectedvirtual |
|
protectedvirtual |
|
protectedvirtual |
Utility method to cleanup an encoded path name.
By default, this method makes sure, that the first slash in the path is not encoded, and that the second slash before the first path segment, is encoded (to "%2F"). It modifies the path in the url, for example: "ftp://host//aaa//bbb" to "ftp://host/%2Faaa//bbb" or as encoded path only also "%2f/name" to "/%2fname".
This operation is required to fulfill the path-absolute rule of RFC3986, if there is no authority. It avoids the missinterpretation of the path as an authority separator.
It is not required if there is an authority ("//" behind the "scheme:"), that is in the path-abempty rule, but it is used e.g. in ftp url's defined by RFC1738.
We apply this operation in both cases (for all paths), but if authority
is true, the encoding of the second slash depends on the schema configuration (for ftp only).
path | The encoded path name to cleanup. |
authority | Whether the url contains authority or not. |
|
protectedvirtual |
Utility method to cleanup an encoded path name.
This variant of the method checks if the host component in the url is empty or not to differentiate if there is an authority.
path | The encoded path name to cleanup. |
|
virtual |
Clears all data in the object.
|
virtual |
Returns pointer to a copy of the current object.
Should be reimplemented by all derived object using the copy constructor of the derived class, e.g.:
std::string ca_mgm::url::UrlBase::config | ( | const std::string & | opt | ) | const |
Get the value of a UrlBase configuration variable.
See configure() method for names an purpose of the configuration variables used in UrlBase class.
opt | The name of the configuration variable. |
void ca_mgm::url::UrlBase::config | ( | const std::string & | opt, |
const std::string & | val | ||
) |
Set the value of a UrlBase configuration variable.
See configure() method for names an purpose of the configuration variables used in UrlBase class.
opt | The name of the configuration variable. |
val | The new value for the configuration variable. |
|
virtual |
Configures behaviour of the instance.
This method is called in UrlBase constructors before any URL components are applied. Derived classes may reimplement this method to change the behaviour of the object. Use the config() methods to query and change them.
The UrlBase class uses following config variables:
sep_pathparams
";"
Separator used to split path parameters from path name. Setting it to empty string disables splitting of path name and path parameters. Set also rx_pathparams to an empty string.psep_pathparam
","
Separator between path parameters.vsep_pathparam
"="
Separator between key and value of a path parameter.psep_querystr
"&"
Separator between query string parameters.vsep_querystr
"="
Separator between key and value of a query parameter.
|
virtual |
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.
|
virtual |
Returns the encoded fragment component of the URL.
eflag | Flag if the fragment should be percent-decoded or not. |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
Returns the hostname or IP from the URL authority.
In case the Url contains an IPv6 number, it is be surrounded by "[" and "]" characters, for example "[::1]" for an IPv6 localhost address.
eflag | Flag if the host should be percent-decoded or not. |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
Returns scheme names known by this object.
This method is used in the isValidScheme() method and is intended to be reimplemented by derived classes to return the scheme names it implements (is restricted or compatible to).
For example, if your derived class implements special features of LDAP URL's, this method may return "ldap" and "ldaps" scheme names.
The UrlBase class returns an empty array, that signals that it is useable with all URL's.
|
virtual |
Returns the password from the URL authority.
eflag | Flag if the password should be percent-decoded or not. |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
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".
|
virtual |
Returns the path name from the URL.
eflag | Flag if the path should be decoded or not. |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
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. |
UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
Returns the encoded path parameters from the URL.
|
virtual |
Returns an array with encoded 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".
|
virtual |
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. |
UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
Returns the port number from the URL authority.
|
virtual |
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. |
UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
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.
|
virtual |
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".
|
virtual |
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. |
UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
Returns the scheme name of the URL.
|
virtual |
Returns the username from the URL authority.
eflag | Flag if the usename should be percent-decoded or not. |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
ViewOptions ca_mgm::url::UrlBase::getViewOptions | ( | ) | const |
Return the view options of the current object.
This method is used to query the view options used by the asString() method.
|
virtual |
Initializes current object with new URL components.
components | The url main component string to use. |
UrlNotAllowedException | if one of the components is not allowed in the scheme. |
UrlBadComponentException | if one of the components contains an invalid character. |
|
virtual |
Returns if scheme name is known to this object.
|
virtual |
|
virtual |
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 (as in the UrlBase class).
scheme | The scheme name to verify. |
Assign shared copy of url
to the current object.
Upon return, both objects will point to the same underlying data. This state will remain until one of the object is modified.
url | The UrlBase object to make a copy of. |
UrlBase& ca_mgm::url::UrlBase::operator= | ( | const std::string & | urlString | ) |
Assigns parsed percent-encoded URL string to the object.
In case of a parse failure, the object will remain unchanged.
urlString | A percent-encoded URL string. |
url::UrlParsingException | if parsing of the url fails. |
url::UrlNotAllowedException | if one of the components is not allowed for the scheme. |
url::UrlNotSupportedException | if the format of one of the components is not supported (e.g. IPvFeature host). |
url::UrlBadComponentException | if one of the components contains an invalid character. |
|
virtual |
Set the authority component in the URL.
The authority
string shoud not contain any leading "//" separator characters (just "user:pass@host:port").
authority | The authority component string. |
UrlNotAllowedException | if the authority has to be empty in for the current scheme. |
UrlBadComponentException | if the authority contains an invalid character. |
UrlParsingException | if authority parsing fails. |
|
virtual |
Set the fragment string in the URL.
fragment | The new fragment string. |
eflag | If the fragment is encoded or not. |
UrlBadComponentException | if the querystr contains an invalid character. |
|
virtual |
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 registered hostname (dns hostname) may contain national alphanumeric UTF8 characters (letters other than ASCII a-zA-Z), that has to be percent-encoded.
Other IP literals in "[v ... ]" square bracket format are not supported by the implementation in UrlBase class.
host | The new hostname or IP address. |
eflag | If the registered hostname is encoded or not. |
UrlNotAllowedException | if the host has to be empty in for the current scheme. |
UrlBadComponentException | if the host is invalid. |
|
virtual |
Set the password in the URL authority.
pass | The new password. |
eflag | If the password is encoded or not. |
UrlNotAllowedException | if the pass has to be empty in for the current scheme. |
UrlBadComponentException | if the pass contains an invalid character. |
|
virtual |
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. |
UrlBadComponentException | if the pathdata contains an invalid character. |
|
virtual |
Set the path name.
path | The new path name. |
eflag | If the path name is encoded or not. |
UrlBadComponentException | if the path name contains an invalid character. |
|
virtual |
Set or add value for the specified path parameter.
param | The decoded path parameter name. |
value | The decoded path parameter value. |
UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
Set the path parameters.
params | The new encoded path parameter string. |
UrlBadComponentException | if the path params contains an invalid character. |
|
virtual |
Set the path parameters.
parray | The array with encoded path parameters. |
UrlBadComponentException | if the parray contains an invalid character. |
|
virtual |
Set the path parameters.
pmap | The map with decoded path parameters. |
UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
|
virtual |
Set the port number in the URL authority.
port | The new port number. |
UrlNotAllowedException | if the port has to be empty in for the current scheme. |
UrlBadComponentException | if the port is invalid. |
|
virtual |
Set or add value for the specified query parameter.
param | The decoded query parameter name. |
value | The decoded query parameter value. |
UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
UrlDecodingException | if the decoded result string would contain a '\0' character. |
|
virtual |
Set the query string in the URL.
The querystr
string parameter is supposed to not to contain the "?" URL query separator character (use just a "foo=bar&x=22" instead of "?foo=bar&x=22").
querystr | The new encoded query string. |
UrlBadComponentException | if the querystr contains an invalid character. |
|
virtual |
Set the query parameters.
qarray | The array with encoded query parameters. |
UrlBadComponentException | if the qarray contains an invalid character. |
|
virtual |
Set the query parameters.
qmap | The map with decoded query parameters. |
UrlNotSupportedException | if parameter parsing is not supported for a URL (scheme). |
|
virtual |
Set the scheme name in the URL.
scheme | The new scheme name. |
UrlBadComponentException | if the scheme contains an invalid character or is empty. |
|
virtual |
Set the username in the URL authority.
user | The new username. |
eflag | If the username is encoded or not. |
UrlNotAllowedException | if the user has to be empty in for the current scheme. |
UrlBadComponentException | if the user contains an invalid character. |
void ca_mgm::url::UrlBase::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. |
|
virtual |
|
virtual |
|
private |