Arman Habibi / mbed-libxively-6eca970

test

Fork of mbed-libxively-6eca970 by Xively Official

src/libxively/comm_layer.h@0:82702e998d3f, 2013-06-26 (annotated)

Committer:
xively
Date:
Wed Jun 26 10:40:43 2013 +0000
Revision:
0:82702e998d3f
libxively v0.1.1-rc0 (34c8b32)

Who changed what in which revision?

UserRevisionLine numberNew contents of line
xively 0:82702e998d3f 1 // Copyright (c) 2003-2013, LogMeIn, Inc. All rights reserved.
xively 0:82702e998d3f 2 // This is part of Xively C library, it is under the BSD 3-Clause license.
xively 0:82702e998d3f 3
xively 0:82702e998d3f 4 /**
xively 0:82702e998d3f 5 * \file comm_layer.h
xively 0:82702e998d3f 6 * \author Olgierd Humenczuk
xively 0:82702e998d3f 7 * \brief Defines _communication layer_ abstraction interface
xively 0:82702e998d3f 8 *
xively 0:82702e998d3f 9 * The design of _communication layer_ was based on Berkley/POSIX socket API.
xively 0:82702e998d3f 10 */
xively 0:82702e998d3f 11
xively 0:82702e998d3f 12 #ifndef __POSIX_COMM_LAYER_H__
xively 0:82702e998d3f 13 #define __POSIX_COMM_LAYER_H__
xively 0:82702e998d3f 14
xively 0:82702e998d3f 15
xively 0:82702e998d3f 16 #include <stdlib.h>
xively 0:82702e998d3f 17 #include <stdint.h>
xively 0:82702e998d3f 18
xively 0:82702e998d3f 19 #include "connection.h"
xively 0:82702e998d3f 20
xively 0:82702e998d3f 21 #ifdef __cplusplus
xively 0:82702e998d3f 22 extern "C" {
xively 0:82702e998d3f 23 #endif
xively 0:82702e998d3f 24
xively 0:82702e998d3f 25 /**
xively 0:82702e998d3f 26 * \brief _The communication layer interface_ - contains function pointers,
xively 0:82702e998d3f 27 * that's what we expose to the layers above and below
xively 0:82702e998d3f 28 *
xively 0:82702e998d3f 29 * It is effectively a class that holds declarations of pure virtual functions.
xively 0:82702e998d3f 30 *
xively 0:82702e998d3f 31 * The interface contain methods related to connecting/disconnecting as well as
xively 0:82702e998d3f 32 * reading/writing data to/from the remote endpoint.
xively 0:82702e998d3f 33 *
xively 0:82702e998d3f 34 * This interface uses abstract `connection_t` class to hold information
xively 0:82702e998d3f 35 * about the connection in a platform-independent fashion.
xively 0:82702e998d3f 36 */
xively 0:82702e998d3f 37 typedef struct {
xively 0:82702e998d3f 38 /**
xively 0:82702e998d3f 39 * \brief Connect to a given host using it's address and port
xively 0:82702e998d3f 40 * \note It should not reset an existing connection.
xively 0:82702e998d3f 41 *
xively 0:82702e998d3f 42 * \return Pointer to `connection_t` or `0` in case of an error.
xively 0:82702e998d3f 43 */
xively 0:82702e998d3f 44 connection_t* ( *open_connection )( const char* address, int32_t port );
xively 0:82702e998d3f 45
xively 0:82702e998d3f 46 /**
xively 0:82702e998d3f 47 * \brief Send data over the connection
xively 0:82702e998d3f 48 *
xively 0:82702e998d3f 49 * \return Number of bytes sent or `-1` in case of an error.
xively 0:82702e998d3f 50 */
xively 0:82702e998d3f 51 int ( *send_data )( connection_t* conn, const char* data, size_t size );
xively 0:82702e998d3f 52
xively 0:82702e998d3f 53 /**
xively 0:82702e998d3f 54 * \brief Read data from a connection
xively 0:82702e998d3f 55 *
xively 0:82702e998d3f 56 * \return Number of bytes read or `-1` in case of an error.
xively 0:82702e998d3f 57 */
xively 0:82702e998d3f 58 int ( *read_data )( connection_t* conn, char* buffer, size_t buffer_size );
xively 0:82702e998d3f 59
xively 0:82702e998d3f 60 /**
xively 0:82702e998d3f 61 * \brief Close connection and free all allocated memory (if any)
xively 0:82702e998d3f 62 * \note Some implementations may be stack-based as only limited
xively 0:82702e998d3f 63 * number of connections is expected in a typical use-case.
xively 0:82702e998d3f 64 */
xively 0:82702e998d3f 65 void ( *close_connection )( connection_t* conn );
xively 0:82702e998d3f 66 } comm_layer_t;
xively 0:82702e998d3f 67
xively 0:82702e998d3f 68
xively 0:82702e998d3f 69 /**
xively 0:82702e998d3f 70 * \brief Initialise an implementation of the _communication layer_
xively 0:82702e998d3f 71 *
xively 0:82702e998d3f 72 * This intialiser assigns function pointers to the actual implementations
xively 0:82702e998d3f 73 * using static function variable trick, hence the intialisation should
xively 0:82702e998d3f 74 * not give any overhead.
xively 0:82702e998d3f 75 *
xively 0:82702e998d3f 76 * \return Structure with function pointers for platform-specific communication
xively 0:82702e998d3f 77 * methods (see `mbed_comm.h` and `posix_comm.h` for how it's done).
xively 0:82702e998d3f 78 */
xively 0:82702e998d3f 79 const comm_layer_t* get_comm_layer( void );
xively 0:82702e998d3f 80
xively 0:82702e998d3f 81 #ifdef __cplusplus
xively 0:82702e998d3f 82 }
xively 0:82702e998d3f 83 #endif
xively 0:82702e998d3f 84
xively 0:82702e998d3f 85 #endif // __POSIX_COMM_LAYER_H__