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