Debian Codegraph @

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

raw
1 # wsio requirements
2
3 ## Overview
4
5 `wsio` is module that implements a concrete IO that implements the WebSockets protocol by using the uws library.
6
7 ## References
8
9 RFC6455 - The WebSocket Protocol.
10
11 ## Exposed API
12
13 ```c
14 typedef struct WSIO_CONFIG_TAG
15 {
16 const char* hostname;
17 int port;
18 const char* resource_name;
19 const char* protocol;
20 bool use_ssl;
21 } WSIO_CONFIG;
22
23 extern const IO_INTERFACE_DESCRIPTION* wsio_get_interface_description(void);
24 ```
25
26 ### wsio_create
27
28 ```c
29 CONCRETE_IO_HANDLE wsio_create(void* io_create_parameters);
30 ```
31
32 `wsio_create` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_create` member.
33
34 **SRS_WSIO_01_001: [** `wsio_create` shall create an instance of wsio and return a non-NULL handle to it. **]**
35
36 **SRS_WSIO_01_065: [** If the argument `io_create_parameters` is NULL then `wsio_create` shall return NULL. **]**
37
38 **SRS_WSIO_01_066: [** `io_create_parameters` shall be used as a `WSIO_CONFIG*` . **]**
39
40 **SRS_WSIO_01_067: [** If any of the members `hostname`, `resource_name` or `protocol` is NULL in `WSIO_CONFIG` then `wsio_create` shall return NULL. **]**
41
42 **SRS_WSIO_01_068: [** If allocating memory for the new wsio instance fails then `wsio_create` shall return NULL. **]**
43
44 **SRS_WSIO_01_070: [** The underlying uws instance shall be created by calling `uws_client_create_with_io`. **]**
45
46 **SRS_WSIO_01_071: [** The arguments for `uws_client_create_with_io` shall be: **]**
47
48 **SRS_WSIO_01_185: [** - `underlying_io_interface` shall be set to the `underlying_io_interface` field in the `io_create_parameters` passed to `wsio_create`. **]**
49
50 **SRS_WSIO_01_186: [** - `underlying_io_parameters` shall be set to the `underlying_io_parameters` field in the `io_create_parameters` passed to `wsio_create`. **]**
51
52 **SRS_WSIO_01_072: [** - `hostname` set to the `hostname` field in the `io_create_parameters` passed to `wsio_create`. **]**
53
54 **SRS_WSIO_01_130: [** - `port` set to the `port` field in the `io_create_parameters` passed to `wsio_create`. **]**
55
56 **SRS_WSIO_01_128: [** - `resource_name` set to the `resource_name` field in the `io_create_parameters` passed to `wsio_create`. **]**
57
58 **SRS_WSIO_01_129: [** - `protocols` shall be filled with only one structure, that shall have the `protocol` set to the value of the `protocol` field in the `io_create_parameters` passed to `wsio_create`. **]**
59
60 **SRS_WSIO_01_075: [** If `uws_client_create_with_io` fails, then `wsio_create` shall fail and return NULL. **]**
61
62 **SRS_WSIO_01_076: [** `wsio_create` shall create a pending send IO list that is to be used to queue send packets by calling `singlylinkedlist_create`. **]**
63
64 **SRS_WSIO_01_077: [** If `singlylinkedlist_create` fails then `wsio_create` shall fail and return NULL. **]**
65
66 ### wsio_destroy
67
68 ```c
69 void wsio_destroy(CONCRETE_IO_HANDLE ws_io);
70 ```
71
72 `wsio_destroy` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_destroy` member.
73
74 **SRS_WSIO_01_078: [** `wsio_destroy` shall free all resources associated with the wsio instance. **]**
75
76 **SRS_WSIO_01_079: [** If `ws_io` is NULL, `wsio_destroy` shall do nothing. **]**
77
78 **SRS_WSIO_01_080: [** `wsio_destroy` shall destroy the uws instance created in `wsio_create` by calling `uws_client_destroy`. **]**
79
80 **SRS_WSIO_01_081: [** `wsio_destroy` shall free the list used to track the pending send IOs by calling `singlylinkedlist_destroy`. **]**
81
82 ### wsio_open
83
84 ```c
85 int wsio_open(CONCRETE_IO_HANDLE ws_io, ON_IO_OPEN_COMPLETE on_io_open_complete, void* on_io_open_complete_context, ON_BYTES_RECEIVED on_bytes_received, void* on_bytes_received_context, ON_IO_ERROR on_io_error, void* on_io_error_context);
86 ```
87
88 `wsio_open` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_open` member.
89
90 **SRS_WSIO_01_082: [** `wsio_open` shall open the underlying uws instance by calling `uws_client_open_async` and providing the uws handle created in `wsio_create` as argument. **]**
91
92 **SRS_WSIO_01_083: [** On success, `wsio_open` shall return 0. **]**
93
94 **SRS_WSIO_01_132: [** If any of the arguments `ws_io`, `on_io_open_complete`, `on_bytes_received`, `on_io_error` is NULL, `wsio_open` shall fail and return a non-zero value. **]**
95
96 **SRS_WSIO_01_165: [** `wsio_open` when CLOSING shall fail and return a non-zero value. **]**
97
98 **SRS_WSIO_01_084: [** If opening the underlying uws instance fails then `wsio_open` shall fail and return a non-zero value. **]**
99
100 **SRS_WSIO_01_131: [** `wsio_open` when already OPEN or OPENING shall fail and return a non-zero value. **]**
101
102 ### wsio_close
103
104 ```c
105 int wsio_close(CONCRETE_IO_HANDLE ws_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
106 ```
107
108 `wsio_close` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_close` member.
109
110 **SRS_WSIO_01_085: [** `wsio_close` shall close the websockets IO if an open action is either pending or has completed successfully (if the IO is open). **]**
111
112 **SRS_WSIO_01_133: [** On success `wsio_close` shall return 0. **]**
113
114 **SRS_WSIO_01_086: [** if `ws_io` is NULL, `wsio_close` shall return a non-zero value. **]**
115
116 **SRS_WSIO_01_087: [** `wsio_close` shall call `uws_client_close_async` while passing as argument the IO handle created in `wsio_create`. **]**
117
118 **SRS_WSIO_01_164: [** When `uws_client_close_async` fails, `wsio_close` shall call the `on_io_close_complete` callback and continue. **]**
119
120 **SRS_WSIO_01_088: [** `wsio_close` when no open action has been issued shall fail and return a non-zero value. **]**
121
122 **SRS_WSIO_01_089: [** `wsio_close` after a `wsio_close` shall fail and return a non-zero value. **]**
123
124 **SRS_WSIO_01_090: [** The argument `on_io_close_complete` shall be optional, if NULL is passed by the caller then no close complete callback shall be triggered. **]**
125
126 **SRS_WSIO_01_091: [** `wsio_close` shall obtain all the pending IO items by repetitively querying for the head of the pending IO list and freeing that head item. **]**
127
128 **SRS_WSIO_01_092: [** Obtaining the head of the pending IO list shall be done by calling `singlylinkedlist_get_head_item`. **]**
129
130 **SRS_WSIO_01_093: [** For each pending item the send complete callback shall be called with `IO_SEND_CANCELLED`.**\]**
131
132 ### wsio_send
133
134 ```c
135 int wsio_send(CONCRETE_IO_HANDLE ws_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
136 ```
137
138 `wsio_send` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_send` member.
139
140 **SRS_WSIO_01_095: [** `wsio_send` shall call `uws_client_send_frame_async`, passing the `buffer` and `size` arguments as they are: **]**
141
142 **SRS_WSIO_01_098: [** On success, `wsio_send` shall return 0. **]**
143
144 **SRS_WSIO_01_100: [** If any of the arguments `ws_io` or `buffer` are NULL, `wsio_send` shall fail and return a non-zero value. **]**
145
146 **SRS_WSIO_01_099: [** If the wsio is not OPEN (open has not been called or is still in progress) then `wsio_send` shall fail and return a non-zero value. **]**
147
148 **SRS_WSIO_01_102: [** An entry shall be queued in the singly linked list by calling `singlylinkedlist_add`. **]**
149
150 **SRS_WSIO_01_103: [** The entry shall contain the `on_send_complete` callback and its context. **]**
151
152 **SRS_WSIO_01_096: [** The frame type used shall be `WS_FRAME_TYPE_BINARY`. **]**
153
154 **SRS_WSIO_01_097: [** The `is_final` argument shall be set to true. **]**
155
156 **SRS_WSIO_01_101: [** If `size` is zero then `wsio_send` shall fail and return a non-zero value. **]**
157
158 **SRS_WSIO_01_134: [** If allocating memory for the pending IO data fails, `wsio_send` shall fail and return a non-zero value. **]**
159
160 **SRS_WSIO_01_104: [** If `singlylinkedlist_add` fails, `wsio_send` shall fail and return a non-zero value. **]**
161
162 **SRS_WSIO_01_105: [** The argument `on_send_complete` shall be optional, if NULL is passed by the caller then no send complete callback shall be triggered. **]**
163
164 ### wsio_dowork
165
166 ```c
167 void wsio_dowork(CONCRETE_IO_HANDLE ws_io);
168 ```
169
170 `wsio_dowork` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_dowork` member.
171
172 **SRS_WSIO_01_106: [** `wsio_dowork` shall call `uws_client_dowork` with the uws handle created in `wsio_create`. **]**
173
174 **SRS_WSIO_01_107: [** If the `ws_io` argument is NULL, `wsio_dowork` shall do nothing. **]**
175
176 **SRS_WSIO_01_108: [** If the IO is not yet open, `wsio_dowork` shall do nothing. **]**
177
178 ### wsio_setoption
179
180 ```c
181 int wsio_setoption(CONCRETE_IO_HANDLE ws_io, const char* option_name, const void* value);
182 ```
183
184 `wsio_setoption` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_setoption` member.
185
186 **SRS_WSIO_01_109: [** If any of the arguments `ws_io` or `option_name` is NULL `wsio_setoption` shall return a non-zero value. **]**
187
188 **SRS_WSIO_01_183: [** If the option name is `WSIOOptions` then `wsio_setoption` shall call `OptionHandler_FeedOptions` and pass to it the underlying IO handle and the `value` argument. **]**
189
190 **SRS_WSIO_01_184: [** If `OptionHandler_FeedOptions` fails, `wsio_setoption` shall fail and return a non-zero value. **]**
191
192 **SRS_WSIO_01_156: [** Otherwise all options shall be passed as they are to uws by calling `uws_client_set_option`. **]**
193
194 **SRS_WSIO_01_158: [** On success, `wsio_setoption` shall return 0. **]**
195
196 **SRS_WSIO_01_157: [** If `uws_client_set_option` fails, `wsio_setoption` shall fail and return a non-zero value. **]**
197
198 ### wsio_retrieveoptions
199
200 ```c
201 OPTIONHANDLER_HANDLE wsio_retrieveoptions(CONCRETE_IO_HANDLE handle)
202 ```
203
204 `wsio_retrieveoptions` is the implementation provided via `wsio_get_interface_description` for the `concrete_io_retrieveoptions` member.
205
206 **SRS_WSIO_01_118: [** If parameter `handle` is `NULL` then `wsio_retrieveoptions` shall fail and return NULL. **]**
207
208 **SRS_WSIO_01_119: [** `wsio_retrieveoptions` shall call `OptionHandler_Create` to produce an `OPTIONHANDLER_HANDLE` and on success return the new `OPTIONHANDLER_HANDLE` handle. **]**
209
210 **SRS_WSIO_01_120: [** If `OptionHandler_Create` fails then `wsio_retrieveoptions` shall fail and return NULL. **]**
211
212 **SRS_WSIO_01_178: [** `uws_client_retrieve_options` shall add to the option handler one option, whose name shall be `uWSCLientOptions` and the value shall be queried by calling `uws_client_retrieve_options`. **]**
213
214 **SRS_WSIO_01_179: [** When calling `uws_client_retrieve_options` the uws client handle shall be passed to it. **]**
215
216 **SRS_WSIO_01_180: [** If `uws_client_retrieve_options` fails, `uws_client_retrieve_options` shall fail and return NULL. **]**
217
218 **SRS_WSIO_01_181: [** Adding the option shall be done by calling `OptionHandler_AddOption`. **]**
219
220 **SRS_WSIO_01_182: [** If `OptionHandler_AddOption` fails, `uws_client_retrieve_options` shall fail and return NULL. **]**
221
222 ### wsio_clone_option
223
224 `wsio_clone_option` is the implementation provided to the option handler instance created as part of `wsio_retrieve_options`.
225
226 ```c
227 void* wsio_clone_option(const char* name, const void* value)
228 ```
229
230 **SRS_WSIO_01_171: [** `wsio_clone_option` called with `name` being `WSIOOptions` shall return the same value. **]**
231
232 **SRS_WSIO_01_173: [** `wsio_clone_option` called with any other option name than `WSIOOptions` shall return NULL. **]**
233
234 **SRS_WSIO_01_174: [** If `wsio_clone_option` is called with NULL `name` or `value` it shall return NULL. **]**
235
236 ### wsio_destroy_option
237
238 `wsio_destroy_option` is the implementation provided to the option handler instance created as part of `wsio_retrieve_options`.
239
240 ```c
241 void wsio_destroy_option(const char* name, const void* value)
242 ```
243
244 **SRS_WSIO_01_175: [** `wsio_destroy_option` called with the option `name` being `WSIOOptions` shall destroy the value by calling `OptionHandler_Destroy`. **]**
245
246 **SRS_WSIO_01_176: [** If `wsio_destroy_option` is called with any other `name` it shall do nothing. **]**
247
248 **SRS_WSIO_01_177: [** If `wsio_destroy_option` is called with NULL `name` or `value` it shall do nothing. **]**
249
250 ### wsio_get_interface_description
251
252 ```c
253 const IO_INTERFACE_DESCRIPTION* wsio_get_interface_description(void);
254 ```
255
256 **SRS_WSIO_01_064: [** wsio_get_interface_description shall return a pointer to an IO_INTERFACE_DESCRIPTION structure that contains pointers to the functions: wsio_retrieveoptions, wsio_create, wsio_destroy, wsio_open, wsio_close, wsio_send and wsio_dowork. **]**
257
258 ### on_underlying_ws_error
259
260 **SRS_WSIO_01_121: [** When `on_underlying_ws_error` is called while the IO is OPEN the wsio instance shall be set to ERROR and an error shall be indicated via the `on_io_error` callback passed to `wsio_open`. **]**
261
262 **SRS_WSIO_01_123: [** When calling `on_io_error`, the `on_io_error_context` argument given in `wsio_open` shall be passed to the callback `on_io_error`. **]**
263
264 **SRS_WSIO_01_122: [** When `on_underlying_ws_error` is called while the IO is OPENING, the `on_io_open_complete` callback passed to `wsio_open` shall be called with `IO_OPEN_ERROR`. **]**
265
266 **SRS_WSIO_01_135: [** When `on_underlying_ws_error` is called with a NULL context, it shall do nothing. **]**
267
268 ### on_underlying_ws_frame_received
269
270 **SRS_WSIO_01_124: [** When `on_underlying_ws_frame_received` is called the bytes in the frame shall be indicated by calling the `on_bytes_received` callback passed to `wsio_open`. **]**
271
272 **SRS_WSIO_01_125: [** When calling `on_bytes_received`, the `on_bytes_received_context` argument given in `wsio_open` shall be passed to the callback `on_bytes_received`. **]**
273
274 **SRS_WSIO_01_126: [** If `on_underlying_ws_frame_received` is called while the IO is in any state other than OPEN, it shall do nothing. **]**
275
276 **SRS_WSIO_01_150: [** If `on_underlying_ws_frame_received` is called with NULL context it shall do nothing. **]**
277
278 **SRS_WSIO_01_151: [** If the WebSocket frame type is not binary then an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
279
280 **SRS_WSIO_01_153: [** When `on_underlying_ws_frame_received` is called with zero `size`, no bytes shall be indicated up as received. **]**
281
282 **SRS_WSIO_01_154: [** When `on_underlying_ws_frame_received` is called with a positive `size` and a NULL `buffer`, an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
283
284 **SRS_WSIO_01_152: [** When calling `on_io_error`, the `on_io_error_context` argument given in `wsio_open` shall be passed to the callback `on_io_error`. **]**
285
286 ### on_underlying_ws_open_complete
287
288 **SRS_WSIO_01_136: [** When `on_underlying_ws_open_complete` is called with `WS_OPEN_OK` while the IO is opening, the callback `on_io_open_complete` shall be called with `IO_OPEN_OK`. **]**
289
290 **SRS_WSIO_01_149: [** When `on_underlying_ws_open_complete` is called with `WS_OPEN_CANCELLED` while the IO is opening, the callback `on_io_open_complete` shall be called with `IO_OPEN_CANCELLED`. **]**
291
292 **SRS_WSIO_01_137: [** When `on_underlying_ws_open_complete` is called with any other error code while the IO is opening, the callback `on_io_open_complete` shall be called with `IO_OPEN_ERROR`. **]**
293
294 **SRS_WSIO_01_138: [** When `on_underlying_ws_open_complete` is called with a NULL context, it shall do nothing. **]**
295
296 **SRS_WSIO_01_139: [** When `on_underlying_ws_open_complete` is called while in OPEN state it shall indicate an error by calling the `on_io_error` callback passed to `wsio_open` and switch to the ERROR state. **]**
297
298 **SRS_WSIO_01_141: [** When `on_underlying_ws_open_complete` is called while in the ERROR state it shall indicate an error by calling the `on_io_error` callback passed to `wsio_open`. **]**
299
300 **SRS_WSIO_01_140: [** When calling `on_io_error`, the `on_io_error_context` argument given in `wsio_open` shall be passed to the callback `on_io_error`. **]**
301
302 **SRS_WSIO_01_142: [** When `on_underlying_ws_open_complete` is called while in the CLOSING state an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
303
304 ### on_underlying_ws_send_frame_complete
305
306 **SRS_WSIO_01_143: [** When `on_underlying_ws_send_frame_complete` is called after sending a WebSocket frame, the pending IO shall be removed from the list. **]**
307
308 **SRS_WSIO_01_145: [** Removing it from the list shall be done by calling `singlylinkedlist_remove`. **]**
309
310 **SRS_WSIO_01_144: [** Also the pending IO data shall be freed. **]**
311
312 **SRS_WSIO_01_146: [** When `on_underlying_ws_send_frame_complete` is called with `WS_SEND_OK`, the callback `on_send_complete` shall be called with `IO_SEND_OK`. **]**
313
314 **SRS_WSIO_01_147: [** When `on_underlying_ws_send_frame_complete` is called with `WS_SEND_CANCELLED`, the callback `on_send_complete` shall be called with `IO_SEND_CANCELLED`. **]**
315
316 **SRS_WSIO_01_148: [** When `on_underlying_ws_send_frame_complete` is called with any other error code, the callback `on_send_complete` shall be called with `IO_SEND_ERROR`. **]**
317
318 **SRS_WSIO_01_155: [** When `on_underlying_ws_send_frame_complete` is called with a NULL context it shall do nothing. **]**
319
320 ### on_underlying_ws_close_complete
321
322 **SRS_WSIO_01_159: [** When `on_underlying_ws_close_complete` while the IO is closing (after `wsio_close`), the close shall be indicated up by calling the `on_io_close_complete` callback passed to `wsio_close`. **]**
323
324 **SRS_WSIO_01_163: [** When `on_io_close_complete` is called, the context passed to `wsio_close` shall be passed as argument to `on_io_close_complete`. **]**
325
326 **SRS_WSIO_01_160: [** If NULL was passed to `wsio_close` no callback shall be called. **]**
327
328 **SRS_WSIO_01_161: [** If the context passed to `on_underlying_ws_close_complete` is NULL, `on_underlying_ws_close_complete` shall do nothing. **]**
329
330 ### on_underlying_ws_peer_closed
331
332 **SRS_WSIO_01_166: [** When `on_underlying_ws_peer_closed` and the state of the IO is OPEN an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
333
334 **SRS_WSIO_01_169: [** When `on_underlying_ws_peer_closed` and the state of the IO is CLOSING an error shall be indicated by calling the `on_io_error` callback passed to `wsio_open`. **]**
335
336 **SRS_WSIO_01_170: [** When `on_underlying_ws_peer_closed` and the state of the IO is OPENING an error shall be indicated by calling the `on_io_open_complete` callback passed to `wsio_open` with the error code `IO_OPEN_ERROR`. **]**
337
338 **SRS_WSIO_01_168: [** The `close_code`, `extra_data` and `extra_data_length` arguments shall be ignored. **]**
339
340 **SRS_WSIO_01_167: [** If `on_underlying_ws_peer_closed` is called with a NULL context it shall do nothing. **]**
341
342 **SRS_WSIO_07_001: [** When `on_underlying_ws_peer_closed` and the state of the IO is NOT_OPEN an error will be raised and the io_state will remain as NOT_OPEN **]**