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...
 
errno_t ComposeString (OutputStream *os) const noexcept
 Writes a URI string. 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 (InputStream *is, OutputStream *os) noexcept
 Decodes a percent-encoded string. More...
 
static errno_t EncodeUriComponent (InputStream *is, OutputStream *os, bool fragment_mode=false) noexcept
 Percent-encodes a 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 *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 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 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.
For details, see RFC 3986 (https://www.ietf.org/rfc/rfc3986.txt).
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"
Examples:
misc/uri/uri.cpp.

Definition at line 18 of file Uri.h.

Member Function Documentation

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.
nn::nlib::Uri::ComposeString ( OutputStream os) const
noexcept

Writes a URI string.

Parameters
[in]osThe output stream to which to write the URI string.
Returns
Returns 0 if successful.
Description
  • EINVAL: os was NULL.
  • EIO: There was an error with the stream.
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.
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 85 of file Uri.h.

nn::nlib::Uri::DecodeUriComponent ( InputStream is,
OutputStream os 
)
staticnoexcept

Decodes a percent-encoded string.

Parameters
[in]isThe stream from which to get the percent-encoded string.
[in]osThe stream to store the decoded string to.
Returns
Returns 0 on success. All other values are an error.
Description
Decodes all percent-encoded characters.
Any value other than 0 returned by the function indicates an error.
  • EINVAL: is or os is NULL.
  • EIO: An error was generated by is or os.
  • EILSEQ: A character was detected that is invalid for a URI.
nn::nlib::Uri::DecodeUriComponent ( size_t *  written,
char *  buf,
size_t  n,
const char *  s 
)
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]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.
nn::nlib::Uri::EncodeUriComponent ( InputStream is,
OutputStream os,
bool  fragment_mode = false 
)
staticnoexcept

Percent-encodes a string.

Parameters
[in]isThe stream from which to get the string to encode.
[in]osThe stream to store the decoded string to.
[in]fragment_modeCustomization of the characters to encode.
Returns
Returns 0 on success. All other values are an error.
Description
If fragment_mode is set to false, the characters that are percent-encoded excludes those that belong to unreserved(ALPHA / DIGIT / "-" / "." / "_" / "~") in RFC 3986.
If fragment_mode is true, the characters that are percent-encoded exclude those that belong to unreserved described in RFC 3986 and the symbols : @ ! $ & ' ( ) * + , ; = / and ?.
Any value other than 0 returned by the function indicates an error.
  • EINVAL: is or os is NULL.
  • EIO: An error was generated by is or os.
nn::nlib::Uri::EncodeUriComponent ( size_t *  written,
char *  buf,
size_t  n,
const char *  s,
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]sThe string to decode.
[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.
nn::nlib::Uri::GetFragment ( ) const
inlinenoexcept

Gets a fragment string.

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

Definition at line 106 of file Uri.h.

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

Gets the hostname.

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

Definition at line 98 of file Uri.h.

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

Gets a path.

Returns
The path string.

Definition at line 102 of file Uri.h.

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

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.

Definition at line 100 of file Uri.h.

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

Gets a query string.

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

Definition at line 104 of file Uri.h.

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

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).

Definition at line 94 of file Uri.h.

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

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

Returns
A string of user-specific information.

Definition at line 96 of file Uri.h.

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.
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: