Simulated product dispenser

Dependencies:   HTS221

Fork of mbed-cloud-workshop-connect-HTS221 by Jim Carver

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers MbedCloudClient.h Source File

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 Adds a list of M2MBase interface implementing objects that the application wants
00139      * to register to the LWM2M server. This function MUST be called before calling the setup()
00140      * API. Otherwise, the application gets the error ConnectInvalidParameters, when
00141      * calling setup().
00142      * \param base_list Object implementing the M2MBase interface that contain information about the
00143      * client attempting to register to the LWM2M server.
00144      */
00145     void add_objects(const M2MBaseList& base_list);
00146 
00147     void remove_object(M2MBase *object);
00148     /**
00149      * \brief Sets the callback function that is called when there is
00150      * any new update on any Object/ObjectInstance/Resource from the LWM2M server,
00151      * typically on receiving PUT commands on the registered objects.
00152      * \param callback Passes the class object that implements the callback
00153      * function to handle the incoming PUT request on a given object.
00154      */
00155     void set_update_callback(MbedCloudClientCallback *callback);
00156 
00157     /**
00158      * \brief Initiates the Cloud Client set up on the Cloud service. This
00159      * function manages device provisioning (first time usage), bootstrapping
00160      * (first time usage) and registering the client application to the Cloud
00161      * service.
00162      * \param iface A handler to the network interface on mbedOS, can be NULL on
00163      * other platforms.
00164      */
00165     bool setup(void* iface);
00166 
00167     /**
00168      * \brief Sets the callback function that is called when the client is registered
00169      * successfully to the Cloud. This is used for a statically defined function.
00170      * \param fn A function pointer to the function that is called when the client
00171      * is registered.
00172      */
00173     void on_registered(void(*fn)(void));
00174 
00175     /**
00176     * \brief Sets the callback function that is called when the client is registered
00177     * successfully to the Cloud. This is an overloaded function for a class function.
00178     * \param object A function pointer to the function that is called when the client
00179     * is registered.
00180     */
00181     template<typename T>
00182     void on_registered(T *object, void (T::*member)(void));
00183 
00184     /**
00185      * \brief Sets the callback function that is called when there is any error
00186      * occuring in the client functionality. The error code can be mapped from the
00187      * MbedCloudClient::Error enum. This is used for a statically defined function.
00188      * \param fn A function pointer to the function that is called when there
00189      * is any error in the client.
00190      */
00191     void on_error(void(*fn)(int));
00192 
00193     /**
00194      * \brief Sets the callback function that is called when there is an error
00195      * occuring in the client functionality. The error code can be mapped from
00196      * MbedCloudClient::Error enum. This is an overloaded function for a class function.
00197      * \param object A function pointer to the function that is called when there
00198      * is an error in the client.
00199      */
00200     template<typename T>
00201     void on_error(T *object, void (T::*member)(int));
00202 
00203     /**
00204      * \brief Sets the callback function that is called when the client is unregistered
00205      * successfully from the Cloud. This is used for a statically defined function.
00206      * \param fn A function pointer to the function that is called when the client
00207      * is unregistered.
00208      */
00209     void on_unregistered(void(*fn)(void));
00210 
00211     /**
00212     * \brief Sets the callback function that is called when the client is unregistered
00213     * successfully from the Cloud. This is an overloaded function for a class function.
00214     * \param object A function pointer to the function that is called when the client
00215     * is unregistered.
00216     */
00217     template<typename T>
00218     void on_unregistered(T *object, void (T::*member)(void));
00219 
00220     /**
00221      * \brief Sets the callback function that is called when the client registration
00222      * is updated successfully to the Cloud. This is used for a statically defined function.
00223      * \param fn A function pointer to the function that is called when the client
00224      * registration is updated.
00225      */
00226     void on_registration_updated(void(*fn)(void));
00227 
00228     /**
00229      * \brief Sets the callback function that is called when the client registration
00230      * is updated successfully to the Cloud. This is an overloaded function for a class
00231      * function.
00232      * \param object A function pointer to the function that is called when the client
00233      * registration is updated.
00234      */
00235     template<typename T>
00236         void on_registration_updated(T *object, void (T::*member)(void));
00237 
00238     /**
00239     * \brief Sends a registration update message to the Cloud when the client is registered
00240     * successfully to the Cloud and there is no internal connection error.
00241     * If the client is not connected and there is some other internal network
00242     * transaction ongoing, this function triggers an error MbedCloudClient::ConnectNotAllowed.
00243     * \deprecated
00244     */
00245     void keep_alive() m2m_deprecated;
00246 
00247     /**
00248     * \brief Sends a registration update message to the Cloud when the client is registered
00249     * successfully to the Cloud and there is no internal connection error.
00250     * If the client is not connected and there is some other internal network
00251     * transaction ongoing, this function triggers an error MbedCloudClient::ConnectNotAllowed.
00252     */
00253     void register_update();
00254 
00255     /**
00256     * \brief Closes the connection towards Cloud and unregisters the client.
00257     * This function triggers the on_unregistered() callback if set by the application.
00258     */
00259     void close();
00260 
00261     /**
00262      * \brief Returns pointer to the ConnectorClientEndpointInfo object.
00263      * \return ConnectorClientEndpointInfo pointer.
00264      */
00265     const ConnectorClientEndpointInfo *endpoint_info() const;
00266 
00267     /**
00268      * \brief Sets the function that is called for indicating that the client
00269      * is going to sleep when the binding mode is selected with queue mode.
00270      * \param callback A function pointer that is called when the client
00271      * goes to sleep.
00272      */
00273     void set_queue_sleep_handler(callback_handler handler);
00274 
00275     /**
00276      * \brief Sets the function callback that is called by client to
00277      * fetch a random number from an application to ensure strong entropy.
00278      * \param random_callback A function pointer that is called by client
00279      * while performing a secure handshake.
00280      * The function signature should be uint32_t (*random_number_callback)(void);
00281      */
00282     void set_random_number_callback(random_number_cb callback);
00283 
00284     /**
00285      * \brief Sets the function callback that is called by client to
00286      * provide an entropy source from an application to ensure strong entropy.
00287      * \param entropy_callback A function pointer that is called by mbed Client
00288      * while performing a secure handshake.
00289      * Function signature, if using mbed-client-mbedtls, should be
00290      * int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output,
00291      *                                     size_t len, size_t *olen);
00292      */
00293     void set_entropy_callback(entropy_cb callback);
00294 
00295     /**
00296      * \brief Set resource value in the Device Object
00297      *
00298      * \param resource Device enum to have value set.
00299      * \param value String object.
00300      * \return True if successful, false otherwise.
00301      */
00302     bool set_device_resource_value(M2MDevice::DeviceResource resource,
00303                                    const std::string &value);
00304 
00305 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE
00306     /**
00307      * \brief Registers a callback function for authorizing firmware downloads and reboots.
00308      * \param handler Callback function.
00309      */
00310     void set_update_authorize_handler(void (*handler)(int32_t request));
00311 
00312     /**
00313      * \brief Authorize request passed to authorization handler.
00314      * \param request Request being authorized.
00315      */
00316     void update_authorize(int32_t request);
00317 
00318     /**
00319      * \brief Registers a callback function for monitoring download progress.
00320      * \param handler Callback function.
00321      */
00322     void set_update_progress_handler(void (*handler)(uint32_t progress, uint32_t total));
00323 #endif
00324 
00325     /**
00326      * @brief Return error description for the latest error code
00327      * @return Error description string
00328      */
00329     const char *error_description() const;
00330 
00331     /**
00332      * @brief Sends the CoAP GET request to the server.
00333      * API must be called again with the updated offset to complete the whole transfer.
00334      * @uri Uri path to the data.
00335      * @offset Data offset.
00336      * @get_data_cb Callback which is triggered once there is data available.
00337      * @get_data_error_cb Callback which is trigged in case of any error.
00338     */
00339     void send_get_request(const char *uri,
00340                           const size_t offset,
00341                           get_data_cb data_cb,
00342                           get_data_error_cb error_cb,
00343                           void *context);
00344 
00345 protected: // from ServiceClientCallback
00346 
00347     /**
00348     * \brief Indicates that the setup or close operation is complete
00349     * with success or failure.
00350     * \param status Indicates success or failure in terms of status code.
00351     */
00352     virtual void complete(ServiceClientCallbackStatus status);
00353 
00354     /**
00355     * \brief Indicates an error condition from the underlying clients like
00356     * identity, connector or update client.
00357     * \param error Indicates an error code translated to MbedCloudClient::Error.
00358     * \param reason, Indicates human readable text for error description.
00359     */
00360     virtual void error(int error, const char *reason);
00361 
00362     /**
00363     * \brief A callback indicating that the value of the resource object is updated
00364     *  by the LWM2M Cloud server.
00365     * \param base The object whose value is updated.
00366     * \param type The type of the object.
00367     */
00368     virtual void value_updated(M2MBase *base, M2MBase::BaseType type);
00369 
00370 private:
00371 
00372     /**
00373     * \brief Registers the update callback functions for SimpleM2MResourceBase
00374     * objects.
00375     * \param route The URI path of the registered resource such as "/Test/0/res/".
00376     * \param resource Object of the SimpleM2MResourceBase.
00377     */
00378     void register_update_callback(string route, SimpleM2MResourceBase* resource);
00379 
00380 private:
00381 
00382     ServiceClient                                   _client;
00383     MbedCloudClientCallback                         *_value_callback;
00384     map<string, M2MObject*>                         _objects;
00385     map<string, M2MResource*>                       _resources;
00386     M2MBaseList                                     _object_list;
00387     map<string, SimpleM2MResourceBase*>             _update_values;
00388     FP0<void>                                       _on_registered;
00389     FP0<void>                                       _on_unregistered;
00390     FP0<void>                                       _on_registration_updated;
00391     FP1<void,int>                                    _on_error;
00392     const char                                      *_error_description;
00393 
00394 
00395 friend class SimpleM2MResourceBase;
00396 };
00397 
00398 template<typename T>
00399 void MbedCloudClient::on_registered(T *object, void (T::*member)(void))
00400 {
00401     FP0<void> fp(object, member);
00402     _on_registered = fp;
00403 }
00404 
00405 template<typename T>
00406 void MbedCloudClient::on_error(T *object, void (T::*member)(int))
00407 {
00408     FP1<void, int>  fp(object, member);
00409     _on_error = fp;
00410 }
00411 
00412 template<typename T>
00413 void MbedCloudClient::on_unregistered(T *object, void (T::*member)(void))
00414 {
00415     FP0<void> fp(object, member);
00416     _on_unregistered = fp;
00417 }
00418 
00419 template<typename T>
00420 void MbedCloudClient::on_registration_updated(T *object, void (T::*member)(void))
00421 {
00422     FP0<void> fp(object, member);
00423     _on_registration_updated = fp;
00424 }
00425 #endif // __MBED_CLOUD_CLIENT_H__