nlib
nn::nlib::Uri Class Referencefinal

The class for parsing and constructing regular URIs. More...

#include "nn/nlib/Uri.h"

Public Types

enum  Error {
  kOk = 0,
  kInvalidParam,
  kOutOfMemory,
  kNotInitialized,
  kInvalidUri,
  kAbsoluteUriRequired,
  kPathNormalizationError,
  kUriTooLong,
  kBufferSizeNotEnough
}
 An error value, as an enumerator, that can be obtained with GetError(). More...
 

Public Member Functions

constexpr Uri () noexcept
 Instantiates the object with default parameters (default constructor). Initializes an object.
 
bool Parse (const char *first, const char *last) noexcept
 Parses a URI string. More...
 
bool Parse (const char *str) noexcept
 Returns Parse(str, str + strlen(str)).
 
bool SetUri (const char *scheme, const char *userinfo, const char *host, const char *port, const char *path, const char *query, const char *fragment) noexcept
 Sets the various parts of the URI. More...
 
bool IsAbsolute () const noexcept
 Returns true if the URI is an absolute URI. This function determines the string is an absolute URI if a scheme is specified.
 
bool ComposeString (char *buf, size_t size) const noexcept
 Writes a URI string. More...
 
template<size_t N>
bool ComposeString (char(&buf)[N]) const noexcept
 Writes a URI string. More...
 
bool AddBaseUri (const Uri &relative, const Uri &base) noexcept
 Resolves a relative path. More...
 
const char * GetScheme () const noexcept
 Returns the string for the URI scheme (such as "http" or "file"). More...
 
const char * GetUserInfo () const noexcept
 Gets user-specific information (like a user name and password) associated with the specified URI. More...
 
const char * GetHost () const noexcept
 Gets the hostname. More...
 
const char * GetPort () const noexcept
 Gets the string that is the port number. More...
 
int GetPortNumber () const noexcept
 Gets the port number. If a port number string has been set and it can be converted into the int type, the function returns a non-negative integer, otherwise it returns -1.
 
const char * GetPath () const noexcept
 Gets a path. More...
 
const char * GetQuery () const noexcept
 Gets a query string. More...
 
const char * GetFragment () const noexcept
 Gets a fragment string. More...
 
bool SetScheme (const char *first, const char *last) noexcept
 Sets the scheme as a string, excluding the colon at its end.
 
bool SetUserInfo (const char *first, const char *last) noexcept
 Sets user-specific information, including the user name and password, associated with the specified URI.
 
bool SetHost (const char *first, const char *last) noexcept
 Sets the hostname.
 
bool SetPort (const char *first, const char *last) noexcept
 Sets the port number as a string, excluding the colon.
 
bool SetPath (const char *first, const char *last) noexcept
 Sets the path.
 
bool SetQuery (const char *first, const char *last) noexcept
 Sets the query string, excluding the "?" character at its beginning.
 
bool SetFragment (const char *first, const char *last) noexcept
 Sets the fragment string, excluding the "#" character at its beginning.
 
bool SetScheme (const char *scheme) noexcept
 Sets the scheme as a string, excluding the colon at its end.
 
bool SetUserInfo (const char *userinfo) noexcept
 Sets user-specific information, including the user name and password, associated with the specified URI.
 
bool SetHost (const char *host) noexcept
 Sets the hostname.
 
bool SetPort (const char *port) noexcept
 Sets the port number as a string, excluding the colon.
 
bool SetPortNumber (int port) noexcept
 Sets the port number.
 
bool SetPath (const char *path) noexcept
 Sets the path.
 
bool SetQuery (const char *query) noexcept
 Sets the query string, excluding the "?" character at its beginning.
 
bool SetFragment (const char *fragment) noexcept
 Sets the fragment string, excluding the "#" character at its beginning.
 
template<size_t N>
bool SetQuery (const UriQueryEncoder< N > &encoder) noexcept
 Sets the query string, excluding the "?" character at its beginning.
 
void Reset () noexcept
 Initializes (resets) an object.
 
