m2minterfaceimpl.h

00001 /*
00002  * Copyright (c) 2015 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef M2M_INTERFACE_IMPL_H
00017 #define M2M_INTERFACE_IMPL_H
00018 
00019 #include "mbed-client/m2minterface.h"
00020 #include "mbed-client/m2mserver.h"
00021 #include "mbed-client/m2mconnectionobserver.h"
00022 #include "mbed-client/m2mconnectionsecurity.h"
00023 #include "include/m2mnsdlobserver.h"
00024 #include "include/m2mnsdlinterface.h"
00025 #include "mbed-client/m2mtimerobserver.h"
00026 #include "mbed-client/m2mtimer.h"
00027 #include "mbed-client/m2mconnectionhandler.h"
00028 
00029 //FORWARD DECLARATION
00030 class M2MConnectionSecurity;
00031 class EventData;
00032 class M2MUpdateRegisterData;
00033 /**
00034  *  @brief M2MInterfaceImpl.
00035  *  This class implements handling of all mbed Client Interface operations
00036  *  defined in OMA LWM2M specifications.
00037  *  This includes Bootstrapping, Client Registration, Device Management &
00038  *  Service Enablement and Information Reporting.
00039  */
00040 
00041 class  M2MInterfaceImpl : public M2MInterface,
00042                           public M2MNsdlObserver,
00043                           public M2MConnectionObserver,
00044                           public M2MTimerObserver
00045 {
00046 private:
00047     // Prevents the use of assignment operator by accident.
00048     M2MInterfaceImpl& operator=( const M2MInterfaceImpl& /*other*/ );
00049 
00050     // Prevents the use of copy constructor by accident
00051     M2MInterfaceImpl( const M2MInterfaceImpl& /*other*/ );
00052 
00053 friend class M2MInterfaceFactory;
00054 
00055 private:
00056 
00057     /**
00058      * @brief Constructor
00059      * @param observer, Observer to pass the event callbacks for various
00060      * interface operations.
00061      * @param endpoint_name Endpoint name of the client.
00062      * @param endpoint_type Endpoint type of the client.
00063      * @param life_time Life time of the client in seconds
00064      * @param listen_port Listening port for the endpoint, default is 8000.
00065      * @param domain Domain of the client.
00066      * @param mode Binding mode of the client, default is UDP
00067      * @param stack Network stack to be used for connection, default is LwIP_IPv4.
00068      * @param context_address Context address, default is empty.
00069      */
00070     M2MInterfaceImpl(M2MInterfaceObserver& observer,
00071                      const String &endpoint_name,
00072                      const String &endpoint_type,
00073                      const int32_t life_time,
00074                      const uint16_t listen_port,
00075                      const String &domain = "",
00076                      BindingMode mode = M2MInterface::NOT_SET,
00077                      M2MInterface::NetworkStack stack = M2MInterface::LwIP_IPv4,
00078                      const String &context_address = "");
00079 
00080 public:
00081 
00082     /**
00083      * @brief Destructor
00084      */
00085     virtual ~M2MInterfaceImpl();
00086 
00087     /**
00088      * @brief Initiates bootstrapping of the client with the provided Bootstrap
00089      * server information.
00090      * @param security_object Security object which contains information
00091      * required for successful bootstrapping of the client.
00092      */
00093     virtual void bootstrap(M2MSecurity *security);
00094 
00095     /**
00096      * @brief Cancels on going bootstrapping operation of the client. If the client has
00097      * already successfully bootstrapped then this function deletes existing
00098      * bootstrap information from the client.
00099      */
00100     virtual void cancel_bootstrap();
00101 
00102     /**
00103      * @brief Initiates registration of the provided Security object to the
00104      * corresponding LWM2M server.
00105      * @param security_object Security object which contains information
00106      * required for registering to the LWM2M server.
00107      * If client wants to register to multiple LWM2M servers then it has call
00108      * this function once for each of LWM2M server object separately.
00109      * @param object_list Objects which contains information
00110      * which the client want to register to the LWM2M server.
00111      */
00112     virtual void register_object(M2MSecurity *security_object, const M2MObjectList &object_list);
00113 
00114     /**
00115      * @brief Updates or refreshes the client's registration on the LWM2M
00116      * server.
00117      * @param security_object Security object from which the device object
00118      * needs to update registration, if there is only one LWM2M server registered
00119      * then this parameter can be NULL.
00120      * @param lifetime Lifetime for the endpoint client in seconds.
00121      */
00122     virtual void update_registration(M2MSecurity *security_object, const uint32_t lifetime = 0);
00123 
00124     /**
00125      * @brief Updates or refreshes the client's registration on the LWM2M
00126      * server. Use this function to publish new objects to LWM2M server.
00127      * @param security_object The security object from which the device object
00128      * needs to update the registration. If there is only one LWM2M server registered,
00129      * this parameter can be NULL.
00130      * @param object_list Objects that contain information about the
00131      * client attempting to register to the LWM2M server.
00132      * @param lifetime The lifetime of the endpoint client in seconds. If the same value
00133      * has to be passed, set the default value to 0.
00134      */
00135     virtual void update_registration(M2MSecurity *security_object, const M2MObjectList &object_list,
00136                                      const uint32_t lifetime = 0);
00137 
00138     /**
00139      * @brief Unregisters the registered object from the LWM2M server
00140      * @param security_object Security object from which the device object
00141      * needs to be unregistered. If there is only one LWM2M server registered
00142      * this parameter can be NULL.
00143      */
00144     virtual void unregister_object(M2MSecurity* security = NULL);
00145 
00146     /**
00147      * @brief Sets the function which will be called indicating client
00148      * is going to sleep when the Binding mode is selected with Queue mode.
00149      * @param callback A function pointer that will be called when client
00150      * goes to sleep.
00151      */
00152     virtual void set_queue_sleep_handler(callback_handler handler);
00153 
00154     /**
00155      * @brief Sets the network interface handler that is used by client to connect
00156      * to a network over IP.
00157      * @param handler A network interface handler that is used by client to connect.
00158      *  This API is optional but provides a mechanism for different platforms to
00159      * manage usage of underlying network interface by client.
00160      */
00161     virtual void set_platform_network_handler(void *handler = NULL);
00162 
00163     /**
00164      * \brief Sets the function callback that will be called by mbed-client for
00165      * fetching random number from application for ensuring strong entropy.
00166      * \param random_callback A function pointer that will be called by mbed-client
00167      * while performing secure handshake.
00168      * Function signature should be uint32_t (*random_number_callback)(void);
00169      */
00170     virtual void set_random_number_callback(random_number_cb callback);
00171 
00172     /**
00173      * \brief Sets the function callback that will be called by mbed-client for
00174      * providing entropy source from application for ensuring strong entropy.
00175      * \param entropy_callback A function pointer that will be called by mbed-client
00176      * while performing secure handshake.
00177      * Function signature , if using mbed-client-mbedtls should be
00178      * int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output,
00179      *                                     size_t len, size_t *olen);
00180      */
00181     virtual void set_entropy_callback(entropy_cb callback);
00182 
00183 
00184 protected: // From M2MNsdlObserver
00185 
00186     virtual void coap_message_ready(uint8_t *data_ptr,
00187                                     uint16_t data_len,
00188                                     sn_nsdl_addr_s *address_ptr);
00189 
00190     virtual void client_registered(M2MServer *server_object);
00191 
00192     virtual void registration_updated(const M2MServer &server_object);
00193 
00194     virtual void registration_error(uint8_t error_code, bool retry = false);
00195 
00196     virtual void client_unregistered();
00197 
00198     virtual void bootstrap_done(M2MSecurity *security_object);
00199 
00200     virtual void bootstrap_wait(M2MSecurity *security_object);
00201 
00202     virtual void bootstrap_error();
00203 
00204     virtual void coap_data_processed();
00205 
00206     virtual void value_updated(M2MBase *base);
00207 
00208 protected: // From M2MConnectionObserver
00209 
00210     virtual void data_available(uint8_t* data,
00211                                 uint16_t data_size,
00212                                 const M2MConnectionObserver::SocketAddress &address);
00213 
00214     virtual void socket_error(uint8_t error_code, bool retry = true);
00215 
00216     virtual void address_ready(const M2MConnectionObserver::SocketAddress &address,
00217                                M2MConnectionObserver::ServerType server_type,
00218                                const uint16_t server_port);
00219 
00220     virtual void data_sent();
00221 
00222 protected: // from M2MTimerObserver
00223 
00224     virtual void timer_expired(M2MTimerObserver::Type type);
00225 
00226 
00227 private: // state machine state functions
00228 
00229     /**
00230     * When the state is Idle.
00231     */
00232     void state_idle(EventData* data);
00233 
00234     /**
00235     * When the client starts bootstrap.
00236     */
00237     void state_bootstrap( EventData *data);
00238 
00239     /**
00240     * When the bootstrap server address is resolved.
00241     */
00242     void state_bootstrap_address_resolved( EventData *data);
00243 
00244     /**
00245     * When the bootstrap resource is created.
00246     */
00247     void state_bootstrap_resource_created( EventData *data);
00248 
00249     /**
00250     * When the server has sent response and bootstrapping is done.
00251     */
00252     void state_bootstrapped( EventData *data);
00253 
00254     /**
00255     * When the client starts register.
00256     */
00257     void state_register( EventData *data);
00258 
00259     /**
00260     * When the server address for register is resolved.
00261     */
00262     void state_register_address_resolved( EventData *data);
00263 
00264     /**
00265     * When the client is registered.
00266     */
00267     void state_registered( EventData *data);
00268 
00269     /**
00270     * When the client is updating registration.
00271     */
00272     void state_update_registration( EventData *data);
00273 
00274     /**
00275     * When the client starts unregister.
00276     */
00277     void state_unregister( EventData *data);
00278 
00279     /**
00280     * When the client has been unregistered.
00281     */
00282     void state_unregistered( EventData *data);
00283 
00284     /**
00285     * When the coap data is been sent through socket.
00286     */
00287     void state_sending_coap_data( EventData *data);
00288 
00289     /**
00290     * When the coap data is sent successfully.
00291     */
00292     void state_coap_data_sent( EventData *data);
00293 
00294     /**
00295     * When the socket is receiving coap data.
00296     */
00297     void state_receiving_coap_data( EventData *data);
00298 
00299     /**
00300     * When the socket has received coap data.
00301     */
00302     void state_coap_data_received( EventData *data);
00303 
00304     /**
00305     * When the coap message is being processed.
00306     */
00307     void state_processing_coap_data( EventData *data);
00308 
00309     /**
00310     * When the coap message has been processed.
00311     */
00312     void state_coap_data_processed( EventData *data);
00313 
00314     /**
00315     * When the client is waiting to receive or send data.
00316     */
00317     void state_waiting( EventData *data);
00318 
00319     /**
00320      * Start registration update.
00321      */
00322     void start_register_update(M2MUpdateRegisterData *data);
00323 
00324     /**
00325     * State enumeration order must match the order of state
00326     * method entries in the state map
00327     */
00328     enum E_States {
00329         STATE_IDLE = 0,
00330         STATE_BOOTSTRAP,
00331         STATE_BOOTSTRAP_ADDRESS_RESOLVED,
00332         STATE_BOOTSTRAP_RESOURCE_CREATED,
00333         STATE_BOOTSTRAP_WAIT,
00334         STATE_BOOTSTRAPPED, //5
00335         STATE_REGISTER,
00336         STATE_REGISTER_ADDRESS_RESOLVED,
00337         STATE_REGISTERED,
00338         STATE_UPDATE_REGISTRATION,
00339         STATE_UNREGISTER, //10
00340         STATE_UNREGISTERED,
00341         STATE_SENDING_COAP_DATA,
00342         STATE_COAP_DATA_SENT,
00343         STATE_COAP_DATA_RECEIVED,
00344         STATE_PROCESSING_COAP_DATA, //15
00345         STATE_COAP_DATA_PROCESSED,
00346         STATE_WAITING,
00347         STATE_MAX_STATES
00348     };
00349 
00350     /**
00351      * @brief Redirects the state machine to right function.
00352      * @param current_state Current state to be set.
00353      * @param data Data to be passed to the state function.
00354      */
00355     void state_function( uint8_t current_state, EventData* data  );
00356 
00357     /**
00358      * @brief State Engine maintaining state machine logic.
00359      */
00360     void state_engine(void);
00361 
00362     /**
00363     * External event which can trigger the state machine.
00364     * @param New The state to which the state machine should go.
00365     * @param data The data to be passed to the state machine.
00366     */
00367     void external_event(uint8_t, EventData* = NULL);
00368 
00369     /**
00370     * Internal event generated by state machine.
00371     * @param New State which the state machine should go to.
00372     * @param data The data to be passed to the state machine.
00373     */
00374     void internal_event(uint8_t, EventData* = NULL);
00375 
00376     enum
00377     {
00378         EVENT_IGNORED = 0xFE,
00379         CANNOT_HAPPEN
00380     };
00381 
00382     /**
00383      * Helper method for extracting the IP address part and port from the
00384      * given server address.
00385      * @param server_address Source URL (without "coap" or "coaps" prefix).
00386      * @param ip_address The extracted IP.
00387      * @param port The extracted port.
00388      */
00389     static void process_address(const String& server_address, String& ip_address, uint16_t& port);
00390 
00391 private:
00392 
00393     EventData                   *_event_data;
00394     M2MTimer                    *_bootstrap_timer;
00395     uint16_t                    _server_port;
00396     uint16_t                    _listen_port;
00397     String                      _endpoint_type;
00398     String                      _domain;
00399     int32_t                     _life_time;
00400     String                      _context_address;
00401     String                      _server_ip_address;
00402     M2MSecurity                 *_register_server; //TODO: to be the list not owned
00403     M2MTimer                    _queue_sleep_timer;
00404     M2MTimer                    _retry_timer;
00405     callback_handler            _callback_handler;
00406     const uint8_t               _max_states;
00407     bool                        _event_ignored;
00408     bool                        _event_generated;
00409     bool                        _reconnecting;
00410     bool                        _retry_timer_expired;
00411     bool                        _bootstrapped;
00412     uint8_t                     _current_state;
00413     uint8_t                     _retry_count;
00414     BindingMode                 _binding_mode;
00415     M2MInterfaceObserver        &_observer;
00416     M2MConnectionSecurity       *_security_connection; // Doesn't own
00417     M2MConnectionHandler        _connection_handler;
00418     M2MNsdlInterface            _nsdl_interface;
00419     M2MSecurity                 *_security;
00420 
00421     friend class Test_M2MInterfaceImpl;
00422 
00423 };
00424 
00425 #define BEGIN_TRANSITION_MAP \
00426     static const uint8_t TRANSITIONS[] = {\
00427 
00428 #define TRANSITION_MAP_ENTRY(entry)\
00429     entry,
00430 
00431 #define END_TRANSITION_MAP(data) \
00432     0 };\
00433     external_event(TRANSITIONS[_current_state], data);
00434 
00435 #endif //M2M_INTERFACE_IMPL_H
00436 
00437