Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
MbedCloudClient.h
Go to the documentation of this file.
00001 // ---------------------------------------------------------------------------- 00002 // Copyright 2016-2017 ARM Ltd. 00003 // 00004 // SPDX-License-Identifier: Apache-2.0 00005 // 00006 // Licensed under the Apache License, Version 2.0 (the "License"); 00007 // you may not use this file except in compliance with the License. 00008 // You may obtain a copy of the License at 00009 // 00010 // http://www.apache.org/licenses/LICENSE-2.0 00011 // 00012 // Unless required by applicable law or agreed to in writing, software 00013 // distributed under the License is distributed on an "AS IS" BASIS, 00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00015 // See the License for the specific language governing permissions and 00016 // limitations under the License. 00017 // ---------------------------------------------------------------------------- 00018 00019 00020 #ifndef __MBED_CLOUD_CLIENT_H__ 00021 #define __MBED_CLOUD_CLIENT_H__ 00022 00023 #include <map> 00024 #include <string> 00025 #include <vector> 00026 #include "include/ServiceClient.h" 00027 #include "mbed-cloud-client/MbedCloudClientConfig.h" 00028 00029 using namespace std; 00030 class SimpleM2MResourceBase; 00031 00032 /** 00033 * \brief MbedCloudClientCallback 00034 * A callback class for informing updated object and resource value from the 00035 * LWM2M server to the user of the MbedCloudClient class. The user MUST instantiate the 00036 * class derived out of this and pass the object to MbedCloudClient::set_update_callback(). 00037 */ 00038 class MbedCloudClientCallback { 00039 00040 public: 00041 00042 /** 00043 * \brief A callback indicating that the value of the resource object is updated 00044 * by the LWM2M Cloud server. 00045 * \param base The object whose value is updated. 00046 * \param type The type of the object. 00047 */ 00048 virtual void value_updated(M2MBase *base, M2MBase::BaseType type) = 0; 00049 }; 00050 00051 00052 00053 /*! \file MbedCloudClient.h 00054 * \brief MbedCloudClient. 00055 * This class provides an interface for handling all the mbed Cloud Client Interface operations 00056 * including device provisioning, identity setup, device resource management defined in the OMA 00057 * LWM2M specifications, and update firmware. 00058 * Device resource management includes Bootstrapping, Client Registration, Device Management & 00059 * Service Enablement and Information Reporting. 00060 */ 00061 00062 class MbedCloudClient : public ServiceClientCallback { 00063 00064 public: 00065 00066 /** 00067 * \brief An enum defining different kinds of errors 00068 * that can occur during various client operations. 00069 */ 00070 typedef enum { 00071 ConnectErrorNone = 0x0, // Range reserved for Connector Error from 0x30 - 0x3FF 00072 ConnectAlreadyExists, 00073 ConnectBootstrapFailed, 00074 ConnectInvalidParameters, 00075 ConnectNotRegistered, 00076 ConnectTimeout, 00077 ConnectNetworkError, 00078 ConnectResponseParseFailed, 00079 ConnectUnknownError, 00080 ConnectMemoryConnectFail, 00081 ConnectNotAllowed, 00082 ConnectSecureConnectionFailed, 00083 ConnectDnsResolvingFailed, 00084 ConnectorFailedToStoreCredentials, 00085 ConnectorFailedToReadCredentials, 00086 ConnectorInvalidCredentials, 00087 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE 00088 UpdateWarningNoActionRequired = UpdateClient::WarningBase, // Range reserved for Update Error from 0x0400 - 0x04FF 00089 UpdateWarningCertificateNotFound = UpdateClient::WarningCertificateNotFound, 00090 UpdateWarningIdentityNotFound = UpdateClient::WarningIdentityNotFound, 00091 UpdateWarningCertificateInvalid = UpdateClient::WarningCertificateInvalid, 00092 UpdateWarningSignatureInvalid = UpdateClient::WarningSignatureInvalid, 00093 UpdateWarningVendorMismatch = UpdateClient::WarningVendorMismatch, 00094 UpdateWarningClassMismatch = UpdateClient::WarningClassMismatch, 00095 UpdateWarningDeviceMismatch = UpdateClient::WarningDeviceMismatch, 00096 UpdateWarningURINotFound = UpdateClient::WarningURINotFound, 00097 UpdateWarningRollbackProtection = UpdateClient::WarningRollbackProtection, 00098 UpdateWarningUnknown = UpdateClient::WarningUnknown, 00099 UpdateErrorUserActionRequired = UpdateClient::ErrorBase, 00100 UpdateErrorWriteToStorage = UpdateClient::ErrorWriteToStorage, 00101 UpdateErrorInvalidHash = UpdateClient::ErrorInvalidHash, 00102 UpdateFatalRebootRequired 00103 #endif 00104 }Error; 00105 00106 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE 00107 /** 00108 * \brief Enum defining authorization requests from the Update client. 00109 */ 00110 enum { 00111 UpdateRequestInvalid = UpdateClient::RequestInvalid, 00112 UpdateRequestDownload = UpdateClient::RequestDownload, 00113 UpdateRequestInstall = UpdateClient::RequestInstall 00114 }; 00115 #endif 00116 00117 /** 00118 * \brief Constructor 00119 */ 00120 MbedCloudClient(); 00121 00122 /** 00123 * \brief Destructor 00124 */ 00125 virtual ~MbedCloudClient(); 00126 00127 /** 00128 * \brief Adds a list of objects that the application wants to register to the 00129 * LWM2M server. This function MUST be called before calling the setup() 00130 * API. Otherwise, the application gets the error ConnectInvalidParameters, when 00131 * calling setup(). 00132 * \param object_list Objects that contain information about the 00133 * client attempting to register to the LWM2M server. 00134 */ 00135 void add_objects(const M2MObjectList& object_list); 00136 00137 /** 00138 * \brief Sets the callback function that is called when there is 00139 * any new update on any Object/ObjectInstance/Resource from the LWM2M server, 00140 * typically on receiving PUT commands on the registered objects. 00141 * \param callback Passes the class object that implements the callback 00142 * function to handle the incoming PUT request on a given object. 00143 */ 00144 void set_update_callback(MbedCloudClientCallback *callback); 00145 00146 /** 00147 * \brief Initiates the Cloud Client set up on the Cloud service. This 00148 * function manages device provisioning (first time usage), bootstrapping 00149 * (first time usage) and registering the client application to the Cloud 00150 * service. 00151 * \param iface A handler to the network interface on mbedOS, can be NULL on 00152 * other platforms. 00153 */ 00154 bool setup(void* iface); 00155 00156 /** 00157 * \brief Sets the callback function that is called when the client is registered 00158 * successfully to the Cloud. This is used for a statically defined function. 00159 * \param fn A function pointer to the function that is called when the client 00160 * is registered. 00161 */ 00162 void on_registered(void(*fn)(void)); 00163 00164 /** 00165 * \brief Sets the callback function that is called when the client is registered 00166 * successfully to the Cloud. This is an overloaded function for a class function. 00167 * \param object A function pointer to the function that is called when the client 00168 * is registered. 00169 */ 00170 template<typename T> 00171 void on_registered(T *object, void (T::*member)(void)); 00172 00173 /** 00174 * \brief Sets the callback function that is called when there is any error 00175 * occuring in the client functionality. The error code can be mapped from the 00176 * MbedCloudClient::Error enum. This is used for a statically defined function. 00177 * \param fn A function pointer to the function that is called when there 00178 * is any error in the client. 00179 */ 00180 void on_error(void(*fn)(int)); 00181 00182 /** 00183 * \brief Sets the callback function that is called when there is an error 00184 * occuring in the client functionality. The error code can be mapped from 00185 * MbedCloudClient::Error enum. This is an overloaded function for a class function. 00186 * \param object A function pointer to the function that is called when there 00187 * is an error in the client. 00188 */ 00189 template<typename T> 00190 void on_error(T *object, void (T::*member)(int)); 00191 00192 /** 00193 * \brief Sets the callback function that is called when the client is unregistered 00194 * successfully from the Cloud. This is used for a statically defined function. 00195 * \param fn A function pointer to the function that is called when the client 00196 * is unregistered. 00197 */ 00198 void on_unregistered(void(*fn)(void)); 00199 00200 /** 00201 * \brief Sets the callback function that is called when the client is unregistered 00202 * successfully from the Cloud. This is an overloaded function for a class function. 00203 * \param object A function pointer to the function that is called when the client 00204 * is unregistered. 00205 */ 00206 template<typename T> 00207 void on_unregistered(T *object, void (T::*member)(void)); 00208 00209 /** 00210 * \brief Sets the callback function that is called when the client registration 00211 * is updated successfully to the Cloud. This is used for a statically defined function. 00212 * \param fn A function pointer to the function that is called when the client 00213 * registration is updated. 00214 */ 00215 void on_registration_updated(void(*fn)(void)); 00216 00217 /** 00218 * \brief Sets the callback function that is called when the client registration 00219 * is updated successfully to the Cloud. This is an overloaded function for a class 00220 * function. 00221 * \param object A function pointer to the function that is called when the client 00222 * registration is updated. 00223 */ 00224 template<typename T> 00225 void on_registration_updated(T *object, void (T::*member)(void)); 00226 00227 /** 00228 * \brief Sends a registration update message to the Cloud when the client is registered 00229 * successfully to the Cloud and there is no internal connection error. 00230 * If the client is not connected and there is some other internal network 00231 * transaction ongoing, this function triggers an error MbedCloudClient::ConnectNotAllowed. 00232 * \deprecated 00233 */ 00234 void keep_alive() m2m_deprecated; 00235 00236 /** 00237 * \brief Sends a registration update message to the Cloud when the client is registered 00238 * successfully to the Cloud and there is no internal connection error. 00239 * If the client is not connected and there is some other internal network 00240 * transaction ongoing, this function triggers an error MbedCloudClient::ConnectNotAllowed. 00241 */ 00242 void register_update(); 00243 00244 /** 00245 * \brief Closes the connection towards Cloud and unregisters the client. 00246 * This function triggers the on_unregistered() callback if set by the application. 00247 */ 00248 void close(); 00249 00250 /** 00251 * \brief Returns pointer to the ConnectorClientEndpointInfo object. 00252 * \return ConnectorClientEndpointInfo pointer. 00253 */ 00254 const ConnectorClientEndpointInfo *endpoint_info() const; 00255 00256 /** 00257 * \brief Sets the function that is called for indicating that the client 00258 * is going to sleep when the binding mode is selected with queue mode. 00259 * \param callback A function pointer that is called when the client 00260 * goes to sleep. 00261 */ 00262 void set_queue_sleep_handler(callback_handler handler); 00263 00264 /** 00265 * \brief Sets the function callback that is called by client to 00266 * fetch a random number from an application to ensure strong entropy. 00267 * \param random_callback A function pointer that is called by client 00268 * while performing a secure handshake. 00269 * The function signature should be uint32_t (*random_number_callback)(void); 00270 */ 00271 void set_random_number_callback(random_number_cb callback); 00272 00273 /** 00274 * \brief Sets the function callback that is called by client to 00275 * provide an entropy source from an application to ensure strong entropy. 00276 * \param entropy_callback A function pointer that is called by mbed Client 00277 * while performing a secure handshake. 00278 * Function signature, if using mbed-client-mbedtls, should be 00279 * int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output, 00280 * size_t len, size_t *olen); 00281 */ 00282 void set_entropy_callback(entropy_cb callback); 00283 00284 /** 00285 * \brief Set resource value in the Device Object 00286 * 00287 * \param resource Device enum to have value set. 00288 * \param value String object. 00289 * \return True if successful, false otherwise. 00290 */ 00291 bool set_device_resource_value(M2MDevice::DeviceResource resource, 00292 const std::string &value); 00293 00294 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE 00295 /** 00296 * \brief Registers a callback function for authorizing firmware downloads and reboots. 00297 * \param handler Callback function. 00298 */ 00299 void set_update_authorize_handler(void (*handler)(int32_t request)); 00300 00301 /** 00302 * \brief Authorize request passed to authorization handler. 00303 * \param request Request being authorized. 00304 */ 00305 void update_authorize(int32_t request); 00306 00307 /** 00308 * \brief Registers a callback function for monitoring download progress. 00309 * \param handler Callback function. 00310 */ 00311 void set_update_progress_handler(void (*handler)(uint32_t progress, uint32_t total)); 00312 #endif 00313 00314 /** 00315 * @brief Return error description for the latest error code 00316 * @return Error description string 00317 */ 00318 const char *error_description() const; 00319 00320 protected: // from ServiceClientCallback 00321 00322 /** 00323 * \brief Indicates that the setup or close operation is complete 00324 * with success or failure. 00325 * \param status Indicates success or failure in terms of status code. 00326 */ 00327 virtual void complete(ServiceClientCallbackStatus status); 00328 00329 /** 00330 * \brief Indicates an error condition from the underlying clients like 00331 * identity, connector or update client. 00332 * \param error Indicates an error code translated to MbedCloudClient::Error. 00333 * \param reason, Indicates human readable text for error description. 00334 */ 00335 virtual void error(int error, const char *reason); 00336 00337 /** 00338 * \brief A callback indicating that the value of the resource object is updated 00339 * by the LWM2M Cloud server. 00340 * \param base The object whose value is updated. 00341 * \param type The type of the object. 00342 */ 00343 virtual void value_updated(M2MBase *base, M2MBase::BaseType type); 00344 00345 private: 00346 00347 /** 00348 * \brief Registers the update callback functions for SimpleM2MResourceBase 00349 * objects. 00350 * \param route The URI path of the registered resource such as "/Test/0/res/". 00351 * \param resource Object of the SimpleM2MResourceBase. 00352 */ 00353 void register_update_callback(string route, SimpleM2MResourceBase* resource); 00354 00355 private: 00356 00357 ServiceClient _client; 00358 MbedCloudClientCallback *_value_callback; 00359 map<string, M2MObject*> _objects; 00360 map<string, M2MResource*> _resources; 00361 M2MObjectList _object_list; 00362 map<string, SimpleM2MResourceBase*> _update_values; 00363 FP0<void> _on_registered; 00364 FP0<void> _on_unregistered; 00365 FP0<void> _on_registration_updated; 00366 FP1<void,int> _on_error; 00367 const char *_error_description; 00368 00369 00370 friend class SimpleM2MResourceBase; 00371 }; 00372 00373 template<typename T> 00374 void MbedCloudClient::on_registered(T *object, void (T::*member)(void)) 00375 { 00376 FP0<void> fp(object, member); 00377 _on_registered = fp; 00378 } 00379 00380 template<typename T> 00381 void MbedCloudClient::on_error(T *object, void (T::*member)(int)) 00382 { 00383 FP1<void, int> fp(object, member); 00384 _on_error = fp; 00385 } 00386 00387 template<typename T> 00388 void MbedCloudClient::on_unregistered(T *object, void (T::*member)(void)) 00389 { 00390 FP0<void> fp(object, member); 00391 _on_unregistered = fp; 00392 } 00393 00394 template<typename T> 00395 void MbedCloudClient::on_registration_updated(T *object, void (T::*member)(void)) 00396 { 00397 FP0<void> fp(object, member); 00398 _on_registration_updated = fp; 00399 } 00400 #endif // __MBED_CLOUD_CLIENT_H__
Generated on Tue Jul 12 2022 19:01:35 by 1.7.2