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

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 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.
 
Error GetError () const noexcept
 A detailed reason for an error can be obtained when that error occurs.
 
 operator bool () const
 Returns true if the object has been initialized and an error has not occurred inside, or returns false if an error has occurred inside.
 
Constructor, Destructor, and Initialization
constexpr Uri () noexcept
 Instantiates the object with default parameters (default constructor).
 
 Uri (Uri &&rhs)
 Instantiates the object (move constructor).
 
Urioperator= (Uri &&rhs)
 Move assignment operator.
 
void Reset () noexcept
 Resets this object to the state immediately after the default constructor was executed.
 
URI String Parsing and URI String Generation
bool Parse (const char *first, const char *last) noexcept
 Parses a URI string. More...
 
bool Parse (const char *str) noexcept
 A parameter omitted version of the above function which receives a null terminated string.
 
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
 A template overload of the above function.
 

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
 A parameter omitted version of the above function which receives a null terminated string.
 
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
 A parameter omitted version of the above function which receives a null terminated string.
 
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
 A parameter omitted version of the above function which receives a null terminated string.
 
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
 A parameter omitted version of the above function which receives a null terminated string.
 
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
 A parameter omitted version of the above function which receives a null terminated string.
 
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
 A parameter omitted version of the above function which receives a null terminated string.
 
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.
 
Decoding
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
 A template overload of the above function.
 
static errno_t DecodeUriComponent (size_t *written, char *buf, size_t n, const char *s) noexcept
 A parameter omitted version of the above function which receives a null terminated string.
 
template<size_t N>
static errno_t DecodeUriComponent (size_t *written, char(&buf)[N], const char *first, const char *last) noexcept
 A template overload of the above function.
 
static std::pair< errno_t, size_t > DecodeUriComponent (char *buf, size_t n, const char *first, const char *last) noexcept
 Decodes a percent-encoded string. Returns a pair of the error value and the number of bytes in the decoded string (not including the null character).
 
template<size_t N>
static std::pair< errno_t, size_t > DecodeUriComponent (char(&buf)[N], const char *first, const char *last) noexcept
 A template overload of the above function.
 
static std::pair< errno_t, size_t > DecodeUriComponent (char *buf, size_t n, const char *s) noexcept
 A parameter omitted version of the above function which receives a null terminated string.
 
template<size_t N>
static std::pair< errno_t, size_t > DecodeUriComponent (char(&buf)[N], const char *s) noexcept
 A template overload of the above function.
 
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
 A template overload of the above function.
 
