Xively Official / mbed-libxively-5d6fdd4

Xively C library

Dependents:   xively-jumpstart-demo

This is Xively C library, the code lives on GitHub.

See our example program and the tutorial, documentation can bee found here.

src/libxively/data_layer.h@0:53753690a8bf, 2013-05-13 (annotated)

Committer:
xively
Date:
Mon May 13 19:28:22 2013 +0000
Revision:
0:53753690a8bf
libxively v0.1.1-rc0

Who changed what in which revision?

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