transport_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    transport_layer.h
00006  * \author  Olgierd Humenczuk
00007  * \brief   Defines _transport layer_ abstraction interface
00008  */
00009 
00010 #ifndef __TRANSPORT_LAYER_H__
00011 #define __TRANSPORT_LAYER_H__
00012 
00013 #include "xively.h"
00014 #include "data_layer.h"
00015 
00016 #ifdef __cplusplus
00017 extern "C" {
00018 #endif
00019 
00020 /**
00021  * \brief   _The transport layer interface_ - contains function pointers,
00022  *          that's what we expose to the layers above and below
00023  *
00024  *    It is effectively a class that holds declarations of pure virtual functions.
00025  *    * All functions take `data_layer_t` as the first argument.
00026  *    * Most encoders convert the result from data layer to an implementation-specific representaion.
00027  *
00028  * \note    It depends on the implementation whether any given _transport layer_ method will call upon
00029  *          the _data layer_. In `http_transport_layer.c` you can see that `http_encode_datapoint_delete_range()`
00030  *          only needs to generate request headers and no body needs to be posted, neither it gets any
00031  *          response body as it is doing a `DELETE` request. One should use `XI_UNUSED(data_layer)` at the
00032  *          top of the function definition, that is a macro that casts the pointer to unused _data layer_ to void.
00033  * \note    Similarly to the _data layer_ (see notes in `data_layer.h`), there no symmetry needed and we only have
00034  *          one decoder.
00035  */
00036 typedef struct {
00037     const char* ( *encode_update_feed )(
00038           const data_layer_t*, const char* api_key
00039         , const xi_feed_t* feed );
00040 
00041     const char* ( *encode_get_feed )(
00042           const data_layer_t*, const char* api_key
00043         , const xi_feed_t* feed );
00044 
00045     const char* ( *encode_create_datastream )(
00046           const data_layer_t*, const char* api_key, int32_t feed_id
00047         , const char* datastream_id
00048         , const xi_datapoint_value_t* dp );
00049 
00050     const char* ( *encode_update_datastream )(
00051           const data_layer_t*, const char* api_key, int32_t feed_id
00052         , const char* datastream_id
00053         , const xi_datapoint_value_t* value );
00054 
00055     const char* ( *encode_get_datastream )(
00056           const data_layer_t*, const char* api_key, int32_t feed_id
00057         , const char* datastream_id );
00058 
00059     const char* ( *encode_delete_datastream )(
00060           const data_layer_t*, const char* api_key, int32_t feed_id
00061         , const char* datastream_id );
00062 
00063     const char* ( *encode_delete_datapoint )(
00064           const data_layer_t*, const char* api_key, int32_t feed_id
00065         , const char* datastream_id
00066         , const xi_datapoint_t* datapoint );
00067 
00068     const char* ( *encode_datapoint_delete_range )(
00069           const data_layer_t*, const char* api_key, int32_t feed_id
00070         , const char* datastream_id
00071         , const xi_timestamp_t* start
00072         , const xi_timestamp_t* end );
00073 
00074     const xi_response_t* ( *decode_reply )(
00075         const data_layer_t*, const char* data );
00076 } transport_layer_t;
00077 
00078 #ifdef __cplusplus
00079 }
00080 #endif
00081 
00082 #endif // __TRANSPORT_LAYER_H__