m2mresourcebase.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_RESOURCE_BASE_H
00017 #define M2M_RESOURCE_BASE_H
00018 
00019 #include "mbed-client/m2mbase.h"
00020 #include "mbed-client/functionpointer.h"
00021 
00022 
00023 /*! \file m2mresourcebase.h
00024  *  \brief M2MResourceBase.
00025  *  This class is the base class for mbed Client Resources. All defined
00026  *  LWM2M resource models can be created based on it.
00027  */
00028 class M2MBlockMessage;
00029 
00030 typedef FP1<void,void*> execute_callback;
00031 typedef void(*execute_callback_2) (void *arguments);
00032 
00033 typedef FP0<void> notification_sent_callback;
00034 typedef void(*notification_sent_callback_2) (void);
00035 
00036 #ifndef DISABLE_BLOCK_MESSAGE
00037 typedef FP1<void, M2MBlockMessage *> incoming_block_message_callback;
00038 typedef FP3<void, const String &, uint8_t *&, uint32_t &> outgoing_block_message_callback;
00039 #endif
00040 
00041 class M2MResource;
00042 
00043 class M2MResourceBase : public M2MBase {
00044 
00045 friend class M2MObjectInstance;
00046 friend class M2MResource;
00047 friend class M2MResourceInstance;
00048 
00049 public:
00050 
00051     typedef enum {
00052         INIT = 0,   // Initial state.
00053         SENT,       // Notification created/sent but not received ACK yet.
00054         DELIVERED   // Received ACK from server.
00055     } NotificationStatus;
00056 
00057     typedef FP2<void, const uint16_t, const M2MResourceBase::NotificationStatus> notification_status_callback;
00058 
00059     typedef void(*notification_status_callback_2) (const uint16_t msg_id,
00060                                                    const M2MResourceBase::NotificationStatus status);
00061 
00062     /**
00063      * An enum defining a resource type that can be
00064      * supported by a given resource.
00065     */
00066     typedef enum {
00067         STRING,
00068         INTEGER,
00069         FLOAT,
00070         BOOLEAN,
00071         OPAQUE,
00072         TIME,
00073         OBJLINK
00074     } ResourceType;
00075 
00076     /*
00077      * \brief Value set callback function.
00078      * \param resource Pointer to resource whose value should be updated
00079      * \param value Pointer to value buffer containing new value, ownership is transferred to callback function
00080      * \param value_length Length of value buffer
00081      */
00082     typedef void(*value_set_callback) (const M2MResourceBase *resource, uint8_t *value, const uint32_t value_length);
00083 
00084     /*
00085      * \brief Read resource value callback function.
00086      * \param resource Pointer to resource whose value should will be read
00087      * \param buffer[OUT] Buffer containing the resource value
00088      * \param buffer_size[IN/OUT] Buffer length
00089      * \param client_args Client arguments
00090      * \return Error code, 0 on success otherwise < 0
00091      */
00092     typedef int(*read_resource_value_callback) (const M2MResourceBase& resource,
00093                                                 void *buffer,
00094                                                 size_t *buffer_size,
00095                                                 void *client_args);
00096 
00097     /*
00098      * \brief Set resource value callback function.
00099      * \param resource Pointer to resource whose value will be updated
00100      * \param buffer Buffer containing the new value
00101      * \param buffer_size Size of the data
00102      * \param client_args Client arguments
00103      * \return error code, True if value storing completed otherwise False
00104      */
00105     typedef bool(*write_resource_value_callback) (const M2MResourceBase& resource,
00106                                                   const uint8_t *buffer,
00107                                                   const size_t buffer_size,
00108                                                   void *client_args);
00109 
00110 protected: // Constructor and destructor are private
00111            // which means that these objects can be created or
00112            // deleted only through a function provided by the M2MObjectInstance.
00113 
00114     M2MResourceBase(
00115                         const lwm2m_parameters_s* s,
00116                         M2MBase::DataType type);
00117     /**
00118      * \brief A constructor for creating a resource.
00119      * \param resource_name The name of the resource.
00120      * \param resource_type The type of the resource.
00121      * \param type The resource data type of the object.
00122      * \param object_name Object name where resource exists.
00123      * \param path Path of the object like 3/0/1
00124      * \param external_blockwise_store If true CoAP blocks are passed to application through callbacks
00125      *        otherwise handled in mbed-client-c.
00126      */
00127     M2MResourceBase(
00128                         const String &resource_name,
00129                         M2MBase::Mode mode,
00130                         const String &resource_type,
00131                         M2MBase::DataType type,
00132                         char* path,
00133                         bool external_blockwise_store,
00134                         bool multiple_instance);
00135 
00136     /**
00137      * \brief A Constructor for creating a resource.
00138      * \param resource_name The name of the resource.
00139      * \param resource_type The type of the resource.
00140      * \param type The resource data type of the object.
00141      * \param value The value pointer of the object.
00142      * \param value_length The length of the value pointer.
00143      * \param value_length The length of the value pointer.
00144      * \param object_name Object name where resource exists.
00145      * \param path Path of the object like 3/0/1
00146      * \param external_blockwise_store If true CoAP blocks are passed to application through callbacks
00147      *        otherwise handled in mbed-client-c.
00148      */
00149     M2MResourceBase(
00150                         const String &resource_name,
00151                         M2MBase::Mode mode,
00152                         const String &resource_type,
00153                         M2MBase::DataType type,
00154                         const uint8_t *value,
00155                         const uint8_t value_length,
00156                         char* path,
00157                         bool external_blockwise_store,
00158                         bool multiple_instance);
00159 
00160     // Prevents the use of default constructor.
00161     M2MResourceBase();
00162 
00163     // Prevents the use of assignment operator.
00164     M2MResourceBase& operator=( const M2MResourceBase& /*other*/ );
00165 
00166     // Prevents the use of copy constructor
00167     M2MResourceBase( const M2MResourceBase& /*other*/ );
00168 
00169     /**
00170      * Destructor
00171      */
00172     virtual ~M2MResourceBase();
00173 
00174 public:
00175 
00176     /**
00177      * \brief Returns the resource data type.
00178      * \return ResourceType.
00179      */
00180     M2MResourceBase::ResourceType resource_instance_type() const;
00181 
00182     /**
00183      * \brief Sets the function that should be executed when this
00184      * resource receives a POST command.
00185      * \param callback The function pointer that needs to be executed.
00186      * \return True, if callback could be set, false otherwise.
00187      */
00188     bool set_execute_function(execute_callback callback);
00189 
00190     /**
00191      * \brief Sets the function that should be executed when this
00192      * resource receives a POST command.
00193      * \param callback The function pointer that needs to be executed.
00194      * \return True, if callback could be set, false otherwise.
00195      */
00196     bool set_execute_function(execute_callback_2 callback);
00197 
00198     /**
00199      * \brief Sets the function that is executed when the resource value change.
00200      * \param callback The function pointer that needs to be executed.
00201      * \param client_args Client arguments.
00202      * \return True, if callback could be set, false otherwise.
00203      */
00204     bool set_resource_read_callback(read_resource_value_callback callback, void *client_args);
00205 
00206     /**
00207      * \brief Sets the function that is executed when reading the resource value.
00208      * \param callback The function pointer that needs to be executed.
00209      * \param client_args Client arguments.
00210      * \return True, if callback could be set, false otherwise.
00211      */
00212     bool set_resource_write_callback(write_resource_value_callback callback, void *client_args);
00213 
00214     /**
00215      * \brief Executes the function that is set in "set_resource_read_callback".
00216      * \note If "read_resource_value_callback" is not set this is internally calling value() and value_length() API's.
00217      * \param resource Pointer to resource whose value will be read.
00218      * \param buffer[OUT] Buffer where the value is stored.
00219      * \param buffer_len[IN/OUT] Buffer length
00220      * \return Error code, 0 on success otherwise < 0
00221      */
00222     int read_resource_value(const M2MResourceBase& resource, void *buffer, size_t *buffer_len);
00223 
00224     /**
00225      * \brief Executes the function that is set in "set_resource_write_callback".
00226      * \param resource Pointer to resource where value will be stored.
00227      * \param buffer Buffer containing the new value.
00228      * \param buffer_size Size of the data.
00229      * \return True if storing succeeded otherwise False.
00230      */
00231     bool write_resource_value(const M2MResourceBase& resource, const uint8_t *buffer, const size_t buffer_size);
00232 
00233     /**
00234      * \brief Sets a value of a given resource.
00235      * \param value A pointer to the value to be set on the resource.
00236      * \param value_length The length of the value pointer.
00237      * \return True if successfully set, else false.
00238      * \note If resource is observable, calling this API rapidly (< 1s) can fill up the CoAP resending queue
00239      * and notification sending fails. CoAP resending queue size can be modified through:
00240      * "sn-coap-resending-queue-size-msgs" and "sn-coap-resending-queue-size-bytes" parameters.
00241      * Increasing these parameters will increase the memory consumption.
00242      */
00243     bool set_value(const uint8_t *value, const uint32_t value_length);
00244 
00245     /**
00246      * \brief Sets a value of a given resource.
00247      * \param value A pointer to the value to be set on the resource, ownerhip transfered.
00248      * \param value_length The length of the value pointer.
00249      * \return True if successfully set, else false.
00250      * \note If resource is observable, calling this API rapidly (< 1s) can fill up the CoAP resending queue
00251      * and notification sending fails. CoAP resending queue size can be modified through:
00252      * "sn-coap-resending-queue-size-msgs" and "sn-coap-resending-queue-size-bytes" parameters.
00253      * Increasing these parameters will increase the memory consumption.
00254      */
00255     bool set_value_raw(uint8_t *value, const uint32_t value_length);
00256 
00257     /**
00258      * \brief Sets a value of a given resource.
00259      * \param value, A new value formatted as a string
00260      * and set on the resource.
00261      * \return True if successfully set, else false.
00262      * \note If resource is observable, calling this API rapidly (< 1s) can fill up the CoAP resending queue
00263      * and notification sending fails. CoAP resending queue size can be modified through:
00264      * "sn-coap-resending-queue-size-msgs" and "sn-coap-resending-queue-size-bytes" parameters.
00265      * Increasing these parameters will increase the memory consumption.
00266      */
00267     bool set_value(int64_t value);
00268 
00269     /**
00270      * \brief Sets a value of a given resource.
00271      * \param value, A new value formatted as a string
00272      * and set on the resource.
00273      * \return True if successfully set, else false.
00274      * \note If resource is observable, calling this API rapidly (< 1s) can fill up the CoAP resending queue
00275      * and notification sending fails. CoAP resending queue size can be modified through:
00276      * "sn-coap-resending-queue-size-msgs" and "sn-coap-resending-queue-size-bytes" parameters.
00277      * Increasing these parameters will increase the memory consumption.
00278      */
00279     bool set_value_float(float value);
00280 
00281     /**
00282      * \brief Clears the value of a given resource.
00283      */
00284     void clear_value();
00285 
00286     /**
00287      * \brief Executes the function that is set in "set_execute_function".
00288      * \param arguments The arguments that are passed to be executed.
00289      */
00290     void execute(void *arguments);
00291 
00292     /**
00293      * \brief Provides the value of the given resource.
00294      * \param value[OUT] A pointer to the resource value.
00295      * \param value_length[OUT] The length of the value pointer.
00296      * \note If value argument is not NULL, it will be freed.
00297      */
00298     void get_value(uint8_t *&value, uint32_t &value_length);
00299 
00300     /**
00301      * \brief Converts a value to integer and returns it. Note: Conversion
00302      * errors are not detected.
00303      */
00304     int64_t get_value_int() const;
00305 
00306     /**
00307      * Get the value as a string object. No encoding/charset conversions
00308      * are done for the value, just a raw copy.
00309      */
00310     String get_value_string() const;
00311 
00312     /**
00313      * \brief Converts a value to float and returns it. Note: Conversion
00314      * errors are not detected.
00315      */
00316     float get_value_float() const;
00317 
00318     /**
00319      * \brief Returns the value pointer of the object.
00320      * \return The value pointer of the object.
00321      */
00322     uint8_t* value() const;
00323 
00324     /**
00325      * \brief Returns the length of the value pointer.
00326      * \return The length of the value pointer.
00327      */
00328     uint32_t value_length() const;
00329 
00330     /**
00331      * \brief Set the value set callback. The set callback will be called instead of setting
00332      * the value in set_value methods. When this function is set actual value change is done
00333      * using the update_value function.
00334      * \param callback Callback function that will handle new value
00335      */
00336     void set_value_set_callback(value_set_callback callback);
00337 
00338     /**
00339      * \brief Default value update function. This function frees old value, stores the new value
00340      * and informs report handler in case it changed.
00341      * \param value Pointer to new value, ownership is transferred to client
00342      * \param value_length Length of new value buffer
00343      */
00344     void update_value(uint8_t *value, const uint32_t value_length);
00345 
00346     /**
00347      * \brief Handles the GET request for the registered objects.
00348      * \param nsdl An NSDL handler for the CoAP library.
00349      * \param received_coap_header The CoAP message received from the server.
00350      * \param observation_handler A handler object for sending
00351      * observation callbacks.
00352      * \return sn_coap_hdr_s The message that needs to be sent to the server.
00353      */
00354     virtual sn_coap_hdr_s* handle_get_request(nsdl_s *nsdl,
00355                                               sn_coap_hdr_s *received_coap_header,
00356                                               M2MObservationHandler *observation_handler = NULL);
00357     /**
00358      * \brief Handles the PUT request for the registered objects.
00359      * \param nsdl An NSDL handler for the CoAP library.
00360      * \param received_coap_header The CoAP message received from the server.
00361      * \param observation_handler A handler object for sending
00362      * observation callbacks.
00363      * \param execute_value_updated True will execute the "value_updated" callback.
00364      * \return sn_coap_hdr_s The message that needs to be sent to the server.
00365      */
00366     virtual sn_coap_hdr_s* handle_put_request(nsdl_s *nsdl,
00367                                               sn_coap_hdr_s *received_coap_header,
00368                                               M2MObservationHandler *observation_handler,
00369                                               bool &execute_value_updated);
00370 
00371     /**
00372      * \brief Returns the instance ID of the object where the resource exists.
00373      * \return Object instance ID.
00374     */
00375     virtual uint16_t object_instance_id() const = 0;
00376 
00377     /**
00378      * \brief Returns the name of the object where the resource exists.
00379      * \return Object name.
00380     */
00381     virtual const char* object_name() const = 0;
00382 
00383     virtual M2MResource& get_parent_resource() const = 0;
00384 
00385 #ifndef DISABLE_BLOCK_MESSAGE
00386     /**
00387      * @brief Sets the function that is executed when this
00388      * object receives a block-wise message.
00389      * @param callback The function pointer that is called.
00390      */
00391     bool set_incoming_block_message_callback(incoming_block_message_callback callback);
00392 
00393     /**
00394      * @brief Sets the function that is executed when this
00395      * object receives a GET request.
00396      * This is called if resource values are stored on the application side.
00397      * @note Due to a limitation in the mbed-client-c library, the whole
00398      * payload up to 64 KiB must be supplied in the single callback.
00399      * @param callback The function pointer that is called.
00400      */
00401     bool set_outgoing_block_message_callback(outgoing_block_message_callback callback);
00402 
00403     /**
00404      * \brief Returns the block message object.
00405      * \return Block message.
00406     */
00407     M2MBlockMessage* block_message() const;
00408 
00409 #endif
00410 
00411     /**
00412      * @brief Sets the function that is executed when this object receives
00413      * response(Empty ACK) for notification message.
00414      * @param callback The function pointer that is called.
00415      */
00416     bool set_notification_sent_callback(notification_sent_callback callback) m2m_deprecated;
00417 
00418     /**
00419      * @brief Sets the function that is executed when this object receives
00420      * response(Empty ACK) for notification message.
00421      * @param callback The function pointer that is called.
00422      */
00423     bool set_notification_sent_callback(notification_sent_callback_2 callback) m2m_deprecated;
00424 
00425     /**
00426      * @brief Sets the function that is executed when this object receives
00427      * response(Empty ACK) for notification message.
00428      * @param callback The function pointer that is called.
00429      */
00430     bool set_notification_status_callback(notification_status_callback callback) m2m_deprecated;
00431 
00432     /**
00433      * @brief Sets the function that is executed when this object receives
00434      * response(Empty ACK) for notification message.
00435      * @param callback The function pointer that is called.
00436      */
00437     bool set_notification_status_callback(notification_status_callback_2 callback);
00438 
00439     /**
00440      * \brief Executes the function that is set in "set_notification_sent_callback".
00441      */
00442     void notification_sent();
00443 
00444     /**
00445      * \brief Executes the function that is set in "set_notification_status_callback".
00446      */
00447     void notification_status(const uint16_t msg_id, NotificationStatus status);
00448 
00449     /**
00450      * \brief Returns notification send status.
00451      * \return Notification status.
00452      */
00453     M2MResourceBase::NotificationStatus notification_status() const;
00454 
00455     /**
00456      * \brief Clears the notification send status to initial state.
00457      */
00458     void clear_notification_status();
00459 
00460     /**
00461      * @brief Set the status whether resource value will be part of registration message.     *
00462      * This only allowed for following resource types:
00463      * STRING,
00464      * INTEGER,
00465      * FLOAT,
00466      * BOOLEAN
00467      * OPAQUE
00468      *
00469      * @param publish_value If true then resource value will be part of registration message.
00470      */
00471     void publish_value_in_registration_msg(bool publish_value);
00472 
00473 private:
00474 
00475     void report();
00476 
00477     void report_value_change();
00478 
00479     bool has_value_changed(const uint8_t* value, const uint32_t value_len);
00480 
00481     M2MResourceBase::ResourceType convert_data_type(M2MBase::DataType type) const;
00482 
00483 private:
00484 
00485 #ifndef DISABLE_BLOCK_MESSAGE
00486     M2MBlockMessage     *_block_message_data;
00487 #endif
00488 
00489     NotificationStatus    _notification_status : 2;
00490 
00491     friend class Test_M2MResourceInstance;
00492     friend class Test_M2MResource;
00493     friend class Test_M2MObjectInstance;
00494     friend class Test_M2MObject;
00495     friend class Test_M2MDevice;
00496     friend class Test_M2MSecurity;
00497     friend class Test_M2MServer;
00498     friend class Test_M2MNsdlInterface;
00499     friend class Test_M2MFirmware;
00500     friend class Test_M2MTLVSerializer;
00501     friend class Test_M2MTLVDeserializer;
00502 };
00503 
00504 #endif // M2M_RESOURCE_BASE_H