You.i Engine
Public Types | Public Member Functions | Static Public Member Functions | List of all members
CYIUrl Class Reference
Network

Detailed Description

A class used to encapsulate an URL.

URL objects are created either from an input string, which is then parsed into URL components, or by setting one or more URL components individually.

Warning
While RFC 3986 is used as a base for this class, it is not followed to the letter.
No encoding/decoding is performed on the various URL sections. If an URL section contains characters that would be invalid for that section, it is up to the user to encode the string prior to setting it in the URL object.

#include <network/YiUrl.h>

Public Types

enum  PARTS {
  SCHEME = 0x1,
  USERNAME = 0x2,
  PASSWORD = 0x4,
  HOST = 0x8,
  PORT = 0x10,
  PATH = 0x20,
  QUERY = 0x40,
  FRAGMENT = 0x80,
  AUTHENTICATION = USERNAME | PASSWORD,
  AUTHORITY = AUTHENTICATION | HOST | PORT,
  AUTHORITY_AND_PATH = AUTHORITY | PATH,
  EVERYTHING = SCHEME | AUTHORITY_AND_PATH | QUERY | FRAGMENT,
  NO_SCHEME = EVERYTHING & (~SCHEME),
  NO_AUTHENTICATION = EVERYTHING & (~AUTHENTICATION)
}
 
enum  ENCODING {
  ENCODED,
  DECODED
}
 

Public Member Functions

 CYIUrl ()
 
 CYIUrl (const CYIString &url, ENCODING eEncoding=ENCODED)
 
bool operator== (const CYIUrl &other) const
 
bool operator!= (const CYIUrl &other) const
 
bool operator< (const CYIUrl &other) const
 
void SetScheme (const CYIString &scheme)
 
void SetAuthority (const CYIString &authority, ENCODING eEncoding=DECODED)
 
void SetAuthentication (const CYIString &authentication, ENCODING eEncoding=DECODED)
 
void SetUsername (const CYIString &username, ENCODING eEncoding=DECODED)
 
void SetPassword (const CYIString &password, ENCODING eEncoding=DECODED)
 
void SetHost (const CYIString &host, ENCODING eEncoding=DECODED)
 
void SetPort (int32_t nPort)
 
void SetPort (const CYIString &port)
 
void SetPath (const CYIString &path, CYIUrl::ENCODING eEncoding=DECODED)
 
void SetQuery (const CYIString &query, CYIUrl::ENCODING eEncoding=DECODED)
 
void SetQuery (const CYIUrlQuery &query)
 
void SetFragment (const CYIString &fragment, CYIUrl::ENCODING eEncoding=DECODED)
 
void SetString (const CYIString &url, ENCODING eEncoding=ENCODED)
 
const CYIString & GetScheme () const
 
CYIString GetAuthority (ENCODING eEncoding=DECODED) const
 
CYIString GetAuthentication (ENCODING eEncoding=DECODED) const
 
CYIString GetUsername (ENCODING eEncoding=DECODED) const
 
CYIString GetPassword (ENCODING eEncoding=DECODED) const
 
CYIString GetHost (ENCODING eEncoding=DECODED) const
 
int32_t GetPort () const
 
const CYIString & GetPortString () const
 
CYIString GetPath (ENCODING eEncoding=DECODED) const
 
CYIString GetQuery (ENCODING eEncoding=DECODED) const
 
CYIString GetFragment (ENCODING eEncoding=DECODED) const
 
CYIUrlQuery GetQueryBuilder () const
 
CYIString ToString (PARTS eParts=EVERYTHING, ENCODING eEncoding=ENCODED) const
 
bool IsEmpty () const
 
void Clear ()
 

Static Public Member Functions

static const CYIUrl & EmptyUrl ()
 
static CYIString Encode (const CYIString &input)
 
static CYIString Decode (const CYIString &input)
 

Member Enumeration Documentation

