SmartRest.h

00001 /*
00002  * SmartRest.h
00003  *
00004  * Created on: Nov 1, 2013
00005  * * Authors: Vincent Wochnik <v.wochnik@gmail.com>
00006  *
00007  * Copyright (c) 2013 Cumulocity GmbH
00008  *
00009  * Permission is hereby granted, free of charge, to any person obtaining
00010  * a copy of this software and associated documentation files (the
00011  * "Software"), to deal in the Software without restriction, including
00012  * without limitation the rights to use, copy, modify, merge, publish,
00013  * distribute, sublicense, and/or sell copies of the Software, and to
00014  * permit persons to whom the Software is furnished to do so, subject to
00015  * the following conditions:
00016  *
00017  * The above copyright notice and this permission notice shall be
00018  * included in all copies or substantial portions of the Software.
00019  *
00020  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00021  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00022  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00023  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
00024  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
00025  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00026  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00027  */
00028 
00029 /**
00030  * @file SmartRest.h
00031  * The main SmartRest facade class. This class is abstract, because the
00032  * actual implementation has to supply a client.
00033  */
00034 
00035 #ifndef SMARTREST_H
00036 #define SMARTREST_H
00037 
00038 #ifdef HAVE_CONFIG_H
00039 #include <config.h>
00040 #endif
00041 
00042 #include <stddef.h>
00043 #include <stdint.h>
00044 #include "AbstractClient.h"
00045 #include "ParsedRecord.h"
00046 #include "Parser.h"
00047 
00048 #ifndef SMARTREST_MOGID_BUFFER_SIZE
00049 #define SMARTREST_MOGID_BUFFER_SIZE 11
00050 #endif
00051 
00052 /** Return value indicating that no error occurred. */
00053 #define SMARTREST_SUCCESS 0
00054 /** Return value indicating that the connection has been closed during
00055  * data transmission. */
00056 #define SMARTREST_CONNECTION_FAILED 1
00057 /** Return value indicating an internal state error. */
00058 #define SMARTREST_INTERNAL_ERROR 2
00059 /** Return value indicating a transmission timeout. */
00060 #define SMARTREST_TIMEOUT_ERROR 3
00061 /** Return value indicating an end of response indicated by the
00062  * Content-Length header. */
00063 #define SMARTREST_END_OF_RESPONSE 4
00064 /** Return value indicating that the connection has been closed. */
00065 #define SMARTREST_CONNECTION_CLOSED 5
00066 
00067 /**
00068  * SmartRest Arduino client implementation.
00069  * This class provides methods to send a request and receive a response
00070  * from the server.
00071  */
00072 class SmartRest
00073 {
00074 protected:
00075     /**
00076      * Creates a new GenericSmartRest object.
00077      * @param client the abstract client to use
00078      * @param identifier the device identifier
00079      */
00080     SmartRest(AbstractClient&, const char*);
00081 
00082 public:
00083     virtual ~SmartRest() { };
00084 
00085     /**
00086      * Sends a smart request.
00087      * @param generator the generator which will generate the data to be
00088      *                  sent.
00089      * @return a non-zero value if and only if an error occured
00090      */
00091     int8_t send(DataGenerator&);
00092 
00093     /**
00094      * Tries to receive a parsed response row.
00095      * When the function succeeds, but the row pointer is NULL, there are
00096      * no more rows to be read.
00097      * @param record an instance to where the parsed row is written
00098      * @return a non-zero value if and only if an error occured
00099      */
00100     int8_t receive(ParsedRecord&);
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     int8_t bootstrap(DataGenerator&);
00111 
00112     /*
00113      * Closes the connection.
00114      */
00115     void stop();
00116 
00117 private:
00118     uint8_t beginRequest();
00119     uint8_t awaitResponse();
00120     bool setMoGid(Record&);
00121 
00122 private:
00123     AbstractClient& _client;
00124     AbstractDataSource *_source;
00125     Parser _parser;
00126     const char *_identifier;
00127     char _mogid[SMARTREST_MOGID_BUFFER_SIZE];
00128 };
00129 
00130 #endif