AbstractSmartRest.h

00001 #ifndef ABSTRACTSMARTREST_H
00002 #define ABSTRACTSMARTREST_H
00003 
00004 #include "config.h"
00005 #include <stddef.h>
00006 #include <stdint.h>
00007 #include "DataGenerator.h"
00008 #include "ParsedRecord.h"
00009 #ifdef SMARTREST_TRANSACTIONAL
00010 #include "Aggregator.h"
00011 #endif
00012 
00013 /** Return value indicating that no error occurred. */
00014 #define SMARTREST_SUCCESS 0
00015 /** Return value indicating that the connection has been closed during
00016  * data transmission. */
00017 #define SMARTREST_CONNECTION_FAILED 1
00018 /** Return value indicating an internal state error. */
00019 #define SMARTREST_INTERNAL_ERROR 2
00020 /** Return value indicating a transmission timeout. */
00021 #define SMARTREST_TIMEOUT_ERROR 3
00022 /** Return value indicating an end of response indicated by the
00023  * Content-Length header. */
00024 #define SMARTREST_END_OF_RESPONSE 4
00025 /** Return value indicating that the connection has been closed. */
00026 #define SMARTREST_CONNECTION_CLOSED 5
00027 
00028 /**
00029  * Abstract SmartRest facade class.
00030  * This class provides methods to send a request and receive a response
00031  * from the server.
00032  * 
00033  * Example:
00034  * @code
00035  * // given a concrete SmartRest implementation and a template
00036  * SmartRest client;
00037  * StaticData template;
00038  * 
00039  * // bootstrap
00040  * if (client.bootstrap(template) != SMARTREST_SUCCESS) {
00041  *     // error handling
00042  *     return;
00043  * }
00044  * 
00045  * if (client.send(StaticData("100,Hello")) != SMARTREST_SUCCESS) {
00046  *     // error handling
00047  * }
00048  * 
00049  * uint8_t ret;
00050  * while ((ret = client.receive(record)) == SMARTREST_SUCCESS) {
00051  *     // work with data
00052  * }
00053  * 
00054  * // error handling
00055  * 
00056  * // call after every request.
00057  * client.stop();
00058  * @encode
00059  */
00060 class AbstractSmartRest
00061 {
00062     public:
00063         virtual ~AbstractSmartRest() { };
00064 
00065         /**
00066          * Sets the client authorization.
00067          * @param username the authorization username
00068          * @param password the authorization password
00069          */
00070         virtual uint8_t setAuthorization(const char*, const char*) = 0;
00071 
00072 #ifdef SMARTREST_TRANSACTIONAL
00073         /**
00074          * Performs a SmartRest request without receiving any data from the
00075          * server.
00076          * @param generator the generator which will generate the data to be
00077          *                  sent as a template.
00078          * @param overrideIdentifier a device identifier which gets sent instead
00079          *                           of the identifier specified in the
00080          *                           constructor. If an empty string is
00081          *                           specified, no identifier is sent at all.
00082          * @return a non-zero value if and only if an error occured
00083          */
00084         virtual uint8_t request(const DataGenerator&, const char* = NULL) = 0;
00085 
00086         /**
00087          * Performs a SmartRest request.
00088          * @param generator the generator which will generate the data to be
00089          *                  sent as a template.
00090          * @param aggregator the aggregator where all received records will
00091          *                   be stored. The aggregator must be managed,
00092          *                   otherwise an error will be returned.
00093          * @param overrideIdentifier a device identifier which gets sent instead
00094          *                           of the identifier specified in the
00095          *                           constructor. If an empty string is
00096          *                           specified, no identifier is sent at all.
00097          * @return a non-zero value if and only if an error occured
00098          */
00099         virtual uint8_t request(const DataGenerator&, Aggregator&, const char* = NULL) = 0;
00100 #endif
00101 
00102         /*
00103          * Initiates the SmartRest bootstrap process.
00104          * When successful, the template identifier will be replaced by the
00105          * global managed object ID in future requests.
00106          * @param generator the generator which will generate the data to be
00107          *                  sent as a template.
00108          * @return a non-zero value if and only if an error occured
00109          */
00110         virtual uint8_t bootstrap(const DataGenerator&) = 0;
00111 
00112         /**
00113          * Sends a smart request.
00114          * @param generator the generator which will generate the data to be
00115          *                  sent.
00116          * @param overrideIdentifier a device identifier which gets sent instead
00117          *                           of the identifier specified in the
00118          *                           constructor. If an empty string is
00119          *                           specified, no identifier is sent at all.
00120          * @return a non-zero value if and only if an error occured
00121          */
00122         virtual uint8_t send(const DataGenerator&, const char* = NULL) = 0;
00123 
00124         /**
00125          * Starts a SmartRest stream.
00126          * @param uri the stream endpoint URI
00127          * @param record the record which will be sent to the endpoint
00128          * @param overrideIdentifier a device identifier which gets sent instead
00129          *                           of the identifier specified in the
00130          *                           constructor. If an empty string is
00131          *                           specified, no identifier is sent at all.
00132          * @return a non-zero value if and only if an error occured
00133          */
00134         virtual uint8_t stream(const char*, const Record&, const char* = NULL) = 0;
00135 
00136         /**
00137          * Tries to receive a parsed response row.
00138          * When the function succeeds, but the row pointer is NULL, there are
00139          * no more rows to be read.
00140          * @param record an instance to where the parsed row is written
00141          * @return a non-zero value if and only if an error occured
00142          */
00143         virtual uint8_t receive(ParsedRecord&) = 0;
00144 
00145         /*
00146          * Closes the connection.
00147          */
00148         virtual void stop() = 0;
00149 
00150         /*
00151          * Retrieves the template identifier.
00152          * @return template identifier
00153          */
00154         virtual const char * getIdentifier() = 0;
00155 };
00156 
00157 #endif