libcamgm
Classes | Typedefs | Enumerations | Functions
ca_mgm::url Namespace Reference

Classes

class  Url
 Url manipulation class. More...
 
struct  UrlAuthority
 
class  UrlBase
 Generic Url base class. More...
 
struct  UrlComponents
 
struct  ViewOptions
 

Typedefs

typedef RWCOW_pointer< UrlBaseUrlRef
 Copy-On-Write Url reference. More...
 
typedef std::map< std::string,
std::string > 
ParamMap
 

Enumerations

enum  EEncoding { E_ENCODED, E_DECODED }
 

Functions

 CA_MGM_DECLARE_EXCEPTION (Url)
 
 CA_MGM_DECLARE_EXCEPTION2 (UrlParsing, UrlException)
 
 CA_MGM_DECLARE_EXCEPTION2 (UrlDecoding, UrlException)
 
 CA_MGM_DECLARE_EXCEPTION2 (UrlBadComponent, UrlException)
 
 CA_MGM_DECLARE_EXCEPTION2 (UrlNotAllowed, UrlException)
 
 CA_MGM_DECLARE_EXCEPTION2 (UrlNotSupported, UrlException)
 
std::string encode (const std::string &str, const std::string &safe="", ca_mgm::url::EEncoding eflag=E_DECODED)
 
std::string encode_buf (const ca_mgm::ByteBuffer &buf, const std::string &safe="", ca_mgm::url::EEncoding eflag=E_DECODED)
 
std::string decode (const std::string &str)
 
ca_mgm::ByteBuffer decode_buf (const std::string &str, bool allowNUL)
 
std::string encode_octet (const unsigned char c)
 
int decode_octet (const char *hex)
 
std::vector< std::string > split (const std::string &pstr, const std::string &psep)
 
ca_mgm::url::ParamMap split (const std::string &pstr, const std::string &psep, const std::string &vsep, EEncoding eflag=E_ENCODED)
 
std::string join (const std::vector< std::string > &parr, const std::string &psep)
 
std::string join (const ca_mgm::url::ParamMap &pmap, const std::string &psep, const std::string &vsep, const std::string &safe)
 
UrlComponents parse_url_string (const std::string &url)
 
UrlAuthority parse_url_authority (const std::string &authority)
 

Typedef Documentation

typedef std::map<std::string,std::string> ca_mgm::url::ParamMap

A parameter map container. A string map, containing key and value pairs parsed from a PathParam- or Query-String.

Copy-On-Write Url reference.

Enumeration Type Documentation

Encoding flags.

Enumerator
E_ENCODED 

Flag to request encoded string(s).

E_DECODED 

Flag to request decoded string(s).

Function Documentation

ca_mgm::url::CA_MGM_DECLARE_EXCEPTION ( Url  )
ca_mgm::url::CA_MGM_DECLARE_EXCEPTION2 ( UrlParsing  ,
UrlException   
)
ca_mgm::url::CA_MGM_DECLARE_EXCEPTION2 ( UrlDecoding  ,
UrlException   
)
ca_mgm::url::CA_MGM_DECLARE_EXCEPTION2 ( UrlBadComponent  ,
UrlException   
)
ca_mgm::url::CA_MGM_DECLARE_EXCEPTION2 ( UrlNotAllowed  ,
UrlException   
)
ca_mgm::url::CA_MGM_DECLARE_EXCEPTION2 ( UrlNotSupported  ,
UrlException   
)
std::string ca_mgm::url::decode ( const std::string &  str)

Decodes a percent-encoded string into a string.

Replaces all occurences of "%<hex><hex>" in the str string with the character encoded using the two hexadecimal digits that follows the "%" character.

For example, the encoded string "%40%3F%3D%26%25" will be decoded to "@?=&%".

Parameters
strA string to decode.
Returns
A decoded strig.
Exceptions
UrlDecodingExceptionif str contains encoded NUL byte.
ca_mgm::ByteBuffer ca_mgm::url::decode_buf ( const std::string &  str,
bool  allowNUL 
)

Decodes a percent-encoded string into a byte buffer.

Replaces all occurences of "%<hex><hex>" in the str string with the character encoded using the two hexadecimal digits that follows the "%" character.

For example, the encoded string "%40%3F%3D%26%25" will be decoded to "@?=&%".

Parameters
strAn encoded string to decode.
allowNULA flag, if "%00" (encoded '\0') is allowed.
Returns
A byte buffer with decoded strig.
Exceptions
UrlDecodingExceptionif allowNUL str contains encoded NUL byte ("%00").
int ca_mgm::url::decode_octet ( const char *  hex)

Decode one character.

Decode the hex parameter pointing to (at least) two hexadecimal digits into its character value and return it.

Example:

char *str = "%40";
char *pct = strchr(str, '%');
int chr = pct ? decode_octet(pct+1) : -1;
// chr is set to the '@' ASCII character now.
Parameters
hexPointer to two hex characters representing the character value in percent-encoded strings.
Returns
The value (0-255) encoded in the hex characters or -1 if hex does not point to two hexadecimal characters.
std::string ca_mgm::url::encode ( const std::string &  str,
const std::string &  safe = "",
ca_mgm::url::EEncoding  eflag = E_DECODED 
)

