ConnectorClient.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 __CONNECTOR_CLIENT_H__
00020 #define __CONNECTOR_CLIENT_H__
00021 
00022 #include "mbed-client/functionpointer.h"
00023 #include "mbed-client/m2minterfacefactory.h"
00024 #include "mbed-client/m2mdevice.h"
00025 #include "mbed-client/m2minterfaceobserver.h"
00026 #include "mbed-client/m2minterface.h"
00027 #include "mbed-client/m2mobjectinstance.h"
00028 #include "mbed-client/m2mresource.h"
00029 #include "mbed-client/m2mtimerobserver.h"
00030 #include "mbed-client/m2mtimer.h"
00031 #include "include/CloudClientStorage.h"
00032 
00033 class ConnectorClientCallback;
00034 
00035 using namespace std;
00036 
00037 
00038 /**
00039  * \brief ConnectorClientEndpointInfo
00040  * A structure that contains the needed endpoint information to register with the Cloud service.
00041  * Note: this should be changed to a class instead of struct and/or members changed to "const char*".
00042  */
00043 struct ConnectorClientEndpointInfo {
00044 
00045 public:
00046     ConnectorClientEndpointInfo(M2MSecurity::SecurityModeType m) : mode(m) {};
00047     ~ConnectorClientEndpointInfo() {};
00048 
00049 public:
00050 
00051     String                          endpoint_name;
00052     String                          account_id;
00053     String                          internal_endpoint_name;
00054     M2MSecurity::SecurityModeType   mode;
00055 };
00056 
00057 /**
00058  * \brief ConnectorClient
00059  * This class is an interface towards the M2MInterface client to handle all
00060  * data flow towards Connector through this client.
00061  * This class is intended to be used via ServiceClient, not directly.
00062  * This class contains also the bootstrap functionality.
00063  */
00064 class ConnectorClient : public M2MInterfaceObserver, public M2MTimerObserver {
00065 
00066 public:
00067     /**
00068      * \brief An enum defining the different states of
00069      * ConnectorClient during the client flow.
00070      */
00071     enum StartupSubStateRegistration {
00072         State_Bootstrap_Start,
00073         State_Bootstrap_Started,
00074         State_Bootstrap_Success,
00075         State_Bootstrap_Failure,
00076 #ifndef MBED_CLIENT_DISABLE_EST_FEATURE
00077         State_EST_Start,
00078         State_EST_Started,
00079         State_EST_Success,
00080         State_EST_Failure,
00081 #endif // !MBED_CLIENT_DISABLE_EST_FEATURE
00082         State_Registration_Start,
00083         State_Registration_Started,
00084         State_Registration_Success,
00085         State_Registration_Failure,
00086         State_Registration_Updated,
00087         State_Unregistered
00088     };
00089 
00090 public:
00091 
00092     /**
00093     *  \brief Constructor.
00094     *  \param callback, A callback for the status from ConnectorClient.
00095     */
00096     ConnectorClient(ConnectorClientCallback* callback);
00097 
00098     /**
00099     *  \brief Destructor.
00100     */
00101     ~ConnectorClient();
00102 
00103     /**
00104     *  \brief Starts the bootstrap sequence from the Service Client.
00105     */
00106     void start_bootstrap();
00107 
00108     /**
00109     *  \brief Starts the registration sequence from the Service Client.
00110     *  \param client_objs, A list of objects implementing the M2MBase interface to be registered with Cloud.
00111     */
00112     void start_registration(M2MBaseList* client_objs);
00113 
00114     /**
00115     *  \brief Sends an update registration message to the LWM2M server.
00116     */
00117     void update_registration();
00118 
00119     /**
00120      * \brief Returns the M2MInterface handler.
00121      * \return M2MInterface, Handled for M2MInterface.
00122     */
00123     M2MInterface * m2m_interface();
00124 
00125     /**
00126      * \brief Checks whether to use Bootstrap or direct Connector mode.
00127      * \return True if bootstrap mode, False if direct Connector flow
00128     */
00129     bool use_bootstrap();
00130 
00131     /**
00132      * \brief Checks whether to go connector registration flow
00133      * \return True if connector credentials available otherwise false.
00134     */
00135     bool connector_credentials_available();
00136 
00137     /**
00138      * \brief A utility function to generate the key name.
00139      * \param key, The key to get the value for.
00140      * \param endpoint, The name of the endpoint to be appended
00141      * to the key.
00142      * \param key_name, The [OUT] final key name.
00143      * \return True if available, else false.
00144     */
00145     bool get_key(const char *key, const char *endpoint, char *&key_name);
00146 
00147     /**
00148      * \brief Returns pointer to the ConnectorClientEndpointInfo object.
00149      * \return ConnectorClientEndpointInfo pointer.
00150     */
00151    const ConnectorClientEndpointInfo *endpoint_info() const;
00152 
00153    void est_enrollment_result(bool success,
00154                               const uint8_t *payload_ptr,
00155                               const uint16_t payload_len);
00156 
00157    static void est_post_data_cb(const uint8_t *buffer,
00158                                 size_t buffer_size,
00159                                 size_t total_size,
00160                                 void *context);
00161 
00162    static void est_post_data_error_cb(get_data_req_error_t error_code,
00163                                       void *context);
00164 
00165    /**
00166     * \brief Returns KCM Certificate chain handle pointer.
00167     * \return KCM Certificate chain handle pointer.
00168    */
00169    void *certificate_chain_handle() const;
00170 
00171    /**
00172     * \brief Sets the KCM certificate chain handle pointer.
00173     * \param cert_handle KCM Certificate chain handle.
00174    */
00175    void set_certificate_chain_handle(void *cert_handle);
00176 
00177 public:
00178     // implementation of M2MInterfaceObserver:
00179 
00180     /**
00181      * \brief A callback indicating that the bootstap has been performed successfully.
00182      * \param server_object, The server object that contains the information fetched
00183      * about the LWM2M server from the bootstrap server. This object can be used
00184      * to register with the LWM2M server. The object ownership is passed.
00185      */
00186     virtual void bootstrap_done(M2MSecurity *server_object);
00187 
00188     /**
00189      * \brief A callback indicating when all bootstrap data has been received.
00190      * \param security_object, The security object that contains the security information.
00191      */
00192     virtual void bootstrap_data_ready(M2MSecurity *security_object);
00193 
00194     /**
00195      * \brief A callback indicating that the device object has been registered
00196      * successfully with the LWM2M server.
00197      * \param security_object, The server object on which the device object is
00198      * registered. The object ownership is passed.
00199      * \param server_object, An object containing information about the LWM2M server.
00200      * The client maintains the object.
00201      */
00202     virtual void object_registered(M2MSecurity *security_object, const M2MServer &server_object);
00203 
00204     /**
00205      * \brief A callback indicating that the device object has been successfully unregistered
00206      * from the LWM2M server.
00207      * \param server_object, The server object from which the device object is
00208      * unregistered. The object ownership is passed.
00209      */
00210     virtual void object_unregistered(M2MSecurity *server_object);
00211 
00212     /**
00213      * \brief A callback indicating that the device object registration has been successfully
00214      * updated on the LWM2M server.
00215      * \param security_object, The server object on which the device object registration is
00216      * updated. The object ownership is passed.
00217      * \param server_object, An object containing information about the LWM2M server.
00218      * The client maintains the object.
00219      */
00220     virtual void registration_updated(M2MSecurity *security_object, const M2MServer & server_object);
00221 
00222     /**
00223      * \brief A callback indicating that there was an error during the operation.
00224      * \param error, An error code for the occurred error.
00225      */
00226     virtual void error(M2MInterface::Error error);
00227 
00228     /**
00229      * \brief A callback indicating that the value of the resource object is updated by the server.
00230      * \param base, The object whose value is updated.
00231      * \param type, The type of the object.
00232      */
00233     virtual void value_updated(M2MBase *base, M2MBase::BaseType type);
00234 
00235 protected: // from M2MTimerObserver
00236 
00237     virtual void timer_expired(M2MTimerObserver::Type type);
00238 
00239 private:
00240     /**
00241      * \brief Redirects the state machine to right function.
00242      * \param current_state, The current state to be set.
00243      * \param data, The data to be passed to the state function.
00244      */
00245     void state_function(StartupSubStateRegistration current_state);
00246 
00247     /**
00248      * \brief The state engine maintaining the state machine logic.
00249      */
00250     void state_engine(void);
00251 
00252     /**
00253     * \brief An internal event generated by the state machine.
00254     * \param new_state, The new state to which the state machine should go.
00255     * \param data, The data to be passed to the state machine.
00256     */
00257     void internal_event(StartupSubStateRegistration new_state);
00258 
00259     /**
00260     * When the bootstrap starts.
00261     */
00262     void state_bootstrap_start();
00263 
00264     /**
00265     * When the bootstrap is started.
00266     */
00267     void state_bootstrap_started();
00268 
00269     /**
00270     * When the bootstrap is successful.
00271     */
00272     void state_bootstrap_success();
00273 
00274     /**
00275     * When the bootstrap failed.
00276     */
00277     void state_bootstrap_failure();
00278 
00279     /**
00280      * When the EST (enrollment-over-secure-transport) enrollment starts.
00281      */
00282     void state_est_start();
00283 
00284     /**
00285      * When the EST (enrollment-over-secure-transport) enrollment has been started.
00286      */
00287     void state_est_started();
00288 
00289     /**
00290      * When the EST (enrollment-over-secure-transport) enrollment is successful.
00291      */
00292     void state_est_success();
00293 
00294     /**
00295      * When the EST (enrollment-over-secure-transport) enrollment failed.
00296      */
00297     void state_est_failure();
00298 
00299     /**
00300     * When the registration starts.
00301     */
00302     void state_registration_start();
00303 
00304     /**
00305     * When the registration started.
00306     */
00307     void state_registration_started();
00308 
00309     /**
00310     * When the registration is successful.
00311     */
00312     void state_registration_success();
00313 
00314     /**
00315      * When the registration failed.
00316     */
00317     void state_registration_failure();
00318 
00319     /**
00320     * When the client is unregistered.
00321     */
00322     void state_unregistered();
00323 
00324     /**
00325      * \brief A utility function to create an M2MSecurity object
00326      * for registration.
00327      */
00328     void create_register_object();
00329 
00330     /**
00331      * \brief A utility function to create an M2MSecurity object
00332      * for bootstrap.
00333      */
00334     bool create_bootstrap_object();
00335 
00336     /**
00337      * \brief A utility function to set the connector credentials
00338      * in storage. This includes endpoint, domain, connector URI
00339      *  and certificates.
00340      * \param security, The Connector certificates.
00341      */
00342     ccs_status_e set_connector_credentials(M2MSecurity *security);
00343 
00344     /**
00345      * \brief A utility function to set the bootstrap credentials
00346      * in storage. This includes Bootstrap URI and certificates.
00347      * \param security, The Bootstrap certificates.
00348      */
00349     ccs_status_e set_bootstrap_credentials(M2MSecurity *security);
00350 
00351     /**
00352      * \brief A utility function to set the bootstrap address in storage.
00353      * \param security, The bootstrap security object containing the address.
00354      */
00355     ccs_status_e store_bootstrap_address(M2MSecurity *security);
00356 
00357     /**
00358      * \brief A utility function to check whether bootstrap credentials are stored in KCM.
00359      */
00360     bool bootstrap_credentials_stored_in_kcm();
00361 
00362     /**
00363      * \brief A utility function to check whether first to claim feature is configured.
00364      */
00365     bool is_first_to_claim();
00366 
00367     /**
00368      * \brief A utility function to clear the first to claim parameter in storage.
00369      */
00370     ccs_status_e clear_first_to_claim();
00371 
00372     /**
00373     * \brief Returns the binding mode selected by the client
00374     * through the configuration.
00375     * \return Binding mode of the client.
00376     */
00377     static M2MInterface::BindingMode transport_mode();
00378 
00379     /**
00380     * \brief Initializes the security object and callbacks.
00381     *
00382     */
00383     void init_security_object();
00384 
00385 private:
00386     // A callback to be called after the sequence is complete.
00387     ConnectorClientCallback*            _callback;
00388     StartupSubStateRegistration         _current_state;
00389     bool                                _event_generated;
00390     bool                                _state_engine_running;
00391     M2MInterface                        *_interface;
00392     M2MSecurity                         *_security;
00393     ConnectorClientEndpointInfo         _endpoint_info;
00394     M2MBaseList                         *_client_objs;
00395     M2MTimer                            _rebootstrap_timer;
00396     uint16_t                            _bootstrap_security_instance;
00397     uint16_t                            _lwm2m_security_instance;
00398     void                                *_certificate_chain_handle;
00399 };
00400 
00401 /**
00402  * \brief ConnectorClientCallback
00403  * A callback class for passing the client progress and error condition to the
00404  * ServiceClient class object.
00405  */
00406 class ConnectorClientCallback {
00407 public:
00408 
00409     /**
00410     * \brief Indicates that the registration or unregistration operation is complete
00411     * with success or failure.
00412     * \param status, Indicates success or failure in terms of status code.
00413     */
00414     virtual void registration_process_result(ConnectorClient::StartupSubStateRegistration status) = 0;
00415 
00416     /**
00417     * \brief Indicates the Connector error condition of an underlying M2MInterface client.
00418     * \param error, Indicates an error code translated from M2MInterface::Error.
00419     * \param reason, Indicates human readable text for error description.
00420     */
00421     virtual void connector_error(M2MInterface::Error error, const char *reason) = 0;
00422 
00423     /**
00424     * \brief A callback indicating that the value of the resource object is updated
00425     *  by the LWM2M Cloud server.
00426     * \param base, The object whose value is updated.
00427     * \param type, The type of the object.
00428     */
00429     virtual void value_updated(M2MBase *base, M2MBase::BaseType type) = 0;
00430 };
00431 
00432 #endif // !__CONNECTOR_CLIENT_H__