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 
00025 //FORWARD DECLARATION
00026 struct sn_coap_hdr_;
00027 typedef sn_coap_hdr_ sn_coap_hdr_s;
00028 struct nsdl_s;
00029 
00030 typedef FP1<void, const char*>  value_updated_callback ;
00031 typedef void(*value_updated_callback2) (const char* object_name);
00032 class M2MObservationHandler;
00033 class M2MReportHandler;
00034 
00035 /**
00036  *  \brief M2MBase.
00037  *  This class is the base class based on which all LWM2M object models
00038  *  can be created. This serves base class for Object, ObjectInstances and Resources.
00039  */
00040 
00041 
00042 
00043 class M2MBase : public M2MReportObserver {
00044 
00045 public:
00046 
00047     /**
00048       * Enum to define the type of object.
00049       */
00050     typedef enum {
00051         Object = 0x0,
00052         Resource = 0x1,
00053         ObjectInstance = 0x2,
00054         ResourceInstance = 0x3
00055     } BaseType;
00056 
00057     /**
00058       * Enum to define observation level.
00059       */
00060     typedef enum {
00061         None                 = 0x0,
00062         R_Attribute          = 0x01,
00063         OI_Attribute         = 0x02,
00064         OIR_Attribute        = 0x03,
00065         O_Attribute          = 0x04,
00066         OR_Attribute         = 0x05,
00067         OOI_Attribute        = 0x06,
00068         OOIR_Attribute       = 0x07
00069     } Observation;
00070 
00071 
00072     /**
00073      * \brief Enum defining an operation that can be
00074      * supported by a given resource.
00075     */
00076     typedef enum {
00077         Static,
00078         Dynamic,
00079         Directory
00080     }Mode;
00081 
00082     /**
00083      * Enum defining an operation that can be
00084      * supported by a given resource.
00085     */
00086     typedef enum {
00087         NOT_ALLOWED                 = 0x00,
00088         GET_ALLOWED                 = 0x01,
00089         PUT_ALLOWED                 = 0x02,
00090         GET_PUT_ALLOWED             = 0x03,
00091         POST_ALLOWED                = 0x04,
00092         GET_POST_ALLOWED            = 0x05,
00093         PUT_POST_ALLOWED            = 0x06,
00094         GET_PUT_POST_ALLOWED        = 0x07,
00095         DELETE_ALLOWED              = 0x08,
00096         GET_DELETE_ALLOWED          = 0x09,
00097         PUT_DELETE_ALLOWED          = 0x0A,
00098         GET_PUT_DELETE_ALLOWED      = 0x0B,
00099         POST_DELETE_ALLOWED         = 0x0C,
00100         GET_POST_DELETE_ALLOWED     = 0x0D,
00101         PUT_POST_DELETE_ALLOWED     = 0x0E,
00102         GET_PUT_POST_DELETE_ALLOWED = 0x0F,
00103 
00104     }Operation;
00105 
00106 protected:
00107 
00108     // Prevents the use of default constructor.
00109     M2MBase();
00110 
00111     // Prevents the use of assignment operator.
00112     M2MBase& operator=( const M2MBase& /*other*/ );
00113 
00114     // Prevents the use of copy constructor
00115     M2MBase( const M2MBase& /*other*/ );
00116 
00117     /**
00118      * \brief Constructor
00119      * \param baseType Type of the object created
00120      * \param name Name of the object
00121      * \param id ID of the object
00122      */
00123     M2MBase(const String &name,
00124             M2MBase::Mode mode);
00125 public:
00126 
00127     /**
00128      * Destructor
00129      */
00130     virtual ~M2MBase();
00131 
00132     /**
00133      * \brief Sets the operation type for an object.
00134      * \param operation Operation to be set.
00135      */
00136     virtual void set_operation(M2MBase::Operation operation);
00137 
00138     /**
00139      * \brief Sets the interface description of the object.
00140      * \param description Description to be set.
00141      */
00142     virtual void set_interface_description(const String &description);
00143 
00144     /**
00145      * \brief Sets the resource type of the object.
00146      * \param resource_type Resource type to be set.
00147      */
00148     virtual void set_resource_type(const String &resource_type);
00149 
00150     /**
00151      * \brief Sets the CoAP content type of the object.
00152      * \param content_type Content Type to be set based on
00153      * CoAP specifications.
00154      */
00155     virtual void set_coap_content_type(const uint8_t content_type);
00156 
00157     /**
00158      * \brief Sets the observable mode for the object.
00159      * \param observable Value for the observation.
00160      */
00161     virtual void set_observable(bool observable);
00162 
00163     /**
00164      * \brief Adds the observation level for the object.
00165      * \param observation_level Level of the observation.
00166      */
00167     virtual void add_observation_level(M2MBase::Observation observation_level);
00168 
00169     /**
00170      * \brief Removes the observation level for the object.
00171      * \param observation_level Level of the observation.
00172      */
00173     virtual void remove_observation_level(M2MBase::Observation observation_level);
00174 
00175     /**
00176      * \brief Sets the object under observation.
00177      * \param observed Value for the observation. When true, starts observing. When false, ongoing observation is cancelled.
00178      * \param handler Handler object for sending
00179      * observation callbacks.
00180      */
00181     virtual void set_under_observation(bool observed,
00182                                        M2MObservationHandler *handler);
00183 
00184     /**
00185      * \brief Sets the observation token value.
00186      * \param token Pointer to the token of the resource.
00187      * \param length Length of the token pointer.
00188      */
00189     virtual void set_observation_token(const uint8_t *token,
00190                                        const uint8_t length);
00191 
00192     /**
00193      * \brief Sets the instance ID of the object.
00194      * \param instance_id Instance ID of the object.
00195      */
00196     virtual void set_instance_id(const uint16_t instance_id);
00197 
00198     /**
00199      * Function is deprecated. Increment of observation number is done internally.
00200      * \brief Sets the observation number of the object.
00201      * \param observation_number Observation number of the object.
00202      */
00203     virtual void set_observation_number(const uint16_t observation_number)
00204         m2m_deprecated;
00205 
00206     /**
00207      * \brief Sets the max age for the resource value to be cached.
00208      * \param max_age Max age in seconds.
00209      */
00210     virtual void set_max_age(const uint32_t max_age);
00211 
00212     /**
00213      * \brief Returns object type.
00214      * \return BaseType of the object.
00215      */
00216     virtual M2MBase::BaseType base_type() const;
00217 
00218     /**
00219      * \brief Returns the operation type of the object.
00220      * \return Operation Supported operation on the object.
00221      */
00222     virtual M2MBase::Operation operation() const;
00223 
00224     /**
00225      * \brief Returns the object name.
00226      * \return Name of the object.
00227      */
00228     virtual const String &name() const;
00229 
00230     /**
00231      * \brief Returns the object name in integer.
00232      * \return Name of the object in integer.
00233      */
00234     virtual int32_t name_id() const;
00235 
00236     /**
00237      * \brief Returns the object's Instance ID.
00238      * \returns Instance ID of the object.
00239      */
00240     virtual uint16_t instance_id() const;
00241 
00242     /**
00243      * \brief Returns the interface description of the object.
00244      * \return Description of the object.
00245      */
00246     virtual const String& interface_description() const;
00247 
00248     /**
00249      * \brief Returns the resource type of the object.
00250      * \return Resource type of the object.
00251      */
00252     virtual const String& resource_type() const;
00253 
00254     /**
00255      * \brief Returns the CoAP content type of the object.
00256      * \return Content type of the object.
00257      */
00258     virtual uint8_t coap_content_type() const;
00259 
00260     /**
00261      * \brief Returns the observation status of the object.
00262      * \return True if observable, else false.
00263      */
00264     virtual bool is_observable() const;
00265 
00266     /**
00267      * \brief Returns the observation level of the object.
00268      * \return Observation level of the object.
00269      */
00270     virtual M2MBase::Observation observation_level() const;
00271 
00272     /**
00273      * \brief Provides the observation token of the object.
00274      * \param value[OUT] A pointer to the value of the token.
00275      * \param value_length[OUT] Length of the token pointer.
00276      */
00277     virtual void get_observation_token(uint8_t *&token, uint32_t &token_length);
00278 
00279     /**
00280      * \brief Returns the mode of the resource.
00281      * \return Mode of the resource.
00282      */
00283      virtual Mode mode() const;
00284 
00285     /**
00286      * \brief Returns the observation number.
00287      * \return Observation number of the object.
00288      */
00289     virtual uint16_t observation_number() const;
00290 
00291     /**
00292      * \brief Returns max age for the resource value to be cached.
00293      * \return Max age in seconds.
00294      */
00295     virtual uint32_t max_age() const;
00296 
00297 
00298     /**
00299      * \brief Parses the received query for the notification
00300      * attribute.
00301      * \param query The query that needs to be parsed.
00302      * \return True if required attributes are present, else false.
00303      */
00304     virtual bool handle_observation_attribute(char *&query);
00305 
00306     /**
00307      * \brief Handles GET request for the registered objects.
00308      * \param nsdl NSDL handler for the CoAP library.
00309      * \param received_coap_header Received CoAP message from the server.
00310      * \param observation_handler Handler object for sending
00311      * observation callbacks.
00312      * \return sn_coap_hdr_s The message that needs to be sent to server.
00313      */
00314     virtual sn_coap_hdr_s* handle_get_request(nsdl_s *nsdl,
00315                                               sn_coap_hdr_s *received_coap_header,
00316                                               M2MObservationHandler *observation_handler = NULL);
00317     /**
00318      * \brief Handles PUT request for the registered objects.
00319      * \param nsdl NSDL handler for the CoAP library.
00320      * \param received_coap_header The received CoAP message from the server.
00321      * \param observation_handler The handler object for sending
00322      * observation callbacks.
00323      * \param execute_value_updated True will execute "value_updated" callback.
00324      * \return sn_coap_hdr_s The message that needs to be sent to server.
00325      */
00326     virtual sn_coap_hdr_s* handle_put_request(nsdl_s *nsdl,
00327                                               sn_coap_hdr_s *received_coap_header,
00328                                               M2MObservationHandler *observation_handler,
00329                                               bool &execute_value_updated);
00330 
00331     /**
00332      * \brief Handles GET request for the registered objects.
00333      * \param nsdl NSDL handler for the CoAP library.
00334      * \param received_coap_header The received CoAP message from the server.
00335      * \param observation_handler The handler object for sending
00336      * observation callbacks.
00337      * \param execute_value_updated True will execute "value_updated" callback.
00338      * \return sn_coap_hdr_s  The message that needs to be sent to server.
00339      */
00340     virtual sn_coap_hdr_s* handle_post_request(nsdl_s *nsdl,
00341                                                sn_coap_hdr_s *received_coap_header,
00342                                                M2MObservationHandler *observation_handler,
00343                                                bool &execute_value_updated);
00344 
00345     /**
00346      * \brief Sets whether this resource will be published to server or not.
00347      * \param register_uri True sets the resource as part of registration message.
00348      */
00349     virtual void set_register_uri( bool register_uri);
00350 
00351     /**
00352      * \brief Returns whether this resource will be published to server or not.
00353      * \return True if the resource is part of the registration message, else false.
00354      */
00355     virtual bool register_uri();
00356 
00357     /**
00358      * \brief Sets object URI path.
00359      * \param path Object path
00360      */
00361     virtual void set_uri_path(const String &path);
00362 
00363     /**
00364      * \brief Returns the URI path of the object.
00365      * \return URI path of the object.
00366      */
00367     virtual const String &uri_path() const;
00368 
00369     /**
00370      * @brief Returns whether this resource is under observation or not.
00371      * @return True if the resource is under observation, else false,
00372      */
00373     virtual bool is_under_observation() const;
00374 
00375     /**
00376      * @brief Sets the function that is executed when this
00377      * object receives a PUT or POST command.
00378      * @param callback The function pointer that is called.
00379      */
00380     virtual void set_value_updated_function(value_updated_callback  callback);
00381 
00382     /**
00383      * @brief Sets the function that is executed when this
00384      * object receives a PUT or POST command.
00385      * @param callback The function pointer that is called.
00386      */
00387     virtual void set_value_updated_function(value_updated_callback2 callback);
00388 
00389     /**
00390      * @brief Returns whether callback function is set or not.
00391      * @return True if the callback function is set, else false.
00392      */
00393     virtual bool is_value_updated_function_set();
00394 
00395     /**
00396      * @brief Calls the function that is set in "set_value_updated_function".
00397      * @param name Name of the object.
00398      */
00399     virtual void execute_value_updated(const String& name);
00400 
00401 protected : // from M2MReportObserver
00402 
00403     virtual void observation_to_be_sent(m2m::Vector<uint16_t> changed_instance_ids,
00404                                         bool send_object = false);
00405 
00406 protected:
00407 
00408     /**
00409      * \brief Sets the Base type for object.
00410      * \param type The type of the base object.
00411      */
00412     virtual void set_base_type(M2MBase::BaseType type);
00413 
00414     /**
00415      * \brief Removes the resource from the CoAP structure.
00416      * \param resource_name The name of the resource.
00417      */
00418     virtual void remove_resource_from_coap(const String &resource_name);
00419 
00420     /**
00421      * \brief Removes an object from the NSDL list.
00422      */
00423     virtual void remove_object_from_coap();
00424 
00425     /**
00426      * \brief Memory allocation required for libCoap.
00427      * \param size The size of memory to be reserved.
00428     */
00429     virtual void* memory_alloc(uint32_t size);
00430 
00431     /**
00432      * \brief Memory free functions required for libCoap.
00433      * \param ptr The Object whose memory needs to be freed.
00434     */
00435     virtual void memory_free(void *ptr);
00436 
00437     /**
00438      * \brief Allocate (size + 1) amount of memory, copy size bytes into
00439      * it and add zero termination.
00440      * \param source Source string to copy, may not be NULL.
00441      * \param size The size of memory to be reserved.
00442     */
00443     virtual uint8_t* alloc_string_copy(const uint8_t* source, uint32_t size);
00444 
00445     /**
00446      * \brief Allocate (size) amount of memory, copy size bytes into it.
00447      * \param source Source buffer to copy, may not be NULL.
00448      * \param size The size of memory to be reserved.
00449     */
00450     virtual uint8_t* alloc_copy(const uint8_t* source, uint32_t size);
00451 
00452     /**
00453      * \brief Returns the Report Handler object.
00454      * \return M2MReportHandler object.
00455     */
00456     M2MReportHandler* report_handler();
00457 
00458     /**
00459      * \brief Returns the Observation Handler object.
00460      * \return M2MObservationHandler object.
00461     */
00462     M2MObservationHandler* observation_handler();
00463 
00464 private:
00465 
00466     static bool is_integer(const String &value);
00467 
00468 private:
00469 
00470     M2MReportHandler           *_report_handler;
00471     M2MObservationHandler      *_observation_handler;
00472     String                      _name;
00473     String                      _resource_type;
00474     String                      _interface_description;
00475     String                      _uri_path;
00476     int32_t                     _name_id;
00477     uint32_t                    _max_age;
00478     uint16_t                    _instance_id;
00479     uint16_t                    _observation_number;
00480     uint8_t                     *_token;
00481     uint8_t                     _token_length;
00482     uint8_t                     _coap_content_type;
00483     M2MBase::Operation          _operation;
00484     M2MBase::Mode               _mode;
00485     M2MBase::BaseType           _base_type;
00486     M2MBase::Observation        _observation_level;
00487     bool                        _observable;
00488     bool                        _register_uri;
00489     bool                        _is_under_observation;
00490     value_updated_callback       _value_updated_callback;
00491     FP1<void, const char*>       *_function_pointer;
00492 
00493 friend class Test_M2MBase;
00494 
00495 };
00496 
00497 #endif // M2M_BASE_H
00498