Encodes a string using URL percent encoding.

By default, all characters except of "a-zA-Z0-9_.-" will be encoded. Additional characters from the set ":/?#[]@!$&'()*+,;=", that are safe for a URL compoent without encoding, can be specified in the safe argument.

If the eflag parameter is set to E_ENCODED, then already encoded substrings will be detected and not encoded a second time.

The following function call will encode the "@" character as "%40", but skip encoding of the "%" character, because the eflag is set to E_ENCODED and "%ba" is detected as a valid encoded character.

ca_mgm::url::encode("foo%bar@localhost", "", E_ENCODED);

With eflag set to E_DECODED, the "%" character would be encoded as well. The complete encoded string would be "foo%25bar%40localhost".

Parameters
strA string to encode.
safeCharacters safe to skip in encoding, e.g. "/" for path names.
eflagIf to detect and skip already encoded substrings.
Returns
A percent encoded string.
std::string ca_mgm::url::encode_buf ( const ca_mgm::ByteBuffer buf,
const std::string &  safe = "",
ca_mgm::url::EEncoding  eflag = E_DECODED 
)

Encodes a byte buffer using URL percent encoding.

For more informations, see encode() function.

Parameters
bufA string buffer to encode (binary data).
safeCharacters safe to skip in encoding, e.g. "/" for path names.
eflagIf to detect and skip already encoded substrings.
Returns
A percent encoded string.
std::string ca_mgm::url::encode_octet ( const unsigned char  c)

Encode one character.

Encode the specified character c into its "%<hex><hex>" representation.

Parameters
cA character to encode.
Returns
A percent encoded representation of the character, e.g. %20 for a ' ' (space).
std::string ca_mgm::url::join ( const std::vector< std::string > &  parr,
const std::string &  psep 
)

Join parameter array into a string.

Creates a string containing all substrings from the parr separated by psep separator character. The substrings in parr should be already URL percent encoded and should't contain psep characters.

Usual parameter separators are '&' for Query- and ',' for PathParam-Strings.

Parameters
parrReference to encoded parameter array.
psepParameter separator character to use.
Returns
A parameter string.
std::string ca_mgm::url::join ( const ca_mgm::url::ParamMap pmap,
const std::string &  psep,
const std::string &  vsep,
const std::string &  safe 
)

Join parameter map to a string.

Creates a string containing all parameter key-value pairs from the parameter map pmap, that will be joined using the psep character and the parameter key is separated from the parameter value using the vsep character. Both, key and value will be automatically encoded.

Usual parameter separators are '&' for Query- and ',' for PathParam-Strings. A usual parameter-value separator is '=' for both, Query- and PathParam-Strings.

See encode() function from details about the safe characters.

Parameters
pmapReference to a parameter map.
psepSeparator character to use between key-value pairs.
vsepSeparator character to use between keys and values.
safeList of characters to accept without encoding.
Returns
A URL percent-encoded parameter string.
Exceptions
UrlNotSupportedExceptionif psep or vsep separator is empty.
UrlAuthority ca_mgm::url::parse_url_authority ( const std::string &  authority)
UrlComponents ca_mgm::url::parse_url_string ( const std::string &  url)
std::vector<std::string> ca_mgm::url::split ( const std::string &  pstr,
const std::string &  psep 
)

Split into a parameter array.

Splits a parameter string pstr at psep characters into an array of substrings.

Usual parameter separators are '&' for Query- and ',' for PathParams-Strings.

Parameters
pstrReference to the PathParam- or Query-String to split.
psepParameter separator character to split at.
Returns
The resulting parameter array.
Exceptions
UrlNotSupportedExceptionif psep separator is empty.
ca_mgm::url::ParamMap ca_mgm::url::split ( const std::string &  pstr,
const std::string &  psep,
const std::string &  vsep,
EEncoding  eflag = E_ENCODED 
)

Split into a parameter map.

Splits a parameter string pstr into substrings using psep as separator and then, each substring into key and value pair using vsep as separator between parameter key and value and adds them to the parameter map pmap.

If a parameter substring doesn't contain any value separator vsep, the substring is used as a parameter key and value is set to an empty string.

Usual parameter separators are '&' for Query- and ',' for PathParam-Strings. A usual parameter-value separator is '=' for both, Query- and PathParam-Strings.

If the encoding flag eflag is set to E_DECODED, then the key and values are dedcoded before they are stored in the map.

Parameters
pstrReference to the PathParam- or Query-String to split.
psepSeparator character to split key-value pairs.
vsepSeparator character to split key and value.
eflagFlag if the key and value strings should be URL percent decoded before they're stored in the map.
Returns
The resulting parameter map.
Exceptions
UrlNotSupportedExceptionif psep or vsep separator is empty.