Error GetError () const noexcept
 A detailed reason for an error can be obtained when that error occurs.
 

Static Public Member Functions

static bool IsHostName (const nlib_utf8_t *first, const nlib_utf8_t *last) noexcept
 Determines whether the string complies with the host name requirements (RFC 1034 3.1). More...
 
static bool IsHostName (const nlib_utf8_t *str) noexcept
 Returns IsHostName(str, str + strlen(str)).
 
static bool IsIpv4 (const nlib_utf8_t *first, const nlib_utf8_t *last) noexcept
 Determines whether the string complies with IPv4 requirements. More...
 
static bool IsIpv4 (const nlib_utf8_t *str) noexcept
 Returns IsIpv4(str, str + strlen(str)).
 
static bool IsIpv6 (const nlib_utf8_t *first, const nlib_utf8_t *last) noexcept
 Determines whether the string complies with IPv6 requirements. More...
 
static bool IsIpv6 (const nlib_utf8_t *str) noexcept
 Returns IsIpv6(str, str + strlen(str)).
 
static bool IsEmailAddress (const nlib_utf8_t *first, const nlib_utf8_t *last) noexcept
 Determines whether the string complies with the email address requirements (RFC 5322 3.4). More...
 
static bool IsEmailAddress (const nlib_utf8_t *str) noexcept
 Returns IsEmailAddress(str, str + strlen(str)).
 
static bool IsUri (const nlib_utf8_t *first, const nlib_utf8_t *last) noexcept
 Determines whether the string is a URI. Note that, when the string is a relative path, that string is a URI reference, instead of a URI. More...
 
static bool IsUri (const nlib_utf8_t *str) noexcept
 Returns IsUri(str, str + strlen(str)).
 
static bool IsUriReference (const nlib_utf8_t *first, const nlib_utf8_t *last) noexcept
 Determines whether the string is a URI reference. More...
 
static bool IsUriReference (const nlib_utf8_t *str) noexcept
 Returns IsUriReference(str, str + strlen(str)).
 
static bool IsReserved (int c) noexcept
 Returns true if c is a reserved character in RFC 3986.
 
static bool IsUnreserved (int c) noexcept
 Returns true if c is an unreserved character in RFC 3986.
 
static bool IsHexDigit (int c) noexcept
 Returns true if the value is a hexadecimal number.
 
static errno_t DecodeUriComponent (size_t *written, char *buf, size_t n, const char *first, const char *last) noexcept
 Decodes a percent-encoded string. More...
 
template<size_t N>
static errno_t DecodeUriComponent (size_t *written, char(&buf)[N], const char *s) noexcept
 Calls DecodeUriComponent(written, buf, N, s).
 
static errno_t DecodeUriComponent (size_t *written, char *buf, size_t n, const char *s) noexcept
 Decodes a percent-encoded string. More...
 
template<size_t N>
static errno_t DecodeUriComponent (size_t *written, char(&buf)[N], const char *first, const char *last) noexcept
 Calls DecodeUriComponent(written, buf, N, first, last).
 
static errno_t EncodeUriComponent (size_t *written, char *buf, size_t n, const char *first, const char *last, bool fragment_mode) noexcept
 Percent-encodes a string. More...
 
template<size_t N>
static errno_t EncodeUriComponent (size_t *written, char(&buf)[N], const char *first, const char *last, bool fragment_mode) noexcept
 Calls EncodeUriComponent(written, buf, N, first, last, fragment_mode).
 
static errno_t EncodeUriComponent (size_t *written, char *buf, size_t n, const char *s, bool fragment_mode) noexcept
 Percent-encodes a string. More...
 
template<size_t N>
static errno_t EncodeUriComponent (size_t *written, char(&buf)[N], const char *s, bool fragment_mode) noexcept
 Calls EncodeUriComponent(written, buf, N, s, fragment_mode).
 
static errno_t DecodePath (size_t *written, char *buf, size_t n, const char *s) noexcept
 Decodes a percent-encoded string. This function is the same as DecodeUriComponent, except that it returns EILSEQ if the decoded character is the forward slash ('/').
 
