comm_layer.h

00001 // Copyright (c) 2003-2013, LogMeIn, Inc. All rights reserved.
00002 // This is part of Xively C library, it is under the BSD 3-Clause license.
00003 
00004 /**
00005  * \file    comm_layer.h
00006  * \author  Olgierd Humenczuk
00007  * \brief   Defines _communication layer_ abstraction interface
00008  *
00009  *    The design of _communication layer_ was based on Berkley/POSIX socket API.
00010  */
00011 
00012 #ifndef __POSIX_COMM_LAYER_H__
00013 #define __POSIX_COMM_LAYER_H__
00014 
00015 
00016 #include <stdlib.h>
00017 #include <stdint.h>
00018 
00019 #include "connection.h"
00020 
00021 #ifdef __cplusplus
00022 extern "C" {
00023 #endif
00024 
00025 /**
00026  * \brief   _The communication layer interface_ - contains function pointers,
00027  *          that's what we expose to the layers above and below
00028  *
00029  *    It is effectively a class that holds declarations of pure virtual functions.
00030  *
00031  *   The interface contain methods related to connecting/disconnecting as well as
00032  *   reading/writing data to/from the remote endpoint.
00033  *
00034  *   This interface uses abstract `connection_t` class to hold information
00035  *   about the connection in a platform-independent fashion.
00036  */
00037 typedef struct {
00038     /**
00039      * \brief   Connect to a given host using it's address and port
00040      * \note    It should not reset an existing connection.
00041      *
00042      * \return Pointer to `connection_t` or `0` in case of an error.
00043      */
00044     connection_t* ( *open_connection )( const char* address, int32_t port );
00045 
00046     /**
00047      * \brief   Send data over the connection
00048      *
00049      * \return  Number of bytes sent or `-1` in case of an error.
00050      */
00051     int ( *send_data )( connection_t* conn, const char* data, size_t size );
00052 
00053     /**
00054      * \brief   Read data from a connection
00055      *
00056      * \return  Number of bytes read or `-1` in case of an error.
00057      */
00058     int ( *read_data )( connection_t* conn, char* buffer, size_t buffer_size );
00059 
00060     /**
00061      * \brief   Close connection and free all allocated memory (if any)
00062      * \note    Some implementations may be stack-based as only limited
00063      *          number of connections is expected in a typical use-case.
00064      */
00065     void ( *close_connection )( connection_t* conn );
00066 } comm_layer_t;
00067 
00068 
00069  /**
00070   * \brief   Initialise an implementation of the _communication layer_
00071   *
00072   *    This intialiser assigns function pointers to the actual implementations
00073   *    using  static function variable trick, hence the intialisation should
00074   *    not give any overhead.
00075   *
00076   * \return  Structure with function pointers for platform-specific communication
00077   *          methods (see `mbed_comm.h` and `posix_comm.h` for how it's done).
00078   */
00079 const comm_layer_t* get_comm_layer( void );
00080 
00081 #ifdef __cplusplus
00082 }
00083 #endif
00084 
00085 #endif // __POSIX_COMM_LAYER_H__