ServiceClient.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 #ifndef __SERVICE_CLIENT_H__
00020 #define __SERVICE_CLIENT_H__
00021 
00022 #include "mbed-cloud-client/MbedCloudClientConfig.h"
00023 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE
00024 #include "UpdateClient.h"
00025 #endif
00026 #include "mbed-client/m2minterface.h"
00027 #include "mbed-client/m2mdevice.h"
00028 #include "ConnectorClient.h"
00029 
00030 #include <stdint.h>
00031 
00032 #if MBED_CLOUD_CLIENT_STL_API
00033 #include <string>
00034 #endif
00035 
00036 class M2MSecurity;
00037 class ConnectorClientCallback;
00038 struct MbedClientDeviceInfo;
00039 struct MBedClientInterfaceInfo;
00040 
00041 /**
00042  * \brief ServiceClientCallback
00043  * A callback class for passing the client progress and error condition to the
00044  * MbedCloudClient class object.
00045  */
00046 class ServiceClientCallback {
00047 public:
00048 
00049     typedef enum {
00050         Service_Client_Status_Failure = -1,
00051         Service_Client_Status_Registered = 0,
00052         Service_Client_Status_Unregistered = 1,
00053         Service_Client_Status_Register_Updated = 2
00054     } ServiceClientCallbackStatus;
00055 
00056     /**
00057     * \brief Indicates that the setup or close operation is complete
00058     * with success or failure.
00059     * \param status, Indicates success or failure in terms of status code.
00060     */
00061     virtual void complete(ServiceClientCallbackStatus status) = 0;
00062 
00063     /**
00064     * \brief Indicates an error condition from one of the underlying clients, including
00065     * identity, connector or update client.
00066     * \param error, Indicates an error code translated to MbedCloudClient::Error.
00067     * \param reason, Indicates human readable text for error description.
00068     */
00069     virtual void error(int error, const char *reason) = 0;
00070 
00071     /**
00072     * \brief A callback indicating that the value of the resource object is updated
00073     *  by the LWM2M Cloud server.
00074     * \param base, The object whose value is updated.
00075     * \param type, The type of the object.
00076     */
00077     virtual void value_updated(M2MBase *base, M2MBase::BaseType type) = 0;
00078 };
00079 
00080 
00081 /**
00082  *  \brief ServiceClient
00083  *  This class handles all internal interactions between various client
00084  *  components including connector, identity and update.
00085  *  This class maintains the state machine for the use case flow of mbed Cloud
00086  *  Client.
00087  */
00088 
00089 class ServiceClient : private ConnectorClientCallback
00090 {
00091 public:
00092 
00093     /**
00094      * \brief An enum defining the different states of
00095      * ServiceClient during the client flow.
00096      */
00097     enum StartupMainState {
00098         State_Init,
00099         State_Bootstrap,
00100         State_Register,
00101         State_Success,
00102         State_Failure,
00103         State_Unregister
00104     };
00105 
00106 public:
00107 
00108     /**
00109     *  \brief Constructor.
00110     *  \param interface, Takes the structure that contains the
00111     *   needed information for an endpoint client to register.
00112     */
00113     ServiceClient(ServiceClientCallback& callback);
00114 
00115     /**
00116     *  \brief Destructor.
00117     */
00118     virtual ~ServiceClient();
00119 
00120     /**
00121     *  \brief Starts the registration or bootstrap sequence from MbedCloudClient.
00122     *  \param callback, Takes the callback for the status from ConnectorClient.
00123     *  \param client_objs, A list of objects to be registered to Cloud.
00124     */
00125     void initialize_and_register(M2MBaseList& reg_objs);
00126 
00127     /**
00128     *  \brief Finished the initialization of MbedCloudClient.
00129     */
00130     void finish_initialization(void);
00131 
00132     /**
00133      * \brief Returns the ConnectorClient handler.
00134      * \return ConnectorClient, handled for ConnectorClient.
00135     */
00136     ConnectorClient &connector_client();
00137 
00138     /**
00139      * \brief Returns const ConnectorClient handler.
00140      * \return const ConnectorClient, handled for ConnectorClient.
00141     */
00142     const ConnectorClient &connector_client() const;
00143 
00144 #if MBED_CLOUD_CLIENT_STL_API
00145     /**
00146      * \brief Set resource value in the Device Object
00147      *
00148      * \note This is deprecated as the rest of API's using std::string,
00149      *  but there is no m2m_deprecated tag as that would cause warning on
00150      *  default builds from MbedCloudClient::set_device_resource_value(),
00151      *  which is the public API for this as it will be built but not used.
00152      *
00153      * \param resource Device enum to have value set.
00154      * \param value String object.
00155      * \return True if successful, false otherwise.
00156      */
00157     bool set_device_resource_value(M2MDevice::DeviceResource resource,
00158                                    const std::string& value);
00159 #endif
00160 
00161     /**
00162      * \brief Set resource value in the Device Object
00163      *
00164      * \param resource Device enum to have value set.
00165      * \param value Byte buffer.
00166      * \param length Buffer length.
00167      * \return True if successful, false otherwise.
00168      */
00169     bool set_device_resource_value(M2MDevice::DeviceResource resource,
00170                                    const char* value,
00171                                    uint32_t length);
00172 
00173 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE
00174     /**
00175      * \brief Registers a callback function for authorizing firmware downloads and reboots.
00176      * \param handler Callback function.
00177      */
00178     void set_update_authorize_handler(void (*handler)(int32_t request));
00179 
00180     /**
00181      * \brief Authorize request passed to authorization handler.
00182      * \param request Request being authorized.
00183      */
00184     void update_authorize(int32_t request);
00185 
00186     /**
00187      * \brief Registers a callback function for monitoring download progress.
00188      * \param handler Callback function.
00189      */
00190     void set_update_progress_handler(void (*handler)(uint32_t progress, uint32_t total));
00191 
00192     /**
00193      * \brief Callback function for the Update Client.
00194      * \param error Internal Update Client error code.
00195      */
00196     void update_error_callback(int32_t error);
00197 #endif
00198 
00199 protected :
00200 
00201     // Implementation of ConnectorClientCallback
00202     /**
00203     * \brief Indicates that the registration or unregistration operation is complete
00204     * with success or failure.
00205     * \param status, Indicates success or failure in terms of status code.
00206     */
00207     virtual void registration_process_result(ConnectorClient::StartupSubStateRegistration status);
00208 
00209     /**
00210     * \brief Indicates a connector error condition from an underlying M2MInterface client.
00211     * \param error, Indicates an error code translated from M2MInterface::Error.
00212     */
00213     virtual void connector_error(M2MInterface::Error error, const char *reason);
00214 
00215     /**
00216     * \brief A callback indicating that the value of the resource object is updated
00217     *  by the LWM2M Cloud server.
00218     * \param base, The object whose value is updated.
00219     * \param type, The type of the object.
00220     */
00221     virtual void value_updated(M2MBase *base, M2MBase::BaseType type);
00222 
00223     /**
00224      * \brief Redirects the state machine to the right function.
00225      * \param current_state, The current state to be set.
00226      * \param data, The data to be passed to the state function.
00227      */
00228     void state_function(StartupMainState current_state);
00229 
00230     /**
00231      * \brief The state engine maintaining the state machine logic.
00232      */
00233     void state_engine(void);
00234 
00235     /**
00236     * An external event that can trigger the state machine.
00237     * \param new_state, The new state to which the state machine should go.
00238     * \param data, The data to be passed to the state machine.
00239     */
00240     void external_event(StartupMainState new_state);
00241 
00242     /**
00243     * An internal event generated by the state machine.
00244     * \param new_state, The new state to which the state machine should go.
00245     * \param data, The data to be passed to the state machine.
00246     */
00247     void internal_event(StartupMainState new_state);
00248 
00249     /**
00250     * When the bootstrap is started.
00251     */
00252     void state_bootstrap();
00253 
00254     /**
00255     * When the registration is started.
00256     */
00257     void state_register();
00258 
00259     /**
00260     * When the registration is successful.
00261     */
00262     void state_success();
00263 
00264     /**
00265     * When the registration has failed.
00266     */
00267 
00268     void state_failure();
00269 
00270     /**
00271     * When the client unregisters.
00272     */
00273     void state_unregister();
00274 
00275 private:
00276     M2MDevice* device_object_from_storage();
00277 
00278     /* lookup table for printing hexadecimal values */
00279     static const uint8_t hex_table[16];
00280 
00281     ServiceClientCallback           &_service_callback;
00282     // data which is pending for the registration
00283     const char                      *_service_uri;
00284     void                            *_stack;
00285     M2MBaseList                     *_client_objs;
00286     StartupMainState                _current_state;
00287     bool                            _event_generated;
00288     bool                            _state_engine_running;
00289 #ifdef MBED_CLOUD_CLIENT_SUPPORT_UPDATE
00290     bool                            _setup_update_client;
00291 #endif
00292     ConnectorClient                 _connector_client;
00293 };
00294 
00295 #endif // !__SERVICE_CLIENT_H__