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

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

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

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

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

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

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

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

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