Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
m2mbase.h
Go to the documentation of this file.
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 "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 * \brief Enum defining a resource data type. 00091 */ 00092 typedef enum { 00093 STRING, 00094 INTEGER, 00095 FLOAT, 00096 BOOLEAN, 00097 OPAQUE, 00098 TIME, 00099 OBJLINK 00100 }DataType; 00101 00102 /** 00103 * Enum defining an operation that can be 00104 * supported by a given resource. 00105 */ 00106 typedef enum { 00107 NOT_ALLOWED = 0x00, 00108 GET_ALLOWED = 0x01, 00109 PUT_ALLOWED = 0x02, 00110 GET_PUT_ALLOWED = 0x03, 00111 POST_ALLOWED = 0x04, 00112 GET_POST_ALLOWED = 0x05, 00113 PUT_POST_ALLOWED = 0x06, 00114 GET_PUT_POST_ALLOWED = 0x07, 00115 DELETE_ALLOWED = 0x08, 00116 GET_DELETE_ALLOWED = 0x09, 00117 PUT_DELETE_ALLOWED = 0x0A, 00118 GET_PUT_DELETE_ALLOWED = 0x0B, 00119 POST_DELETE_ALLOWED = 0x0C, 00120 GET_POST_DELETE_ALLOWED = 0x0D, 00121 PUT_POST_DELETE_ALLOWED = 0x0E, 00122 GET_PUT_POST_DELETE_ALLOWED = 0x0F 00123 }Operation; 00124 00125 enum MaxPathSize { 00126 MAX_NAME_SIZE = 64, 00127 MAX_INSTANCE_SIZE = 5, 00128 00129 MAX_PATH_SIZE = ((MAX_NAME_SIZE * 2) + (MAX_INSTANCE_SIZE * 2) + 3 + 1), 00130 MAX_PATH_SIZE_2 = ((MAX_NAME_SIZE * 2) + MAX_INSTANCE_SIZE + 2 + 1), 00131 MAX_PATH_SIZE_3 = (MAX_NAME_SIZE + (MAX_INSTANCE_SIZE * 2) + 2 + 1), 00132 MAX_PATH_SIZE_4 = (MAX_NAME_SIZE + MAX_INSTANCE_SIZE + 1 + 1) 00133 }; 00134 00135 typedef void(*notification_delivery_status_cb) (const M2MBase& base, 00136 const NotificationDeliveryStatus status, 00137 void *client_args); 00138 00139 typedef struct lwm2m_parameters { 00140 //add multiple_instances 00141 uint32_t max_age; // todo: add flag 00142 union { 00143 char* name; //for backwards compatibility 00144 uint16_t instance_id; // XXX: this is not properly aligned now, need to reorder these after the elimination is done 00145 } identifier; 00146 sn_nsdl_dynamic_resource_parameters_s *dynamic_resource_params; 00147 BaseType base_type : 2; 00148 M2MBase::DataType data_type : 3; 00149 bool multiple_instance; 00150 bool free_on_delete; /**< true if struct is dynamically allocated and it 00151 and its members (name) are to be freed on destructor. 00152 Note: the sn_nsdl_dynamic_resource_parameters_s has 00153 its own similar, independent flag. 00154 Note: this also serves as a read-only flag. */ 00155 bool identifier_int_type; 00156 } lwm2m_parameters_s; 00157 00158 protected: 00159 00160 // Prevents the use of default constructor. 00161 M2MBase(); 00162 00163 // Prevents the use of assignment operator. 00164 M2MBase& operator=( const M2MBase& /*other*/ ); 00165 00166 // Prevents the use of copy constructor 00167 M2MBase( const M2MBase& /*other*/ ); 00168 00169 /** 00170 * \brief Constructor 00171 * \param name Name of the object created. 00172 * \param mode Type of the resource. 00173 * \param resource_type Textual information of resource. 00174 * \param path Path of the object like 3/0/1 00175 * \param external_blockwise_store If true CoAP blocks are passed to application through callbacks 00176 * otherwise handled in mbed-client-c. 00177 */ 00178 M2MBase(const String &name, 00179 M2MBase::Mode mode, 00180 #ifndef DISABLE_RESOURCE_TYPE 00181 const String &resource_type, 00182 #endif 00183 char *path, 00184 bool external_blockwise_store, 00185 bool multiple_instance, 00186 M2MBase::DataType type = M2MBase::OBJLINK); 00187 00188 M2MBase(const lwm2m_parameters_s* s); 00189 00190 public: 00191 00192 /** 00193 * Destructor 00194 */ 00195 virtual ~M2MBase(); 00196 00197 /** 00198 * \brief Sets the operation type for an object. 00199 * \param operation The operation to be set. 00200 */ 00201 void set_operation(M2MBase::Operation operation); 00202 00203 #if !defined(MEMORY_OPTIMIZED_API) || defined(RESOURCE_ATTRIBUTES_LIST) 00204 /** 00205 * \brief Sets the interface description of the object. 00206 * \param description The description to be set. 00207 */ 00208 #if !defined(DISABLE_INTERFACE_DESCRIPTION) || defined(RESOURCE_ATTRIBUTES_LIST) 00209 void set_interface_description(const String &description); 00210 00211 /** 00212 * \brief Sets the interface description of the object. 00213 * \param description The description to be set. 00214 */ 00215 void set_interface_description(const char *description); 00216 00217 /** 00218 * \brief Returns the interface description of the object. 00219 * \return The interface description of the object. 00220 */ 00221 const char* interface_description() const; 00222 #endif 00223 #if !defined(DISABLE_RESOURCE_TYPE) || defined(RESOURCE_ATTRIBUTES_LIST) 00224 /** 00225 * \brief Sets the resource type of the object. 00226 * \param resource_type The resource type to be set. 00227 */ 00228 virtual void set_resource_type(const String &resource_type); 00229 00230 /** 00231 * \brief Sets the resource type of the object. 00232 * \param resource_type The resource type to be set. 00233 */ 00234 virtual void set_resource_type(const char *resource_type); 00235 00236 /** 00237 * \brief Returns the resource type of the object. 00238 * \return The resource type of the object. 00239 */ 00240 const char* resource_type() const; 00241 #endif 00242 #endif 00243 00244 /** 00245 * \brief Sets the CoAP content type of the object. 00246 * \param content_type The content type to be set based on 00247 * CoAP specifications. 00248 */ 00249 void set_coap_content_type(const uint16_t content_type); 00250 00251 /** 00252 * \brief Sets the observable mode for the object. 00253 * \param observable A value for the observation. 00254 */ 00255 void set_observable(bool observable); 00256 00257 /** 00258 * \brief Sets the object to be auto-observable. 00259 * 00260 * \note This is not a standard CoAP or LWM2M feature and it only works in mbed Cloud. 00261 * \note This must be called before registration process, since this info must be in a registration message. 00262 * \note Auto-observable will take higher precedence if both observable methods are set. 00263 * 00264 * \param auto_observable Is auto-obs feature enabled or not. 00265 */ 00266 void set_auto_observable(bool auto_observable); 00267 00268 /** 00269 * \brief Adds the observation level for the object. 00270 * \param observation_level The level of observation. 00271 */ 00272 virtual void add_observation_level(M2MBase::Observation observation_level); 00273 00274 /** 00275 * \brief Removes the observation level for the object. 00276 * \param observation_level The level of observation. 00277 */ 00278 virtual void remove_observation_level(M2MBase::Observation observation_level); 00279 00280 /** 00281 * \brief Sets the object under observation. 00282 * \param observed The value for observation. When true, starts observing. When false, the ongoing observation is cancelled. 00283 * \param handler A handler object for sending 00284 * observation callbacks. 00285 */ 00286 void set_under_observation(bool observed, 00287 M2MObservationHandler *handler); 00288 /** 00289 * \brief Returns the Observation Handler object. 00290 * \return M2MObservationHandler object. 00291 */ 00292 virtual M2MObservationHandler* observation_handler() const = 0; 00293 00294 /** 00295 * \brief Sets the observation handler 00296 * \param handler Observation handler 00297 */ 00298 virtual void set_observation_handler(M2MObservationHandler *handler) = 0; 00299 00300 /** 00301 * \brief Sets the instance ID of the object. 00302 * \param instance_id The instance ID of the object. 00303 */ 00304 void set_instance_id(const uint16_t instance_id); 00305 00306 /** 00307 * \brief Sets the max age for the resource value to be cached. 00308 * \param max_age The max age in seconds. 00309 */ 00310 void set_max_age(const uint32_t max_age); 00311 00312 /** 00313 * \brief Returns the object type. 00314 * \return The base type of the object. 00315 */ 00316 M2MBase::BaseType base_type() const; 00317 00318 /** 00319 * \brief Returns the operation type of the object. 00320 * \return The supported operation on the object. 00321 */ 00322 M2MBase::Operation operation() const; 00323 00324 /** 00325 * \brief Returns the object name. 00326 * \return The name of the object. 00327 */ 00328 const char* name() const; 00329 00330 /** 00331 * \brief Returns the object name in integer. 00332 * \return The name of the object in integer. 00333 */ 00334 int32_t name_id() const; 00335 00336 /** 00337 * \brief Returns the object's instance ID. 00338 * \returns The instance ID of the object. 00339 */ 00340 uint16_t instance_id() const; 00341 00342 /** 00343 * \brief Returns the path of the object. 00344 * \return The path of the object (eg. 3/0/1). 00345 */ 00346 const char* uri_path() const; 00347 00348 /** 00349 * \brief Returns the CoAP content type of the object. 00350 * \return The CoAP content type of the object. 00351 */ 00352 uint16_t coap_content_type() const; 00353 00354 /** 00355 * \brief Returns the observation status of the object. 00356 * \return True if observable, else false. 00357 */ 00358 bool is_observable() const; 00359 00360 /** 00361 * \brief Returns the observation level of the object. 00362 * \return The observation level of the object. 00363 */ 00364 M2MBase::Observation observation_level() const; 00365 00366 /** 00367 * \brief Returns the mode of the resource. 00368 * \return The mode of the resource. 00369 */ 00370 Mode mode() const; 00371 00372 /** 00373 * \brief Returns the observation number. 00374 * \return The observation number of the object. 00375 */ 00376 uint16_t observation_number() const; 00377 00378 /** 00379 * \brief Returns the max age for the resource value to be cached. 00380 * \return The maax age in seconds. 00381 */ 00382 uint32_t max_age() const; 00383 00384 /** 00385 * \brief Parses the received query for the notification 00386 * attribute. 00387 * \param query The query that needs to be parsed. 00388 * \return True if required attributes are present, else false. 00389 */ 00390 virtual bool handle_observation_attribute(const char *query); 00391 00392 /** 00393 * \brief Handles GET request for the registered objects. 00394 * \param nsdl An NSDL handler for the CoAP library. 00395 * \param received_coap_header The received CoAP message from the server. 00396 * \param observation_handler A handler object for sending 00397 * observation callbacks. 00398 * \return sn_coap_hdr_s The message that needs to be sent to server. 00399 */ 00400 virtual sn_coap_hdr_s* handle_get_request(nsdl_s *nsdl, 00401 sn_coap_hdr_s *received_coap_header, 00402 M2MObservationHandler *observation_handler = NULL); 00403 /** 00404 * \brief Handles PUT request for the registered objects. 00405 * \param nsdl An NSDL handler for the CoAP library. 00406 * \param received_coap_header The received CoAP message from the server. 00407 * \param observation_handler A handler object for sending 00408 * observation callbacks. 00409 * \param execute_value_updated True executes the "value_updated" callback. 00410 * \return sn_coap_hdr_s The message that needs to be sent to server. 00411 */ 00412 virtual sn_coap_hdr_s* handle_put_request(nsdl_s *nsdl, 00413 sn_coap_hdr_s *received_coap_header, 00414 M2MObservationHandler *observation_handler, 00415 bool &execute_value_updated); 00416 00417 /** 00418 * \brief Handles GET request for the registered objects. 00419 * \param nsdl An NSDL handler for the CoAP library. 00420 * \param received_coap_header The received CoAP message from the server. 00421 * \param observation_handler A handler object for sending 00422 * observation callbacks. 00423 * \param execute_value_updated True executes the "value_updated" callback. 00424 * \return sn_coap_hdr_s The message that needs to be sent to server. 00425 */ 00426 virtual sn_coap_hdr_s* handle_post_request(nsdl_s *nsdl, 00427 sn_coap_hdr_s *received_coap_header, 00428 M2MObservationHandler *observation_handler, 00429 bool &execute_value_updated, 00430 sn_nsdl_addr_s *address = NULL); 00431 00432 /** 00433 * \brief Executes the function that is set in "set_notification_delivery_status_cb". 00434 */ 00435 void send_notification_delivery_status(const M2MBase& object, const NotificationDeliveryStatus status); 00436 00437 /** 00438 * \brief Sets whether this resource is published to server or not. 00439 * \param register_uri True sets the resource as part of registration message. 00440 */ 00441 void set_register_uri(bool register_uri); 00442 00443 /** 00444 * \brief Returns whether this resource is published to server or not. 00445 * \return True if the resource is a part of the registration message, else false. 00446 */ 00447 bool register_uri(); 00448 00449 /** 00450 * @brief Returns whether this resource is under observation or not. 00451 * @return True if the resource is under observation, else false, 00452 */ 00453 bool is_under_observation() const; 00454 00455 /** 00456 * @brief Sets the function that is executed when this 00457 * object receives a PUT or POST command. 00458 * @param callback The function pointer that is called. 00459 * @return True, if callback could be set, false otherwise. 00460 */ 00461 bool set_value_updated_function(value_updated_callback callback); 00462 00463 /** 00464 * @brief Sets the function that is executed when this 00465 * object receives a PUT or POST command. 00466 * @param callback The function pointer that is called. 00467 * @return True, if callback could be set, false otherwise. 00468 */ 00469 bool set_value_updated_function(value_updated_callback2 callback); 00470 00471 /** 00472 * @brief Returns whether a callback function is set or not. 00473 * @return True if the callback function is set, else false. 00474 */ 00475 bool is_value_updated_function_set() const; 00476 00477 /** 00478 * @brief Calls the function that is set in the "set_value_updated_function". 00479 * @param name The name of the object. 00480 */ 00481 void execute_value_updated(const String& name); 00482 00483 /** 00484 * @brief Returns length of the object name. 00485 * @return Length of the object name. 00486 */ 00487 size_t resource_name_length() const; 00488 00489 /** 00490 * @brief Returns the resource information. 00491 * @return Resource information. 00492 */ 00493 sn_nsdl_dynamic_resource_parameters_s* get_nsdl_resource() const; 00494 00495 /** 00496 * @brief Returns the resource structure. 00497 * @return Resource structure. 00498 */ 00499 M2MBase::lwm2m_parameters_s* get_lwm2m_parameters() const; 00500 00501 /** 00502 * @brief Returns the notification message id. 00503 * @return Message id. 00504 */ 00505 uint16_t get_notification_msgid() const; 00506 00507 /** 00508 * @brief Sets the notification message id. 00509 * This is used to map RESET and EMPTY ACK messages. 00510 * @param msgid The message id. 00511 */ 00512 void set_notification_msgid(uint16_t msgid); 00513 00514 /** 00515 * @brief Sets the function that is executed when notification message state changes. 00516 * @param callback The function pointer that is called. 00517 * @param client_args The argument which is passed to the callback function. 00518 */ 00519 bool set_notification_delivery_status_cb(notification_delivery_status_cb callback, void *client_args); 00520 00521 static char* create_path(const M2MObject &parent, const char *name); 00522 static char* create_path(const M2MObject &parent, uint16_t object_instance); 00523 static char* create_path(const M2MResource &parent, uint16_t resource_instance); 00524 static char* create_path(const M2MResource &parent, const char *name); 00525 static char* create_path(const M2MObjectInstance &parent, const char *name); 00526 00527 protected : // from M2MReportObserver 00528 00529 virtual void observation_to_be_sent(const m2m::Vector<uint16_t> &changed_instance_ids, 00530 uint16_t obs_number, 00531 bool send_object = false); 00532 00533 protected: 00534 00535 /** 00536 * \brief Sets the base type for an object. 00537 * \param type The base type of the object. 00538 */ 00539 void set_base_type(M2MBase::BaseType type); 00540 00541 /** 00542 * \brief Memory allocation required for libCoap. 00543 * \param size The size of memory to be reserved. 00544 */ 00545 static void* memory_alloc(uint32_t size); 00546 00547 /** 00548 * \brief Memory free functions required for libCoap. 00549 * \param ptr The object whose memory needs to be freed. 00550 */ 00551 static void memory_free(void *ptr); 00552 00553 /** 00554 * \brief Allocate and make a copy of given zero terminated string. This 00555 * is functionally equivalent with strdup(). 00556 * \param source The source string to copy, may not be NULL. 00557 */ 00558 static char* alloc_string_copy(const char* source); 00559 00560 /** 00561 * \brief Allocate (size + 1) amount of memory, copy size bytes into 00562 * it and add zero termination. 00563 * \param source The source string to copy, may not be NULL. 00564 * \param size The size of memory to be reserved. 00565 */ 00566 static uint8_t* alloc_string_copy(const uint8_t* source, uint32_t size); 00567 00568 /** 00569 * \brief Allocate (size) amount of memory, copy size bytes into it. 00570 * \param source The source buffer to copy, may not be NULL. 00571 * \param size The size of memory to be reserved. 00572 */ 00573 static uint8_t* alloc_copy(const uint8_t* source, uint32_t size); 00574 00575 // validate string length to be [min_length..max_length] 00576 static bool validate_string_length(const String &string, size_t min_length, size_t max_length); 00577 static bool validate_string_length(const char* string, size_t min_length, size_t max_length); 00578 00579 /** 00580 * \brief Create Report Handler object. 00581 * \return M2MReportHandler object. 00582 */ 00583 M2MReportHandler* create_report_handler(); 00584 00585 /** 00586 * \brief Returns the Report Handler object. 00587 * \return M2MReportHandler object. 00588 */ 00589 M2MReportHandler* report_handler() const; 00590 00591 static bool build_path(StringBuffer<MAX_PATH_SIZE> &buffer, const char *s1, uint16_t i1, const char *s2, uint16_t i2); 00592 00593 static bool build_path(StringBuffer<MAX_PATH_SIZE_2> &buffer, const char *s1, uint16_t i1, const char *s2); 00594 00595 static bool build_path(StringBuffer<MAX_PATH_SIZE_3> &buffer, const char *s1, uint16_t i1, uint16_t i2); 00596 00597 static bool build_path(StringBuffer<MAX_PATH_SIZE_4> &buffer, const char *s1, uint16_t i1); 00598 00599 static char* stringdup(const char* s); 00600 00601 /** 00602 * \brief Delete the resource structures owned by this object. Note: this needs 00603 * to be called separately from each subclass' destructor as this method uses a 00604 * virtual method and the call needs to be done at same class which has the 00605 * implementation of the pure virtual method. 00606 */ 00607 void free_resources(); 00608 00609 /** 00610 * \brief Returns notification send status. 00611 * \return Notification status. 00612 */ 00613 NotificationDeliveryStatus get_notification_delivery_status() const; 00614 00615 /** 00616 * \brief Clears the notification send status to initial state. 00617 */ 00618 void clear_notification_delivery_status(); 00619 00620 /** 00621 * \brief Provides the observation token of the object. 00622 * \param value[OUT] A pointer to the value of the token. 00623 * \param value_length[OUT] The length of the token pointer. 00624 */ 00625 void get_observation_token(uint8_t *token, uint8_t &token_length) const; 00626 00627 /** 00628 * \brief Sets the observation token value. 00629 * \param token A pointer to the token of the resource. 00630 * \param length The length of the token pointer. 00631 */ 00632 void set_observation_token(const uint8_t *token, 00633 const uint8_t length); 00634 00635 private: 00636 00637 static bool is_integer(const String &value); 00638 00639 static bool is_integer(const char *value); 00640 00641 static char* create_path_base(const M2MBase &parent, const char *name); 00642 00643 private: 00644 lwm2m_parameters_s *_sn_resource; 00645 M2MReportHandler *_report_handler; // TODO: can be broken down to smaller classes with inheritance. 00646 00647 friend class Test_M2MBase; 00648 friend class Test_M2MObject; 00649 friend class M2MNsdlInterface; 00650 friend class M2MInterfaceFactory; 00651 }; 00652 00653 #endif // M2M_BASE_H 00654
Generated on Tue Jul 12 2022 19:01:34 by 1.7.2