Debian Codegraph @

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

raw
1 socket_async
2 =================
3
4 ## Overview
5
6 **socket_async** abstracts a non-blocking TCP or UDP socket while hiding OS implementation details. The socket handling code in `socket_async.c` is common to many environments, and
7 a system of header includes and #defines will adapt the code for each particular environment. Validation of SOCKET_ASYNC_HANDLE parameters is deferred to the underlying socket layer.
8
9 It is anticipated that socket_async.c will work for all non-Windows environments, and a socket_async_win32.c will be needed for Windows.
10 ## References
11
12 [socket_async.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/socket_async.h)
13 [sys/socket.h, a typical linux socket implementation](http://pubs.opengroup.org/onlinepubs/7908799/xns/syssocket.h.html)
14
15 ### Exposed API
16
17 **SRS_SOCKET_ASYNC_30_001: [** The socket_async shall use the constants and types defined in `socket_async.h`.
18 ```c
19 #define SOCKET_ASYNC_INVALID_SOCKET -1
20
21 typedef struct
22 {
23 int keep_alive; // < 0 for system defaults, 0 to disable, >= 0 to use supplied keep_alive, idle, interval, and count
24 int keep_idle; // seconds before first keepalive packet (ignored if keep_alive <= 0)
25 int keep_interval; // seconds between keepalive packets (ignored if keep_alive <= 0)
26 int keep_count; // number of times to try before declaring failure (ignored if keep_alive <= 0)
27 } SOCKET_ASYNC_OPTIONS;
28 typedef SOCKET_ASYNC_OPTIONS* SOCKET_ASYNC_OPTIONS_HANDLE;
29
30 typedef int SOCKET_ASYNC_HANDLE;
31 ```
32 **]**
33
34 **SRS_SOCKET_ASYNC_30_002: [** The socket_async shall implement the methods defined in `socket_async.h`.
35 ```c
36 SOCKET_ASYNC_HANDLE socket_async_create(uint32_t host_ipv4, uint16_t port, bool is_UDP, SOCKET_ASYNC_OPTIONS_HANDLE options);
37 int socket_async_is_create_complete(SOCKET_ASYNC_HANDLE sock, bool* is_complete);
38 int socket_async_send(SOCKET_ASYNC_HANDLE sock, void* buffer, size_t size, size_t* sent_count);
39 int socket_async_receive(SOCKET_ASYNC_HANDLE sock, void* buffer, size_t size, size_t* received_count);
40 void socket_async_destroy(SOCKET_ASYNC_HANDLE sock);
41 ```
42 **]**
43
44
45 ### socket_async_create
46 `socket_async_create` creates a socket and sets its configuration, including setting the socket to non-blocking. It then binds the socket to the supplied `host_ipv4` and `port`, and begins the process of connecting the socket to the bound address.
47 ```c
48 SOCKET_ASYNC_HANDLE socket_async_create(uint32_t host_ipv4, uint16_t port, bool is_UDP, SOCKET_ASYNC_OPTIONS_HANDLE options);
49 ```
50
51 **SRS_SOCKET_ASYNC_30_011: [** The `host_ipv4` parameter shall be the 32-bit IP V4 of the target server. **]**
52
53 **SRS_SOCKET_ASYNC_30_012: [** The `port` parameter shall be the port number for the target server. **]**
54
55 **SRS_SOCKET_ASYNC_30_013: [** The `is_UDP` parameter shall be `true` for a UDP connection, and `false` for TCP. **]**
56
57 **SRS_SOCKET_ASYNC_30_014: [** If the optional `options` parameter is non-NULL and `is_UDP` is false, and options->keep_alive is non-negative, `socket_async_create` shall set the socket options to the provided options values. **]**
58
59 **SRS_SOCKET_ASYNC_30_015: [** If the optional `options` parameter is non-NULL and `is_UDP` is false, and options->keep_alive is negative, `socket_async_create` not set the socket keep-alive options. **]**
60
61 **SRS_SOCKET_ASYNC_30_016: [** If `is_UDP` is true, the optional `options` parameter shall be ignored. **]**
62
63 **SRS_SOCKET_ASYNC_30_017: [** If the optional `options` parameter is NULL and `is_UDP` is false, `socket_async_create` shall disable TCP keep-alive. **]**
64
65 **SRS_SOCKET_ASYNC_30_018: [** On success, `socket_async_create` shall return the created and configured SOCKET_ASYNC_HANDLE. **]**
66
67 **SRS_SOCKET_ASYNC_30_019: [** The socket returned shall be non-blocking. **]**
68
69 **SRS_SOCKET_ASYNC_30_010: [** If socket option creation fails, `socket_async_create` shall log an error and return SOCKET_ASYNC_INVALID_SOCKET. **]**
70
71 **SRS_SOCKET_ASYNC_30_020: [** If socket option setting fails, `socket_async_create` shall log an error and return SOCKET_ASYNC_INVALID_SOCKET. **]**
72
73 **SRS_SOCKET_ASYNC_30_021: [** If socket binding fails, `socket_async_create` shall log an error and return SOCKET_ASYNC_INVALID_SOCKET. **]**
74
75 **SRS_SOCKET_ASYNC_30_022: [** If socket connection fails, `socket_async_create` shall log an error and return SOCKET_ASYNC_INVALID_SOCKET. **]**
76
77
78 ### socket_async_is_create_complete
79 `socket_async_is_create_complete` tests whether the socket has completed its initial TCP handshake. For UDP connections the `socket_async_is_create_complete` call is optional and always returns true.
80
81 If this method fails then `socket_async_destroy` must be called.
82
83 Validation of the `sock` parameter is deferred to the underlying socket call.
84
85 ```c
86 int socket_async_is_create_complete(SOCKET_ASYNC_HANDLE sock, bool* is_complete);
87 ```
88
89 **SRS_SOCKET_ASYNC_30_023: [** The `sock` parameter shall be the socket to check for initial handshake completion. **]**
90
91 **SRS_SOCKET_ASYNC_30_024: [** The `is_complete` parameter shall receive the completion state. **]**
92
93 **SRS_SOCKET_ASYNC_30_025: [** If the `is_complete` parameter is NULL, `socket_async_is_create_complete` shall log an error and return _FAILURE_. **]**
94
95 **SRS_SOCKET_ASYNC_30_026: [** On success, the `is_complete` value shall be set to the completion state and `socket_async_create` shall return 0. **]**
96
97 **SRS_SOCKET_ASYNC_30_027: [** On failure, the `is_complete` value shall be set to `false` and `socket_async_create` shall return _FAILURE_. **]**
98
99
100 ### socket_async_send
101 `socket_async_send` attempts to send `size` bytes from `buffer` to the underlying socket.
102
103 If this method fails then `socket_async_destroy` must be called. This includes the case of NULL `buffer` and `sent_count` parameters, which are assumed to be unrecoverable program bugs.
104
105 Validation of the `sock` parameter is deferred to the underlying socket call.
106
107 The function signature for `socket_async_send` is a pass-through for the underlying socket `send()` call, and the parameter types are identical for the two calls.
108
109 ```c
110 int socket_async_send(SOCKET_ASYNC_HANDLE sock, void* buffer, size_t size, size_t* sent_count);
111 ```
112
113 **SRS_SOCKET_ASYNC_30_030: [** The `sock` parameter shall be the socket to send the message to. **]**
114
115 **SRS_SOCKET_ASYNC_30_031: [** The `buffer` parameter shall contain the message to send to the target server. **]**
116
117 **SRS_SOCKET_ASYNC_30_032: [** The `size` parameter shall be the size of the message in bytes. **]**
118
119 **SRS_SOCKET_ASYNC_30_033: [** If the `buffer` parameter is NULL, `socket_async_send` shall log the error return _FAILURE_. **]**
120
121 **SRS_SOCKET_ASYNC_30_034: [** If the `sent_count` parameter is NULL, `socket_async_send` shall log the error return _FAILURE_. **]**
122
123 **SRS_SOCKET_ASYNC_30_073: [** If the `size` parameter is 0, `socket_async_send` shall set `sent_count` to 0 and return 0. **]**
124
125 **SRS_SOCKET_ASYNC_30_035: [** If the underlying socket accepts one or more bytes for transmission, `socket_async_send` shall return 0 and the `sent_count` parameter shall receive the number of bytes accepted for transmission. **]**
126
127 **SRS_SOCKET_ASYNC_30_036: [** If the underlying socket is unable to accept any bytes for transmission because its buffer is full, `socket_async_send` shall return 0 and the `sent_count` parameter shall receive the value 0. **]**
128
129 **SRS_SOCKET_ASYNC_30_037: [** If `socket_async_send` fails unexpectedly, `socket_async_send` shall log the error return _FAILURE_. **]**
130
131 ### socket_async_receive
132 `socket_async_receive` attempts to receive up to `size` bytes into `buffer`.
133
134 If this method fails then `socket_async_destroy` must be called. This includes the case of NULL `buffer` and `received_count` parameters, which are assumed to be unrecoverable program bugs.
135
136 Validation of the `sock` parameter is deferred to the underlying socket call.
137
138 The function signature for `socket_async_receive` is a pass-through for the underlying socket `send()` call, and the parameter types are identical for the two calls.
139
140 ```c
141 int socket_async_receive(SOCKET_ASYNC_HANDLE sock, void* buffer, size_t size, size_t* received_count);
142 ```
143
144 **SRS_SOCKET_ASYNC_30_050: [** The `sock` parameter shall be the socket to receive the message from. **]**
145
146 **SRS_SOCKET_ASYNC_30_051: [** The `size` parameter shall be the size of the `buffer` in bytes. **]**
147
148 **SRS_SOCKET_ASYNC_30_052: [** If the `buffer` parameter is NULL, `socket_async_receive` shall log the error and return _FAILURE_. **]**
149
150 **SRS_SOCKET_ASYNC_30_053: [** If the `received_count` parameter is NULL, `socket_async_receive` shall log the error and return _FAILURE_. **]**
151
152 **SRS_SOCKET_ASYNC_30_072: [** If the `size` parameter is 0, `socket_async_receive` shall log an error and return _FAILURE_. **]**
153
154 **SRS_SOCKET_ASYNC_30_054: [** On success, the underlying socket shall set one or more received bytes into `buffer`, `socket_async_receive` shall return 0, and the `received_count` parameter shall receive the number of bytes received into `buffer`. **]**
155
156 **SRS_SOCKET_ASYNC_30_055: [** If the underlying socket has no received bytes available, `socket_async_receive` shall return 0 and the `received_count` parameter shall receive the value 0. **]**
157
158 **SRS_SOCKET_ASYNC_30_056: [** If the underlying socket fails unexpectedly, `socket_async_receive` shall log the error and return _FAILURE_. **]**
159
160
161 ### socket_async_destroy
162 `socket_async_destroy` calls the underlying socket `close()` on the supplied socket. Parameter validation is deferred to the underlying call, so no validation is performed by `socket_async_destroy`.
163
164 ```c
165 void socket_async_destroy(SOCKET_ASYNC_HANDLE sock);
166 ```
167
168 **SRS_SOCKET_ASYNC_30_070: [** The `sock` parameter shall be the SOCKET_ASYNC_HANDLE of the socket to be closed. **]**
169
170 **SRS_SOCKET_ASYNC_30_071: [** `socket_async_destroy` shall call the underlying `close` method on the supplied socket. **]**