nlib
nn::nlib::Uri Class Referencefinal

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

#include "nn/nlib/Uri.h"

Public Member Functions

 Uri () noexcept
 Instantiates the object with default parameters (default constructor). Initializes an object.
 
bool Parse (const char *str) noexcept
 Parses a URI string. More...
 
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 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...
 
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...
 
void Reset () noexcept
 Initializes (resets) an object.
 

Static Public Member Functions

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...
 
static errno_t DecodeUriComponent (size_t *written, char *buf, size_t n, const char *s) noexcept
 Decodes a percent-encoded string. More...
 
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...
 
static errno_t EncodeUriComponent (size_t *written, char *buf, size_t n, const char *s, bool fragment_mode) noexcept
 Percent-encodes a string. More...
 
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 ('/').
 
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 DecodeUriComponent (size_t *written, char(&buf)[N], const char *s) noexcept
 Calls DecodeUriComponent(written, buf, N, s).
 
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).
 
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).
 
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).
 
template<size_t N>
static errno_t DecodePath (size_t *written, char(&buf)[N], const char *s) noexcept
 Calls DecodePath(written, buf, N, s) .
 
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 31 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 104 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 43 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 49 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.

◆ Parse()

nn::nlib::Uri::Parse ( const char *  str)
noexcept

Parses a URI string.

Parameters
[in]strThe URI string.
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 200 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: