m2minterface.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_H
00017 #define M2M_INTERFACE_H
00018 
00019 #include <stdint.h>
00020 #include "mbed-client/m2mvector.h"
00021 #include "mbed-client/m2mconfig.h"
00022 #include "mbed-client/functionpointer.h"
00023 
00024 //FORWARD DECLARATION
00025 class M2MSecurity;
00026 class M2MObject;
00027 class M2MInterfaceObserver;
00028 
00029 typedef Vector<M2MObject *> M2MObjectList;
00030 typedef FP callback_handler;
00031 
00032 /*! \file m2minterface.h
00033  *  \brief M2MInterface.
00034  *  This class provides an interface for handling all mbed Client interface operations
00035  *  defined in the OMA LWM2M specifications.
00036  *  This includes Bootstrapping, Client Registration, Device Management &
00037  *  Service Enablement and Information Reporting.
00038  */
00039 
00040 class M2MInterface {
00041 
00042 public:
00043 
00044     /**
00045      * \brief An enum defining different kinds of errors
00046      * that can occur during various client operations.
00047      */
00048     typedef enum {
00049         ErrorNone = 0,
00050         AlreadyExists,
00051         BootstrapFailed,
00052         InvalidParameters,
00053         NotRegistered,
00054         Timeout,
00055         NetworkError,
00056         ResponseParseFailed,
00057         UnknownError,
00058         MemoryFail,
00059         NotAllowed,
00060         SecureConnectionFailed,
00061         DnsResolvingFailed
00062     }Error;
00063 
00064     /**
00065      * \brief An enum defining different kinds of binding
00066      * modes handled for client operations.
00067      */
00068     typedef enum {
00069         NOT_SET = 0,
00070         UDP = 0x01,
00071         UDP_QUEUE = 0x03,
00072         SMS = 0x04,
00073         SMS_QUEUE =0x06,
00074         UDP_SMS_QUEUE = 0x07,
00075         TCP = 0x09, //not real value, spec does not have one!
00076                     //this has nsdl binding mode bit UDP set
00077         TCP_QUEUE = 0x0b //not real value, spec does not have one!
00078                          //this has nsdl binding mode bits, UDP and UDP_QUEUE set
00079     }BindingMode;
00080 
00081     /**
00082      * \brief An enum defining different kinds of network
00083      * stacks that can be used by mbed Client.
00084      */
00085     typedef enum {
00086         Uninitialized = 0,
00087         LwIP_IPv4,
00088         LwIP_IPv6,
00089         Reserved,
00090         Nanostack_IPv6,
00091         ATWINC_IPv4,
00092         Unknown
00093     }NetworkStack;
00094 
00095 public:
00096 
00097     virtual ~M2MInterface(){}
00098 
00099     /**
00100      * \brief Initiates bootstrapping of the client with the provided Bootstrap
00101      * Server information.
00102      * NOTE: This API is not supported for developers!!
00103      * \param security_object A security object that contains information
00104      * required for successful bootstrapping of the client.
00105      */
00106     virtual void bootstrap(M2MSecurity *security_object) = 0;
00107 
00108     /**
00109      * \brief Cancels an ongoing bootstrapping operation of the client. If the client has
00110      * already successfully bootstrapped, this function deletes the existing
00111      * bootstrap information from the client.
00112      * NOTE: This API is not supported for developers!!
00113      */
00114     virtual void cancel_bootstrap() = 0;
00115 
00116     /**
00117      * \brief Initiates the registration of a provided security object to the
00118      * corresponding LWM2M server.
00119      * \param security_object The security object that contains information
00120      * required for registering to the LWM2M server.
00121      * If the client wants to register to multiple LWM2M servers, it must call
00122      * this function once for each of the LWM2M server objects separately.
00123      * \param object_list Objects that contain information about the
00124      * client attempting to register to the LWM2M server.
00125      */
00126     virtual void register_object(M2MSecurity *security_object, const M2MObjectList &object_list) = 0;
00127 
00128     /**
00129      * \brief Updates or refreshes the client's registration on the LWM2M
00130      * server.
00131      * \param security_object A security object from which the device object
00132      * needs to update the registration. If there is only one LWM2M server registered,
00133      * this parameter can be NULL.
00134      * \param lifetime The lifetime of the endpoint client in seconds. If the same value
00135      * has to be passed, set the default value to 0.
00136      */
00137     virtual void update_registration(M2MSecurity *security_object, const uint32_t lifetime = 0) = 0;
00138 
00139     /**
00140      * \brief Updates or refreshes the client's registration on the LWM2M
00141      * server. Use this function to publish new objects to LWM2M server.
00142      * \param security_object The security object from which the device object
00143      * needs to update the registration. If there is only one LWM2M server registered,
00144      * this parameter can be NULL.
00145      * \param object_list Objects that contain information about the
00146      * client attempting to register to the LWM2M server.
00147      * \param lifetime The lifetime of the endpoint client in seconds. If the same value
00148      * has to be passed, set the default value to 0.
00149      */
00150     virtual void update_registration(M2MSecurity *security_object, const M2MObjectList &object_list,
00151                                      const uint32_t lifetime = 0) = 0;
00152 
00153     /**
00154      * \brief Unregisters the registered object from the LWM2M server.
00155      * \param security_object The security object from which the device object
00156      * needs to be unregistered. If there is only one LWM2M server registered,
00157      * this parameter can be NULL.
00158      */
00159     virtual void unregister_object(M2MSecurity* security_object = NULL) = 0;
00160 
00161     /**
00162      * \brief Sets the function that is called for indicating that the client
00163      * is going to sleep when the binding mode is selected with queue mode.
00164      * \param callback A function pointer that is called when the client
00165      * goes to sleep.
00166      */
00167     virtual void set_queue_sleep_handler(callback_handler handler) = 0;
00168 
00169     /**
00170      * \brief Sets the function callback that is called by mbed Client to
00171      * fetch a random number from an application to ensure strong entropy.
00172      * \param random_callback A function pointer that is called by mbed Client
00173      * while performing a secure handshake.
00174      * The function signature should be uint32_t (*random_number_callback)(void);
00175      */
00176     virtual void set_random_number_callback(random_number_cb callback) = 0;
00177 
00178     /**
00179      * \brief Sets the function callback that is called by mbed Client to
00180      * provide an entropy source from an application to ensure strong entropy.
00181      * \param entropy_callback A function pointer that is called by mbed Client
00182      * while performing a secure handshake.
00183      * Function signature, if using mbed-client-mbedtls, should be
00184      * int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output,
00185      *                                     size_t len, size_t *olen);
00186      */
00187     virtual void set_entropy_callback(entropy_cb callback) = 0;
00188 
00189     /**
00190      * \brief Sets the network interface handler that is used by mbed Client to connect
00191      * to a network over IP.
00192      * \param handler A network interface handler that is used by mbed Client to connect.
00193      *  This API is optional but it provides a mechanism for different platforms to
00194      * manage the usage of underlying network interface by the client.
00195      */
00196     virtual void set_platform_network_handler(void *handler = NULL) = 0;
00197 };
00198 
00199 #endif // M2M_INTERFACE_H