enum CYIUrl::ENCODING
Enumerator
ENCODED 
DECODED 
enum CYIUrl::PARTS
Enumerator
SCHEME 
USERNAME 
PASSWORD 
HOST 
PORT 
PATH 
QUERY 
FRAGMENT 
AUTHENTICATION 
AUTHORITY 
AUTHORITY_AND_PATH 
EVERYTHING 
NO_SCHEME 
NO_AUTHENTICATION 

Constructor & Destructor Documentation

CYIUrl::CYIUrl ( )

Creates a blank URL.

Note
A blank URL also has a blank scheme.
CYIUrl::CYIUrl ( const CYIString &  url,
ENCODING  eEncoding = ENCODED 
)
explicit

Creates an URL from the string url. The string will be parsed into URL components.

The eEncoding parameter can be used to specify the encoding of the provided url string. The various delimiters used in URLs are expected to be unencoded. By default, the provided string is expected to be encoded.

Member Function Documentation

void CYIUrl::Clear ( )

Clears this URL and resets it to a 'blank' URL. Note that blank URLs have no scheme.

static CYIString CYIUrl::Decode ( const CYIString &  input)
static

Decodes the string input using URL percent encoding.

All character sequences 'XX', where XX is two hexadeicmal digits, are transformed to their single-byte representation. 'Orphan' percent characters (such as in '100% coverage') are left as-is, as are percent sequences with invalid data (such as 'AX').

Example: The string 'The%20100%%20quick%20brown%20fox' gets encoded to 'The 100% quick brown fox'.

Note
Escape character sequences with hexadecimal values above 7F are interpreted as being part of a UTF-8 sequence.
static const CYIUrl& CYIUrl::EmptyUrl ( )
static

Returns an instance of an empty URL. Useful for functions that return references.

static CYIString CYIUrl::Encode ( const CYIString &  input)
static

Encodes the string input using URL percent encoding.

The following characters are left as is: a-z, A-Z, 0-9, '-', '.', '_' and '~'. All other characters, including UTF-8 characters and controls characters, are encoded as follows XX, where XX is two uppercase hexadecimal digits. UTF-8 characters with codepoints above 127 are encoded as multiple bytes represented in XX format.

Example: The string 'The quick brown fox' gets encoded to 'The%20quick%20brown%20fox'.

Warning
Encoding the same string twice may yield unexpected results because the '' character itself would get encoded.
CYIString CYIUrl::GetAuthentication ( ENCODING  eEncoding = DECODED) const

Returns the authentication portion of this URL. The authentication portion is composted of the username and, password sections.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'myuser:mypassword'.

The eEncoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded.
CYIString CYIUrl::GetAuthority ( ENCODING  eEncoding = DECODED) const

Returns the authority portion of this URL. The authority portion is composted of the username, password, host and port sections.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'myuser:mypas.nosp@m.swor.nosp@m.d@www.nosp@m..exa.nosp@m.mple..nosp@m.com:123'.

The eEncoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded.
CYIString CYIUrl::GetFragment ( ENCODING  eEncoding = DECODED) const

Returns the fragment portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'bookmark'.

The eEncoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

CYIString CYIUrl::GetHost ( ENCODING  eEncoding = DECODED) const

Returns the host portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'www.example.com'.

The eEncoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

CYIString CYIUrl::GetPassword ( ENCODING  eEncoding = DECODED) const

Returns the password portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'mypassword'.

The eEncoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

CYIString CYIUrl::GetPath ( ENCODING  eEncoding = DECODED) const

Returns the path portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'my/path'.

The eEncoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded.
Note
What is considered the path in a URL differs depending on if an authority section is present or not. For example, in the URL 'http://server/my/path', the path is 'my/path', but in the URL 'scheme:/my/path' the path is '/my/path'.
int32_t CYIUrl::GetPort ( ) const

Returns the port portion of this URL as an integer. Returns -1 if no port is set, or if the set port string cannot be parsed as a (valid) port.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 123.

const CYIString& CYIUrl::GetPortString ( ) const

