Arman Habibi / mbed-libxively-6eca970

test

Fork of mbed-libxively-6eca970 by Xively Official

src/libxively/data_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 data_layer.h
xively 0:82702e998d3f 6 * \author Olgierd Humenczuk
xively 0:82702e998d3f 7 * \brief Defines _data layer_ abstraction interface
xively 0:82702e998d3f 8 */
xively 0:82702e998d3f 9
xively 0:82702e998d3f 10 #ifndef __DATA_LAYER_H__
xively 0:82702e998d3f 11 #define __DATA_LAYER_H__
xively 0:82702e998d3f 12
xively 0:82702e998d3f 13 #ifdef __cplusplus
xively 0:82702e998d3f 14 extern "C" {
xively 0:82702e998d3f 15 #endif
xively 0:82702e998d3f 16
xively 0:82702e998d3f 17 /**
xively 0:82702e998d3f 18 * \brief _The data layer interface_ - contains function pointers,
xively 0:82702e998d3f 19 * that's what we expose to the layers above and below
xively 0:82702e998d3f 20 *
xively 0:82702e998d3f 21 * It is effectively a class that holds declarations of pure virtual functions.
xively 0:82702e998d3f 22 * * All encoders take a given data type (e.g. `xi_feed_t`, `xi_datapoint_t`) and produce
xively 0:82702e998d3f 23 * an encoded string in a buffer, which can be wrapped as payload to _transport layer_
xively 0:82702e998d3f 24 * or any other layer, such as _gzip_.
xively 0:82702e998d3f 25 * * All decoders take a given data buffer and convert to an appropriate data type.
xively 0:82702e998d3f 26 *
xively 0:82702e998d3f 27 * \note The encoders and decoders do not have to be paired, e.g. `encode_feed` is actually
xively 0:82702e998d3f 28 * implemented using `encode_datapoint_in_place` in a loop (see `http_encode_update_feed`),
xively 0:82702e998d3f 29 * so we only need `decode_feed`. However, this presumption had been made with CSV _data_
xively 0:82702e998d3f 30 * _layer_ implementation and the interface may need to change if other data formats are
xively 0:82702e998d3f 31 * to be implemented, but it is currently more important to have it the way it is.
xively 0:82702e998d3f 32 * The layering model should allow for simple way of integrating anything, even if there
xively 0:82702e998d3f 33 * might seem to be some inconsistency right now.
xively 0:82702e998d3f 34 */
xively 0:82702e998d3f 35 typedef struct {
xively 0:82702e998d3f 36 /**
xively 0:82702e998d3f 37 * \brief This function converts `xi_datapoint_t` into an implementation-specific format
xively 0:82702e998d3f 38 * for a datapoint.
xively 0:82702e998d3f 39 *
xively 0:82702e998d3f 40 * \return Pointer to the buffer where encoded string resides.
xively 0:82702e998d3f 41 */
xively 0:82702e998d3f 42 const char* ( *encode_datapoint )( const xi_datapoint_t* dp );
xively 0:82702e998d3f 43
xively 0:82702e998d3f 44 /**
xively 0:82702e998d3f 45 * \brief This function converts `xi_datapoint_t` into an implementation-specific format
xively 0:82702e998d3f 46 * for a datapoint with output buffer given as an argument.
xively 0:82702e998d3f 47 *
xively 0:82702e998d3f 48 * \return Offset or -1 if an error occurred.
xively 0:82702e998d3f 49 */
xively 0:82702e998d3f 50 int ( *encode_datapoint_in_place )(
xively 0:82702e998d3f 51 char* buffer, size_t buffer_size
xively 0:82702e998d3f 52 , const xi_datapoint_t* dp );
xively 0:82702e998d3f 53
xively 0:82702e998d3f 54 /**
xively 0:82702e998d3f 55 * \brief This function converts `xi_datapoint_t` and a given datastream ID string
xively 0:82702e998d3f 56 * into an implementation-specific format for creating datastreams.
xively 0:82702e998d3f 57
xively 0:82702e998d3f 58 * \return Pointer to the buffer where encoded string resides.
xively 0:82702e998d3f 59 */
xively 0:82702e998d3f 60 const char* ( *encode_create_datastream )(
xively 0:82702e998d3f 61 const char* data
xively 0:82702e998d3f 62 , const xi_datapoint_t* dp );
xively 0:82702e998d3f 63
xively 0:82702e998d3f 64 /**
xively 0:82702e998d3f 65 * \brief This function converts from an implementation-specific format for a feed
xively 0:82702e998d3f 66 * into `xi_feed_t` that is given as an argument.
xively 0:82702e998d3f 67 *
xively 0:82702e998d3f 68 * \return Pointer to feed structure or null if an error occurred.
xively 0:82702e998d3f 69 */
xively 0:82702e998d3f 70 xi_feed_t* ( *decode_feed )( const char* data, xi_feed_t* feed );
xively 0:82702e998d3f 71
xively 0:82702e998d3f 72 /**
xively 0:82702e998d3f 73 * \brief This function converts from an implementation-specific format for a datapoint
xively 0:82702e998d3f 74 * into `xi_datapoint_t` that is given as an argument.
xively 0:82702e998d3f 75 *
xively 0:82702e998d3f 76 * \return Pointer to datastream structure or null if an error occurred.
xively 0:82702e998d3f 77
xively 0:82702e998d3f 78 */
xively 0:82702e998d3f 79 xi_datapoint_t* ( *decode_datapoint )( const char* data, xi_datapoint_t* dp );
xively 0:82702e998d3f 80 } data_layer_t;
xively 0:82702e998d3f 81
xively 0:82702e998d3f 82 #ifdef __cplusplus
xively 0:82702e998d3f 83 }
xively 0:82702e998d3f 84 #endif
xively 0:82702e998d3f 85
xively 0:82702e998d3f 86 #endif // __DATA_LAYER_H__