m2mbase.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_BASE_H
00017 #define M2M_BASE_H
00018 
00019 // Support for std args
00020 #include <stdint.h>
00021 #include "mbed-client/m2mconfig.h"
00022 #include "mbed-client/m2mreportobserver.h"
00023 #include "mbed-client/functionpointer.h"
00024 #include "mbed-client/m2mstringbuffer.h"
00025 #include "nsdl-c/sn_nsdl.h"
00026 #include "nsdl-c/sn_coap_header.h"
00027 #include "nsdl-c/sn_nsdl_lib.h"
00028 
00029 //FORWARD DECLARATION
00030 struct sn_coap_hdr_;
00031 typedef sn_coap_hdr_ sn_coap_hdr_s;
00032 struct nsdl_s;
00033 struct sn_nsdl_addr_;
00034 typedef sn_nsdl_addr_ sn_nsdl_addr_s;
00035 
00036 typedef FP1<void, const char*>  value_updated_callback ;
00037 typedef void(*value_updated_callback2) (const char* object_name);
00038 class M2MObservationHandler;
00039 class M2MReportHandler;
00040 
00041 class M2MObjectInstance;
00042 class M2MObject;
00043 class M2MResource;
00044 
00045 
00046 /*! \file m2mbase.h
00047  *  \brief M2MBase.
00048  *  This class is the base class based on which all LWM2M object models
00049  *  can be created. This serves base class for Object, ObjectInstances and Resources.
00050  */
00051 class M2MBase : public M2MReportObserver {
00052 
00053 public:
00054 
00055     /**
00056       * Enum to define the type of object.
00057       */
00058     typedef enum {
00059         Object = 0x0,
00060         Resource = 0x1,
00061         ObjectInstance = 0x2,
00062         ResourceInstance = 0x3
00063     } BaseType;
00064 
00065     /**
00066       * Enum to define observation level.
00067       */
00068     typedef enum {
00069         None                 = 0x0,
00070         R_Attribute          = 0x01,
00071         OI_Attribute         = 0x02,
00072         OIR_Attribute        = 0x03,
00073         O_Attribute          = 0x04,
00074         OR_Attribute         = 0x05,
00075         OOI_Attribute        = 0x06,
00076         OOIR_Attribute       = 0x07
00077     } Observation;
00078 
00079 
00080     /**
00081      * \brief Enum defining a resource type.
00082     */
00083     typedef enum {
00084         Static,
00085         Dynamic,
00086         Directory
00087     }Mode;
00088 
00089     /**
00090      * Enum defining an operation that can be
00091      * supported by a given resource.
00092     */
00093     typedef enum {
00094         NOT_ALLOWED                 = 0x00,
00095         GET_ALLOWED                 = 0x01,
00096         PUT_ALLOWED                 = 0x02,
00097         GET_PUT_ALLOWED             = 0x03,
00098         POST_ALLOWED                = 0x04,
00099         GET_POST_ALLOWED            = 0x05,
00100         PUT_POST_ALLOWED            = 0x06,
00101         GET_PUT_POST_ALLOWED        = 0x07,
00102         DELETE_ALLOWED              = 0x08,
00103         GET_DELETE_ALLOWED          = 0x09,
00104         PUT_DELETE_ALLOWED          = 0x0A,
00105         GET_PUT_DELETE_ALLOWED      = 0x0B,
00106         POST_DELETE_ALLOWED         = 0x0C,
00107         GET_POST_DELETE_ALLOWED     = 0x0D,
00108         PUT_POST_DELETE_ALLOWED     = 0x0E,
00109         GET_PUT_POST_DELETE_ALLOWED = 0x0F,
00110     }Operation;
00111 
00112     enum MaxPathSize {
00113         MAX_NAME_SIZE = 64,
00114         MAX_INSTANCE_SIZE = 5,
00115 
00116         MAX_PATH_SIZE = ((MAX_NAME_SIZE * 2) + (MAX_INSTANCE_SIZE * 2) + 3 + 1),
00117         MAX_PATH_SIZE_2 = ((MAX_NAME_SIZE * 2) + MAX_INSTANCE_SIZE + 2 + 1),
00118         MAX_PATH_SIZE_3 = (MAX_NAME_SIZE + (MAX_INSTANCE_SIZE * 2) + 2 + 1),
00119         MAX_PATH_SIZE_4 = (MAX_NAME_SIZE + MAX_INSTANCE_SIZE + 1 + 1),
00120     };
00121 
00122     typedef struct lwm2m_parameters {
00123         //add multiple_instances
00124         uint32_t            max_age;
00125         uint32_t            instance_id;
00126         int32_t             name_id;
00127         char*               name; //for backwards compability
00128         sn_nsdl_dynamic_resource_parameters_s *dynamic_resource_params;
00129         BaseType            base_type;
00130         bool                free_on_delete;   /**< true if struct is dynamically allocted and it
00131                                                  and its members (name) are to be freed on destructor.
00132                                                  Note: the sn_nsdl_dynamic_resource_parameters_s has
00133                                                  its own similar, independent flag.
00134                                                  Note: this also serves as a read-only flag. */
00135     } lwm2m_parameters_s;
00136 
00137 protected:
00138 
00139     // Prevents the use of default constructor.
00140     M2MBase();
00141 
00142     // Prevents the use of assignment operator.
00143     M2MBase& operator=( const M2MBase& /*other*/ );
00144 
00145     // Prevents the use of copy constructor
00146     M2MBase( const M2MBase& /*other*/ );
00147 
00148     /**
00149      * \brief Constructor
00150      * \param name Name of the object created.
00151      * \param mode Type of the resource.
00152      * \param resource_type Textual information of resource.
00153      * \param path Path of the object like 3/0/1
00154      * \param external_blockwise_store If true CoAP blocks are passed to application through callbacks
00155      *        otherwise handled in mbed-client-c.
00156      */
00157     M2MBase(const String &name,
00158             M2MBase::Mode mode,
00159             const String &resource_type,
00160             char *path,
00161             bool external_blockwise_store);
00162 
00163     M2MBase(const lwm2m_parameters_s* s);
00164 
00165 public:
00166 
00167     /**
00168      * Destructor
00169      */
00170     virtual ~M2MBase();
00171 
00172     /**
00173      * \brief Sets the operation type for an object.
00174      * \param operation The operation to be set.
00175      */
00176     virtual void set_operation(M2MBase::Operation operation);
00177 
00178 #ifndef MEMORY_OPTIMIZED_API
00179     /**
00180      * \brief Sets the interface description of the object.
00181      * \param description The description to be set.
00182      */
00183     virtual void set_interface_description(const String &description);
00184 
00185     /**
00186      * \brief Sets the interface description of the object.
00187      * \param description The description to be set.
00188      */
00189     virtual void set_interface_description(const char *description);
00190 
00191     /**
00192      * \brief Sets the resource type of the object.
00193      * \param resource_type The resource type to be set.
00194      */
00195     virtual void set_resource_type(const String &resource_type);
00196 
00197     /**
00198      * \brief Sets the resource type of the object.
00199      * \param resource_type The resource type to be set.
00200      */
00201     virtual void set_resource_type(const char *resource_type);
00202 #endif
00203 
00204     /**
00205      * \brief Sets the CoAP content type of the object.
00206      * \param content_type The content type to be set based on
00207      * CoAP specifications.
00208      */
00209     virtual void set_coap_content_type(const uint8_t content_type);
00210 
00211     /**
00212      * \brief Sets the observable mode for the object.
00213      * \param observable A value for the observation.
00214      */
00215     virtual void set_observable(bool observable);
00216 
00217     /**
00218      * \brief Adds the observation level for the object.
00219      * \param observation_level The level of observation.
00220      */
00221     virtual void add_observation_level(M2MBase::Observation observation_level);
00222 
00223     /**
00224      * \brief Removes the observation level for the object.
00225      * \param observation_level The level of observation.
00226      */
00227     virtual void remove_observation_level(M2MBase::Observation observation_level);
00228 
00229     /**
00230      * \brief Sets the object under observation.
00231      * \param observed The value for observation. When true, starts observing. When false, the ongoing observation is cancelled.
00232      * \param handler A handler object for sending
00233      * observation callbacks.
00234      */
00235     virtual void set_under_observation(bool observed,
00236                                        M2MObservationHandler *handler);
00237     /**
00238      * \brief Returns the Observation Handler object.
00239      * \return M2MObservationHandler object.
00240     */
00241     M2MObservationHandler* observation_handler();
00242 
00243     /**
00244      * \brief Sets the observation handler
00245      * \param handler Observation handler
00246     */
00247     void set_observation_handler(M2MObservationHandler *handler);
00248 
00249     /**
00250      * \brief Sets the observation token value.
00251      * \param token A pointer to the token of the resource.
00252      * \param length The length of the token pointer.
00253      */
00254     virtual void set_observation_token(const uint8_t *token,
00255                                        const uint8_t length);
00256 
00257     /**
00258      * \brief Sets the instance ID of the object.
00259      * \param instance_id The instance ID of the object.
00260      */
00261     virtual void set_instance_id(const uint16_t instance_id);
00262 
00263     /**
00264      * This function is deprecated. An increment of the observation number is done internally.
00265      * \brief Sets the observation number of the object.
00266      * \param observation_number The observation number of the object.
00267      */
00268     virtual void set_observation_number(const uint16_t observation_number)
00269         m2m_deprecated;
00270 
00271     /**
00272      * \brief Sets the max age for the resource value to be cached.
00273      * \param max_age The max age in seconds.
00274      */
00275     virtual void set_max_age(const uint32_t max_age);
00276 
00277     /**
00278      * \brief Returns the object type.
00279      * \return The base type of the object.
00280      */
00281     virtual M2MBase::BaseType base_type() const;
00282 
00283     /**
00284      * \brief Returns the operation type of the object.
00285      * \return The supported operation on the object.
00286      */
00287     virtual M2MBase::Operation operation() const;
00288 
00289     /**
00290      * \brief Returns the object name.
00291      * \return The name of the object.
00292      */
00293     virtual const char* name() const;
00294 
00295     /**
00296      * \brief Returns the object name in integer.
00297      * \return The name of the object in integer.
00298      */
00299     virtual int32_t name_id() const;
00300 
00301     /**
00302      * \brief Returns the object's instance ID.
00303      * \returns The instance ID of the object.
00304      */
00305     virtual uint16_t instance_id() const;
00306 
00307     /**
00308      * \brief Returns the interface description of the object.
00309      * \return The interface description of the object.
00310      */
00311     virtual const char* interface_description() const;
00312 
00313     /**
00314      * \brief Returns the resource type of the object.
00315      * \return The resource type of the object.
00316      */
00317     virtual const char* resource_type() const;
00318 
00319     /**
00320      * \brief Returns the path of the object.
00321      * \return The path of the object (eg. 3/0/1).
00322      */
00323     virtual const char* uri_path() const;
00324 
00325     /**
00326      * \brief Returns the CoAP content type of the object.
00327      * \return The CoAP content type of the object.
00328      */
00329     virtual uint8_t coap_content_type() const;
00330 
00331     /**
00332      * \brief Returns the observation status of the object.
00333      * \return True if observable, else false.
00334      */
00335     virtual bool is_observable() const;
00336 
00337     /**
00338      * \brief Returns the observation level of the object.
00339      * \return The observation level of the object.
00340      */
00341     virtual M2MBase::Observation observation_level() const;
00342 
00343     /**
00344      * \brief Provides the observation token of the object.
00345      * \param value[OUT] A pointer to the value of the token.
00346      * \param value_length[OUT] The length of the token pointer.
00347      */
00348     virtual void get_observation_token(uint8_t *&token, uint32_t &token_length);
00349 
00350     /**
00351      * \brief Returns the mode of the resource.
00352      * \return The mode of the resource.
00353      */
00354      virtual Mode mode() const;
00355 
00356     /**
00357      * \brief Returns the observation number.
00358      * \return The observation number of the object.
00359      */
00360     virtual uint16_t observation_number() const;
00361 
00362     /**
00363      * \brief Returns the max age for the resource value to be cached.
00364      * \return The maax age in seconds.
00365      */
00366     virtual uint32_t max_age() const;
00367 
00368     /**
00369      * \brief Parses the received query for the notification
00370      * attribute.
00371      * \param query The query that needs to be parsed.
00372      * \return True if required attributes are present, else false.
00373      */
00374     virtual bool handle_observation_attribute(const char *query);
00375 
00376     /**
00377      * \brief Handles GET request for the registered objects.
00378      * \param nsdl An NSDL handler for the CoAP library.
00379      * \param received_coap_header The received CoAP message from the server.
00380      * \param observation_handler A handler object for sending
00381      * observation callbacks.
00382      * \return sn_coap_hdr_s The message that needs to be sent to server.
00383      */
00384     virtual sn_coap_hdr_s* handle_get_request(nsdl_s *nsdl,
00385                                               sn_coap_hdr_s *received_coap_header,
00386                                               M2MObservationHandler *observation_handler = NULL);
00387     /**
00388      * \brief Handles PUT request for the registered objects.
00389      * \param nsdl An NSDL handler for the CoAP library.
00390      * \param received_coap_header The received CoAP message from the server.
00391      * \param observation_handler A handler object for sending
00392      * observation callbacks.
00393      * \param execute_value_updated True executes the "value_updated" callback.
00394      * \return sn_coap_hdr_s The message that needs to be sent to server.
00395      */
00396     virtual sn_coap_hdr_s* handle_put_request(nsdl_s *nsdl,
00397                                               sn_coap_hdr_s *received_coap_header,
00398                                               M2MObservationHandler *observation_handler,
00399                                               bool &execute_value_updated);
00400 
00401     /**
00402      * \brief Handles GET request for the registered objects.
00403      * \param nsdl An NSDL handler for the CoAP library.
00404      * \param received_coap_header The received CoAP message from the server.
00405      * \param observation_handler A handler object for sending
00406      * observation callbacks.
00407      * \param execute_value_updated True executes the "value_updated" callback.
00408      * \return sn_coap_hdr_s  The message that needs to be sent to server.
00409      */
00410     virtual sn_coap_hdr_s* handle_post_request(nsdl_s *nsdl,
00411                                                sn_coap_hdr_s *received_coap_header,
00412                                                M2MObservationHandler *observation_handler,
00413                                                bool &execute_value_updated,
00414                                                sn_nsdl_addr_s *address = NULL);
00415 
00416     /**
00417      * \brief Sets whether this resource is published to server or not.
00418      * \param register_uri True sets the resource as part of registration message.
00419      */
00420     virtual void set_register_uri(bool register_uri);
00421 
00422     /**
00423      * \brief Returns whether this resource is published to server or not.
00424      * \return True if the resource is a part of the registration message, else false.
00425      */
00426     virtual bool register_uri();
00427 
00428     /**
00429      * @brief Returns whether this resource is under observation or not.
00430      * @return True if the resource is under observation, else false,
00431      */
00432     virtual bool is_under_observation() const;
00433 
00434     /**
00435      * @brief Sets the function that is executed when this
00436      * object receives a PUT or POST command.
00437      * @param callback The function pointer that is called.
00438      */
00439     virtual void set_value_updated_function(value_updated_callback  callback);
00440 
00441     /**
00442      * @brief Sets the function that is executed when this
00443      * object receives a PUT or POST command.
00444      * @param callback The function pointer that is called.
00445      */
00446     virtual void set_value_updated_function(value_updated_callback2 callback);
00447 
00448     /**
00449      * @brief Returns whether a callback function is set or not.
00450      * @return True if the callback function is set, else false.
00451      */
00452     virtual bool is_value_updated_function_set();
00453 
00454     /**
00455      * @brief Calls the function that is set in the "set_value_updated_function".
00456      * @param name The name of the object.
00457      */
00458     virtual void execute_value_updated(const String& name);
00459 
00460     /**
00461      * @brief Returns length of the object name.
00462      * @return Length of the object name.
00463      */
00464     size_t resource_name_length() const;
00465 
00466     /**
00467      * @brief Returns the resource information.
00468      * @return Resource information.
00469      */
00470     sn_nsdl_dynamic_resource_parameters_s* get_nsdl_resource();
00471 
00472     static char* create_path(const M2MObject &parent, const char *name);
00473     static char* create_path(const M2MObject &parent, uint16_t object_instance);
00474     static char* create_path(const M2MResource &parent, uint16_t resource_instance);
00475     static char* create_path(const M2MResource &parent, const char *name);
00476     static char* create_path(const M2MObjectInstance &parent, const char *name);
00477 
00478 protected : // from M2MReportObserver
00479 
00480     virtual void observation_to_be_sent(m2m::Vector<uint16_t> changed_instance_ids,
00481                                         bool send_object = false);
00482 
00483 protected:
00484 
00485     /**
00486      * \brief Sets the base type for an object.
00487      * \param type The base type of the object.
00488      */
00489     virtual void set_base_type(M2MBase::BaseType type);
00490 
00491     /**
00492      * \brief Memory allocation required for libCoap.
00493      * \param size The size of memory to be reserved.
00494     */
00495     static void* memory_alloc(uint32_t size);
00496 
00497     /**
00498      * \brief Memory free functions required for libCoap.
00499      * \param ptr The object whose memory needs to be freed.
00500     */
00501     static void memory_free(void *ptr);
00502 
00503     /**
00504      * \brief Allocate and make a copy of given zero terminated string. This
00505      * is functionally equivalent with strdup().
00506      * \param source The source string to copy, may not be NULL.
00507     */
00508     static char* alloc_string_copy(const char* source);
00509 
00510     /**
00511      * \brief Allocate (size + 1) amount of memory, copy size bytes into
00512      * it and add zero termination.
00513      * \param source The source string to copy, may not be NULL.
00514      * \param size The size of memory to be reserved.
00515     */
00516     static uint8_t* alloc_string_copy(const uint8_t* source, uint32_t size);
00517 
00518     /**
00519      * \brief Allocate (size) amount of memory, copy size bytes into it.
00520      * \param source The source buffer to copy, may not be NULL.
00521      * \param size The size of memory to be reserved.
00522     */
00523     static uint8_t* alloc_copy(const uint8_t* source, uint32_t size);
00524 
00525     // validate string length to be [min_length..max_length]
00526     static bool validate_string_length(const String &string, size_t min_length, size_t max_length);
00527     static bool validate_string_length(const char* string, size_t min_length, size_t max_length);
00528 
00529     /**
00530      * \brief Create Report Handler object.
00531      * \return M2MReportHandler object.
00532     */
00533     M2MReportHandler* create_report_handler();
00534 
00535     /**
00536      * \brief Returns the Report Handler object.
00537      * \return M2MReportHandler object.
00538     */
00539     M2MReportHandler* report_handler();
00540 
00541 
00542     static bool build_path(StringBuffer<MAX_PATH_SIZE> &buffer, const char *s1, uint16_t i1, const char *s2, uint16_t i2);
00543 
00544     static bool build_path(StringBuffer<MAX_PATH_SIZE_2> &buffer, const char *s1, uint16_t i1, const char *s2);
00545 
00546     static bool build_path(StringBuffer<MAX_PATH_SIZE_3> &buffer, const char *s1, uint16_t i1, uint16_t i2);
00547 
00548     static bool build_path(StringBuffer<MAX_PATH_SIZE_4> &buffer, const char *s1, uint16_t i1);
00549 
00550     static char* stringdup(const char* s);
00551 
00552 private:
00553 
00554     static bool is_integer(const String &value);
00555 
00556     static bool is_integer(const char *value);
00557 
00558     void free_resources();
00559 
00560 private:
00561     lwm2m_parameters_s          *_sn_resource;
00562     M2MReportHandler            *_report_handler;
00563     M2MObservationHandler       *_observation_handler; // Not owned
00564     uint8_t                     *_token;
00565     FP1<void, const char*>       *_function_pointer;
00566     value_updated_callback       *_value_updated_callback;
00567     unsigned                    _observation_number : 16;
00568     unsigned                    _token_length : 8;
00569     M2MBase::Observation        _observation_level : 4;
00570     bool                        _is_under_observation : 1;
00571 
00572 friend class Test_M2MBase;
00573 friend class Test_M2MObject;
00574 
00575 };
00576 
00577 #endif // M2M_BASE_H
00578