| 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) **]** |