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 M2MBase;
00028 class M2MInterfaceObserver;
00029 
00030 typedef Vector<M2MObject*> M2MObjectList;
00031 typedef Vector<M2MBase*> M2MBaseList;
00032 typedef FP callback_handler;
00033 
00034 // TODO! Add more errors
00035 typedef enum request_error_e {
00036     FAILED_TO_SEND_MSG = 0,
00037     FAILED_TO_ALLOCATE_MEMORY = 1
00038 } request_error_t;
00039 
00040 typedef request_error_e get_data_req_error_e;
00041 typedef request_error_t get_data_req_error_t;
00042 
00043 /*!
00044  * @brief A callback function to receive data from GET request.
00045  *        Transfer is completed once total size equals to received size.
00046  *        Caller needs to take care of counting how many bytes it has received.
00047  * @param buffer Buffer containing the payload.
00048  * @param buffer_size Size of the payload.
00049  * @param total_size Total size of the package. This information is available only in first package.
00050  *                   Caller must store this information to detect when the download has completed.
00051  * @param context Application context
00052 */
00053 typedef void (*request_data_cb)(const uint8_t *buffer,
00054                                 size_t buffer_size,
00055                                 size_t total_size,
00056                                 void *context);
00057 typedef request_data_cb get_data_cb; // For backward compatibility
00058 
00059 /*!
00060  * @brief A callback function to receive errors from GET transfer.
00061  * @param error_code
00062  * @param context Application context
00063 */
00064 typedef void (*request_error_cb)(request_error_t error_code, void *context);
00065 typedef request_error_cb get_data_error_cb; // For backward compatibility
00066 
00067 
00068 /*! \file m2minterface.h
00069  *  \brief M2MInterface.
00070  *  This class provides an interface for handling all mbed Client interface operations
00071  *  defined in the OMA LWM2M specifications.
00072  *  This includes Bootstrapping, Client Registration, Device Management &
00073  *  Service Enablement and Information Reporting.
00074  */
00075 
00076 class M2MInterface {
00077 
00078 public:
00079 
00080     /**
00081      * \brief An enum defining different kinds of errors
00082      * that can occur during various client operations.
00083      */
00084     typedef enum {
00085         ErrorNone = 0,
00086         AlreadyExists,
00087         BootstrapFailed,
00088         InvalidParameters,
00089         NotRegistered,
00090         Timeout,
00091         NetworkError,
00092         ResponseParseFailed,
00093         UnknownError,
00094         MemoryFail,
00095         NotAllowed,
00096         SecureConnectionFailed,
00097         DnsResolvingFailed,
00098         UnregistrationFailed,
00099         ESTEnrollmentFailed
00100     }Error;
00101 
00102     /**
00103      * \brief An enum defining different kinds of binding
00104      * modes handled for client operations.
00105      */
00106     typedef enum {
00107         NOT_SET = 0,
00108         UDP = 0x01,
00109         UDP_QUEUE = 0x03,
00110         SMS = 0x04,
00111         SMS_QUEUE =0x06,
00112         UDP_SMS_QUEUE = 0x07,
00113         TCP = 0x09, //not real value, spec does not have one!
00114                     //this has nsdl binding mode bit UDP set
00115         TCP_QUEUE = 0x0b //not real value, spec does not have one!
00116                          //this has nsdl binding mode bits, UDP and UDP_QUEUE set
00117     }BindingMode;
00118 
00119     /**
00120      * \brief An enum defining different kinds of network
00121      * stacks that can be used by mbed Client.
00122      */
00123     typedef enum {
00124         Uninitialized = 0,
00125         LwIP_IPv4,
00126         LwIP_IPv6,
00127         Reserved,
00128         Nanostack_IPv6,
00129         ATWINC_IPv4,
00130         Unknown
00131     }NetworkStack;
00132 
00133 public:
00134 
00135     virtual ~M2MInterface(){}
00136 
00137     /**
00138      * \brief Initiates bootstrapping of the client with the provided Bootstrap
00139      * Server information.
00140      * NOTE: This API is not supported for developers!!
00141      * \param security_object A security object that contains information
00142      * required for successful bootstrapping of the client.
00143      */
00144     virtual void bootstrap(M2MSecurity *security_object) = 0;
00145 
00146     /**
00147      * \brief Cancels an ongoing bootstrapping operation of the client. If the client has
00148      * already successfully bootstrapped, this function deletes the existing
00149      * bootstrap information from the client.
00150      * NOTE: This API is not supported for developers!!
00151      */
00152     virtual void cancel_bootstrap() = 0;
00153 
00154     /**
00155      * \brief Finishes bootstrap in cases where client will be the one to finish it.
00156      */
00157     virtual void finish_bootstrap() = 0;
00158 
00159     /**
00160      * \brief Initiates the registration of a provided security object to the
00161      * corresponding LWM2M server.
00162      * \param security_object The security object that contains information
00163      * required for registering to the LWM2M server.
00164      * If the client wants to register to multiple LWM2M servers, it must call
00165      * this function once for each of the LWM2M server objects separately.
00166      * \param object_list Objects that contain information about the
00167      * client attempting to register to the LWM2M server.
00168      */
00169     virtual void register_object(M2MSecurity *security_object, const M2MBaseList &list) = 0;
00170 
00171     /**
00172      * \brief Initiates the registration of a provided security object to the
00173      * corresponding LWM2M server.
00174      * \param security_object The security object that contains information
00175      * required for registering to the LWM2M server.
00176      * If the client wants to register to multiple LWM2M servers, it must call
00177      * this function once for each of the LWM2M server objects separately.
00178      * \param object_list Objects that contain information about the
00179      * client attempting to register to the LWM2M server.
00180      */
00181     virtual void register_object(M2MSecurity *security_object, const M2MObjectList &object_list) = 0;
00182 
00183 
00184     /**
00185       * \brief Removes an object from M2MInterface.
00186       * Does not call delete on the object though.
00187       * \return true if the object was found and false if the object was not found.
00188       */
00189     virtual bool remove_object(M2MBase *base) = 0;
00190 
00191     /**
00192      * \brief Updates or refreshes the client's registration on the LWM2M
00193      * server.
00194      * \param security_object A security object from which the device object
00195      * needs to update the registration. If there is only one LWM2M server registered,
00196      * this parameter can be NULL.
00197      * \param lifetime The lifetime of the endpoint client in seconds. If the same value
00198      * has to be passed, set the default value to 0.
00199      */
00200     virtual void update_registration(M2MSecurity *security_object, const uint32_t lifetime = 0) = 0;
00201 
00202     /**
00203      * \brief Updates or refreshes the client's registration on the LWM2M
00204      * server. Use this function to publish new objects to LWM2M server.
00205      * \param security_object The security object from which the device object
00206      * needs to update the registration. If there is only one LWM2M server registered,
00207      * this parameter can be NULL.
00208      * \param object_list Objects that contain information about the
00209      * client attempting to register to the LWM2M server.
00210      * \param lifetime The lifetime of the endpoint client in seconds. If the same value
00211      * has to be passed, set the default value to 0.
00212      */
00213     virtual void update_registration(M2MSecurity *security_object, const M2MBaseList &list,
00214                                      const uint32_t lifetime = 0) = 0;
00215 
00216     /**
00217      * \brief Updates or refreshes the client's registration on the LWM2M
00218      * server. Use this function to publish new objects to LWM2M server.
00219      * \param security_object The security object from which the device object
00220      * needs to update the registration. If there is only one LWM2M server registered,
00221      * this parameter can be NULL.
00222      * \param object_list Objects that contain information about the
00223      * client attempting to register to the LWM2M server.
00224      * \param lifetime The lifetime of the endpoint client in seconds. If the same value
00225      * has to be passed, set the default value to 0.
00226      */
00227     virtual void update_registration(M2MSecurity *security_object, const M2MObjectList &object_list,
00228                                      const uint32_t lifetime = 0) = 0;
00229 
00230     /**
00231      * \brief Unregisters the registered object from the LWM2M server.
00232      * \param security_object The security object from which the device object
00233      * needs to be unregistered. If there is only one LWM2M server registered,
00234      * this parameter can be NULL.
00235      */
00236     virtual void unregister_object(M2MSecurity* security_object = NULL) = 0;
00237 
00238     /**
00239      * \brief Sets the function that is called for indicating that the client
00240      * is going to sleep when the binding mode is selected with queue mode.
00241      * \param callback A function pointer that is called when the client
00242      * goes to sleep.
00243      */
00244     virtual void set_queue_sleep_handler(callback_handler handler) = 0;
00245 
00246     /**
00247      * \brief Sets the function callback that is called by mbed Client to
00248      * fetch a random number from an application to ensure strong entropy.
00249      * \param random_callback A function pointer that is called by mbed Client
00250      * while performing a secure handshake.
00251      * The function signature should be uint32_t (*random_number_callback)(void);
00252      */
00253     virtual void set_random_number_callback(random_number_cb callback) = 0;
00254 
00255     /**
00256      * \brief Sets the function callback that is called by mbed Client to
00257      * provide an entropy source from an application to ensure strong entropy.
00258      * \param entropy_callback A function pointer that is called by mbed Client
00259      * while performing a secure handshake.
00260      * Function signature, if using mbed-client-mbedtls, should be
00261      * int (*mbedtls_entropy_f_source_ptr)(void *data, unsigned char *output,
00262      *                                     size_t len, size_t *olen);
00263      */
00264     virtual void set_entropy_callback(entropy_cb callback) = 0;
00265 
00266     /**
00267      * \brief Sets the network interface handler that is used by mbed Client to connect
00268      * to a network over IP.
00269      * \param handler A network interface handler that is used by mbed Client to connect.
00270      *  This API is optional but it provides a mechanism for different platforms to
00271      * manage the usage of underlying network interface by the client.
00272      */
00273     virtual void set_platform_network_handler(void *handler = NULL) = 0;
00274 
00275     /**
00276      * @brief Updates the endpoint name.
00277      * @param name New endpoint name
00278      */
00279     virtual void update_endpoint(String &name) = 0;
00280 
00281     /**
00282      * @brief Updates the domain name.
00283      * @param domain New domain name
00284      */
00285     virtual void update_domain(String &domain) = 0;
00286 
00287 
00288     /**
00289      * @brief Return internal endpoint name
00290      * @return internal endpoint name
00291      */
00292     virtual const String internal_endpoint_name() const = 0;
00293 
00294     /**
00295      * @brief Return error description for the latest error code
00296      * @return Error description string
00297      */
00298     virtual const char *error_description() const = 0;
00299 
00300     /**
00301      * @brief Sends the CoAP GET request to the server.
00302      * @uri Uri path to the data.
00303      * @offset Data offset.
00304      * @async In async mode application must call this API again with the updated offset.
00305      *        If set to false then client will automatically download the whole package.
00306      * @get_data_cb Callback which is triggered once there is data available.
00307      * @get_data_error_cb Callback which is trigged in case of any error.
00308     */
00309     virtual void get_data_request(const char *uri,
00310                                   const size_t offset,
00311                                   const bool async,
00312                                   get_data_cb,
00313                                   get_data_error_cb,
00314                                   void *context) = 0;
00315 
00316     /**
00317      * @brief Sends the CoAP POST request to the server.
00318      * @uri Uri path to the data.
00319      * @async In async mode application must call this API again with the updated offset.
00320      *        If set to false then client will automatically download the whole package.
00321      * @payload_len Length of payload.
00322      * @payload_ptr, Pointer to payload buffer.
00323      * @get_data_cb Callback which is triggered once there is data available.
00324      * @get_data_error_cb Callback which is trigged in case of any error.
00325      */
00326     virtual void post_data_request(const char *uri,
00327                                    const bool async,
00328                                    const uint16_t payload_len,
00329                                    uint8_t *payload_ptr,
00330                                    get_data_cb data_cb,
00331                                    get_data_error_cb error_cb,
00332                                    void *context) = 0;
00333 
00334     /**
00335      * @brief Set custom uri query paramaters used in LWM2M registration.
00336      * @uri_query_params Uri query params. Parameters must be in key-value format:
00337      * "a=100&b=200". Maximum length can be up to 64 bytes.
00338      * @return False if maximum length exceeded otherwise True.
00339     */
00340     virtual bool set_uri_query_parameters(const char *uri_query_params) = 0;
00341 };
00342 
00343 #endif // M2M_INTERFACE_H