xively.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    xively.h
00006  * \brief   Xively C library
00007  */
00008 
00009 #ifndef __XI_H__
00010 #define __XI_H__
00011 
00012 #include <stdlib.h>
00013 #include <stdint.h>
00014 
00015 #include <time.h>
00016 
00017 #include "comm_layer.h"
00018 #include "xi_consts.h"
00019 
00020 #ifdef __cplusplus
00021 extern "C" {
00022 #endif
00023 
00024 //-----------------------------------------------------------------------
00025 // TYPES AND STRUCTURES
00026 //-----------------------------------------------------------------------
00027 
00028 /**
00029  * \brief    The protocols currently supported by Xively
00030  * \note     See source code for details of what's implemented.
00031  */
00032 typedef enum {
00033     /** `http://api.xively.com` */
00034     XI_HTTP,
00035     /** `https://api.xively.com` */
00036     XI_HTTPS,
00037     /** `telnet api.xively.com 8081` */
00038     XI_TCP,
00039     /** `openssl s_client -host api.xively.com -port 8091 -tls1` */
00040     XI_TCPS,
00041     /** `ws://api.xively.com:8080` */
00042     XI_WS,
00043     /** `wss://api.xively.com:8090` */
00044     XI_WSS,
00045 } xi_protocol_t;
00046 
00047 /**
00048  * \brief   _The context structure_ - it's the first agument for all functions
00049  *          that communicate with Xively API (_i.e. not helpers or utilities_)
00050  */
00051 typedef struct {
00052     char *api_key; /** Xively API key */
00053     xi_protocol_t protocol; /** Xively protocol */
00054     int32_t feed_id; /** Xively feed ID */
00055 } xi_context_t;
00056 
00057 /**
00058  * \brief HTTP headers
00059  */
00060 typedef enum
00061 {
00062     /** `Date` */
00063     XI_HTTP_HEADER_DATE = 0,
00064     /** `Content-Type` */
00065     XI_HTTP_HEADER_CONTENT_TYPE,
00066     /** `Content-Length` */
00067     XI_HTTP_HEADER_CONTENT_LENGTH,
00068     /** `Connection` */
00069     XI_HTTP_HEADER_CONNECTION,
00070     /** `X-Request-Id` */
00071     XI_HTTP_HEADER_X_REQUEST_ID,
00072     /** `Cache-Control` */
00073     XI_HTTP_HEADER_CACHE_CONTROL,
00074     /** `Vary` */
00075     XI_HTTP_HEADER_VARY,
00076     /** `Count` */
00077     XI_HTTP_HEADER_COUNT,
00078     /** `Age` */
00079     XI_HTTP_HEADER_AGE,
00080     // must go before the last here
00081     XI_HTTP_HEADER_UNKNOWN,
00082     // must be the last here
00083     XI_HTTP_HEADERS_COUNT
00084 } http_header_type_t;
00085 
00086 /** Datapoint value types */
00087 typedef enum
00088 {   /** 32-bit signed integer */
00089     XI_VALUE_TYPE_I32 = 0,
00090     /** 32-bit floating point number */
00091     XI_VALUE_TYPE_F32,
00092     /** any string-econded data */
00093     XI_VALUE_TYPE_STR,
00094     XI_VALUE_TYPE_COUNT
00095 } xi_value_type_t;
00096 
00097 typedef struct {
00098     http_header_type_t  header_type;
00099     char                name[ XI_HTTP_HEADER_NAME_MAX_SIZE ];
00100     char                value[ XI_HTTP_HEADER_VALUE_MAX_SIZE ];
00101 } http_header_t;
00102 
00103 typedef struct {
00104     int             http_version1;
00105     int             http_version2;
00106     int             http_status;
00107     char            http_status_string[ XI_HTTP_STATUS_STRING_SIZE ];
00108     http_header_t*  http_headers_checklist[ XI_HTTP_HEADERS_COUNT ];
00109     http_header_t   http_headers[ XI_HTTP_MAX_HEADERS ];
00110     size_t          http_headers_size;
00111     char            http_content[ XI_HTTP_MAX_CONTENT_SIZE ];
00112 } http_response_t;
00113 
00114 /**
00115  * \brief   _The response structure_ - it's the return type for all functions
00116  *          that communicate with Xively API (_i.e. not helpers or utilities_)
00117  */
00118 typedef struct {
00119     http_response_t http;
00120 } xi_response_t;
00121 
00122 /**
00123  * \brief   The datapoint value union
00124  */
00125 typedef union {
00126     int32_t i32_value;
00127     float   f32_value;
00128     char    str_value[ XI_VALUE_STRING_MAX_SIZE ];
00129 } xi_datapoint_value_t;
00130 
00131 /**
00132  * \brief   The datapoint timestamp
00133  */
00134 typedef struct {
00135     time_t timestamp;
00136     time_t micro;
00137 } xi_timestamp_t;
00138 
00139 /**
00140  * \brief   _Xively datapoint structure_ - it contains value and timestamp
00141  * \note    A zero-valued timestamp is used by most functions as a convention
00142  *          to opt for server-side timestamps.
00143  */
00144 typedef struct {
00145     xi_datapoint_value_t  value;
00146     xi_value_type_t       value_type;
00147     xi_timestamp_t        timestamp;
00148 } xi_datapoint_t;
00149 
00150 typedef struct {
00151     char              datastream_id[ XI_MAX_DATASTREAM_NAME ];
00152     size_t            datapoint_count;
00153     xi_datapoint_t    datapoints[ XI_MAX_DATAPOINTS ];
00154 } xi_datastream_t;
00155 
00156 /**
00157  * \brief   _Xively feed structure_ - it contains a fixed array of datastream
00158  * \note    The implementation is such that user will need to know in advance
00159  *          how many datastreams there can be, which should be sufficent for
00160  *          a real-world application. It's also undesired to have some devices
00161  *          create dozens of datastreams due to a bug.
00162  */
00163 typedef struct {
00164     int32_t           feed_id;
00165     size_t            datastream_count;
00166     xi_datastream_t   datastreams[ XI_MAX_DATASTREAMS ];
00167 } xi_feed_t;
00168 
00169 //-----------------------------------------------------------------------
00170 // HELPER FUNCTIONS
00171 //-----------------------------------------------------------------------
00172 
00173 /**
00174  * \brief   Sets the xi_datapoint_t value field to `int32_t` value
00175  *
00176  * \return  Pointer or `0` if an error occurred.
00177  */
00178 extern xi_datapoint_t* xi_set_value_i32( xi_datapoint_t* dp, int32_t v );
00179 
00180 /**
00181  * \brief   Sets the `xi_datapoint_t` value field to `float` value
00182  * \return  Pointer or `0` if an error occurred.
00183  */
00184 extern xi_datapoint_t* xi_set_value_f32( xi_datapoint_t* dp, float v );
00185 
00186 /**
00187  * \brief   Sets the `xi_datapoint_t` value field to zero-terminated string value
00188  *
00189  * \return  Pointer or `0` if an error occurred.
00190  */
00191 extern xi_datapoint_t* xi_set_value_str( xi_datapoint_t* dp, const char* v );
00192 
00193 /**
00194  * \brief   Sets the timeout for network operations
00195  *
00196  * \note    The timeout is used by the comunication layer
00197  *          to determine whenever it should treat the lag
00198  *          in a connection as an error, so if your device
00199  *          or your connection is slow, you can try to increase
00200  *          the timeout for network operations. It only affects the
00201  *          send/recv operations it does not work with connect but that
00202  *          behaviour may differ between platforms and communication
00203  *          layer imlementations.
00204  */
00205 extern void xi_set_network_timeout( uint32_t milliseconds );
00206 
00207 /**
00208  * \brief   Gets the current network timeout
00209  */
00210 extern uint32_t xi_get_network_timeout( void );
00211 
00212 //-----------------------------------------------------------------------
00213 // MAIN LIBRARY FUNCTIONS
00214 //-----------------------------------------------------------------------
00215 
00216 /**
00217  * \brief   Library context constructor
00218  *
00219  *   The purpose of this function is to allocate memory and initialise the
00220  *   data structures needed in order to use any other library functions.
00221  *
00222  * \return  Initialised context structure or `0` if an error occurred
00223  */
00224 extern xi_context_t* xi_create_context(
00225           xi_protocol_t protocol, const char* api_key
00226         , int32_t feed_id );
00227 
00228 /**
00229  * \brief   Library context destructor
00230  *
00231  *   The purpose of this fucntion is to free all allocated resources
00232  *   when the application is intending to terminate or stop using the library.
00233  */
00234 extern void xi_delete_context( xi_context_t* context );
00235 
00236 
00237 /**
00238  * \brief   Update Xively feed
00239  */
00240 extern const xi_response_t* xi_feed_update(
00241           xi_context_t* xi
00242         , const xi_feed_t* value );
00243 
00244 /**
00245  * \brief   Retrieve Xively feed
00246  */
00247 extern const xi_response_t* xi_feed_get(
00248           xi_context_t* xi
00249         , xi_feed_t* value );
00250 
00251 /**
00252  * \brief   Create a datastream with given value using server timestamp
00253  */
00254 extern const xi_response_t* xi_datastream_create(
00255           xi_context_t* xi, int32_t feed_id
00256         , const char * datastream_id
00257         , const xi_datapoint_t* value);
00258 
00259 /**
00260  * \brief   Update a datastream with given datapoint using server or local timestamp
00261  */
00262 extern const xi_response_t* xi_datastream_update(
00263           xi_context_t* xi, int32_t feed_id
00264         , const char * datastream_id
00265         , const xi_datapoint_t* value );
00266 
00267 /**
00268  * \brief   Retrieve latest datapoint from a given datastream
00269  */
00270 extern const xi_response_t* xi_datastream_get(
00271           xi_context_t* xi, int32_t feed_id
00272         , const char * datastream_id, xi_datapoint_t* dp );
00273 
00274 /**
00275  * \brief   Delete datastream
00276  * \warning This function destroys the data in Xively and there is no way to restore it!
00277  */
00278 extern const xi_response_t* xi_datastream_delete(
00279           xi_context_t* xi, int feed_id
00280           , const char* datastream_id );
00281 
00282 /**
00283  * \brief   Delete datapoint at a given timestamp
00284  * \warning This function destroys the data in Xively and there is no way to restore it!
00285  * \note    You need to provide exact timestamp value to guarantee successful response
00286  *          from the API, i.e. it will respond with error 404 if datapoint didn't exist.
00287  *          If you need to determine the exact timestamp, it may be easier to call
00288  *          `xi_datapoint_delete_range()` with short range instead.
00289  */
00290 extern const xi_response_t* xi_datapoint_delete(
00291           const xi_context_t* xi, int feed_id
00292         , const char * datastream_id
00293         , const xi_datapoint_t* dp );
00294 
00295 /**
00296  * \brief   Delete all datapoints in given time range
00297  * \warning This function destroys the data in Xively and there is no way to restore it!
00298  */
00299 extern const xi_response_t* xi_datapoint_delete_range(
00300           const xi_context_t* xi, int feed_id, const char * datastream_id
00301         , const xi_timestamp_t* start, const xi_timestamp_t* end );
00302 
00303 #ifdef __cplusplus
00304 }
00305 #endif
00306 
00307 #endif // __XI_H__