static std::pair< errno_t, size_t > DecodePath (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 ('/'). More...
 
template<size_t N>
static std::pair< errno_t, size_t > DecodePath (char(&buf)[N], const char *s) noexcept
 A parameter omitted version of the above function which passes settings as the default value.
 
Encoding
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
 A template overload of the above function.
 
static errno_t EncodeUriComponent (size_t *written, char *buf, size_t n, const char *s, bool fragment_mode) noexcept
 
template<size_t N>
static errno_t EncodeUriComponent (size_t *written, char(&buf)[N], const char *s, bool fragment_mode) noexcept
 A template overload of the above function.
 
static std::pair< errno_t, size_t > EncodeUriComponent (char *buf, size_t n, const char *first, const char *last, bool fragment_mode) noexcept
 Percent-encodes a string. Returns a pair of the error value and the number of bytes in the encoded string (not including the null character).
 
template<size_t N>
static std::pair< errno_t, size_t > EncodeUriComponent (char(&buf)[N], const char *first, const char *last, bool fragment_mode) noexcept
 A template overload of the above function.
 
static std::pair< errno_t, size_t > EncodeUriComponent (char *buf, size_t n, const char *s, bool fragment_mode)
 
template<size_t N>
static std::pair< errno_t, size_t > EncodeUriComponent (char(&buf)[N], const char *s, bool fragment_mode)
 A template overload of the above function.
 
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
 A template overload of the above function.
 
static std::pair< errno_t, size_t > EncodePath (char *buf, size_t n, const char *s) noexcept
 test
 
template<size_t N>
static std::pair< errno_t, size_t > EncodePath (char(&buf)[N], const char *s) noexcept
 A template overload of the above function.
 

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.
Sample code is provided below.
bool result = uri.Parse("http://www.example.com/dir/index.html?query=test#part1");
SUCCEED_IF(!!result);
nlib_printf("scheme: %s\n", uri.GetScheme());
nlib_printf("host: %s\n", uri.GetHost());
nlib_printf("path: %s\n", uri.GetPath());
nlib_printf("query: %s\n", uri.GetQuery());
nlib_printf("fragment: %s\n", uri.GetFragment());
/*
Output:
scheme: http
host: www.example.com
path: /dir/index.html
query: query=test
fragment: 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 285 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()

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.

◆ DecodePath()

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

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 ('/').

Parameters
[in,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.
Returns
A pair of the error value and the number of bytes in the decoded string (not including the null character).

Definition at line 133 of file Uri.h.

◆ DecodeUriComponent()

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. To decode a path within a URI, use the DecodePath() function.
Sample code is provided below.
char buf[256];
size_t written;
nlib_ns::Uri::DecodeUriComponent(&written, buf, "https://ja.wikipedia.org/wiki/%E3%83%A1%E3%82%A4%E3%83%B3%E3%83%9A%E3%83%BC%E3%82%B8");
nlib_printf("%s\n", buf);
/*
Output:
https://ja.wikipedia.org/wiki/メインページ
*/

◆ EncodeUriComponent() [1/3]

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_modetrue if encoded characters are written into a fragment part.
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/3]

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

A parameter omitted version of the above function which receives a null terminated string.

Definition at line 150 of file Uri.h.

◆ EncodeUriComponent() [3/3]

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

A parameter omitted version of the above function which receives a null terminated string.

Definition at line 173 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.
Description
Be aware of corner cases and special cases. Sample code is provided below.
nlib_printf("IsEmailAddress(foo@example.com): %d\n",
nlib_ns::Uri::IsEmailAddress("foo@example.com"));
nlib_printf("IsEmailAddress(foo.bar@example.com): %d\n",
nlib_ns::Uri::IsEmailAddress("foo.bar@example.com"));
nlib_printf("IsEmailAddress(.foo.@example.com): %d\n",
nlib_ns::Uri::IsEmailAddress(".foo.@example.com"));
nlib_printf("IsEmailAddress(\".(foo:).\"@example.com): %d\n",
nlib_ns::Uri::IsEmailAddress("\".(foo:).\"@example.com"));
/*
Output:
IsEmailAddress(foo@example.com): 1
IsEmailAddress(foo.bar@example.com): 1
IsEmailAddress(.foo.@example.com): 0
IsEmailAddress(".(foo:)."@example.com): 1
*/
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.
Description
Be aware of detailed rules that, for example, prohibit underscores from being used and a hyphen from being placed at the beginning or end of a "label." Sample code is provided below.
nlib_printf("IsHostName(\"www.example.com\"): %d\n",
nlib_ns::Uri::IsHostName("www.example.com"));
nlib_printf("IsHostName(\"www.-example-.com\"): %d\n",
nlib_ns::Uri::IsHostName("www.-example-.com"));
nlib_printf("IsHostName(\"www.example-host.com\"): %d\n",
nlib_ns::Uri::IsHostName("www.example-host.com"));
nlib_printf("IsHostName(\"www.example_host.com\"): %d\n",
nlib_ns::Uri::IsHostName("www.example_host.com"));
nlib_printf("IsHostName(\"www.example..com\"): %d\n",
nlib_ns::Uri::IsHostName("www.example..com"));
/*
Output:
IsHostName("www.example.com"): 1
IsHostName("www.-example-.com"): 0
IsHostName("www.example-host.com"): 1
IsHostName("www.example_host.com"): 0
IsHostName("www.example..com"): 0
*/
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: