RemoteDataStoreAPI.h

00001 /*******************************************************************
00002  *
00003  *  File: RemoteDataStoreAPI.h
00004  *
00005  *  Description: Remote DataStore API definition
00006  *
00007  *  Copyright 2015 Innomatix, LLC., All Rights Reserved
00008  *
00009  *  THIS DOCUMENT AND ITS CONTENTS ARE INTELLECTUAL PROPERTY
00010  *  OF INNOMATIX, LLC.  ANY DUPLICATION IN PART OR WHOLE
00011  *  WITHOUT PRIOR WRITTEN CONSENT IS STRICTLY PROHIBITED.
00012  *
00013  *******************************************************************/
00014 #ifndef _REMOTEDATASTOREAPI_H_
00015 #define _REMOTEDATASTOREAPI_H_
00016 
00017 typedef enum 
00018 {
00019     rdsSuccess,
00020     rdsNoConnection,
00021     rdsNotAllowed,
00022     rdsServerFull,
00023     rdsInvalidBin,
00024     rdsNoData,
00025     rdsTooBig,
00026     rdsBadParameter,
00027     rdsIncompatibleType,
00028     rdsInUse,
00029     rdsReadOnly,
00030     rdsGeneralError
00031 }RdsResults_e;
00032 
00033 
00034 // Information about a data bin
00035 typedef struct
00036 {
00037     unsigned int BinId;
00038     unsigned char BinDataType;      // Store as uchar instead of DataType so 
00039                                     // we dont have to include rdsdefinds.h  
00040     char BinName[ 64 ];  /* NULL terminated */
00041 
00042 }BinInfoStruct_t;
00043 
00044 
00045 // Since storage for the data bin is a short, 
00046 #define BinId_None  ((unsigned int)-1)
00047 
00048 
00049 /**
00050 * Initialize the Remote DataStore API and establish a connection to the server 
00051 *
00052 * @retval RdsResults_e - 
00053 *   •   rdsSuccess – a connection was established
00054 *   •   rdsNoConnection – the timeout expired without a connection
00055 ***************************************************************************************************************************/
00056 RdsResults_e DataStoreInit( const char *addr, unsigned short port );
00057 
00058 /**
00059 * Close the host connection and shut down the Remote DataStore API 
00060 **************************************************************************************************************************/
00061 void DataStoreClose();
00062 
00063 /**
00064 * Retrieve information from the server about the named data bin  
00065 *
00066 * @param binName - name of bin of interest
00067 * @param BinInfoStruct - structure to be populated with the data bin info
00068 * @retval RdsResults_e - 
00069 *   • rdsSuccess – the BinInfoStruct has been filled with information about the requested data bin
00070 *   • resNoConnection – the connection has been lost, or the timeout expired with no response 
00071 *                   from the server
00072 *   • rdsInvalidDataBin – a data bin with the given name does not exist
00073 *   • rdsGeneralError – an unknown or unspecified error has occurred
00074 *
00075 **************************************************************************************************************************/
00076 RdsResults_e GetDataBinInfo(const char *Name, BinInfoStruct_t *Info);
00077 
00078 /**
00079 * Retrieve the current value from a data bin
00080 *
00081 * @param BinId - Bin ID as returned by GetBinInfo
00082 * @param Value - value retrieved from the data bin 
00083 * @param Timestamp - system-relative timestamp that the data bin was last udpated
00084 *                       NOTE: the value may not coorelate to clock-time.  Checking
00085 *                       the value against a previously-saved timestamp indicates
00086 *                       the data bin has been updated since the previous timestamp 
00087 *                       was saved.
00088 * @retval RdsResults_e - 
00089 *   •   rdsSuccess – the Value and Timestamp parameters have been filled
00090 *   •   rdsNoConnection – the connection has been lost, or the timeout expired with no response from the server
00091 *   •   rdsInvalidBin – a data bin with the given ID does not exist
00092 *   •   rdsIncompatibleType – the specified data bin is not of the requested type and the data bin value cannot 
00093 *                           be convereted to the requested type.
00094 *   •   rdsNoData – the specified data bin has not been written to yet
00095 *   •   rdsBadParameter – the value buffer pointer is NULL
00096 *   •   rdsTooBig – the value buffer is not big enough to hold the retrieved data, the value buffer is left unchanged
00097 *   •   rdsInUse – the requested data bin is in use by another application or client and cannot be read 
00098 *   •   rdsGeneralError – an unknown or unspecified error has occurred
00099 ***************************************************************************************************************************/
00100 RdsResults_e GetSignedInteger(unsigned int BinId, int *Value, unsigned int *Timestamp);
00101 RdsResults_e GetUnsignedInteger(unsigned int BinId, unsigned int *Value, unsigned int *Timestamp);
00102 RdsResults_e GetDouble(unsigned int BinId, double *Value, unsigned int *Timestamp);
00103 RdsResults_e GetString(unsigned int BinId, char *Str, unsigned short MaxStrLen,unsigned int *Timestamp);
00104 RdsResults_e GetBlob( unsigned int BinId, unsigned char *Blob, unsigned short MaxBlobLen, unsigned short *ActualBlobLen, unsigned int *Timestamp);
00105 
00106 /**
00107 * Put a new value into the data bin
00108 *
00109 * @param BinId - Bin ID to update, as retrieved from GetBinInfo()
00110 * @param Value - new value for the data bin 
00111 * @retval RdsResults_e - 
00112 *   •   rdsSuccess – the Value and Timestamp parameters have been filled
00113 *   •   rdsNoConnection – the connection has been lost, or the timeout expired with no response from the server
00114 *   •   rdsInvalidBin – a data bin with the given ID does not exist
00115 *   •   rdsIncompatibleType – the specified data bin is not of the requested type and the data bin value cannot 
00116 *                           be convereted to the requested type.
00117 *   •   rdsNoData – the specified data bin has not been written to yet
00118 *   •   rdsBadParameter – the value buffer pointer is NULL
00119 *   •   rdsTooBig – the value buffer is not big enough to hold the retrieved data, the value buffer is left unchanged
00120 *   •   rdsInUse – the requested data bin is in use by another application or client and cannot be read 
00121 *   •   rdsGeneralError – an unknown or unspecified error has occurred
00122 *
00123 *   example function call:  PutSignedInteger( BinId, SignedValue )
00124 ******************************************************************************************************************************/
00125 RdsResults_e PutSignedInteger(unsigned int BinId, int Value);
00126 RdsResults_e PutUnsignedInteger(unsigned int BinId, unsigned int Value);
00127 RdsResults_e PutDouble(unsigned int BinId, double Value);
00128 RdsResults_e PutString(unsigned int BinId, char *Str);
00129 RdsResults_e PutBlob( unsigned int BinId, unsigned char *Blob, unsigned short BlobLen );
00130 
00131 
00132 /**
00133 * Helper function to send a string to a pre-defined "debug log" data bin
00134 *
00135 * @param String - the message to send
00136 * @retval RdsResults_e - same as PutString()
00137 ******************************************************************************************************************************/
00138 RdsResults_e PutDebug( char *Str );
00139 
00140 
00141 #endif // _REMOTEDATASTOREAPI_H_