template<size_t N>
static errno_t DecodePath (size_t *written, char(&buf)[N], const char *s) noexcept
 Calls DecodePath(written, buf, N, s) .
 
static errno_t EncodePath (size_t *written, char *buf, size_t n, const char *s) noexcept
 Percent-encodes a string. This function is the same as EncodeUriComponent, except that it does not percent-encode the forward slash ( ' / ' ).
 
template<size_t N>
static errno_t EncodePath (size_t *written, char(&buf)[N], const char *s) noexcept
 Calls EncodePath(written, buf, N, s).
 

Detailed Description

The class for parsing and constructing regular URIs.

Description
The HttpStyleUri and FileStyleUri classes parse URIs using this class.
This class is also used with relative URIs (relative paths). When a URI is parsed, some of the percent-encoded characters are decoded. The characters that are decoded belong to unreserved(ALPHA / DIGIT / "-" / "." / "_" / "~") in RFC 3986. Other percent-encoded characters are left the way they are.
Uri uri;
uri.Parse("http://www.example.com/dir/index.html?query=test#part1");
uri.GetScheme(); // "http"
uri.GetHost(); // "www.example.com"
uri.GetPath(); // "/dir/index.html"
uri.GetQuery(); // "query=test"
uri.GetFragment(); // "part1"
See also
https://www.ietf.org/rfc/rfc3986.txt (RFC 3986)
http://www.eonet.ne.jp/~h-hash/rfc_ja/rfc3986.ja.html (RFC 3986, in Japanese)
Examples:
misc/uri/uri.cpp.

Definition at line 51 of file Uri.h.

Member Enumeration Documentation

◆ Error

An error value, as an enumerator, that can be obtained with GetError().

Enumerator
kOk 

An error has not occurred.

kInvalidParam 

Invalid argument.

kOutOfMemory 

Failed to allocate memory.

kNotInitialized 

The object has not been initialized.

kInvalidUri 

Invalid URI.

kAbsoluteUriRequired 

An absolute URI needs to be specified.

kPathNormalizationError 

Failed to normalize the (absolute) path.

kUriTooLong 

The URI is too long.

kBufferSizeNotEnough 

Insufficient buffer size.

Definition at line 292 of file Uri.h.

Member Function Documentation

◆ AddBaseUri()

nn::nlib::Uri::AddBaseUri ( const Uri relative,
const Uri base 
)
noexcept

Resolves a relative path.

Parameters
[in]relativeA relative path.
[in]baseThe base URI.
Returns
Returns true when successful.
Description
If a scheme has been specified for the relative path, it is treated as a relative path even if its scheme is the same as that of the base URI.

◆ ComposeString() [1/2]

nn::nlib::Uri::ComposeString ( char *  buf,
size_t  size 
) const
noexcept

Writes a URI string.

Parameters
[out]bufThe pointer to the buffer to which the string was written.
[in]sizeThe size of the buffer.
Returns
Returns true when successful.

◆ ComposeString() [2/2]

template<size_t N>
nn::nlib::Uri::ComposeString ( char(&)  buf[N]) const
inlinenoexcept

Writes a URI string.

Parameters
[out]bufThe buffer to which the string was written.
Returns
Returns true when successful.

Definition at line 224 of file Uri.h.

◆ DecodeUriComponent() [1/2]

nn::nlib::Uri::DecodeUriComponent ( size_t *  written,
char *  buf,
size_t  n,
const char *  first,
const char *  last 
)
staticnoexcept

Decodes a percent-encoded string.

Parameters
[in]writtenThe number of bytes in the decoded string (not including the null character).
[out]bufPointer to the location in memory where the decoded string will be stored.
[in]nThe size of the buffer.
[in]firstThe position at which the string to be decoded starts.
[in]lastThe position at which the string to be decoded ends.
Return values
0Success.
EINVALIndicates that either first and last are NULL, or buf is NULL and n is not 0.
EILSEQIndicates that the percent-encoded string is incorrect.
ERANGEIndicates that buf is not large enough.
Description
Decodes all percent-encoded characters. To store the number of required bytes in written, run the function with buff set to NULL and n set to 0.

