m2mresource.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_H
00017 #define M2M_RESOURCE_H
00018 
00019 #include "mbed-client/m2mvector.h"
00020 #include "mbed-client/m2mresourcebase.h"
00021 #include "mbed-client/m2mresourceinstance.h"
00022 #include "mbed-client/coap_response.h"
00023 #include <stdlib.h>
00024 
00025 //FORWARD DECLARATION
00026 class M2MObjectInstance;
00027 typedef Vector<M2MResourceInstance *> M2MResourceInstanceList;
00028 
00029 /*! \file m2mresource.h
00030  *  \brief M2MResource.
00031  *  This class is the base class for mbed Client Resources.
00032  *
00033  *  All defined LwM2M object models can be created using it.
00034  *  This class will also hold all resources instances associated with the given object.
00035  */
00036 
00037 /*! \class M2MResource
00038  *  \brief The base class for Client Resources.
00039  */
00040 class M2MResource : public M2MResourceBase
00041 {
00042 
00043     friend class M2MObjectInstance;
00044 
00045 public:
00046     class M2MExecuteParameter;
00047 
00048 private: // Constructor and destructor are private,
00049          // which means that these objects can be created or
00050          // deleted only through a function provided by the M2MObjectInstance.
00051 
00052     M2MResource(M2MObjectInstance &_parent,
00053                  const lwm2m_parameters_s* s,
00054                  M2MBase::DataType type);
00055     /**
00056      * \brief Constructor
00057      * \param resource_name The resource name of the object.
00058      * \param resource_type The resource type of the object.
00059      * \param type The resource data type of the object.
00060      * \param value The value pointer of the object.
00061      * \param value_length The length of the value pointer.
00062      * \param path Full path of the resource, eg. 1/2/3. Ownership of the memory is transferred.
00063      * \param object_name The name of the object where the resource exists.
00064      * \param multiple_instance True if the resource supports instances.
00065      * \param external_blockwise_store If true CoAP blocks are passed to application through callbacks
00066      *        otherwise handled in mbed-client-c.
00067      */
00068     M2MResource(M2MObjectInstance &_parent,
00069                 const String &resource_name,
00070                 M2MBase::Mode mode,
00071                 const String &resource_type,
00072                 M2MBase::DataType type,
00073                 const uint8_t *value,
00074                 const uint8_t value_length,
00075                 char *path,
00076                 bool multiple_instance = false,
00077                 bool external_blockwise_store = false);
00078 
00079     /**
00080      * \brief Constructor
00081      * \param resource_name The resource name of the object.
00082      * \param resource_type The resource type of the object.
00083      * \param type The resource data type of the object.
00084      * \param observable Indicates whether the resource is observable or not.
00085      * \param path Full path of the resource, eg. 1/2/3. Ownership of the memory is transferred.
00086      * \param object_name The name of the object where the resource exists.
00087      * \param multiple_instance True if the resource supports instances.
00088      * \param external_blockwise_store If true CoAP blocks are passed to application through callbacks
00089      *        otherwise handled in mbed-client-c.
00090      */
00091     M2MResource(M2MObjectInstance &_parent,
00092                 const String &resource_name,
00093                 M2MBase::Mode mode,
00094                 const String &resource_type,
00095                 M2MBase::DataType type,
00096                 bool observable,
00097                 char *path,
00098                 bool multiple_instance = false,
00099                 bool external_blockwise_store = false);
00100 
00101     // Prevents the use of a default constructor.
00102     M2MResource();
00103 
00104     // Prevents the use of an assignment operator.
00105     M2MResource& operator=( const M2MResource& /*other*/ );
00106 
00107     // Prevents the use of a copy constructor
00108     M2MResource( const M2MResource& /*other*/ );
00109 
00110     /**
00111      * \brief Returns the owner object. Can return NULL if the object has no parent.
00112      */
00113     virtual M2MBase *get_parent() const;
00114 
00115     /**
00116      * Destructor
00117      */
00118     virtual ~M2MResource();
00119 
00120 public:
00121 
00122     /**
00123      * \brief Adds resource instances to a M2MResource.
00124      * \param resource_instance The resource instance to be added.
00125      */
00126     void add_resource_instance(M2MResourceInstance *resource_instance);
00127 
00128     /**
00129      * \brief Returns whether the resource has multiple
00130      * resource instances or not.
00131      * \return True if the resource base has multiple instances,
00132      * else false.
00133      */
00134     bool supports_multiple_instances() const;
00135 
00136 #ifndef DISABLE_DELAYED_RESPONSE
00137     /**
00138      * \brief Sets whether the resource should send a delayed response for a POST request.
00139      * This only works for resources which don't support multiple instances.
00140      * Please use M2MBase::set_async_coap_request_cb method, if you are using
00141      * ENABLE_ASYNC_REST_RESPONSE flag, because this method will be deprecated.
00142      * \param delayed_response A boolean value to set the delayed response.
00143      */
00144 #ifdef ENABLE_ASYNC_REST_RESPONSE
00145     void set_delayed_response(bool delayed_response) m2m_deprecated;
00146 #else
00147     void set_delayed_response(bool delayed_response);
00148 #endif
00149     /**
00150      * \brief A trigger to send the delayed response for the POST request.
00151      * The delayed_response flag must be set before receiving the POST request
00152      * and the value of the resource must be updated before calling this function.
00153      * This sends the post response with code 'COAP_MSG_CODE_RESPONSE_CHANGED'.
00154      * Please use M2MBase::send_async_response_with_code method, if you are using
00155      * ENABLE_ASYNC_REST_RESPONSE flag, because this method will be deprecated.
00156      * \return True if a response is sent, else false.
00157      */
00158     bool send_delayed_post_response();
00159 
00160     /**
00161      * \brief Provides the value of the token of the delayed post response.
00162      * \param[out] token A pointer to the token value.
00163      * \param[out] token_length The length of the token pointer.
00164      */
00165     void get_delayed_token(uint8_t *&token, uint8_t &token_length);
00166 
00167     /**
00168      * \brief Returns the value set for delayed response for POST requests.
00169      * \return The value for delayed response.
00170      */
00171     bool delayed_response() const;
00172 #endif //DISABLE_DELAYED_RESPONSE
00173 
00174     /**
00175      * \brief Removes a resource with a given name.
00176      * \param instance_id The instance ID of the resource to be removed, default is 0.
00177      * \return True if removed, else false.
00178      */
00179     bool remove_resource_instance(uint16_t instance_id = 0);
00180 
00181     /**
00182      * \brief Returns a resource instance with a given name.
00183      * \param instance_id The instance ID of the requested resource, default is 0
00184      * \return M2MResourceInstance object if found, else NULL.
00185      */
00186     M2MResourceInstance* resource_instance(uint16_t instance_id = 0) const;
00187 
00188     /**
00189      * \brief Returns a list of resources.
00190      * \return A list of resources.
00191      */
00192     const M2MResourceInstanceList& resource_instances() const;
00193 
00194     /**
00195      * \brief Returns the total number of resources.
00196      * \return The total number of resources.
00197      */
00198     uint16_t resource_instance_count() const;
00199 
00200     /**
00201      * \brief Returns the Observation Handler object.
00202      * \return M2MObservationHandler object.
00203     */
00204     virtual M2MObservationHandler* observation_handler() const;
00205 
00206     /**
00207      * \brief Sets the observation handler
00208      * \param handler Observation handler
00209     */
00210     virtual void set_observation_handler(M2MObservationHandler *handler);
00211 
00212     /**
00213      * \brief Parses the received query for a notification
00214      * attribute.
00215      * \return True if required attributes are present, else false.
00216      */
00217     virtual bool handle_observation_attribute(const char *query);
00218 
00219     /**
00220      * \brief Adds the observation level for the object.
00221      * \param observation_level The level of observation.
00222      */
00223     virtual void add_observation_level(M2MBase::Observation observation_level);
00224 
00225     /**
00226      * \brief Removes the observation level from an object.
00227      * \param observation_level The level of observation.
00228      */
00229     virtual void remove_observation_level(M2MBase::Observation observation_level);
00230 
00231     /**
00232      * \brief Handles the GET request for registered objects.
00233      * \param nsdl An NSDL handler for the CoAP library.
00234      * \param received_coap_header The CoAP message received from the server.
00235      * \param observation_handler A handler object for sending
00236      * observation callbacks.
00237      * \return sn_coap_hdr_s The message that needs to be sent to the server.
00238      */
00239     virtual sn_coap_hdr_s* handle_get_request(nsdl_s *nsdl,
00240                                               sn_coap_hdr_s *received_coap_header,
00241                                               M2MObservationHandler *observation_handler = NULL);
00242     /**
00243      * \brief Handles the PUT request for registered objects.
00244      * \param nsdl An NSDL handler for the CoAP library.
00245      * \param received_coap_header The CoAP message received from the server.
00246      * \param observation_handler A handler object for sending
00247      * observation callbacks.
00248      * \param execute_value_updated True executes the "value_updated" callback.
00249      * \return sn_coap_hdr_s The message that needs to be sent to the server.
00250      */
00251     virtual sn_coap_hdr_s* handle_put_request(nsdl_s *nsdl,
00252                                               sn_coap_hdr_s *received_coap_header,
00253                                               M2MObservationHandler *observation_handler,
00254                                               bool &execute_value_updated);
00255     /**
00256      * \brief Handles the POST request for registered objects.
00257      * \param nsdl An NSDL handler for the CoAP library.
00258      * \param received_coap_header The CoAP message received from the server.
00259      * \param observation_handler A handler object for sending
00260      * observation callbacks.
00261      * \param execute_value_updated True executes the "value_updated" callback.
00262      * \return sn_coap_hdr_s The message that needs to be sent to the server.
00263      */
00264     virtual sn_coap_hdr_s* handle_post_request(nsdl_s *nsdl,
00265                                                sn_coap_hdr_s *received_coap_header,
00266                                                M2MObservationHandler *observation_handler,
00267                                                bool &execute_value_updated,
00268                                                sn_nsdl_addr_s *address = NULL);
00269 
00270     M2MObjectInstance& get_parent_object_instance() const;
00271 
00272     /**
00273      * \brief Returns the instance ID of the object where the resource exists.
00274      * \return Object instance ID.
00275     */
00276     virtual uint16_t object_instance_id() const;
00277 
00278     /**
00279      * \brief Returns the name of the object where the resource exists.
00280      * \return Object name.
00281     */
00282     virtual const char* object_name() const;
00283 
00284     virtual M2MResource& get_parent_resource() const;
00285 private:
00286     M2MObjectInstance &_parent;
00287 
00288     M2MResourceInstanceList     _resource_instance_list; // owned
00289 #ifndef DISABLE_DELAYED_RESPONSE
00290     uint8_t                     *_delayed_token;
00291     uint8_t                     _delayed_token_len;
00292     bool                        _delayed_response;
00293 #endif
00294 
00295 friend class Test_M2MResource;
00296 friend class Test_M2MObjectInstance;
00297 friend class Test_M2MObject;
00298 friend class Test_M2MDevice;
00299 friend class Test_M2MSecurity;
00300 friend class Test_M2MServer;
00301 friend class Test_M2MNsdlInterface;
00302 friend class Test_M2MFirmware;
00303 friend class Test_M2MTLVSerializer;
00304 friend class Test_M2MTLVDeserializer;
00305 friend class Test_M2MBase;
00306 friend class Test_M2MResourceInstance;
00307 friend class TestFactory;
00308 };
00309 
00310 /**
00311  *  \brief M2MResource::M2MExecuteParameter.
00312  *  This class handles the "Execute" operation arguments.
00313  */
00314 class M2MResource::M2MExecuteParameter {
00315 
00316 private:
00317 
00318     /**
00319      * \brief Constructor, since there is no implementation, it prevents invalid use of it
00320      */
00321     M2MExecuteParameter();
00322 
00323 #ifdef MEMORY_OPTIMIZED_API
00324     M2MExecuteParameter(const char *object_name, const char *resource_name, uint16_t object_instance_id);
00325 #else
00326     // This is a deprecated constructor, to be removed on next release.
00327     M2MExecuteParameter(const String &object_name, const String &resource_name, uint16_t object_instance_id);
00328 #endif
00329 
00330 public:
00331 
00332     /**
00333      * \brief Returns the value of an argument.
00334      * \return uint8_t * The argument value.
00335      */
00336     const uint8_t *get_argument_value() const;
00337 
00338     /**
00339      * \brief Returns the length of the value argument.
00340      * \return uint8_t The argument value length.
00341      */
00342     uint16_t get_argument_value_length() const;
00343 
00344     /**
00345      * \brief Returns the name of the object where the resource exists.
00346      * \return Object name.
00347     */
00348 #ifdef MEMORY_OPTIMIZED_API
00349     const char* get_argument_object_name() const;
00350 #else
00351     const String& get_argument_object_name() const;
00352 #endif
00353 
00354     /**
00355      * \brief Returns the resource name.
00356      * \return Resource name.
00357     */
00358 #ifdef MEMORY_OPTIMIZED_API
00359     const char* get_argument_resource_name() const;
00360 #else
00361     const String& get_argument_resource_name() const;
00362 #endif
00363 
00364     /**
00365      * \brief Returns the instance ID of the object where the resource exists.
00366      * \return Object instance ID.
00367     */
00368     uint16_t get_argument_object_instance_id() const;
00369 
00370 private:
00371     // pointers to const data, not owned by this instance
00372 
00373 #ifdef MEMORY_OPTIMIZED_API
00374     const char      *_object_name;
00375     const char      *_resource_name;
00376 #else
00377     const String    &_object_name;
00378     const String    &_resource_name;
00379 #endif
00380 
00381     const uint8_t   *_value;
00382     uint16_t        _value_length;
00383     uint16_t        _object_instance_id;
00384 
00385 friend class Test_M2MResource;
00386 friend class M2MResource;
00387 };
00388 
00389 #endif // M2M_RESOURCE_H