xio requirements
================

## Overview

xio is module that implements an IO interface, abstracting from upper layers the functionality of simply sending or receiving a sequence of bytes.

## Exposed API

```c
typedef struct XIO_INSTANCE_TAG* XIO_HANDLE;
typedef void* CONCRETE_IO_HANDLE;

typedef enum IO_SEND_RESULT_TAG
{
    IO_SEND_OK,
    IO_SEND_ERROR,
    IO_SEND_CANCELLED
} IO_SEND_RESULT;

typedef enum IO_OPEN_RESULT_TAG
{
    IO_OPEN_OK,
    IO_OPEN_ERROR,
    IO_OPEN_CANCELLED
} IO_OPEN_RESULT;

typedef void(*ON_BYTES_RECEIVED)(void* context, const unsigned char* buffer, size_t size);
typedef void(*ON_SEND_COMPLETE)(void* context, IO_SEND_RESULT send_result);
typedef void(*ON_IO_OPEN_COMPLETE)(void* context, IO_OPEN_RESULT open_result);
typedef void(*ON_IO_CLOSE_COMPLETE)(void* context);
typedef void(*ON_IO_ERROR)(void* context);

typedef OPTIONHANDLER_HANDLE (*IO_RETRIEVEOPTIONS)(CONCRETE_IO_HANDLE concrete_io);
typedef CONCRETE_IO_HANDLE(*IO_CREATE)(void* io_create_parameters);
typedef void(*IO_DESTROY)(CONCRETE_IO_HANDLE concrete_io);
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);
typedef int(*IO_CLOSE)(CONCRETE_IO_HANDLE concrete_io, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
typedef int(*IO_SEND)(CONCRETE_IO_HANDLE concrete_io, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
typedef void(*IO_DOWORK)(CONCRETE_IO_HANDLE concrete_io);
typedef int(*IO_SETOPTION)(CONCRETE_IO_HANDLE concrete_io, const char* optionName, const void* value);

typedef struct IO_INTERFACE_DESCRIPTION_TAG
{
    IO_RETRIEVEOPTIONS concrete_io_retrieveoptions;
    IO_CREATE concrete_io_create;
    IO_DESTROY concrete_io_destroy;
    IO_OPEN concrete_io_open;
    IO_CLOSE concrete_io_close;
    IO_SEND concrete_io_send;
    IO_DOWORK concrete_io_dowork;
    IO_SETOPTION concrete_io_setoption;
} IO_INTERFACE_DESCRIPTION;

extern XIO_HANDLE xio_create(const IO_INTERFACE_DESCRIPTION* io_interface_description, const void* io_create_parameters);
extern void xio_destroy(XIO_HANDLE xio);
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);
extern int xio_close(XIO_HANDLE xio, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
extern int xio_send(XIO_HANDLE xio, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
extern void xio_dowork(XIO_HANDLE xio);
extern int xio_setoption(XIO_HANDLE xio, const char* optionName, const void* value);
```

### xio_create

```c
extern XIO_HANDLE xio_create(const IO_INTERFACE_DESCRIPTION* io_interface_description, const void* io_create_parameters);
```

**SRS_XIO_01_001: [** xio_create shall return on success a non-NULL handle to a new IO interface. **]**

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

**SRS_XIO_01_016: [** If the underlying concrete_xio_create call fails, xio_create shall return NULL. **]**

**SRS_XIO_01_003: [** If the argument io_interface_description is NULL, xio_create shall return NULL. **]**

**SRS_XIO_01_004: [** If any io_interface_description member is NULL, xio_create shall return NULL. **]**

**SRS_XIO_01_017: [** If allocating the memory needed for the IO interface fails then xio_create shall return NULL. **]**

### xio_destroy

```c
extern void xio_destroy(XIO_HANDLE xio);
```

**SRS_XIO_01_005: [** xio_destroy shall free all resources associated with the IO handle. **]**

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

**SRS_XIO_01_007: [** If the argument io is NULL, xio_destroy shall do nothing. **]**

### xio_open

```c
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);
```

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

**SRS_XIO_01_020: [** On success, xio_open shall return 0. **]**

**SRS_XIO_01_021: [** If handle is NULL, xio_open shall return a non-zero value. **]**

**SRS_XIO_01_022: [** If the underlying concrete_xio_open fails, xio_open shall return a non-zero value. **]**

### xio_close

```c
extern int xio_close(XIO_HANDLE xio, ON_IO_CLOSE_COMPLETE on_io_close_complete, void* callback_context);
```

**SRS_XIO_01_023: [** xio_close shall call the specific concrete_xio_close function specified in xio_create. **]**

**SRS_XIO_01_024: [** On success, xio_close shall return 0. **]**

**SRS_XIO_01_025: [** If the argument io is NULL, xio_close shall return a non-zero value. **]**

**SRS_XIO_01_026: [** If the underlying concrete_xio_close fails, xio_close shall return a non-zero value. **]**

### xio_send

```c
extern int xio_send(XIO_HANDLE xio, const void* buffer, size_t size, ON_SEND_COMPLETE on_send_complete, void* callback_context);
```

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

**SRS_XIO_01_027: [** xio_send shall pass to the concrete_xio_send function the on_send_complete and callback_context arguments. **]**

**SRS_XIO_01_009: [** On success, xio_send shall return 0. **]**

**SRS_XIO_01_010: [** If the argument xio is NULL, xio_send shall return a non-zero value. **]**

**SRS_XIO_01_015: [** If the underlying concrete_xio_send fails, xio_send shall return a non-zero value. **]**

**SRS_XIO_01_011: [** No error check shall be performed on buffer and size. **]**

### xio_dowork

```c
extern void xio_dowork(XIO_HANDLE xio);
```

**SRS_XIO_01_012: [** xio_dowork shall call the concrete IO implementation specified in xio_create, by calling the concrete_xio_dowork function. **]**

**SRS_XIO_01_013: [** On success, xio_send shall return 0. **]**

**SRS_XIO_01_014: [** If the underlying concrete_xio_dowork fails, xio_dowork shall return a non-zero value. **]**

**SRS_XIO_01_018: [** When the io argument is NULL, xio_dowork shall do nothing. **]**

### xio_setoption

```c
extern int xio_setoption(XIO_HANDLE xio, const char* optionName, const void* value);
```

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

**SRS_XIO_03_029: [** xio_setoption shall return 0 upon success. **]**

**SRS_XIO_03_030: [** If the xio argument or the optionName argument is NULL, xio_setoption shall return a non-zero value. **]**

**SRS_XIO_03_031: [** If the underlying concrete_xio_setoption fails, xio_setOption shall return a non-zero value. **]**

###  xio_retrieveoptions
```
OPTIONHANDLER_HANDLE xio_retrieveoptions(XIO_HANDLE xio)
```

**SRS_XIO_02_001: [** If argument `xio` is `NULL` then `xio_retrieveoptions` shall fail and return `NULL`. **]**

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

**SRS_XIO_02_003: [** `xio_retrieveoptions` shall retrieve the concrete handle's options by a call to `concrete_io_retrieveoptions`. **]**

**SRS_XIO_02_004: [** `xio_retrieveoptions` shall add a hardcoded option named `concreteOptions` having the same content as the concrete handle's options. **]**

**SRS_XIO_02_005: [** If any operation fails, then `xio_retrieveoptions` shall fail and return NULL. **]**

**SRS_XIO_02_006: [** Otherwise, `xio_retrieveoptions` shall succeed and return a non-NULL handle. **]**