Returns the port portion of this URL as a string.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return '123'.

CYIString CYIUrl::GetQuery ( ENCODING  eEncoding = DECODED) const

Returns the query portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'key=value'.

The eEncoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded. For example, if the '&' or '=' characters are encoded as part of a parameter, the decoded query may no longer be parsable as a list of key-value pairs. Thus, calling SetQuery(GetQuery()) may result in corrupt data.
CYIUrlQuery CYIUrl::GetQueryBuilder ( ) const

Returns a CYIUrlQuery query object initialized from this URL's query.

Note
Modifying the returned query object does not modify this URL object – CYIUrl::SetQuery has to be called with the modified CYIUrlQuery.
const CYIString& CYIUrl::GetScheme ( ) const

Returns the scheme portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'http'.

CYIString CYIUrl::GetUsername ( ENCODING  eEncoding = DECODED) const

Returns the username portion of this URL.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function would return 'myuser'.

The eEncoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in decoded form.

bool CYIUrl::IsEmpty ( ) const

Returns true if this URL has no non-empty sections.

bool CYIUrl::operator!= ( const CYIUrl &  other) const
bool CYIUrl::operator< ( const CYIUrl &  other) const
bool CYIUrl::operator== ( const CYIUrl &  other) const
void CYIUrl::SetAuthentication ( const CYIString &  authentication,
ENCODING  eEncoding = DECODED 
)

Sets the authentication portion of this URL. The authentication is composed of the username and password, though both sections are optional.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'bob:smith' will result in the URL 'ftp://bob:smith@www.example.com:123/my/path?key=value#bookmark'.

The eEncoding parameter can be used to specify the encoding of the provided authentication string. The ':' delimiter is expected to be unencoded. By default, the authentication is assumed to be decoded.

void CYIUrl::SetAuthority ( const CYIString &  authority,
ENCODING  eEncoding = DECODED 
)

Sets the authority portion of this URL. The authority is composed of the username, password, host and port, though all sections are optional.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'bob:smith.nosp@m.@mys.nosp@m.erver.nosp@m..com:42' will result in the URL 'ftp://bob:smith@myserver.com:42/my/path?key=value#bookmark'.

The eEncoding parameter can be used to specify the encoding of the provided authority string. The ':' and '@' delimiters are expected to be unencoded. By default, the authority is assumed to be decoded.

void CYIUrl::SetFragment ( const CYIString &  fragment,
CYIUrl::ENCODING  eEncoding = DECODED 
)

Sets the fragment portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'place' will result in the URL 'ftp://myuser:mypassword@www.example.com:123/my/path?fruit=banana#place'.

The eEncoding parameter can be used to specify the encoding of the provided fragment string. By default, the fragment is assumed to be decoded.

void CYIUrl::SetHost ( const CYIString &  host,
ENCODING  eEncoding = DECODED 
)

Sets the host portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'myserver.com' will result in the URL 'ftp://myuser:mypassword@myserver.com:123/my/path?key=value#bookmark'.

The eEncoding parameter can be used to specify the encoding of the provided host string. By default, the host is assumed to be decoded.

Note
RFC 2396 specifies that hosts may only contain alpha numerical characters, along with the '-' and '.' characters. For compatibility, this function will percent-encode encountered invalid characters (when eEncoding is DECODED). However, be warned that this does not create a valid URL.
void CYIUrl::SetPassword ( const CYIString &  password,
ENCODING  eEncoding = DECODED 
)

Sets the password portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'smith' will result in the URL 'ftp://myuser:smith@www.example.com:123/my/path?key=value#bookmark'.

The eEncoding parameter can be used to specify the encoding of the provided password string. By default, the password is assumed to be decoded.

void CYIUrl::SetPath ( const CYIString &  path,
CYIUrl::ENCODING  eEncoding = DECODED 
)

Sets the path portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'differentPath' will result in the URL 'ftp://myuser:mypassword@www.example.com:123/differentPath?key=value#bookmark'.

