diff options
Diffstat (limited to 'docs/ref/api')
| -rw-r--r-- | docs/ref/api/url.md | 52 |
1 files changed, 38 insertions, 14 deletions
diff --git a/docs/ref/api/url.md b/docs/ref/api/url.md index db9f3be2..62cf66fd 100644 --- a/docs/ref/api/url.md +++ b/docs/ref/api/url.md @@ -20,28 +20,52 @@ typedef struct nng_url { char *u_query; char *u_fragment; } nng_url; + +const char *nng_url_scheme(const nng_url *url); +const char *nng_url_userinfo(const nng_url *url); +const char *nng_url_hostname(const nng_url *url); +uint16_t nng_url_port(const nng_url *url); +const char *nng_url_path(const nng_url *url); +const char *nng_url_query(const nng_url *url); +const char *nng_url_fragment(const nng_url *url): ``` ### URL Fields -Applications may access individual fields, but must not free or -alter them, as the underlying memory is managed by the library. +The {{i:`nng_url_scheme`}} function returns the scheme, +without any colons or slashes. Values are lower case +strings, like "http" or "inproc" or "tls+tcp4". + +The {{i:`nng_url_userinfo`}} function returns a string corresponding +to the user component of a URL (the part before any `@` sign) if such +a component is present, otherwise it returns `NULL`. + +The {{i:`nng_url_hostname`}} function returns a hostname (which might +actually be an IP address) from the URL, if the URL corresponds to a scheme +that uses hostnames (like "http" or "tcp"). If the URL does not (for example +"inproc" or "ipc" URLs) then it returns `NULL`. -Additionally applications must not depend on the size of this structure. -Obtain one using `nng_parse_url`. +The {{i:`nng_url_port`}} function returns the TCP or UDP port number if the URL +corresponds to a protocol based on TCP or UDP. It returns zero otherwise. +Note that the port number might not have been explicitly specified in the URL. +For example, the port number associated with "http://www.example.com" is 80, +which is the standard port number for HTTP. + +> [!TIP] +> The port number returned by this is in the native machine byte order. +> Be careful when using this with other network-oriented APIs. -The fields of an `nng_url` object are as follows: +The {{i:`nng_url_path`}} function returns the path component of the URL. +This will always be non-`NULL`, but it may be empty. -- `u_scheme`: The URL scheme, such as "http" or "inproc". Always lower case. This will never be `NULL`. -- `u_userinfo`: This username and password if supplied in the URL string. Will be `NULL` when not present. -- `u_hostname`: The name of the host, and may be the empty string in some cases. -- `u_port`: The port. May be zero if irrelevant or not specified. -- `u_path`: The path, typically used with HTTP or WebSockets. Will be empty string if not specified. -- `u_query`: The query info (typically following `?` in the URL.) Will be `NULL` if not present. -- `u_fragment`: This is used for specifying an anchor, the part after `#` in a URL. Will be `NULL` if not present. +The {{i:`nng_url_query`}} and {{i:`nng_url_fragment`}} functions return +the query-information (the part following a '?') and fragment +(the part following a '#') if those components are present, or `NULL` +if they are not. The returned string will not include the leading '?' or '#' +characters. -> [!NOTE] -> Other fields may also be present, but only those documented here are safe for application use. +Note that any strings returned by these functions are only valid until +_url_ is freed with [`nng_url_free`]. ## Format a URL |