socket_async
=================

## Overview

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

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.
## References

[socket_async.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/socket_async.h)  
[sys/socket.h, a typical linux socket implementation](http://pubs.opengroup.org/onlinepubs/7908799/xns/syssocket.h.html)

###   Exposed API

**SRS_SOCKET_ASYNC_30_001: [** The socket_async shall use the constants and types defined in `socket_async.h`.
```c
#define SOCKET_ASYNC_INVALID_SOCKET -1

    typedef struct
    {
      int keep_alive;     // < 0 for system defaults, 0 to disable, >= 0 to use supplied keep_alive, idle, interval, and count
      int keep_idle;      // seconds before first keepalive packet (ignored if keep_alive <= 0)
      int keep_interval;  // seconds between keepalive packets (ignored if keep_alive <= 0)
      int keep_count;     // number of times to try before declaring failure (ignored if keep_alive <= 0)
    } SOCKET_ASYNC_OPTIONS;
    typedef SOCKET_ASYNC_OPTIONS* SOCKET_ASYNC_OPTIONS_HANDLE;

    typedef int SOCKET_ASYNC_HANDLE;
```
 **]**

**SRS_SOCKET_ASYNC_30_002: [** The socket_async shall implement the methods defined in `socket_async.h`.
```c
SOCKET_ASYNC_HANDLE socket_async_create(uint32_t host_ipv4, uint16_t port, bool is_UDP, SOCKET_ASYNC_OPTIONS_HANDLE options);
int socket_async_is_create_complete(SOCKET_ASYNC_HANDLE sock, bool* is_complete);
int socket_async_send(SOCKET_ASYNC_HANDLE sock, void* buffer, size_t size, size_t* sent_count);
int socket_async_receive(SOCKET_ASYNC_HANDLE sock, void* buffer, size_t size, size_t* received_count);
void socket_async_destroy(SOCKET_ASYNC_HANDLE sock);
```
 **]**


###   socket_async_create
`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.
```c
SOCKET_ASYNC_HANDLE socket_async_create(uint32_t host_ipv4, uint16_t port, bool is_UDP, SOCKET_ASYNC_OPTIONS_HANDLE options);
```

**SRS_SOCKET_ASYNC_30_011: [** The `host_ipv4` parameter shall be the 32-bit IP V4 of the target server. **]**

**SRS_SOCKET_ASYNC_30_012: [** The `port` parameter shall be the port number for the target server. **]**

**SRS_SOCKET_ASYNC_30_013: [** The `is_UDP` parameter shall be `true` for a UDP connection, and `false` for TCP. **]**

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

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

**SRS_SOCKET_ASYNC_30_016: [** If `is_UDP` is true, the optional `options` parameter shall be ignored. **]**

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

**SRS_SOCKET_ASYNC_30_018: [** On success, `socket_async_create` shall return the created and configured SOCKET_ASYNC_HANDLE. **]**

**SRS_SOCKET_ASYNC_30_019: [** The socket returned shall be non-blocking. **]**

**SRS_SOCKET_ASYNC_30_010: [** If socket option creation fails, `socket_async_create` shall log an error and return SOCKET_ASYNC_INVALID_SOCKET. **]**

**SRS_SOCKET_ASYNC_30_020: [** If socket option setting fails, `socket_async_create` shall log an error and return SOCKET_ASYNC_INVALID_SOCKET. **]**

**SRS_SOCKET_ASYNC_30_021: [** If socket binding fails, `socket_async_create` shall log an error and return SOCKET_ASYNC_INVALID_SOCKET. **]**

**SRS_SOCKET_ASYNC_30_022: [** If socket connection fails, `socket_async_create` shall log an error and return SOCKET_ASYNC_INVALID_SOCKET. **]**


###   socket_async_is_create_complete
`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.

If this method fails then `socket_async_destroy` must be called.

Validation of the `sock` parameter is deferred to the underlying socket call.

```c
int socket_async_is_create_complete(SOCKET_ASYNC_HANDLE sock, bool* is_complete);
```

**SRS_SOCKET_ASYNC_30_023: [** The `sock` parameter shall be the socket to check for initial handshake completion. **]**

**SRS_SOCKET_ASYNC_30_024: [** The `is_complete` parameter shall receive the completion state. **]**

**SRS_SOCKET_ASYNC_30_025: [** If the `is_complete` parameter is NULL, `socket_async_is_create_complete` shall log an error and return _FAILURE_. **]**

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

**SRS_SOCKET_ASYNC_30_027: [** On failure, the `is_complete` value shall be set to `false` and `socket_async_create` shall return _FAILURE_. **]**


###   socket_async_send
`socket_async_send` attempts to send `size` bytes from `buffer` to the underlying socket.

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.

Validation of the `sock` parameter is deferred to the underlying socket call.

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.

```c
int socket_async_send(SOCKET_ASYNC_HANDLE sock, void* buffer, size_t size, size_t* sent_count);
```

**SRS_SOCKET_ASYNC_30_030: [** The `sock` parameter shall be the socket to send the message to. **]**

**SRS_SOCKET_ASYNC_30_031: [** The `buffer` parameter shall contain the message to send to the target server. **]**

**SRS_SOCKET_ASYNC_30_032: [** The `size` parameter shall be the size of the message in bytes. **]**

**SRS_SOCKET_ASYNC_30_033: [** If the `buffer` parameter is NULL, `socket_async_send` shall log the error return _FAILURE_. **]**

**SRS_SOCKET_ASYNC_30_034: [** If the `sent_count` parameter is NULL, `socket_async_send` shall log the error return _FAILURE_. **]**

**SRS_SOCKET_ASYNC_30_073: [** If the `size` parameter is 0, `socket_async_send` shall set `sent_count` to 0 and return 0. **]**

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

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

**SRS_SOCKET_ASYNC_30_037: [** If `socket_async_send` fails unexpectedly, `socket_async_send` shall log the error return _FAILURE_. **]**

###   socket_async_receive
`socket_async_receive` attempts to receive up to `size` bytes into `buffer`.

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.

Validation of the `sock` parameter is deferred to the underlying socket call.

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.

```c
int socket_async_receive(SOCKET_ASYNC_HANDLE sock, void* buffer, size_t size, size_t* received_count);
```

**SRS_SOCKET_ASYNC_30_050: [** The `sock` parameter shall be the socket to receive the message from. **]**

**SRS_SOCKET_ASYNC_30_051: [** The `size` parameter shall be the size of the `buffer` in bytes. **]**

**SRS_SOCKET_ASYNC_30_052: [** If the `buffer` parameter is NULL, `socket_async_receive` shall log the error and return _FAILURE_. **]**

**SRS_SOCKET_ASYNC_30_053: [** If the `received_count` parameter is NULL, `socket_async_receive` shall log the error and return _FAILURE_. **]**

**SRS_SOCKET_ASYNC_30_072: [** If the `size` parameter is 0, `socket_async_receive` shall log an error and return _FAILURE_. **]**

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

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

**SRS_SOCKET_ASYNC_30_056: [** If the underlying socket fails unexpectedly, `socket_async_receive` shall log the error and return _FAILURE_. **]**


 ###   socket_async_destroy
 `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`.

 ```c
 void socket_async_destroy(SOCKET_ASYNC_HANDLE sock);
 ```

**SRS_SOCKET_ASYNC_30_070: [** The `sock` parameter shall be the SOCKET_ASYNC_HANDLE of the socket to be closed. **]**  

**SRS_SOCKET_ASYNC_30_071: [** `socket_async_destroy` shall call the underlying `close` method on the supplied socket. **]**