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