data_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    data_layer.h
00006  * \author  Olgierd Humenczuk
00007  * \brief   Defines _data layer_ abstraction interface
00008  */
00009 
00010 #ifndef __DATA_LAYER_H__
00011 #define __DATA_LAYER_H__
00012 
00013 #ifdef __cplusplus
00014 extern "C" {
00015 #endif
00016 
00017 /**
00018  * \brief   _The data layer interface_ - contains function pointers,
00019  *          that's what we expose to the layers above and below
00020  *
00021  *    It is effectively a class that holds declarations of pure virtual functions.
00022  *    * All encoders take a given data type (e.g. `xi_feed_t`, `xi_datapoint_t`) and produce
00023  *    an encoded string in a buffer, which can be wrapped as payload to _transport layer_
00024  *    or any other layer, such as _gzip_.
00025  *    * All decoders take a given data buffer and convert to an appropriate data type.
00026  *
00027  * \note    The encoders and decoders do not have to be paired, e.g. `encode_feed` is actually
00028  *          implemented using `encode_datapoint_in_place` in a loop (see `http_encode_update_feed`),
00029  *          so we only need `decode_feed`. However, this presumption had been made with CSV _data_
00030  *          _layer_ implementation and the interface may need to change if other data formats are
00031  *          to be implemented, but it is currently more important to have it the way it is.
00032  *          The layering model should allow for simple way of integrating anything, even if there
00033  *          might seem to be some inconsistency right now.
00034  */
00035 typedef struct {
00036     /**
00037      * \brief   This function converts `xi_datapoint_t` into an implementation-specific format
00038      *          for a datapoint.
00039      *
00040      * \return  Pointer to the buffer where encoded string resides.
00041      */
00042     const char* ( *encode_datapoint )( const xi_datapoint_t* dp );
00043 
00044     /**
00045      * \brief   This function converts `xi_datapoint_t` into an implementation-specific format
00046      *          for a datapoint with output buffer given as an argument.
00047      *
00048      * \return  Offset or -1 if an error occurred.
00049      */
00050     int ( *encode_datapoint_in_place )(
00051           char* buffer, size_t buffer_size
00052         , const xi_datapoint_t* dp );
00053 
00054     /**
00055      * \brief   This function converts `xi_datapoint_t` and a given datastream ID string
00056      *          into an implementation-specific format for creating datastreams.
00057 
00058      * \return  Pointer to the buffer where encoded string resides.
00059      */
00060     const char* ( *encode_create_datastream )(
00061           const char* data
00062         , const xi_datapoint_t* dp );
00063 
00064     /**
00065      * \brief   This function converts from an implementation-specific format for a feed
00066      *          into `xi_feed_t` that is given as an argument.
00067      *
00068      * \return  Pointer to feed structure or null if an error occurred.
00069      */
00070     xi_feed_t* ( *decode_feed )( const char* data, xi_feed_t* feed );
00071 
00072     /**
00073      * \brief   This function converts from an implementation-specific format for a datapoint
00074      *          into `xi_datapoint_t` that is given as an argument.
00075      *
00076      * \return  Pointer to datastream structure or null if an error occurred.
00077 
00078      */
00079     xi_datapoint_t* ( *decode_datapoint )( const char* data, xi_datapoint_t* dp );
00080 } data_layer_t;
00081 
00082 #ifdef __cplusplus
00083 }
00084 #endif
00085 
00086 #endif // __DATA_LAYER_H__