◆ DecodeUriComponent() [2/2]

nn::nlib::Uri::DecodeUriComponent ( size_t *  written,
char *  buf,
size_t  n,
const char *  s 
)
inlinestaticnoexcept

Decodes a percent-encoded string.

Parameters
[in]writtenThe number of bytes in the decoded string (not including the null character).
[out]bufPointer to the location in memory where the decoded string will be stored.
[in]nThe size of the buffer.
[in]sThe string to decode.
Return values
0Success.
EINVALIndicates that either s is NULL, or buf is NULL and n is not 0.
EILSEQIndicates that the percent-encoded string is incorrect.
ERANGEIndicates that buf is not large enough.
Description
Decodes all percent-encoded characters. To store the number of required bytes in written, run the function with buff set to NULL and n set to 0.

Definition at line 100 of file Uri.h.

◆ EncodeUriComponent() [1/2]

nn::nlib::Uri::EncodeUriComponent ( size_t *  written,
char *  buf,
size_t  n,
const char *  first,
const char *  last,
bool  fragment_mode 
)
staticnoexcept

Percent-encodes a string.

Parameters
[in]writtenThe number of bytes in the encoded string (not including the null character).
[out]bufPointer to the location in memory where the encoded string will be stored.
[in]nThe size of the buffer.
[in]firstThe position at which the string to be encoded starts.
[in]lastThe position at which the string to be encoded ends.
[in]fragment_modeCustomization of the characters to encode.
Return values
0Success.
EINVALIndicates that either first and last are NULL, or buf is NULL and n is not 0.
ERANGEIndicates that buf is not large enough.
Description
To store the number of required bytes in written, run the function with buff set to NULL and n set to 0.

◆ EncodeUriComponent() [2/2]

nn::nlib::Uri::EncodeUriComponent ( size_t *  written,
char *  buf,
size_t  n,
const char *  s,
bool  fragment_mode 
)
inlinestaticnoexcept

Percent-encodes a string.

Parameters
[in]writtenThe number of bytes in the encoded string (not including the null character).
[out]bufPointer to the location in memory where the encoded string will be stored.
[in]nThe size of the buffer.
[in]sThe string to encode.
[in]fragment_modeCustomization of the characters to encode.
Return values
0Success.
EINVALIndicates that either s is NULL, or buf is NULL and n is not 0.
ERANGEIndicates that buf is not large enough.
Description
To store the number of required bytes in written, run the function with buff set to NULL and n set to 0.

Definition at line 137 of file Uri.h.

◆ GetFragment()

nn::nlib::Uri::GetFragment ( ) const
noexcept

Gets a fragment string.

Returns
The fragment string (not including the '#' character at the start).

◆ GetHost()

nn::nlib::Uri::GetHost ( ) const
noexcept

Gets the hostname.

Returns
The hostname (the forward slash (' / ') is not included).

◆ GetPath()

nn::nlib::Uri::GetPath ( ) const
noexcept

Gets a path.

Returns
The path string.

◆ GetPort()

nn::nlib::Uri::GetPort ( ) const
noexcept

Gets the string that is the port number.

Returns
The port number string (the ':' character is not included).
Description
This string contains only the characters 0 through 9. It can start with a succession of zeros.

◆ GetQuery()

nn::nlib::Uri::GetQuery ( ) const
noexcept

Gets a query string.

Returns
The query string (not including the '?' character at the start).

◆ GetScheme()

nn::nlib::Uri::GetScheme ( ) const
noexcept

Returns the string for the URI scheme (such as "http" or "file").

Returns
The scheme as a string (not including the colon at the end).
Description
The function returns NULL if a scheme has not been specified (the URI is a relative path).

◆ GetUserInfo()

nn::nlib::Uri::GetUserInfo ( ) const
noexcept

Gets user-specific information (like a user name and password) associated with the specified URI.

Returns
A string of user-specific information.

◆ IsEmailAddress()