The eEncoding parameter can be used to specify the encoding of the provided path string. By default, the path is assumed to be decoded.

Note
What is considered the path in a URL differs depending on if an authority section is present or not. For example, in the URL 'http://server/my/path', the path is 'my/path', but in the URL 'scheme:/my/path' the path is '/my/path'.
void CYIUrl::SetPort ( int32_t  nPort)

Sets the port portion of this URL. Negative values are interpreted as 'no port'.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with '42' will result in the URL 'ftp://myuser:mypassword@www.example.com:42/my/path?key=value#bookmark'.

void CYIUrl::SetPort ( const CYIString &  port)

Sets the port portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with '42' will result in the URL 'ftp://myuser:mypassword@www.example.com:42/my/path?key=value#bookmark'.

Note
RFC 2396 specifies that ports may only contain numerical characters. For compatibility, this function allows any string to be used as port. However, be warned that using non-numerical characters as part of the port may result in parsing errors.
void CYIUrl::SetQuery ( const CYIString &  query,
CYIUrl::ENCODING  eEncoding = DECODED 
)

Sets the query portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'fruit=banana' will result in the URL 'ftp://myuser:mypassword@www.example.com:123/my/path?fruit=banana#bookmark'.

The eEncoding parameter can be used to specify the encoding of the query string. The parameter delimiters, '&' and '=', are expected to be unencoded. By default, the query string is assumed to be decoded.

Note
The CYIUrlQuery::ToString function returns encoded queries by default. To set a query to an URL from a CYIUrlQuery object, it is recommended to use the SetQuery(const CYIUrlQuery &) function instead.
void CYIUrl::SetQuery ( const CYIUrlQuery &  query)

Sets the query portion of this URL from the data contained in a CYIUrlQuery object.

void CYIUrl::SetScheme ( const CYIString &  scheme)

Sets the scheme portion of this URL. The scheme must not be postfixed with ':' or '://'.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'ftp' will result in the URL 'ftp://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark'.

Note
RFC 2396 specifies that only alphanumeric characters, along with the '+', '-' and '.' characters, are allowed in schemes. The presence of any other character will result in an invalid URLs, which may not parse correctly.
void CYIUrl::SetString ( const CYIString &  url,
ENCODING  eEncoding = ENCODED 
)

Sets the string representation of this URL. The string will be parsed into the individual string components.

The eEncoding parameter can be used to specify the encoding of the provided url string. The various delimiters used in URLs are expected to be unencoded. By default, the provided string is expected to be encoded.

See also
CYIUrl(const CYIString&)
void CYIUrl::SetUsername ( const CYIString &  username,
ENCODING  eEncoding = DECODED 
)

Sets the username portion of this URL.

Example: Given the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', calling this function with 'bob' will result in the URL 'ftp://bob:mypassword@www.example.com:123/my/path?key=value#bookmark'.

The eEncoding parameter can be used to specify the encoding of the provided username string. By default, the username is assumed to be decoded.

CYIString CYIUrl::ToString ( PARTS  eParts = EVERYTHING,
ENCODING  eEncoding = ENCODED 
) const

Returns a string generated from the components of this URL.

The eParts parameter can be used to specify which parts of the URL to include in the generated string. Note that some combinations don't really make sense (e.g. 'scheme + port'). By default, all parts of the URL are used to generate the returned string.

Example: For the URL 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark', this function, when called with EVERYTHING, would return 'http://myuser:mypassword@www.example.com:123/my/path?key=value#bookmark'. When called with HOST, it would return 'www.example.com'. When called with NO_SCHEME, it would return 'myuser:mypas.nosp@m.swor.nosp@m.d@www.nosp@m..exa.nosp@m.mple..nosp@m.com:123/my/path?key=value::bookmark'.

The eEncoding parameter can be used to specify the encoding of the returned value. By default, the value is returned in encoded form.

Warning
Some data loss may occur when fetching decoded strings, as encoded delimiters may be decoded.
The documentation for this class was generated from the following file: