1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
# URLs
{{i:Universal Resource Locator}}s, or {{i:URL}}s for short, are a standardized
way of representing a network resource,
defined in [RFC 1738](https://datatracker.ietf.org/doc/html/rfc1738),
and [RFC 3968](https://datatracker.ietf.org/doc/html/rfc3986).
In Scalability Protocols, this concept is extended, although it includes schemes
that are not part of the IETF standards.
## URL Structure
```c
typedef struct nng_url {
const char *u_scheme;
char *u_userinfo;
char *u_hostname;
uint16_t u_port;
char *u_path;
char *u_query;
char *u_fragment;
} nng_url;
```
### URL Fields
Applications may access individual fields, but must not free or
alter them, as the underlying memory is managed by the library.
Additionally applications must not depend on the size of this structure.
Obtain one using `nng_parse_url`.
The fields of an `nng_url` object are as follows:
- `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.
> [!NOTE]
> Other fields may also be present, but only those documented here are safe for application use.
## Format a URL
```c
int nng_url_sprintf(char *buf, size_t bufsz, const nng_url *url);
```
The {{i:`nng_url_sprintf`}} function formats the _url_ to the _buf_,
which must have `bufsz` bytes of free space associated with it.
This function returns the number of bytes formatted to _buf_, excludng
the terminating zero byte, or if _bufsz_ is too small, then it returns
the number of bytes that would have been formatted if there was sufficient
space. The semantics are similar to the `snprintf` function from C99.
> [!TIP]
> If _bufsz_ is 0, then _buf_ can be `NULL`, and the return value
> can be used to determine the amount of space to allocate for a dynamically
> sized buffer.
## Parse a URL
```c
int nng_url_parse(nng_url **urlp, const char *str);
```
The {{i:`nng_url_parse`}} function parses a URL string (in _str_),
and creates a dynamically allocated `nng_url`, returning it in _urlp_.
> [!IMPORTANT]
> Only [`nng_url_free`] should be used to deallocate `nng_url` objects.
## Clone a URL
```c
int nng_url_clone(nng_url **dup, nng_url *url);
```
The {{i:`nng_url_clone`}} function creates a copy of _url_, and returns it in _dup_.
## Destroy a URL
```c
void nng_url_free(nng_url *url);
```
The {{i:`nng_url_free`}} function destroy an `nng_url` object created with
either [`nng_url_parse`] or [`nng_url_free`].
This is the only correct way to destroy an [`nng_url`] object.
## See Also
More information about Universal Resource Locators can be found in
[RFC 3986](https://tools.ietf.org/html/rfc3986).
{{#include ../xref.md}}
|
