Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/ws_url_requirements.md

raw
1 STRING TOKENIZER Requirements
2 ================
3
4 ## Overview
5 The WS_URL provides functionality parse Websocket URLs.
6
7
8 ## Exposed API
9 ```C
10 typedef struct WS_URL_TAG* WS_URL_HANDLE;
11
12 extern WS_URL_HANDLE ws_url_create(const char* url);
13 extern int ws_url_is_secure(WS_URL_HANDLE url, bool* is_secure);
14 extern int ws_url_get_host(WS_URL_HANDLE url, const char** host, size_t* length);
15 extern int ws_url_get_port(WS_URL_HANDLE url, size_t* port);
16 extern int ws_url_get_path(WS_URL_HANDLE url, const char** path, size_t* length);
17 extern int ws_url_get_query(WS_URL_HANDLE url, const char** query, size_t* length);
18 extern void ws_url_destroy(WS_URL_HANDLE url);
19 ```
20
21
22 ### ws_url_create
23
24 ```c
25 extern WS_URL_HANDLE ws_url_create(const char* url);
26 ```
27
28 **SRS_WS_URL_09_001: [** If `url` is NULL the function shall fail and return NULL **]**
29
30 **SRS_WS_URL_09_002: [** Memory shall be allocated for an instance of WS_URL (aka `ws_url`) **]**
31
32 **SRS_WS_URL_09_003: [** If `ws_url` failed to be allocated, the function shall return NULL **]**
33
34 **SRS_WS_URL_09_024: [** `url` shall be copied into `ws_url->url` **]**
35
36 **SRS_WS_URL_09_025: [** If `url` fails to be copied, the function shall free `ws_url` and return NULL **]**
37
38
39 #### Parsing starts
40
41 **SRS_WS_URL_09_004: [** If `url` starts with "ws://" (`protocol`), `ws_url->is_secure` shall be set to false **]**
42
43 **SRS_WS_URL_09_005: [** If `url` starts with "wss://" (`protocol`), `ws_url->is_secure` shall be set to true **]**
44
45 **SRS_WS_URL_09_024: [** If `protocol` cannot be identified in `url`, the function shall fail and return NULL **]**
46
47 **SRS_WS_URL_09_006: [** The pointer to the token starting right after `protocol` (in the `url` string) shall be stored in `ws_url->host` **]**
48
49 **SRS_WS_URL_09_007: [** If `ws_url->host` ends up being NULL, the function shall fail and return NULL **]**
50
51 **SRS_WS_URL_09_008: [** The length from `ws_url->host` up to the first occurrence of either ":" (`port_delimiter`), "/" (`path_delimiter`), "?" (`query_delimiter`) or `\0` shall be stored in `ws_url->host_length` **]**
52
53 **SRS_WS_URL_09_009: [** If `ws_url->host_length` ends up being zero, the function shall fail and return NULL **]**
54
55 **SRS_WS_URL_09_010: [** If after `ws_url->host` the `port_delimiter` occurs (not preceeded by `path_delimiter` or `query_delimiter`) the number that follows shall be parsed and stored in `ws_url->port` **]**
56
57 **SRS_WS_URL_09_011: [** If the port number fails to be parsed, the function shall fail and return NULL **]**
58
59 **SRS_WS_URL_09_012: [** If after `ws_url->host` or the port number the `path_delimiter` occurs (not preceeded by `query_delimiter`) the following pointer address shall be stored in `ws_url->path` **]**
60
61 **SRS_WS_URL_09_013: [** If the path component is present and `ws_url->path` ends up being NULL, the function shall fail and return NULL **]**
62
63 **SRS_WS_URL_09_014: [** The length from `ws_url->path` up to the first occurrence of either `query_delimiter` or `\0` shall be stored in `ws_url->path_length` **]**
64
65 **SRS_WS_URL_09_015: [** If the path component is present and `ws_url->path_length` ends up being zero, the function shall fail and return NULL **]**
66
67 **SRS_WS_URL_09_016: [** Next if the `query_delimiter` occurs the following pointer address shall be stored in `ws_url->query` **]**
68
69 **SRS_WS_URL_09_017: [** If the query component is present and `ws_url->query` ends up being NULL, the function shall fail and return NULL **]**
70
71 **SRS_WS_URL_09_018: [** The length from `ws_url->query` up to `\0` shall be stored in `ws_url->query_length` **]**
72
73 **SRS_WS_URL_09_019: [** If the query component is present and `ws_url->query_length` ends up being zero, the function shall fail and return NULL **]**
74
75 **SRS_WS_URL_09_020: [** If any component cannot be parsed or is out of order, the function shall fail and return NULL **]**
76
77
78 #### Finally
79
80 **SRS_WS_URL_09_021: [** If any failure occurs, all memory allocated by the function shall be released before returning **]**
81
82
83 ### ws_url_destroy
84
85 ```c
86 extern void ws_url_destroy(WS_URL_HANDLE url);
87 ```
88
89 **SRS_WS_URL_09_022: [** If `url` is NULL, the function shall return without further action **]**
90
91 **SRS_WS_URL_09_023: [** Otherwise, the memory allocated for `url` shall released **]**
92
93
94 ### ws_url_is_secure
95 ```c
96 extern int ws_url_is_secure(WS_URL_HANDLE url, bool* is_secure);
97 ```
98
99 **SRS_WS_URL_09_026: [** If `url` is NULL, the function shall return a non-zero value (failure) **]**
100
101 **SRS_WS_URL_09_027: [** Otherwize the function shall set `is_secure` as `url->is_secure` **]**
102
103 **SRS_WS_URL_09_028: [** If no errors occur function shall return zero (success) **]**
104
105
106 ### ws_url_get_host
107 ```c
108 extern int ws_url_get_host(WS_URL_HANDLE url, const char** host, size_t* length);
109 ```
110
111 **SRS_WS_URL_09_029: [** If `url` or `host` or `length` are NULL, the function shall return a non-zero value (failure) **]**
112
113 **SRS_WS_URL_09_030: [** Otherwize the function shall set `host` to `url->host` and `length` to `url->host_length` **]**
114
115 **SRS_WS_URL_09_031: [** If no errors occur function shall return zero (success) **]**
116
117
118 ### ws_url_get_path
119 ```c
120 extern int ws_url_get_path(WS_URL_HANDLE url, const char** path, size_t* length);
121 ```
122
123 **SRS_WS_URL_09_032: [** If `url` or `path` or `length` are NULL, the function shall return a non-zero value (failure) **]**
124
125 **SRS_WS_URL_09_033: [** Otherwize the function shall set `path` to `url->path` and `length` to `url->path_length` **]**
126
127 **SRS_WS_URL_09_034: [** If no errors occur function shall return zero (success) **]**
128
129
130 ### ws_url_get_query
131 ```c
132 extern int ws_url_get_query(WS_URL_HANDLE url, const char** query, size_t* length);
133 ```
134
135 **SRS_WS_URL_09_035: [** If `url` or `query` or `length` are NULL, the function shall return a non-zero value (failure) **]**
136
137 **SRS_WS_URL_09_036: [** Otherwize the function shall set `query` to `url->query` and `length` to `url->query_length` **]**
138
139 **SRS_WS_URL_09_037: [** If no errors occur function shall return zero (success) **]**
140
141
142 ### ws_url_get_port
143 ```c
144 extern int ws_url_get_port(WS_URL_HANDLE url, size_t* port);
145 ```
146
147 **SRS_WS_URL_09_038: [** If `url` or `port` are NULL, the function shall return a non-zero value (failure) **]**
148
149 **SRS_WS_URL_09_039: [** Otherwize the function shall set `port` as `url->port` **]**
150
151 **SRS_WS_URL_09_040: [** If no errors occur function shall return zero (success) **]**