MbedCloudClient.h

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__