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 "include/ServiceClient.h"
00024 #include "mbed-cloud-client/MbedCloudClientConfig.h"
00025 
00026 #ifndef MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT
00027 // This overly long path is needed to have build compatibility with previous
00028 // version. A #include can't just point to a file which is not in application's
00029 // include path and we should not force application to add every internal directory
00030 // of MCC to their paths.
00031 // On next phase, the cmake is used to publish the API paths via
00032 // target_include_directories(), but that requires a bit more cleanups.
00033 #include "certificate-enrollment-client/certificate-enrollment-client/ce_defs.h"
00034 #endif // MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT
00035 
00036 #if MBED_CLOUD_CLIENT_STL_API
00037 #include <map>
00038 #include <string>
00039 #include <vector>
00040 #endif
00041 
00042 #if MBED_CLOUD_CLIENT_STD_NAMESPACE_POLLUTION
00043 // We should not really pollute application's namespace with std:: by having this in
00044 // a public header file.
00045 // But as as removal of the next line may break existing applications, which build due to this
00046 // leakage, we need to maintain the old behavior for a while and just allow one to remove it.
00047 using namespace std;
00048 #endif
00049 
00050 class SimpleM2MResourceBase;
00051 
00052 /**
00053  * \brief MbedCloudClientCallback
00054  * A callback class for informing updated object and resource value from the
00055  * LWM2M server to the user of the MbedCloudClient class. The user MUST instantiate the
00056  * class derived out of this and pass the object to MbedCloudClient::set_update_callback().
00057  */
00058 class MbedCloudClientCallback {
00059 
00060 public:
00061 
00062     /**
00063     * \brief A callback indicating that the value of the resource object is updated
00064     *  by the LWM2M Cloud server.
00065     * \param base The object whose value is updated.
00066     * \param type The type of the object.
00067     */
00068     virtual void value_updated(M2MBase *base, M2MBase::BaseType type) = 0;
00069 };
00070 
00071 
00072 
00073 /*! \file MbedCloudClient.h
00074  *  \brief MbedCloudClient.
00075  *  This class provides an interface for handling all the client interface operations
00076  *  including device provisioning, identity setup, device resource management defined in the OMA
00077  *  LWM2M specifications, and update firmware.
00078  *  Device resource management includes Bootstrapping, Client Registration, Device Management &
00079  *  Service Enablement and Information Reporting.
00080  */
00081 
00082 class MbedCloudClient : public ServiceClientCallback {
00083 
00084 public:
00085 
00086     /**
00087      * \brief An enum defining different kinds of errors
00088      * that can occur during various client operations.
00089      */
00090     typedef enum {
00091         ConnectErrorNone                        = M2MInterface::ErrorNone, // Range reserved for Connector Error from 0x30 - 0x3FF
00092         ConnectAlreadyExists                    = M2MInterface::AlreadyExists,
00093         ConnectBootstrapFailed                  = M2MInterface::BootstrapFailed,
00094         ConnectInvalidParameters                = M2MInterface::InvalidParameters,
00095         ConnectNotRegistered                    = M2MInterface::NotRegistered,
00096         ConnectTimeout                          = M2MInterface::Timeout,
00097         ConnectNetworkError                     = M2MInterface::NetworkError,
00098         ConnectResponseParseFailed              = M2MInterface::ResponseParseFailed,
00099         ConnectUnknownError                     = M2MInterface::UnknownError,
00100         ConnectMemoryConnectFail                = M2MInterface::MemoryFail,
00101         ConnectNotAllowed                       = M2MInterface::NotAllowed,
00102         ConnectSecureConnectionFailed           = M2MInterface::SecureConnectionFailed,
00103         ConnectDnsResolvingFailed               = M2MInterface::DnsResolvingFailed,
00104         ConnectorFailedToStoreCredentials       = M2MInterface::FailedToStoreCredentials,
00105         ConnectorFailedToReadCredentials        = M2MInterface::FailedToReadCredentials,
00106         ConnectorInvalidCredentials,
00107 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE
00108         UpdateWarningNoActionRequired           = UpdateClient::WarningBase, // Range reserved for Update Error from 0x0400 - 0x04FF
00109         UpdateWarningCertificateNotFound        = UpdateClient::WarningCertificateNotFound,
00110         UpdateWarningIdentityNotFound           = UpdateClient::WarningIdentityNotFound,
00111         UpdateWarningVendorMismatch             = UpdateClient::WarningVendorMismatch,
00112         UpdateWarningClassMismatch              = UpdateClient::WarningClassMismatch,
00113         UpdateWarningDeviceMismatch             = UpdateClient::WarningDeviceMismatch,
00114         UpdateWarningCertificateInvalid         = UpdateClient::WarningCertificateInvalid,
00115         UpdateWarningSignatureInvalid           = UpdateClient::WarningSignatureInvalid,
00116         UpdateWarningBadKeytable                = UpdateClient::WarningBadKeytable,
00117         UpdateWarningURINotFound                = UpdateClient::WarningURINotFound,
00118         UpdateWarningRollbackProtection         = UpdateClient::WarningRollbackProtection,
00119         UpdateWarningUnknown                    = UpdateClient::WarningUnknown,
00120         UpdateCertificateInsertion              = UpdateClient::WarningCertificateInsertion,
00121         UpdateErrorUserActionRequired           = UpdateClient::ErrorBase,
00122         UpdateErrorWriteToStorage               = UpdateClient::ErrorWriteToStorage,
00123         UpdateErrorInvalidHash                  = UpdateClient::ErrorInvalidHash,
00124         UpdateErrorConnection                   = UpdateClient::ErrorConnection,
00125         UpdateFatalRebootRequired,
00126 #endif
00127 #ifndef MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT
00128         // Certificate Enrollment error 0x0500 - 0x05ff. Defined in ce_status.h
00129         EnrollmentErrorBase = CE_STATUS_RANGE_BASE,
00130         EnrollmentErrorEnd = CE_STATUS_RANGE_END
00131 #endif // MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT
00132     }Error;
00133 
00134 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE
00135     /**
00136      * \brief Enum defining authorization requests from the Update client.
00137      */
00138     enum {
00139         UpdateRequestInvalid                    = UpdateClient::RequestInvalid,
00140         UpdateRequestDownload                   = UpdateClient::RequestDownload,
00141         UpdateRequestInstall                    = UpdateClient::RequestInstall
00142     };
00143 #endif
00144 
00145     /**
00146      * \brief Constructor
00147      */
00148     MbedCloudClient();
00149 
00150     /**
00151      * \brief Destructor
00152      */
00153     virtual ~MbedCloudClient();
00154 
00155     /**
00156      * \brief Adds a list of objects that the application wants to register to the
00157      * LWM2M server. This function MUST be called before calling the setup()
00158      * API. Otherwise, the application gets the error ConnectInvalidParameters, when
00159      * calling setup().
00160      * \param object_list Objects that contain information about the
00161      * client attempting to register to the LWM2M server.
00162      */
00163     void add_objects(const M2MObjectList& object_list);
00164 
00165     /**
00166      * \brief Adds a list of M2MBase interface implementing objects that the application wants
00167      * to register to the LWM2M server. This function MUST be called before calling the setup()
00168      * API. Otherwise, the application gets the error ConnectInvalidParameters, when
00169      * calling setup().
00170      * \param base_list Object implementing the M2MBase interface that contain information about the
00171      * client attempting to register to the LWM2M server.
00172      */
00173     void add_objects(const M2MBaseList& base_list);
00174 
00175     void remove_object(M2MBase *object);
00176     /**
00177      * \brief Sets the callback function that is called when there is
00178      * any new update on any Object/ObjectInstance/Resource from the LWM2M server,
00179      * typically on receiving PUT commands on the registered objects.
00180      * \param callback Passes the class object that implements the callback
00181      * function to handle the incoming PUT request on a given object.
00182      */
00183     void set_update_callback(MbedCloudClientCallback *callback);
00184 
00185     /**
00186      * \brief Initiates the Cloud Client set up on the Cloud service. This
00187      * function manages device provisioning (first time usage), bootstrapping
00188      * (first time usage) and registering the client application to the Cloud
00189      * service.
00190      * \param iface A handler to the network interface on mbedOS, can be NULL on
00191      * other platforms.
00192      */
00193     bool setup(void* iface);
00194 
00195     /**
00196      * \brief Sets the callback function that is called when the client is registered
00197      * successfully to the Cloud. This is used for a statically defined function.
00198      * \param fn A function pointer to the function that is called when the client
00199      * is registered.
00200      */
00201     void on_registered(void(*fn)(void));
00202 
00203     /**
00204     * \brief Sets the callback function that is called when the client is registered
00205     * successfully to the Cloud. This is an overloaded function for a class function.
00206     * \param object A function pointer to the function that is called when the client
00207     * is registered.
00208     */
00209     template<typename T>
00210     void on_registered(T *object, void (T::*member)(void));
00211 
00212     /**
00213      * \brief Sets the callback function that is called when there is any error
00214      * occuring in the client functionality. The error code can be mapped from the
00215      * MbedCloudClient::Error enum. This is used for a statically defined function.
00216      * \param fn A function pointer to the function that is called when there
00217      * is any error in the client.
00218      */
00219     void on_error(void(*fn)(int));
00220 
00221     /**
00222      * \brief Sets the callback function that is called when there is an error
00223      * occuring in the client functionality. The error code can be mapped from
00224      * MbedCloudClient::Error enum. This is an overloaded function for a class function.
00225      * \param object A function pointer to the function that is called when there
00226      * is an error in the client.
00227      */
00228     template<typename T>
00229     void on_error(T *object, void (T::*member)(int));
00230 
00231     /**
00232      * \brief Sets the callback function that is called when the client is unregistered
00233      * successfully from the Cloud. This is used for a statically defined function.
00234      * \param fn A function pointer to the function that is called when the client
00235      * is unregistered.
00236      */
00237     void on_unregistered(void(*fn)(void));
00238 
00239     /**
00240     * \brief Sets the callback function that is called when the client is unregistered
00241     * successfully from the Cloud. This is an overloaded function for a class function.
00242     * \param object A function pointer to the function that is called when the client
00243     * is unregistered.
00244     */
00245     template<typename T>
00246     void on_unregistered(T *object, void (T::*member)(void));
00247 
00248     /**
00249      * \brief Sets the callback function that is called when the client registration
00250      * is updated successfully to the Cloud. This is used for a statically defined function.
00251      * \param fn A function pointer to the function that is called when the client
00252      * registration is updated.
00253      */
00254     void on_registration_updated(void(*fn)(void));
00255 
00256     /**
00257      * \brief Sets the callback function that is called when the client registration
00258      * is updated successfully to the Cloud. This is an overloaded function for a class
00259      * function.
00260      * \param object A function pointer to the function that is called when the client
00261      * registration is updated.
00262      */
00263     template<typename T>
00264         void on_registration_updated(T *object, void (T::*member)(void));
00265 
00266     /**
00267     * \brief Sends a registration update message to the Cloud when the client is registered
00268     * successfully to the Cloud and there is no internal connection error.
00269     * If the client is not connected and there is some other internal network
00270     * transaction ongoing, this function triggers an error MbedCloudClient::ConnectNotAllowed.
00271     * \deprecated
00272     */
00273     void keep_alive() m2m_deprecated;
00274 
00275     /**
00276     * \brief Sends a registration update message to the Cloud when the client is registered
00277     * successfully to the Cloud and there is no internal connection error.
00278     * If the client is not connected and there is some other internal network
00279     * transaction ongoing, this function triggers an error MbedCloudClient::ConnectNotAllowed.
00280     */
00281     void register_update();
00282 
00283     /**
00284     * \brief Closes the connection towards Cloud and unregisters the client.
00285     * This function triggers the on_unregistered() callback if set by the application.
00286     */
00287     void close();
00288 
00289     /**
00290      * \brief Returns pointer to the ConnectorClientEndpointInfo object.
00291      * \return ConnectorClientEndpointInfo pointer.
00292      */
00293     const ConnectorClientEndpointInfo *endpoint_info() const;
00294 
00295     /**
00296      * \brief Sets the function that is called for indicating that the client
00297      * is going to sleep when the binding mode is selected with queue mode.
00298      * \param callback A function pointer that is called when the client
00299      * goes to sleep.
00300      */
00301     void set_queue_sleep_handler(callback_handler handler);
00302 
00303     /**
00304      * \brief Sets the function callback that is called by client to
00305      * fetch a random number from an application to ensure strong entropy.
00306      * \param random_callback A function pointer that is called by client
00307      * while performing a secure handshake.
00308      * The function signature should be uint32_t (*random_number_callback)(void);
00309      */
00310     void set_random_number_callback(random_number_cb callback);
00311 
00312     /**
00313      * \brief Sets the function callback that is called by client to
00314      * provide an entropy source from an application to ensure strong entropy.
00315      * \param entropy_callback A function pointer that is called by mbed Client
00316      * while performing a secure handshake.
00317      * Function signature, if using mbed-client-mbedtls, should be
00318      * int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output,
00319      *                                     size_t len, size_t *olen);
00320      */
00321     void set_entropy_callback(entropy_cb callback);
00322 
00323 #if MBED_CLOUD_CLIENT_STL_API
00324     /**
00325      * \brief Set resource value in the Device Object
00326      *
00327      * \note This API and functionality using STL is being phased out, as it is wasting resources by
00328      * duplicating data and harming portability by requiring a STL implementation to exist.
00329      *
00330      * \param resource Device enum to have value set.
00331      * \param value String object.
00332      * \return True if successful, false otherwise.
00333      */
00334     bool set_device_resource_value(M2MDevice::DeviceResource resource,
00335                                    const std::string &value) m2m_deprecated;
00336 #endif
00337 
00338 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE
00339     /**
00340      * \brief Registers a callback function for authorizing firmware downloads and reboots.
00341      * \param handler Callback function.
00342      */
00343     void set_update_authorize_handler(void (*handler)(int32_t request));
00344 
00345     /**
00346      * \brief Authorize request passed to authorization handler.
00347      * \param request Request being authorized.
00348      */
00349     void update_authorize(int32_t request);
00350 
00351     /**
00352      * \brief Registers a callback function for monitoring download progress.
00353      * \param handler Callback function.
00354      */
00355     void set_update_progress_handler(void (*handler)(uint32_t progress, uint32_t total));
00356 #endif
00357 
00358     /**
00359      * @brief Return error description for the latest error code
00360      * @return Error description string
00361      */
00362     const char *error_description() const;
00363 
00364     /**
00365      * @brief Sends the CoAP GET request to the server.
00366      * API must be called again with the updated offset to complete the whole transfer.
00367      * @type Download type.
00368      * @uri Uri path to the data.
00369      * @offset Data offset.
00370      * @get_data_cb Callback which is triggered once there is data available.
00371      * @get_data_error_cb Callback which is trigged in case of any error.
00372     */
00373     void send_get_request(DownloadType type,
00374                           const char *uri,
00375                           const size_t offset,
00376                           get_data_cb data_cb,
00377                           get_data_error_cb error_cb,
00378                           void *context);
00379 
00380 #ifndef MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT
00381     /**
00382     * \brief Initiate a renewal for a specific certificate.
00383     * The process will generate new keys in order to create a CSR. The CSR is then sent to the EST service to retrieve the renewed certificate.
00384     * The new certificate is then safely stored in the device, along with its corresponding private key.
00385     * Note: The certificate to be removed *must* already exist in the device.
00386     * \param cert_name A null terminated C string indicating the name of the certificate to be renewed.
00387     * \return CE_STATUS_SUCCESS if the asynchronous operation has started successfully. In this case, user callback will be executed at the end of the operation, indicating completion status.
00388     *         If any other ce_status_e:: status is returned - operation encountered some error prior to the start of the asynchronous stage and user callback will NOT be executed.
00389     */
00390     ce_status_e  certificate_renew(const char *cert_name);
00391 
00392     /**
00393     * \brief Sets the callback function that is called when the certificate renewal process has completed.
00394     * Must be called before any certificate renewal operation.
00395     * \param user_cb A function pointer to the user callback. If `user_cb` is NULL - no callback is called when the process has completed.
00396     */
00397     void on_certificate_renewal(cert_renewal_cb_f user_cb);
00398 #endif // MBED_CONF_MBED_CLOUD_CLIENT_DISABLE_CERTIFICATE_ENROLLMENT
00399 
00400 #ifdef MBED_CLOUD_CLIENT_EDGE_EXTENSION
00401     /**
00402      * @brief Returns the pointer to the inner object list.
00403      * The list is not allowed to be modified and is owned by the client instance.
00404      * @return The inner object list pointer.
00405      */
00406     const M2MBaseList *get_object_list() const;
00407 #endif // MBED_CLOUD_CLIENT_EDGE_EXTENSION
00408 
00409     /**
00410      * \brief Pauses client's timed functionality and closes network connection
00411      * to the Cloud. After successful call the operation is continued
00412      * by calling resume().
00413      *
00414      * \note This operation does not unregister client from the Cloud.
00415      * Closes the socket and removes interface from the interface list.
00416      */
00417     void pause();
00418 
00419     /**
00420      * \brief Resumes client's timed functionality and network connection
00421      * to the Cloud. Updates registration. Can be only called after
00422      * a successful call to pause().
00423      *
00424      * \param iface A handler to the network interface.
00425      */
00426     void resume(void *iface);
00427 
00428 protected: // from ServiceClientCallback
00429 
00430     /**
00431     * \brief Indicates that the setup or close operation is complete
00432     * with success or failure.
00433     * \param status Indicates success or failure in terms of status code.
00434     */
00435     virtual void complete(ServiceClientCallbackStatus status);
00436 
00437     /**
00438     * \brief Indicates an error condition from the underlying clients like
00439     * identity, connector or update client.
00440     * \param error Indicates an error code translated to MbedCloudClient::Error.
00441     * \param reason, Indicates human readable text for error description.
00442     */
00443     virtual void error(int error, const char *reason);
00444 
00445     /**
00446     * \brief A callback indicating that the value of the resource object is updated
00447     *  by the LWM2M Cloud server.
00448     * \param base The object whose value is updated.
00449     * \param type The type of the object.
00450     */
00451     virtual void value_updated(M2MBase *base, M2MBase::BaseType type);
00452 
00453 private:
00454 
00455     /**
00456     * \brief Registers the update callback functions for SimpleM2MResourceBase
00457     * objects.
00458     * \param route The URI path of the registered resource such as "/Test/0/res/".
00459     * \param resource Object of the SimpleM2MResourceBase.
00460     */
00461 #if MBED_CLOUD_CLIENT_STL_API
00462     void register_update_callback(string route, SimpleM2MResourceBase* resource) m2m_deprecated;
00463 #endif
00464 
00465 private:
00466 
00467     ServiceClient                                   _client;
00468     MbedCloudClientCallback                         *_value_callback;
00469     M2MBaseList                                     _object_list;
00470     FP0<void>                                       _on_registered;
00471     FP0<void>                                       _on_unregistered;
00472     FP0<void>                                       _on_registration_updated;
00473     FP1<void,int>                                    _on_error;
00474     const char                                      *_error_description;
00475 
00476 #if MBED_CLOUD_CLIENT_STL_API
00477     // This API and functionality is being phased out, as it is wasting resources by
00478     // duplicating data and harming portability by requiring a STL implementation to exist.
00479     map<string, M2MObject*>                         _objects;
00480     map<string, M2MResource*>                       _resources;
00481     map<string, SimpleM2MResourceBase*>             _update_values;
00482 
00483 friend class SimpleM2MResourceBase;
00484 
00485 #endif // MBED_CLOUD_CLIENT_STL_API
00486 };
00487 
00488 template<typename T>
00489 void MbedCloudClient::on_registered(T *object, void (T::*member)(void))
00490 {
00491     FP0<void> fp(object, member);
00492     _on_registered = fp;
00493 }
00494 
00495 template<typename T>
00496 void MbedCloudClient::on_error(T *object, void (T::*member)(int))
00497 {
00498     FP1<void, int>  fp(object, member);
00499     _on_error = fp;
00500 }
00501 
00502 template<typename T>
00503 void MbedCloudClient::on_unregistered(T *object, void (T::*member)(void))
00504 {
00505     FP0<void> fp(object, member);
00506     _on_unregistered = fp;
00507 }
00508 
00509 template<typename T>
00510 void MbedCloudClient::on_registration_updated(T *object, void (T::*member)(void))
00511 {
00512     FP0<void> fp(object, member);
00513     _on_registration_updated = fp;
00514 }
00515 #endif // __MBED_CLOUD_CLIENT_H__