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