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