nn::nlib::Uri::IsEmailAddress ( const nlib_utf8_t first,
const nlib_utf8_t last 
)
staticnoexcept

Determines whether the string complies with the email address requirements (RFC 5322 3.4).

Parameters
[in]firstThe first character of the string you want to inspect.
[in]lastThe last character of the string you want to inspect.
Return values
Returnstrue if the string complies with email address requirements, otherwise returns false.
See also
https://tools.ietf.org/html/rfc5322#section-3.4
http://srgia.com/docs/rfc5322j.html#p3.4

◆ IsHostName()

nn::nlib::Uri::IsHostName ( const nlib_utf8_t first,
const nlib_utf8_t last 
)
staticnoexcept

Determines whether the string complies with the host name requirements (RFC 1034 3.1).

Parameters
[in]firstThe first character of the string you want to inspect.
[in]lastThe last character of the string you want to inspect.
Return values
Returnstrue if the string is a host name, otherwise returns false.
See also
https://tools.ietf.org/html/rfc1034
http://srgia.com/docs/rfc1034j.html

◆ IsIpv4()

nn::nlib::Uri::IsIpv4 ( const nlib_utf8_t first,
const nlib_utf8_t last 
)
staticnoexcept

Determines whether the string complies with IPv4 requirements.

Parameters
[in]firstThe first character of the string you want to inspect.
[in]lastThe last character of the string you want to inspect.
Return values
Returnstrue if the string complies with IPv4 requirements, otherwise returns false.

◆ IsIpv6()

nn::nlib::Uri::IsIpv6 ( const nlib_utf8_t first,
const nlib_utf8_t last 
)
staticnoexcept

Determines whether the string complies with IPv6 requirements.

Parameters
[in]firstThe first character of the string you want to inspect.
[in]lastThe last character of the string you want to inspect.
Return values
Returnstrue if the string complies with IPv6 requirements, otherwise returns false.

◆ IsUri()

nn::nlib::Uri::IsUri ( const nlib_utf8_t first,
const nlib_utf8_t last 
)
staticnoexcept

Determines whether the string is a URI. Note that, when the string is a relative path, that string is a URI reference, instead of a URI.

Parameters
[in]firstThe first character of the string you want to inspect.
[in]lastThe last character of the string you want to inspect.
Return values
Returnstrue if the string is a URI, otherwise returns false.

◆ IsUriReference()

nn::nlib::Uri::IsUriReference ( const nlib_utf8_t first,
const nlib_utf8_t last 
)
staticnoexcept

Determines whether the string is a URI reference.

Parameters
[in]firstThe first character of the string you want to inspect.
[in]lastThe last character of the string you want to inspect.
Return values
Returnstrue if the string is a URI reference, otherwise returns false.

◆ Parse()

nn::nlib::Uri::Parse ( const char *  first,
const char *  last 
)
noexcept

Parses a URI string.

Parameters
[in]firstThe first character of the string you want to parse.
[in]lastThe last character of the string you want to parse.
Returns
Returns true when successful.
Description
The function fails if the URI string is invalid (for example, because it contains an unusable character). The function also fails if the URI string is longer than 2000 characters.

◆ SetUri()

nn::nlib::Uri::SetUri ( const char *  scheme,
const char *  userinfo,
const char *  host,
const char *  port,
const char *  path,
const char *  query,
const char *  fragment 
)
noexcept

Sets the various parts of the URI.

Parameters
[in]schemeThe scheme name (not including the ':' character at the end).
[in]userinfoThe user information.
[in]hostThe hostname (not including the '@ ' character at the beginning).
[in]portThe port number (not including the ':' character at the start).
[in]pathThe path.
[in]queryThe query string (not including the '?' character at the start).
[in]fragmentThe fragment string (not including the '#' character at the start).
Returns
Returns true when successful.
Description
The URI is composed like this: <scheme>://<userinfo>\<host>:<port><path>?<query>#<fragment> path must begin with a forward slash ('/') if userinfo, host, and port are not all NULL. Characters that require percent-encoding must be percent-encoded ahead of time.

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