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 /**
00033  *  \brief M2MInterface.
00034  *  This class provides an interface for handling all the 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 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 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 = 0x08, //not real value, spec does not have one!
00076         TCP_QUEUE = 0x09 //not real value, spec does not have one!
00077     }BindingMode;
00078 
00079     /**
00080      * \brief Enum defining different kinds of network
00081      * stacks that can be used by mbed Client.
00082      */
00083     typedef enum {
00084         Uninitialized = 0,
00085         LwIP_IPv4,
00086         LwIP_IPv6,
00087         Reserved,
00088         Nanostack_IPv6,
00089         ATWINC_IPv4,
00090         Unknown
00091     }NetworkStack;
00092 
00093 public:
00094 
00095     virtual ~M2MInterface(){}
00096 
00097     /**
00098      * \brief Initiates bootstrapping of the client with the provided Bootstrap
00099      * Server information.
00100      * NOTE: This API is not supported for developers!!
00101      * \param security_object The security object that contains information
00102      * required for successful bootstrapping of the client.
00103      */
00104     virtual void bootstrap(M2MSecurity *security_object) = 0;
00105 
00106     /**
00107      * \brief Cancels the ongoing bootstrapping operation of the client. If the client has
00108      * already successfully bootstrapped, this function deletes the existing
00109      * bootstrap information from the client.
00110      * NOTE: This API is not supported for developers!!
00111      */
00112     virtual void cancel_bootstrap() = 0;
00113 
00114     /**
00115      * \brief Initiates the registration of the provided Security object to the
00116      * corresponding LWM2M server.
00117      * \param security_object The security object that contains information
00118      * required for registering to the LWM2M server.
00119      * If the client wants to register to multiple LWM2M servers, it must call
00120      * this function once for each of the LWM2M server objects separately.
00121      * \param object_list Objects that contain information about the
00122      * client attempting to register to the LWM2M server.
00123      */
00124     virtual void register_object(M2MSecurity *security_object, const M2MObjectList &object_list) = 0;
00125 
00126     /**
00127      * \brief Updates or refreshes the client's registration on the LWM2M
00128      * server.
00129      * \param security_object The security object from which the device object
00130      * needs to update the registration. If there is only one LWM2M server registered,
00131      * this parameter can be NULL.
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 uint32_t lifetime = 0) = 0;
00136 
00137     /**
00138      * \brief Unregisters the registered object from the LWM2M server.
00139      * \param security_object The security object from which the device object
00140      * needs to be unregistered. If there is only one LWM2M server registered,
00141      * this parameter can be NULL.
00142      */
00143     virtual void unregister_object(M2MSecurity* security_object = NULL) = 0;
00144 
00145     /**
00146      * \brief Sets the function that is called for indicating that the client
00147      * is going to sleep when the Binding mode is selected with Queue mode.
00148      * \param callback A function pointer that is called when the client
00149      * goes to sleep.
00150      */
00151     virtual void set_queue_sleep_handler(callback_handler handler) = 0;
00152 
00153     /**
00154      * \brief Sets the function callback that is called by mbed-client to
00155      * fetch a random number from an application to ensure strong entropy.
00156      * \param random_callback A function pointer that is called by mbed-client
00157      * while performing a secure handshake.
00158      * The function signature should be uint32_t (*random_number_callback)(void);
00159      */
00160     virtual void set_random_number_callback(random_number_cb callback) = 0;
00161 
00162     /**
00163      * \brief Sets the function callback that is called by mbed-client to
00164      * provide an entropy source from an application to ensure strong entropy.
00165      * \param entropy_callback A function pointer that is called by mbed-client
00166      * while performing a secure handshake.
00167      * Function signature, if using mbed-client-mbedtls, should be
00168      * int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output,
00169      *                                     size_t len, size_t *olen);
00170      */
00171     virtual void set_entropy_callback(entropy_cb callback) = 0;
00172 
00173     /**
00174      * \brief Sets the network interface handler that is used by client to connect
00175      * to a network over IP..
00176      * \param handler A network interface handler that is used by client to connect.
00177      *  This API is optional but provides a mechanism for different platforms to
00178      * manage usage of underlying network interface by client.
00179      */
00180     virtual void set_platform_network_handler(void *handler = NULL) = 0;
00181 };
00182 
00183 #endif // M2M_INTERFACE_H