Debian Codegraph @

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

raw
1 xio requirements
2 ================
3
4 ## Overview
5
6 xio is module that implements an IO interface, abstracting from upper layers the functionality of simply sending or receiving a sequence of bytes.
7
8 ## Exposed API
9
10 ```c
11 typedef struct XIO_INSTANCE_TAG* XIO_HANDLE;
12 typedef void* CONCRETE_IO_HANDLE;
13
14 typedef enum IO_SEND_RESULT_TAG
15 {
16 IO_SEND_OK,
17 IO_SEND_ERROR,
18 IO_SEND_CANCELLED
19 } IO_SEND_RESULT;
20
21 typedef enum IO_OPEN_RESULT_TAG
22 {
23 IO_OPEN_OK,
24 IO_OPEN_ERROR,
25 IO_OPEN_CANCELLED
26 } IO_OPEN_RESULT;
27
28 typedef void(*ON_BYTES_RECEIVED)(void* context, const unsigned char* buffer, size_t size);
29 typedef void(*ON_SEND_COMPLETE)(void* context, IO_SEND_RESULT send_result);
30 typedef void(*ON_IO_OPEN_COMPLETE)(void* context, IO_OPEN_RESULT open_result);
31 typedef void(*ON_IO_CLOSE_COMPLETE)(void* context);
32 typedef void(*ON_IO_ERROR)(void* context);
33
34 typedef OPTIONHANDLER_HANDLE (*IO_RETRIEVEOPTIONS)(CONCRETE_IO_HANDLE concrete_io);
35 typedef CONCRETE_IO_HANDLE(*IO_CREATE)(void* io_create_parameters);
36 typedef void(*IO_DESTROY)(CONCRETE_IO_HANDLE concrete_io);
37 typedef int(*IO_OPEN)(CONCRETE_IO_HANDLE concrete_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);
38 typedef int(*IO_CLOSE)(CONCRETE_IO_HANDLE concrete_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
39 typedef int(*IO_SEND)(CONCRETE_IO_HANDLE concrete_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
40 typedef void(*IO_DOWORK)(CONCRETE_IO_HANDLE concrete_io);
41 typedef int(*IO_SETOPTION)(CONCRETE_IO_HANDLE concrete_io, const char* optionName, const void* value);
42
43 typedef struct IO_INTERFACE_DESCRIPTION_TAG
44 {
45 IO_RETRIEVEOPTIONS concrete_io_retrieveoptions;
46 IO_CREATE concrete_io_create;
47 IO_DESTROY concrete_io_destroy;
48 IO_OPEN concrete_io_open;
49 IO_CLOSE concrete_io_close;
50 IO_SEND concrete_io_send;
51 IO_DOWORK concrete_io_dowork;
52 IO_SETOPTION concrete_io_setoption;
53 } IO_INTERFACE_DESCRIPTION;
54
55 extern XIO_HANDLE xio_create(const IO_INTERFACE_DESCRIPTION* io_interface_description, const void* io_create_parameters);
56 extern void xio_destroy(XIO_HANDLE xio);
57 extern int xio_open(XIO_HANDLE xio, 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);
58 extern int xio_close(XIO_HANDLE xio, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
59 extern int xio_send(XIO_HANDLE xio, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
60 extern void xio_dowork(XIO_HANDLE xio);
61 extern int xio_setoption(XIO_HANDLE xio, const char* optionName, const void* value);
62 ```
63
64 ### xio_create
65
66 ```c
67 extern XIO_HANDLE xio_create(const IO_INTERFACE_DESCRIPTION* io_interface_description, const void* io_create_parameters);
68 ```
69
70 **SRS_XIO_01_001: [** xio_create shall return on success a non-NULL handle to a new IO interface. **]**
71
72 **SRS_XIO_01_002: [** In order to instantiate the concrete IO implementation the function concrete_xio_create from the io_interface_description shall be called, passing the xio_create_parameters argument. **]**
73
74 **SRS_XIO_01_016: [** If the underlying concrete_xio_create call fails, xio_create shall return NULL. **]**
75
76 **SRS_XIO_01_003: [** If the argument io_interface_description is NULL, xio_create shall return NULL. **]**
77
78 **SRS_XIO_01_004: [** If any io_interface_description member is NULL, xio_create shall return NULL. **]**
79
80 **SRS_XIO_01_017: [** If allocating the memory needed for the IO interface fails then xio_create shall return NULL. **]**
81
82 ### xio_destroy
83
84 ```c
85 extern void xio_destroy(XIO_HANDLE xio);
86 ```
87
88 **SRS_XIO_01_005: [** xio_destroy shall free all resources associated with the IO handle. **]**
89
90 **SRS_XIO_01_006: [** xio_destroy shall also call the concrete_xio_destroy function that is member of the io_interface_description argument passed to xio_create, while passing as argument to concrete_xio_destroy the result of the underlying concrete_xio_create handle that was called as part of the xio_create call. **]**
91
92 **SRS_XIO_01_007: [** If the argument io is NULL, xio_destroy shall do nothing. **]**
93
94 ### xio_open
95
96 ```c
97 extern int xio_open(XIO_HANDLE xio, 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);
98 ```
99
100 **SRS_XIO_01_019: [** xio_open shall call the specific concrete_xio_open function specified in xio_create, passing callback function and context arguments for three events: open completed, bytes received, and IO error. **]**
101
102 **SRS_XIO_01_020: [** On success, xio_open shall return 0. **]**
103
104 **SRS_XIO_01_021: [** If handle is NULL, xio_open shall return a non-zero value. **]**
105
106 **SRS_XIO_01_022: [** If the underlying concrete_xio_open fails, xio_open shall return a non-zero value. **]**
107
108 ### xio_close
109
110 ```c
111 extern int xio_close(XIO_HANDLE xio, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
112 ```
113
114 **SRS_XIO_01_023: [** xio_close shall call the specific concrete_xio_close function specified in xio_create. **]**
115
116 **SRS_XIO_01_024: [** On success, xio_close shall return 0. **]**
117
118 **SRS_XIO_01_025: [** If the argument io is NULL, xio_close shall return a non-zero value. **]**
119
120 **SRS_XIO_01_026: [** If the underlying concrete_xio_close fails, xio_close shall return a non-zero value. **]**
121
122 ### xio_send
123
124 ```c
125 extern int xio_send(XIO_HANDLE xio, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
126 ```
127
128 **SRS_XIO_01_008: [** xio_send shall pass the sequence of bytes pointed to by buffer to the concrete IO implementation specified in xio_create, by calling the concrete_xio_send function while passing down the buffer and size arguments to it. **]**
129
130 **SRS_XIO_01_027: [** xio_send shall pass to the concrete_xio_send function the on_send_complete and callback_context arguments. **]**
131
132 **SRS_XIO_01_009: [** On success, xio_send shall return 0. **]**
133
134 **SRS_XIO_01_010: [** If the argument xio is NULL, xio_send shall return a non-zero value. **]**
135
136 **SRS_XIO_01_015: [** If the underlying concrete_xio_send fails, xio_send shall return a non-zero value. **]**
137
138 **SRS_XIO_01_011: [** No error check shall be performed on buffer and size. **]**
139
140 ### xio_dowork
141
142 ```c
143 extern void xio_dowork(XIO_HANDLE xio);
144 ```
145
146 **SRS_XIO_01_012: [** xio_dowork shall call the concrete IO implementation specified in xio_create, by calling the concrete_xio_dowork function. **]**
147
148 **SRS_XIO_01_013: [** On success, xio_send shall return 0. **]**
149
150 **SRS_XIO_01_014: [** If the underlying concrete_xio_dowork fails, xio_dowork shall return a non-zero value. **]**
151
152 **SRS_XIO_01_018: [** When the io argument is NULL, xio_dowork shall do nothing. **]**
153
154 ### xio_setoption
155
156 ```c
157 extern int xio_setoption(XIO_HANDLE xio, const char* optionName, const void* value);
158 ```
159
160 **SRS_XIO_03_028: [** xio_setoption shall pass the optionName and value to the concrete IO implementation specified in xio_create by invoking the concrete_xio_setoption function. **]**
161
162 **SRS_XIO_03_029: [** xio_setoption shall return 0 upon success. **]**
163
164 **SRS_XIO_03_030: [** If the xio argument or the optionName argument is NULL, xio_setoption shall return a non-zero value. **]**
165
166 **SRS_XIO_03_031: [** If the underlying concrete_xio_setoption fails, xio_setOption shall return a non-zero value. **]**
167
168 ### xio_retrieveoptions
169 ```
170 OPTIONHANDLER_HANDLE xio_retrieveoptions(XIO_HANDLE xio)
171 ```
172
173 **SRS_XIO_02_001: [** If argument `xio` is `NULL` then `xio_retrieveoptions` shall fail and return `NULL`. **]**
174
175 **SRS_XIO_02_002: [** `xio_retrieveoptions` shall create a `OPTIONHANDLER_HANDLE` by calling `OptionHandler_Create` passing `xio_setoption` as `setOption` argument and `xio_CloneOption` and `xio_DestroyOption` for `cloneOption` and `destroyOption`. **]**
176
177 **SRS_XIO_02_003: [** `xio_retrieveoptions` shall retrieve the concrete handle's options by a call to `concrete_io_retrieveoptions`. **]**
178
179 **SRS_XIO_02_004: [** `xio_retrieveoptions` shall add a hardcoded option named `concreteOptions` having the same content as the concrete handle's options. **]**
180
181 **SRS_XIO_02_005: [** If any operation fails, then `xio_retrieveoptions` shall fail and return NULL. **]**
182
183 **SRS_XIO_02_006: [** Otherwise, `xio_retrieveoptions` shall succeed and return a non-NULL handle. **]**