m2mresourceinstance.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_INSTANCE_H
00017 #define M2M_RESOURCE_INSTANCE_H
00018 
00019 #include "mbed-client/m2mbase.h"
00020 #include "mbed-client/functionpointer.h"
00021 
00022 
00023 /*! \file m2mresourceinstance.h
00024  *  \brief M2MResourceInstance.
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 typedef FP1<void, M2MBlockMessage *> incoming_block_message_callback;
00037 typedef FP3<void, const String &, uint8_t *&, uint32_t &> outgoing_block_message_callback;
00038 
00039 class M2MResource;
00040 class M2MResourceCallback;
00041 
00042 class M2MResourceInstance : public M2MBase {
00043 
00044 friend class M2MObjectInstance;
00045 friend class M2MResource;
00046 
00047 public:
00048 
00049     /**
00050      * An enum defining a resource type that can be
00051      * supported by a given resource.
00052     */
00053     typedef enum {
00054         STRING,
00055         INTEGER,
00056         FLOAT,
00057         BOOLEAN,
00058         OPAQUE,
00059         TIME,
00060         OBJLINK
00061     }ResourceType;
00062 
00063 
00064 private: // Constructor and destructor are private
00065          // which means that these objects can be created or
00066          // deleted only through a function provided by the M2MObjectInstance.
00067 
00068     M2MResourceInstance(M2MResource &parent,
00069                         const lwm2m_parameters_s* s,
00070                         M2MResourceInstance::ResourceType type,
00071                         const uint16_t object_instance_id);
00072     /**
00073      * \brief A constructor for creating a resource.
00074      * \param resource_name The name of the resource.
00075      * \param resource_type The type of the resource.
00076      * \param type The resource data type of the object.
00077      * \param object_instance_id Object instance id where resource exists.
00078      * \param object_name Object name where resource exists.
00079      * \param path Path of the object like 3/0/1
00080      * \param external_blockwise_store If true CoAP blocks are passed to application through callbacks
00081      *        otherwise handled in mbed-client-c.
00082      */
00083     M2MResourceInstance(M2MResource &parent,
00084                         const String &resource_name,
00085                         const String &resource_type,
00086                         M2MResourceInstance::ResourceType type,
00087                         const uint16_t object_instance_id,
00088                         char* path,
00089                         bool external_blockwise_store);
00090 
00091     /**
00092      * \brief A Constructor for creating a resource.
00093      * \param resource_name The name of the resource.
00094      * \param resource_type The type of the resource.
00095      * \param type The resource data type of the object.
00096      * \param value The value pointer of the object.
00097      * \param value_length The length of the value pointer.
00098      * \param value_length The length of the value pointer.
00099      * \param object_instance_id Object instance id where resource exists.
00100      * \param object_name Object name where resource exists.
00101      * \param path Path of the object like 3/0/1
00102      * \param external_blockwise_store If true CoAP blocks are passed to application through callbacks
00103      *        otherwise handled in mbed-client-c.
00104      */
00105     M2MResourceInstance(M2MResource &parent,
00106                         const String &resource_name,
00107                         const String &resource_type,
00108                         M2MResourceInstance::ResourceType type,
00109                         const uint8_t *value,
00110                         const uint8_t value_length,
00111                         const uint16_t object_instance_id,
00112                         char* path,
00113                         bool external_blockwise_store);
00114 
00115     // Prevents the use of default constructor.
00116     M2MResourceInstance();
00117 
00118     // Prevents the use of assignment operator.
00119     M2MResourceInstance& operator=( const M2MResourceInstance& /*other*/ );
00120 
00121     // Prevents the use of copy constructor
00122     M2MResourceInstance( const M2MResourceInstance& /*other*/ );
00123 
00124     /**
00125      * Destructor
00126      */
00127     virtual ~M2MResourceInstance();
00128 
00129 public:
00130 
00131     /**
00132      * \brief Returns the object type.
00133      * \return BaseType.
00134      */
00135     virtual M2MBase::BaseType base_type() const;
00136 
00137     /**
00138      * \brief Returns the resource data type.
00139      * \return ResourceType.
00140      */
00141     virtual M2MResourceInstance::ResourceType resource_instance_type() const;
00142 
00143     /**
00144      * \brief Parses the received query for a notification
00145      * attribute.
00146      * \return True if required attributes are present, else false.
00147      */
00148     virtual bool handle_observation_attribute(const char *query);
00149 
00150     /**
00151      * \brief Sets the function that should be executed when this
00152      * resource receives a POST command.
00153      * \param callback The function pointer that needs to be executed.
00154      */
00155     virtual void set_execute_function(execute_callback  callback);
00156 
00157     /**
00158      * \brief Sets the function that should be executed when this
00159      * resource receives a POST command.
00160      * \param callback The function pointer that needs to be executed.
00161      */
00162     virtual void set_execute_function(execute_callback_2 callback);
00163 
00164     /**
00165      * \brief Sets a value of a given resource.
00166      * \param value A pointer to the value to be set on the resource.
00167      * \param value_length The length of the value pointer.
00168      * \return True if successfully set, else false.
00169      */
00170     virtual bool set_value(const uint8_t *value, const uint32_t value_length);
00171 
00172     /**
00173      * \brief Sets a value of a given resource.
00174      * \param value, A new value formatted as a string
00175      * and set on the resource.
00176      * \return True if successfully set, else false.
00177      */
00178     virtual bool set_value(int64_t value);
00179 
00180     /**
00181      * \brief Clears the value of a given resource.
00182      */
00183     virtual void clear_value();
00184 
00185     /**
00186      * \brief Executes the function that is set in "set_execute_function".
00187      * \param arguments The arguments that are passed to be executed.
00188      */
00189     void execute(void *arguments);
00190 
00191     /**
00192      * \brief Provides the value of the given resource.
00193      * \param value[OUT] A pointer to the resource value.
00194      * \param value_length[OUT] The length of the value pointer.
00195      */
00196     virtual void get_value(uint8_t *&value, uint32_t &value_length);
00197 
00198     /**
00199      * \brief Converts a value to integer and returns it. Note: Conversion
00200      * errors are not detected.
00201      */
00202     int get_value_int();
00203 
00204     /**
00205      * Get the value as a string object. No encoding/charset conversions
00206      * are done for the value, just a raw copy.
00207      */
00208     String get_value_string() const;
00209 
00210     /**
00211      * \brief Returns the value pointer of the object.
00212      * \return The value pointer of the object.
00213     */
00214     uint8_t* value() const;
00215 
00216     /**
00217      * \brief Returns the length of the value pointer.
00218      * \return The length of the value pointer.
00219     */
00220     uint32_t value_length() const;
00221 
00222     /**
00223      * \brief Handles the GET request for the registered objects.
00224      * \param nsdl An NSDL handler for the CoAP library.
00225      * \param received_coap_header The CoAP message received from the server.
00226      * \param observation_handler A handler object for sending
00227      * observation callbacks.
00228      * \return sn_coap_hdr_s The message that needs to be sent to the server.
00229      */
00230     virtual sn_coap_hdr_s* handle_get_request(nsdl_s *nsdl,
00231                                               sn_coap_hdr_s *received_coap_header,
00232                                               M2MObservationHandler *observation_handler = NULL);
00233     /**
00234      * \brief Handles the PUT request for the registered objects.
00235      * \param nsdl An NSDL handler for the CoAP library.
00236      * \param received_coap_header The CoAP message received from the server.
00237      * \param observation_handler A handler object for sending
00238      * observation callbacks.
00239      * \param execute_value_updated True will execute the "value_updated" callback.
00240      * \return sn_coap_hdr_s The message that needs to be sent to the server.
00241      */
00242     virtual sn_coap_hdr_s* handle_put_request(nsdl_s *nsdl,
00243                                               sn_coap_hdr_s *received_coap_header,
00244                                               M2MObservationHandler *observation_handler,
00245                                               bool &execute_value_updated);
00246 
00247     /**
00248      * \brief Returns the instance ID of the object where the resource exists.
00249      * \return Object instance ID.
00250     */
00251     uint16_t object_instance_id() const;
00252 
00253     /**
00254      * \brief Returns the name of the object where the resource exists.
00255      * \return Object name.
00256     */
00257     virtual const char* object_name() const;
00258 
00259     /**
00260      * @brief Sets the function that is executed when this
00261      * object receives a block-wise message.
00262      * @param callback The function pointer that is called.
00263      */
00264     virtual void set_incoming_block_message_callback(incoming_block_message_callback callback);
00265 
00266     /**
00267      * @brief Sets the function that is executed when this
00268      * object receives a GET request.
00269      * This is called if resource values are stored on the application side.
00270      * NOTE! Due to a limitation in the mbed-client-c library, a GET request can only contain data size up to 65KB.
00271      * @param callback The function pointer that is called.
00272      */
00273     virtual void set_outgoing_block_message_callback(outgoing_block_message_callback callback);
00274 
00275     /**
00276      * \brief Returns the block message object.
00277      * \return Block message.
00278     */
00279     virtual M2MBlockMessage* block_message() const;
00280 
00281     /**
00282      * @brief Sets the function that is executed when this object receives
00283      * response(Empty ACK) for notification message.
00284      * @param callback The function pointer that is called.
00285      */
00286     void set_notification_sent_callback(notification_sent_callback callback);
00287 
00288     /**
00289      * @brief Sets the function that is executed when this object receives
00290      * response(Empty ACK) for notification message.
00291      * @param callback The function pointer that is called.
00292      */
00293     void set_notification_sent_callback(notification_sent_callback_2 callback);
00294 
00295     /**
00296      * \brief Executes the function that is set in "set_notification_sent_callback".
00297      */
00298     void notification_sent();
00299 
00300     M2MResource& get_parent_resource() const;
00301 
00302 protected:
00303 
00304     /**
00305      * \brief Set an observer for sending the notification update.
00306      * \param resource The callback handle.
00307      */
00308     void set_resource_observer(M2MResourceCallback *resource);
00309 
00310 private:
00311 
00312     void report();
00313 
00314     bool is_value_changed(const uint8_t* value, const uint32_t value_len);
00315 
00316 private:
00317 
00318     // XXX: since the M2MResource is inherited from this class, the resource actually has back
00319     // pointer to itself. If this inheritance was broken, we could save some memory.
00320     M2MResource &_parent_resource;
00321 
00322     uint8_t                                 *_value;
00323     uint32_t                                _value_length;
00324     M2MBlockMessage                         *_block_message_data;
00325     execute_callback                         *_execute_callback;
00326     M2MResourceCallback                     *_resource_callback; // Not owned
00327     FP1<void, void*>                         *_execute_function_pointer;
00328     FP0<void>                               *_notification_sent_function_pointer;
00329 
00330     // Note: these two callbacks should be moved behind ifdef, as they are not needed by all/most apps.
00331     incoming_block_message_callback         *_incoming_block_message_cb;
00332     outgoing_block_message_callback         *_outgoing_block_message_cb;
00333 
00334     notification_sent_callback              *_notification_sent_callback;
00335     uint16_t                                _object_instance_id;
00336     ResourceType                            _resource_type;
00337 
00338     friend class Test_M2MResourceInstance;
00339     friend class Test_M2MResource;
00340     friend class Test_M2MObjectInstance;
00341     friend class Test_M2MObject;
00342     friend class Test_M2MDevice;
00343     friend class Test_M2MSecurity;
00344     friend class Test_M2MServer;
00345     friend class Test_M2MNsdlInterface;
00346     friend class Test_M2MFirmware;
00347     friend class Test_M2MTLVSerializer;
00348     friend class Test_M2MTLVDeserializer;
00349 };
00350 
00351 #endif // M2M_RESOURCE_INSTANCE_H