mbed.org implementation of the abstract SmartREST library for the Cumulocity Platform SmartREST protocol.

Dependents:   MbedSmartRestMain MbedSmartRestMain

Committer:
Cumulocity
Date:
Sat Nov 15 12:21:41 2014 +0100
Revision:
13:aba98ad2ac1b
Parent:
11:e1bee9a77652
Updated from revision 0b898f0efc6d

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Cumulocity 6:cd7ba1ddb664 1 #ifndef ABSTRACTSMARTREST_H
Cumulocity 6:cd7ba1ddb664 2 #define ABSTRACTSMARTREST_H
Cumulocity 6:cd7ba1ddb664 3
Cumulocity 6:cd7ba1ddb664 4 #include "config.h"
Cumulocity 6:cd7ba1ddb664 5 #include <stddef.h>
Cumulocity 6:cd7ba1ddb664 6 #include <stdint.h>
Cumulocity 6:cd7ba1ddb664 7 #include "DataGenerator.h"
Cumulocity 6:cd7ba1ddb664 8 #include "ParsedRecord.h"
Cumulocity 6:cd7ba1ddb664 9 #ifdef SMARTREST_TRANSACTIONAL
Cumulocity 6:cd7ba1ddb664 10 #include "Aggregator.h"
Cumulocity 6:cd7ba1ddb664 11 #endif
Cumulocity 6:cd7ba1ddb664 12
Cumulocity 6:cd7ba1ddb664 13 /** Return value indicating that no error occurred. */
Cumulocity 6:cd7ba1ddb664 14 #define SMARTREST_SUCCESS 0
Cumulocity 6:cd7ba1ddb664 15 /** Return value indicating that the connection has been closed during
Cumulocity 6:cd7ba1ddb664 16 * data transmission. */
Cumulocity 6:cd7ba1ddb664 17 #define SMARTREST_CONNECTION_FAILED 1
Cumulocity 6:cd7ba1ddb664 18 /** Return value indicating an internal state error. */
Cumulocity 6:cd7ba1ddb664 19 #define SMARTREST_INTERNAL_ERROR 2
Cumulocity 6:cd7ba1ddb664 20 /** Return value indicating a transmission timeout. */
Cumulocity 6:cd7ba1ddb664 21 #define SMARTREST_TIMEOUT_ERROR 3
Cumulocity 6:cd7ba1ddb664 22 /** Return value indicating an end of response indicated by the
Cumulocity 6:cd7ba1ddb664 23 * Content-Length header. */
Cumulocity 6:cd7ba1ddb664 24 #define SMARTREST_END_OF_RESPONSE 4
Cumulocity 6:cd7ba1ddb664 25 /** Return value indicating that the connection has been closed. */
Cumulocity 6:cd7ba1ddb664 26 #define SMARTREST_CONNECTION_CLOSED 5
Cumulocity 6:cd7ba1ddb664 27
Cumulocity 6:cd7ba1ddb664 28 /**
Cumulocity 6:cd7ba1ddb664 29 * Abstract SmartRest facade class.
Cumulocity 6:cd7ba1ddb664 30 * This class provides methods to send a request and receive a response
Cumulocity 6:cd7ba1ddb664 31 * from the server.
Cumulocity 6:cd7ba1ddb664 32 *
Cumulocity 6:cd7ba1ddb664 33 * Example:
Cumulocity 6:cd7ba1ddb664 34 * @code
Cumulocity 6:cd7ba1ddb664 35 * // given a concrete SmartRest implementation and a template
Cumulocity 6:cd7ba1ddb664 36 * SmartRest client;
Cumulocity 6:cd7ba1ddb664 37 * StaticData template;
Cumulocity 6:cd7ba1ddb664 38 *
Cumulocity 6:cd7ba1ddb664 39 * // bootstrap
Cumulocity 6:cd7ba1ddb664 40 * if (client.bootstrap(template) != SMARTREST_SUCCESS) {
Cumulocity 6:cd7ba1ddb664 41 * // error handling
Cumulocity 6:cd7ba1ddb664 42 * return;
Cumulocity 6:cd7ba1ddb664 43 * }
Cumulocity 6:cd7ba1ddb664 44 *
Cumulocity 6:cd7ba1ddb664 45 * if (client.send(StaticData("100,Hello")) != SMARTREST_SUCCESS) {
Cumulocity 6:cd7ba1ddb664 46 * // error handling
Cumulocity 6:cd7ba1ddb664 47 * }
Cumulocity 6:cd7ba1ddb664 48 *
Cumulocity 6:cd7ba1ddb664 49 * uint8_t ret;
Cumulocity 6:cd7ba1ddb664 50 * while ((ret = client.receive(record)) == SMARTREST_SUCCESS) {
Cumulocity 6:cd7ba1ddb664 51 * // work with data
Cumulocity 6:cd7ba1ddb664 52 * }
Cumulocity 6:cd7ba1ddb664 53 *
Cumulocity 6:cd7ba1ddb664 54 * // error handling
Cumulocity 6:cd7ba1ddb664 55 *
Cumulocity 6:cd7ba1ddb664 56 * // call after every request.
Cumulocity 6:cd7ba1ddb664 57 * client.stop();
Cumulocity 6:cd7ba1ddb664 58 * @encode
Cumulocity 6:cd7ba1ddb664 59 */
Cumulocity 6:cd7ba1ddb664 60 class AbstractSmartRest
Cumulocity 6:cd7ba1ddb664 61 {
Cumulocity 11:e1bee9a77652 62 public:
Cumulocity 11:e1bee9a77652 63 virtual ~AbstractSmartRest() { };
Cumulocity 6:cd7ba1ddb664 64
Cumulocity 11:e1bee9a77652 65 /**
Cumulocity 11:e1bee9a77652 66 * Sets the client authorization.
Cumulocity 11:e1bee9a77652 67 * @param username the authorization username
Cumulocity 11:e1bee9a77652 68 * @param password the authorization password
Cumulocity 11:e1bee9a77652 69 */
Cumulocity 11:e1bee9a77652 70 virtual uint8_t setAuthorization(const char*, const char*) = 0;
Cumulocity 6:cd7ba1ddb664 71
Cumulocity 6:cd7ba1ddb664 72 #ifdef SMARTREST_TRANSACTIONAL
Cumulocity 11:e1bee9a77652 73 /**
Cumulocity 11:e1bee9a77652 74 * Performs a SmartRest request without receiving any data from the
Cumulocity 11:e1bee9a77652 75 * server.
Cumulocity 11:e1bee9a77652 76 * @param generator the generator which will generate the data to be
Cumulocity 11:e1bee9a77652 77 * sent as a template.
Cumulocity 11:e1bee9a77652 78 * @param overrideIdentifier a device identifier which gets sent instead
Cumulocity 11:e1bee9a77652 79 * of the identifier specified in the
Cumulocity 11:e1bee9a77652 80 * constructor. If an empty string is
Cumulocity 11:e1bee9a77652 81 * specified, no identifier is sent at all.
Cumulocity 11:e1bee9a77652 82 * @return a non-zero value if and only if an error occured
Cumulocity 11:e1bee9a77652 83 */
Cumulocity 11:e1bee9a77652 84 virtual uint8_t request(const DataGenerator&, const char* = NULL) = 0;
Cumulocity 6:cd7ba1ddb664 85
Cumulocity 11:e1bee9a77652 86 /**
Cumulocity 11:e1bee9a77652 87 * Performs a SmartRest request.
Cumulocity 11:e1bee9a77652 88 * @param generator the generator which will generate the data to be
Cumulocity 11:e1bee9a77652 89 * sent as a template.
Cumulocity 11:e1bee9a77652 90 * @param aggregator the aggregator where all received records will
Cumulocity 11:e1bee9a77652 91 * be stored. The aggregator must be managed,
Cumulocity 11:e1bee9a77652 92 * otherwise an error will be returned.
Cumulocity 11:e1bee9a77652 93 * @param overrideIdentifier a device identifier which gets sent instead
Cumulocity 11:e1bee9a77652 94 * of the identifier specified in the
Cumulocity 11:e1bee9a77652 95 * constructor. If an empty string is
Cumulocity 11:e1bee9a77652 96 * specified, no identifier is sent at all.
Cumulocity 11:e1bee9a77652 97 * @return a non-zero value if and only if an error occured
Cumulocity 11:e1bee9a77652 98 */
Cumulocity 11:e1bee9a77652 99 virtual uint8_t request(const DataGenerator&, Aggregator&, const char* = NULL) = 0;
Cumulocity 6:cd7ba1ddb664 100 #endif
Cumulocity 6:cd7ba1ddb664 101
Cumulocity 11:e1bee9a77652 102 /*
Cumulocity 11:e1bee9a77652 103 * Initiates the SmartRest bootstrap process.
Cumulocity 11:e1bee9a77652 104 * When successful, the template identifier will be replaced by the
Cumulocity 11:e1bee9a77652 105 * global managed object ID in future requests.
Cumulocity 11:e1bee9a77652 106 * @param generator the generator which will generate the data to be
Cumulocity 11:e1bee9a77652 107 * sent as a template.
Cumulocity 11:e1bee9a77652 108 * @return a non-zero value if and only if an error occured
Cumulocity 11:e1bee9a77652 109 */
Cumulocity 11:e1bee9a77652 110 virtual uint8_t bootstrap(const DataGenerator&) = 0;
Cumulocity 6:cd7ba1ddb664 111
Cumulocity 11:e1bee9a77652 112 /**
Cumulocity 11:e1bee9a77652 113 * Sends a smart request.
Cumulocity 11:e1bee9a77652 114 * @param generator the generator which will generate the data to be
Cumulocity 11:e1bee9a77652 115 * sent.
Cumulocity 11:e1bee9a77652 116 * @param overrideIdentifier a device identifier which gets sent instead
Cumulocity 11:e1bee9a77652 117 * of the identifier specified in the
Cumulocity 11:e1bee9a77652 118 * constructor. If an empty string is
Cumulocity 11:e1bee9a77652 119 * specified, no identifier is sent at all.
Cumulocity 11:e1bee9a77652 120 * @return a non-zero value if and only if an error occured
Cumulocity 11:e1bee9a77652 121 */
Cumulocity 11:e1bee9a77652 122 virtual uint8_t send(const DataGenerator&, const char* = NULL) = 0;
Cumulocity 6:cd7ba1ddb664 123
Cumulocity 11:e1bee9a77652 124 /**
Cumulocity 13:aba98ad2ac1b 125 * Starts a SmartRest stream.
Cumulocity 13:aba98ad2ac1b 126 * @param uri the stream endpoint URI
Cumulocity 13:aba98ad2ac1b 127 * @param record the record which will be sent to the endpoint
Cumulocity 13:aba98ad2ac1b 128 * @param overrideIdentifier a device identifier which gets sent instead
Cumulocity 13:aba98ad2ac1b 129 * of the identifier specified in the
Cumulocity 13:aba98ad2ac1b 130 * constructor. If an empty string is
Cumulocity 13:aba98ad2ac1b 131 * specified, no identifier is sent at all.
Cumulocity 13:aba98ad2ac1b 132 * @return a non-zero value if and only if an error occured
Cumulocity 13:aba98ad2ac1b 133 */
Cumulocity 13:aba98ad2ac1b 134 virtual uint8_t stream(const char*, const Record&, const char* = NULL) = 0;
Cumulocity 13:aba98ad2ac1b 135
Cumulocity 13:aba98ad2ac1b 136 /**
Cumulocity 11:e1bee9a77652 137 * Tries to receive a parsed response row.
Cumulocity 11:e1bee9a77652 138 * When the function succeeds, but the row pointer is NULL, there are
Cumulocity 11:e1bee9a77652 139 * no more rows to be read.
Cumulocity 11:e1bee9a77652 140 * @param record an instance to where the parsed row is written
Cumulocity 11:e1bee9a77652 141 * @return a non-zero value if and only if an error occured
Cumulocity 11:e1bee9a77652 142 */
Cumulocity 11:e1bee9a77652 143 virtual uint8_t receive(ParsedRecord&) = 0;
Cumulocity 6:cd7ba1ddb664 144
Cumulocity 11:e1bee9a77652 145 /*
Cumulocity 11:e1bee9a77652 146 * Closes the connection.
Cumulocity 11:e1bee9a77652 147 */
Cumulocity 11:e1bee9a77652 148 virtual void stop() = 0;
Cumulocity 7:8159a2d12e4e 149
Cumulocity 11:e1bee9a77652 150 /*
Cumulocity 11:e1bee9a77652 151 * Retrieves the template identifier.
Cumulocity 11:e1bee9a77652 152 * @return template identifier
Cumulocity 11:e1bee9a77652 153 */
Cumulocity 11:e1bee9a77652 154 virtual const char * getIdentifier() = 0;
Cumulocity 6:cd7ba1ddb664 155 };
Cumulocity 6:cd7ba1ddb664 156
Cumulocity 6:cd7ba1ddb664 157 #endif