Xinlei Cao / MbedSmartRest

Own fork of MbedSmartRest

Dependents:   MbedSmartRestMain MbedSmartRestMain

Fork of MbedSmartRest by Cumulocity Official

AbstractSmartRest.h@6:cd7ba1ddb664, 2014-07-28 (annotated)

Committer:
Cumulocity
Date:
Mon Jul 28 12:11:02 2014 +0200
Revision:
6:cd7ba1ddb664
Child:
7:8159a2d12e4e
Updated from revision 908949dc5088

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 6:cd7ba1ddb664 62 public:
Cumulocity 6:cd7ba1ddb664 63 virtual ~AbstractSmartRest() { };
Cumulocity 6:cd7ba1ddb664 64
Cumulocity 6:cd7ba1ddb664 65 /**
Cumulocity 6:cd7ba1ddb664 66 * Sets the client authorization.
Cumulocity 6:cd7ba1ddb664 67 * @param username the authorization username
Cumulocity 6:cd7ba1ddb664 68 * @param password the authorization password
Cumulocity 6:cd7ba1ddb664 69 */
Cumulocity 6:cd7ba1ddb664 70 virtual uint8_t setAuthorization(const char*, const char*) = 0;
Cumulocity 6:cd7ba1ddb664 71
Cumulocity 6:cd7ba1ddb664 72 #ifdef SMARTREST_TRANSACTIONAL
Cumulocity 6:cd7ba1ddb664 73 /**
Cumulocity 6:cd7ba1ddb664 74 * Performs a SmartRest request without receiving any data from the
Cumulocity 6:cd7ba1ddb664 75 * server.
Cumulocity 6:cd7ba1ddb664 76 * @param generator the generator which will generate the data to be
Cumulocity 6:cd7ba1ddb664 77 * sent as a template.
Cumulocity 6:cd7ba1ddb664 78 * @param overrideIdentifier a device identifier which gets sent instead
Cumulocity 6:cd7ba1ddb664 79 * of the identifier specified in the
Cumulocity 6:cd7ba1ddb664 80 * constructor. If an empty string is
Cumulocity 6:cd7ba1ddb664 81 * specified, no identifier is sent at all.
Cumulocity 6:cd7ba1ddb664 82 * @return a non-zero value if and only if an error occured
Cumulocity 6:cd7ba1ddb664 83 */
Cumulocity 6:cd7ba1ddb664 84 virtual uint8_t request(const DataGenerator&, const char* = NULL) = 0;
Cumulocity 6:cd7ba1ddb664 85
Cumulocity 6:cd7ba1ddb664 86 /**
Cumulocity 6:cd7ba1ddb664 87 * Performs a SmartRest request.
Cumulocity 6:cd7ba1ddb664 88 * @param generator the generator which will generate the data to be
Cumulocity 6:cd7ba1ddb664 89 * sent as a template.
Cumulocity 6:cd7ba1ddb664 90 * @param aggregator the aggregator where all received records will
Cumulocity 6:cd7ba1ddb664 91 * be stored. The aggregator must be managed,
Cumulocity 6:cd7ba1ddb664 92 * otherwise an error will be returned.
Cumulocity 6:cd7ba1ddb664 93 * @param overrideIdentifier a device identifier which gets sent instead
Cumulocity 6:cd7ba1ddb664 94 * of the identifier specified in the
Cumulocity 6:cd7ba1ddb664 95 * constructor. If an empty string is
Cumulocity 6:cd7ba1ddb664 96 * specified, no identifier is sent at all.
Cumulocity 6:cd7ba1ddb664 97 * @return a non-zero value if and only if an error occured
Cumulocity 6:cd7ba1ddb664 98 */
Cumulocity 6:cd7ba1ddb664 99 virtual uint8_t request(const DataGenerator&, Aggregator&, const char* = NULL) = 0;
Cumulocity 6:cd7ba1ddb664 100 #endif
Cumulocity 6:cd7ba1ddb664 101
Cumulocity 6:cd7ba1ddb664 102 /*
Cumulocity 6:cd7ba1ddb664 103 * Initiates the SmartRest bootstrap process.
Cumulocity 6:cd7ba1ddb664 104 * When successful, the template identifier will be replaced by the
Cumulocity 6:cd7ba1ddb664 105 * global managed object ID in future requests.
Cumulocity 6:cd7ba1ddb664 106 * @param generator the generator which will generate the data to be
Cumulocity 6:cd7ba1ddb664 107 * sent as a template.
Cumulocity 6:cd7ba1ddb664 108 * @return a non-zero value if and only if an error occured
Cumulocity 6:cd7ba1ddb664 109 */
Cumulocity 6:cd7ba1ddb664 110 virtual uint8_t bootstrap(const DataGenerator&) = 0;
Cumulocity 6:cd7ba1ddb664 111
Cumulocity 6:cd7ba1ddb664 112 #ifndef SMARTREST_TRANSACTIONAL
Cumulocity 6:cd7ba1ddb664 113 /**
Cumulocity 6:cd7ba1ddb664 114 * Sends a smart request.
Cumulocity 6:cd7ba1ddb664 115 * @param generator the generator which will generate the data to be
Cumulocity 6:cd7ba1ddb664 116 * sent.
Cumulocity 6:cd7ba1ddb664 117 * @param overrideIdentifier a device identifier which gets sent instead
Cumulocity 6:cd7ba1ddb664 118 * of the identifier specified in the
Cumulocity 6:cd7ba1ddb664 119 * constructor. If an empty string is
Cumulocity 6:cd7ba1ddb664 120 * specified, no identifier is sent at all.
Cumulocity 6:cd7ba1ddb664 121 * @return a non-zero value if and only if an error occured
Cumulocity 6:cd7ba1ddb664 122 */
Cumulocity 6:cd7ba1ddb664 123 virtual uint8_t send(const DataGenerator&, const char* = NULL) = 0;
Cumulocity 6:cd7ba1ddb664 124
Cumulocity 6:cd7ba1ddb664 125 /**
Cumulocity 6:cd7ba1ddb664 126 * Tries to receive a parsed response row.
Cumulocity 6:cd7ba1ddb664 127 * When the function succeeds, but the row pointer is NULL, there are
Cumulocity 6:cd7ba1ddb664 128 * no more rows to be read.
Cumulocity 6:cd7ba1ddb664 129 * @param record an instance to where the parsed row is written
Cumulocity 6:cd7ba1ddb664 130 * @return a non-zero value if and only if an error occured
Cumulocity 6:cd7ba1ddb664 131 */
Cumulocity 6:cd7ba1ddb664 132 virtual uint8_t receive(ParsedRecord&) = 0;
Cumulocity 6:cd7ba1ddb664 133
Cumulocity 6:cd7ba1ddb664 134 /*
Cumulocity 6:cd7ba1ddb664 135 * Closes the connection.
Cumulocity 6:cd7ba1ddb664 136 */
Cumulocity 6:cd7ba1ddb664 137 virtual void stop() = 0;
Cumulocity 6:cd7ba1ddb664 138 #endif
Cumulocity 6:cd7ba1ddb664 139 };
Cumulocity 6:cd7ba1ddb664 140
Cumulocity 6:cd7ba1ddb664 141 #endif