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 "mbed-client/m2mtimerobserver.h"
00025 
00026 //FORWARD DECLARATION
00027 class M2MNsdlInterface;
00028 class M2MConnectionHandler;
00029 class M2MConnectionSecurity;
00030 class EventData;
00031 class M2MTimer;
00032 
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 Unregisters the registered object from the LWM2M server
00126      * @param security_object, Security object from which the device object
00127      * needs to be unregistered, if there is only one LWM2M server registered
00128      * then this parameter can be NULL.
00129      */
00130     virtual void unregister_object(M2MSecurity* security = NULL);
00131 
00132     /**
00133      * @brief Sets the function which will be called indicating client
00134      * is going to sleep when the Binding mode is selected with Queue mode.
00135      * @param callback, Function pointer which will be called when client
00136      * goes to seleep.
00137      */
00138     virtual void set_queue_sleep_handler(callback_handler handler);
00139 
00140     /**
00141      * @brief Sets the network interface handler that is used by client to connect
00142      * to a network over IP..
00143      * @param handler A network interface handler that is used by client to connect.
00144      *  This API is optional but provides a mechanism for different platforms to
00145      * manage usage of underlying network interface by client.
00146      */
00147     virtual void set_platform_network_handler(void *handler = NULL);
00148 
00149 /**
00150      * \brief Sets the function callback that will be called by mbed-client for
00151      * fetching random number from application for ensuring strong entropy.
00152      * \param random_callback A function pointer that will be called by mbed-client
00153      * while performing secure handshake.
00154      * Function signature should be uint32_t (*random_number_callback)(void);
00155      */
00156     virtual void set_random_number_callback(random_number_cb callback);
00157 
00158     /**
00159      * \brief Sets the function callback that will be called by mbed-client for
00160      * providing entropy source from application for ensuring strong entropy.
00161      * \param entropy_callback A function pointer that will be called by mbed-client
00162      * while performing secure handshake.
00163      * Function signature , if using mbed-client-mbedtls should be
00164      * int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output,
00165      *                                     size_t len, size_t *olen);
00166      */
00167     virtual void set_entropy_callback(entropy_cb callback);
00168 
00169 
00170 protected: // From M2MNsdlObserver
00171 
00172     virtual void coap_message_ready(uint8_t *data_ptr,
00173                                     uint16_t data_len,
00174                                     sn_nsdl_addr_s *address_ptr);
00175 
00176     virtual void client_registered(M2MServer *server_object);
00177 
00178     virtual void registration_updated(const M2MServer &server_object);
00179 
00180     virtual void registration_error(uint8_t error_code, bool retry = false);
00181 
00182     virtual void client_unregistered();
00183 
00184     virtual void bootstrap_done(M2MSecurity *security_object);
00185 
00186     virtual void bootstrap_error();
00187 
00188     virtual void coap_data_processed();
00189 
00190     virtual void value_updated(M2MBase *base);
00191 
00192 protected: // From M2MConnectionObserver
00193 
00194     virtual void data_available(uint8_t* data,
00195                                 uint16_t data_size,
00196                                 const M2MConnectionObserver::SocketAddress &address);
00197 
00198     virtual void socket_error(uint8_t error_code, bool retry = true);
00199 
00200     virtual void address_ready(const M2MConnectionObserver::SocketAddress &address,
00201                                M2MConnectionObserver::ServerType server_type,
00202                                const uint16_t server_port);
00203 
00204     virtual void data_sent();
00205 
00206 protected: // from M2MTimerObserver
00207 
00208     virtual void timer_expired(M2MTimerObserver::Type type);
00209 
00210 
00211 private: // state machine state functions
00212 
00213     /**
00214     * When the state is Idle.
00215     */
00216     void state_idle(EventData* data);
00217 
00218     /**
00219     * When the client starts bootstrap.
00220     */
00221     void state_bootstrap( EventData *data);
00222 
00223     /**
00224     * When the bootstrap server address is resolved.
00225     */
00226     void state_bootstrap_address_resolved( EventData *data);
00227 
00228     /**
00229     * When the bootstrap resource is created.
00230     */
00231     void state_bootstrap_resource_created( EventData *data);
00232 
00233     /**
00234     * When the server has sent response and bootstrapping is done.
00235     */
00236     void state_bootstrapped( EventData *data);
00237 
00238     /**
00239     * When the client starts register.
00240     */
00241     void state_register( EventData *data);
00242 
00243     /**
00244     * When the server address for register is resolved.
00245     */
00246     void state_register_address_resolved( EventData *data);
00247 
00248     /**
00249     * When the register resource is created.
00250     */
00251     void state_register_resource_created( EventData *data);
00252 
00253     /**
00254     * When the client is registered.
00255     */
00256     void state_registered( EventData *data);
00257 
00258     /**
00259     * When the client is updating registration.
00260     */
00261     void state_update_registration( EventData *data);
00262 
00263     /**
00264     * When the client starts unregister.
00265     */
00266     void state_unregister( EventData *data);
00267 
00268     /**
00269     * When the client has been unregistered.
00270     */
00271     void state_unregistered( EventData *data);
00272 
00273     /**
00274     * When the coap data is been sent through socket.
00275     */
00276     void state_sending_coap_data( EventData *data);
00277 
00278     /**
00279     * When the coap data is sent successfully.
00280     */
00281     void state_coap_data_sent( EventData *data);
00282 
00283     /**
00284     * When the socket is receiving coap data.
00285     */
00286     void state_receiving_coap_data( EventData *data);
00287 
00288     /**
00289     * When the socket has received coap data.
00290     */
00291     void state_coap_data_received( EventData *data);
00292 
00293     /**
00294     * When the coap message is being processed.
00295     */
00296     void state_processing_coap_data( EventData *data);
00297 
00298     /**
00299     * When the coap message has been processed.
00300     */
00301     void state_coap_data_processed( EventData *data);
00302 
00303     /**
00304     * When the client is waiting to receive or send data.
00305     */
00306     void state_waiting( EventData *data);
00307 
00308     /**
00309     * State enumeration order must match the order of state
00310     * method entries in the state map
00311     */
00312     enum E_States {
00313         STATE_IDLE = 0,
00314         STATE_BOOTSTRAP,
00315         STATE_BOOTSTRAP_ADDRESS_RESOLVED,
00316         STATE_BOOTSTRAP_RESOURCE_CREATED,
00317         STATE_BOOTSTRAPPED,
00318         STATE_REGISTER, //5
00319         STATE_REGISTER_ADDRESS_RESOLVED,
00320         STATE_REGISTER_RESOURCE_CREATED,
00321         STATE_REGISTERED,
00322         STATE_UPDATE_REGISTRATION,
00323         STATE_UNREGISTER, //10
00324         STATE_UNREGISTERED,
00325         STATE_SENDING_COAP_DATA,
00326         STATE_COAP_DATA_SENT,
00327         STATE_COAP_DATA_RECEIVED,
00328         STATE_PROCESSING_COAP_DATA, //15
00329         STATE_COAP_DATA_PROCESSED,
00330         STATE_WAITING,
00331         STATE_MAX_STATES
00332     };
00333 
00334     /**
00335      * @brief Redirects the state machine to right function.
00336      * @param current_state Current state to be set.
00337      * @param data, Data to be passed to the state function.
00338      */
00339     void state_function( uint8_t current_state, EventData* data  );
00340 
00341     /**
00342      * @brief State Engine maintaining state machine logic.
00343      */
00344     void state_engine(void);
00345 
00346     /**
00347     * External event which can trigger the state machine.
00348     * @param New State which the state machine should go to.
00349     * @param data to be passed to the state machine.
00350     */
00351     void external_event(uint8_t, EventData* = NULL);
00352 
00353     /**
00354     * Internal event generated by state machine.
00355     * @param New State which the state machine should go to.
00356     * @param data to be passed to the state machine.
00357     */
00358     void internal_event(uint8_t, EventData* = NULL);
00359 
00360     enum
00361     {
00362         EVENT_IGNORED = 0xFE,
00363         CANNOT_HAPPEN
00364     };
00365 
00366     /**
00367      * Helper method for extracting the IP address part and port from the
00368      * given server address.
00369      * @param server_address source url (without "coap" or "coaps" prefix)
00370      * @param ip_address extracted IP
00371      * @param port extracted port
00372      */
00373     static void process_address(const String& server_address, String& ip_address, uint16_t& port);
00374 
00375 private:
00376 
00377     M2MInterfaceObserver        &_observer;
00378     M2MConnectionHandler        *_connection_handler;
00379     M2MConnectionSecurity       *_security_connection; // Doesn't own
00380     M2MNsdlInterface            *_nsdl_interface;
00381     uint8_t                     _current_state;
00382     const int                   _max_states;
00383     bool                        _event_generated;
00384     EventData                   *_event_data;
00385     String                      _endpoint_type;
00386     String                      _domain;
00387     int32_t                     _life_time;
00388     BindingMode                 _binding_mode;
00389     String                      _context_address;
00390     uint16_t                    _listen_port;
00391     uint16_t                    _server_port;
00392     String                      _server_ip_address;
00393     M2MSecurity                 *_register_server; //TODO: to be the list not owned
00394     bool                        _event_ignored;
00395     bool                        _register_ongoing;
00396     bool                        _update_register_ongoing;
00397     M2MTimer                    *_queue_sleep_timer;
00398     M2MTimer                    *_retry_timer;
00399     M2MTimer                    *_bootstrap_timer;
00400     callback_handler            _callback_handler;
00401     M2MSecurity                 *_security;
00402     uint8_t                     _retry_count;
00403     bool                        _reconnecting;
00404     bool                        _retry_timer_expired;
00405 
00406    friend class Test_M2MInterfaceImpl;
00407 
00408 };
00409 
00410 #define BEGIN_TRANSITION_MAP \
00411     static const uint8_t TRANSITIONS[] = {\
00412 
00413 #define TRANSITION_MAP_ENTRY(entry)\
00414     entry,
00415 
00416 #define END_TRANSITION_MAP(data) \
00417     0 };\
00418     external_event(TRANSITIONS[_current_state], data);
00419 
00420 #endif //M2M_INTERFACE_IMPL_H
00421 
00422