Mistake on this page? Email us
m2mbase.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2021 Pelion. All rights reserved.
3  * SPDX-License-Identifier: Apache-2.0
4  * Licensed under the Apache License, Version 2.0 (the License); you may
5  * not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #ifndef M2M_BASE_H
17 #define M2M_BASE_H
18 
19 // Support for std args
20 #include <stdint.h>
21 #include "mbed-client/m2mconfig.h"
26 #include "nsdl-c/sn_nsdl.h"
27 #include "sn_coap_header.h"
28 #include "nsdl-c/sn_nsdl_lib.h"
29 
30 //FORWARD DECLARATION
31 struct sn_coap_hdr_;
32 typedef sn_coap_hdr_ sn_coap_hdr_s;
33 struct nsdl_s;
34 struct sn_nsdl_addr_;
35 typedef sn_nsdl_addr_ sn_nsdl_addr_s;
36 
38 typedef void(*value_updated_callback2)(const char *object_name);
40 class M2MReportHandler;
41 
42 class M2MObjectInstance;
43 class M2MObject;
44 class M2MResource;
45 class M2MEndpoint;
46 
47 
54 class M2MBase : public M2MReportObserver {
55 
56 public:
57 
61  typedef enum {
62  Object = 0x0,
63  Resource = 0x1,
64  ObjectInstance = 0x2,
65  ResourceInstance = 0x3
66 #ifdef MBED_CLOUD_CLIENT_EDGE_EXTENSION
67  , ObjectDirectory = 0x4
68 #endif
69  } BaseType;
70 
74  typedef enum {
75  None = 0x0,
76  R_Attribute = 0x01,
77  OI_Attribute = 0x02,
78  OIR_Attribute = 0x03,
79  O_Attribute = 0x04,
80  OR_Attribute = 0x05,
81  OOI_Attribute = 0x06,
82  OOIR_Attribute = 0x07
83  } Observation;
84 
85 
89  typedef enum {
93  } Mode;
94 
98  typedef enum {
99  STRING,
100  INTEGER,
101  FLOAT,
102  BOOLEAN,
103  OPAQUE,
104  TIME,
105  OBJLINK
106  } DataType;
107 
112  typedef enum {
113  NOT_ALLOWED = 0x00,
114  GET_ALLOWED = 0x01,
115  PUT_ALLOWED = 0x02,
117  POST_ALLOWED = 0x04,
121  DELETE_ALLOWED = 0x08,
129  } Operation;
130 
141  typedef enum {
142  MESSAGE_STATUS_INIT = 0, // Initial state.
143  MESSAGE_STATUS_BUILD_ERROR, // CoAP message building fails.
144  MESSAGE_STATUS_RESEND_QUEUE_FULL, // CoAP resend queue full.
145  MESSAGE_STATUS_SENT, // Message sent to the server but ACK not yet received.
146  MESSAGE_STATUS_DELIVERED, // Received ACK from server.
147  MESSAGE_STATUS_SEND_FAILED, // Message sending failed.
148  MESSAGE_STATUS_SUBSCRIBED, // Server has started the observation
149  MESSAGE_STATUS_UNSUBSCRIBED, // Server has stopped the observation (RESET message or GET with observe 1)
150  MESSAGE_STATUS_REJECTED // Server has rejected the response
152 
153  typedef enum {
154  NOTIFICATION = 0,
155  DELAYED_POST_RESPONSE,
156  BLOCK_SUBSCRIBE,
157  PING,
158  DELAYED_RESPONSE
159  } MessageType;
160 
161  enum MaxPathSize {
162  MAX_NAME_SIZE = 64,
163  MAX_INSTANCE_SIZE = 5,
164 
165  MAX_PATH_SIZE = ((MAX_NAME_SIZE * 2) + (MAX_INSTANCE_SIZE * 2) + 3 + 1),
166  MAX_PATH_SIZE_2 = ((MAX_NAME_SIZE * 2) + MAX_INSTANCE_SIZE + 2 + 1),
167  MAX_PATH_SIZE_3 = (MAX_NAME_SIZE + (MAX_INSTANCE_SIZE * 2) + 2 + 1),
168  MAX_PATH_SIZE_4 = (MAX_NAME_SIZE + MAX_INSTANCE_SIZE + 1 + 1)
169  };
170 
171  typedef void(*message_delivery_status_cb)(const M2MBase &base,
172  const MessageDeliveryStatus status,
173  const MessageType type,
174  void *client_args);
175 
176 #ifdef ENABLE_ASYNC_REST_RESPONSE
177 
187  typedef void (*handle_async_coap_request_cb)(const M2MBase &base,
189  const uint8_t *token,
190  const uint8_t token_len,
191  const uint8_t *buffer,
192  size_t buffer_size,
193  void *client_args);
194 #endif // ENABLE_ASYNC_REST_RESPONSE
195 
199  typedef struct lwm2m_parameters {
200  //add multiple_instances
201  uint32_t max_age; // todo: add flag
205  union {
206  char *name; //for backwards compatibility
207  uint16_t instance_id; // XXX: this is not properly aligned now, need to reorder these after the elimination is done
208  } identifier;
209  sn_nsdl_dynamic_resource_parameters_s *dynamic_resource_params;
210  BaseType base_type : 3;
211  M2MBase::DataType data_type : 3;
212  bool multiple_instance;
219  bool identifier_int_type;
223 
224 protected:
225 
226  // Prevents the use of default constructor.
227  M2MBase();
228 
229  // Prevents the use of assignment operator.
230  M2MBase &operator=(const M2MBase & /*other*/);
231 
232  // Prevents the use of copy constructor
233  M2MBase(const M2MBase & /*other*/);
234 
244  M2MBase(const String &name,
246 #ifndef DISABLE_RESOURCE_TYPE
247  const String &resource_type,
248 #endif
249  char *path,
250  bool external_blockwise_store,
251  bool multiple_instance,
252  M2MBase::DataType type = M2MBase::OBJLINK);
253 
254  M2MBase(const lwm2m_parameters_s *s);
255 
256 public:
257 
261  virtual ~M2MBase();
262 
269  void set_operation(M2MBase::Operation operation);
270 
271 #if !defined(MEMORY_OPTIMIZED_API) || defined(RESOURCE_ATTRIBUTES_LIST)
272 #if !defined(DISABLE_INTERFACE_DESCRIPTION) || defined(RESOURCE_ATTRIBUTES_LIST)
273 
278  void set_interface_description(const String &description);
279 
285  void set_interface_description(const char *description);
286 
292  const char *interface_description() const;
293 #endif
294 #if !defined(DISABLE_RESOURCE_TYPE) || defined(RESOURCE_ATTRIBUTES_LIST)
295 
300  virtual void set_resource_type(const String &resource_type);
301 
307  virtual void set_resource_type(const char *resource_type);
308 
314  const char *resource_type() const;
315 #endif
316 #endif
317 
324  void set_coap_content_type(const uint16_t content_type);
325 
331  void set_observable(bool observable);
332 
342  void set_auto_observable(bool auto_observable);
343 
355  void set_confirmable(bool confirmable);
356 
363 
370 
378  void set_under_observation(bool observed,
379  M2MObservationHandler *handler);
385  virtual M2MObservationHandler *observation_handler() const = 0;
386 
392  virtual void set_observation_handler(M2MObservationHandler *handler) = 0;
393 
399  void set_instance_id(const uint16_t instance_id);
400 
405  void set_max_age(const uint32_t max_age);
406 
411  M2MBase::BaseType base_type() const;
412 
418 
423  const char *name() const;
424 
429  int32_t name_id() const;
430 
435  uint16_t instance_id() const;
436 
441  const char *uri_path() const;
442 
448  uint16_t coap_content_type() const;
449 
450 #if defined (MBED_CLIENT_ENABLE_DYNAMIC_OBSERVABLE) && (MBED_CLIENT_ENABLE_DYNAMIC_OBSERVABLE == 1)
451 
456  bool is_observable() const;
457 #else
458 
462  bool is_readable() const;
463 #endif //MBED_CLIENT_ENABLE_DYNAMIC_OBSERVABLE
464 
469  bool is_auto_observable() const;
470 
477 
482  Mode mode() const;
483 
488  uint16_t observation_number() const;
489 
494  uint32_t max_age() const;
495 
496 #if defined (MBED_CONF_MBED_CLIENT_ENABLE_OBSERVATION_PARAMETERS) && (MBED_CONF_MBED_CLIENT_ENABLE_OBSERVATION_PARAMETERS == 1)
497 
504  virtual bool handle_observation_attribute(const char *query);
505 #endif
506 
516  virtual sn_coap_hdr_s *handle_get_request(nsdl_s *nsdl,
517  sn_coap_hdr_s *received_coap_header,
529  virtual sn_coap_hdr_s *handle_put_request(nsdl_s *nsdl,
530  sn_coap_hdr_s *received_coap_header,
532  bool &execute_value_updated);
533 
544  virtual sn_coap_hdr_s *handle_post_request(nsdl_s *nsdl,
545  sn_coap_hdr_s *received_coap_header,
547  bool &execute_value_updated,
548  sn_nsdl_addr_s *address = NULL);
549 
553  void send_message_delivery_status(const M2MBase &object, const MessageDeliveryStatus status, const MessageType type);
554 
560  void set_register_uri(bool register_uri);
561 
567  bool register_uri();
568 
574  bool is_under_observation() const;
575 
584 
591  bool set_value_updated_function(value_updated_callback2 callback);
592 
598  bool is_value_updated_function_set() const;
599 
605  void execute_value_updated(const String &name);
606 
611  size_t resource_name_length() const;
612 
618  sn_nsdl_dynamic_resource_parameters_s *get_nsdl_resource() const;
619 
626 
627 #ifdef ENABLE_ASYNC_REST_RESPONSE
628 
637  bool send_async_response_with_code(const uint8_t *payload,
638  size_t payload_len,
639  const uint8_t *token,
640  const uint8_t token_len,
642 
650  bool set_async_coap_request_cb(handle_async_coap_request_cb callback, void *client_args);
651 
652 #endif //ENABLE_ASYNC_REST_RESPONSE
653 
658  uint16_t get_notification_msgid() const m2m_deprecated;
659 
665  void set_notification_msgid(uint16_t msgid) m2m_deprecated;
666 
673  bool set_message_delivery_status_cb(message_delivery_status_cb callback, void *client_args);
674 
675 #ifdef MBED_CLOUD_CLIENT_EDGE_EXTENSION
676  static char *create_path(const M2MEndpoint &parent, const char *name);
677 #endif
678  static char *create_path(const M2MObject &parent, const char *name);
679  static char *create_path(const M2MObject &parent, uint16_t object_instance);
680  static char *create_path(const M2MResource &parent, uint16_t resource_instance);
681  static char *create_path(const M2MResource &parent, const char *name);
682  static char *create_path(const M2MObjectInstance &parent, const char *name);
683 
684 #ifdef MBED_CLOUD_CLIENT_EDGE_EXTENSION
685 
691  virtual void set_deleted();
692 
693 
698  virtual bool is_deleted();
699 
700 #endif // MBED_CLOUD_CLIENT_EDGE_EXTENSION
701 
706  M2MReportHandler *report_handler() const;
707 
708 protected: // from M2MReportObserver
709 
710  virtual bool observation_to_be_sent(const m2m::Vector<uint16_t> &changed_instance_ids,
711  uint16_t obs_number,
712  bool send_object = false);
713 
718  void set_base_type(M2MBase::BaseType type);
719 
724  static void *memory_alloc(uint32_t size);
725 
730  static void memory_free(void *ptr);
731 
737  static char *alloc_string_copy(const char *source);
738 
745  static uint8_t *alloc_string_copy(const uint8_t *source, uint32_t size);
746 
752  static uint8_t *alloc_copy(const uint8_t *source, uint32_t size);
753 
754  // validate string length to be [min_length..max_length]
755  static bool validate_string_length(const String &string, size_t min_length, size_t max_length);
756  static bool validate_string_length(const char *string, size_t min_length, size_t max_length);
757 
762  M2MReportHandler *create_report_handler();
763 
764  static bool build_path(StringBuffer<MAX_PATH_SIZE> &buffer, const char *s1, uint16_t i1, const char *s2, uint16_t i2);
765 
766  static bool build_path(StringBuffer<MAX_PATH_SIZE_2> &buffer, const char *s1, uint16_t i1, const char *s2);
767 
768  static bool build_path(StringBuffer<MAX_PATH_SIZE_3> &buffer, const char *s1, uint16_t i1, uint16_t i2);
769 
770  static bool build_path(StringBuffer<MAX_PATH_SIZE_4> &buffer, const char *s1, uint16_t i1);
771 
772  static char *stringdup(const char *s);
773 
780  void free_resources();
781 
785  void clear_notification_delivery_status() m2m_deprecated;
786 
792  void get_observation_token(uint8_t *token, uint8_t &token_length) const;
793 
799  void set_observation_token(const uint8_t *token,
800  const uint8_t length);
801 
808  virtual void set_changed();
809 
813  virtual M2MBase *get_parent() const;
814 
821  static bool is_blockwise_needed(const nsdl_s *nsdl, uint32_t payload_len);
822 
831  void handle_observation(nsdl_s *nsdl,
832  const sn_coap_hdr_s &received_coap_header,
833  sn_coap_hdr_s &coap_response,
835  sn_coap_msg_code_e &response_code);
836 
843  void cancel_observation(M2MBase::MessageDeliveryStatus status = M2MBase::MESSAGE_STATUS_UNSUBSCRIBED, bool notify = true);
844 
851  void start_observation(const sn_coap_hdr_s &received_coap_header, M2MObservationHandler *observation_handler);
852 
853 #ifdef ENABLE_ASYNC_REST_RESPONSE
854 
861  void call_async_coap_request_callback(sn_coap_hdr_s *coap_request,
862  M2MBase::Operation operation,
863  bool &handled);
864 
869  bool is_async_coap_request_callback_set();
870 
871 #endif //ENABLE_ASYNC_REST_RESPONSE
872 
873 private:
874 
875  static bool is_integer(const String &value);
876 
877  static bool is_integer(const char *value);
878 
879  static char *create_path_base(const M2MBase &parent, const char *name);
880 
881  lwm2m_parameters_s *_sn_resource;
882  M2MReportHandler *_report_handler; // TODO: can be broken down to smaller classes with inheritance.
883 
884  friend class Test_M2MBase;
885  friend class Test_M2MObject;
886  friend class M2MNsdlInterface;
887  friend class M2MInterfaceFactory;
888  friend class M2MObject;
889 };
890 
891 #endif // M2M_BASE_H
bool set_message_delivery_status_cb(message_delivery_status_cb callback, void *client_args)
Sets the function that is executed when message state changes. Currently this is used to track notifi...
sn_nsdl_dynamic_resource_parameters_s * get_nsdl_resource() const
Returns the resource information.
Mode
Enum defining a resource type.
Definition: m2mbase.h:89
Definition: m2mobject.h:35
Definition: m2mobservationhandler.h:30
virtual void set_changed()
The data has changed and it needs to be updated into Device Management. Current implementation mainta...
const char * interface_description() const
Returns the interface description of the object.
size_t resource_name_length() const
Returns length of the object name.
Static resource, value cannot change.
Definition: m2mbase.h:90
int32_t name_id() const
Returns the object name in integer.
void set_observable(bool observable)
Sets the observable mode for the object.
void free_resources()
Delete the resource structures owned by this object. Note: this needs to be called separately from ea...
Definition: m2mbase.h:118
void get_observation_token(uint8_t *token, uint8_t &token_length) const
Provides the observation token of the object.
bool is_value_updated_function_set() const
Returns whether a callback function is set or not.
Definition: m2mbase.h:54
Definition: m2mbase.h:125
void set_register_uri(bool register_uri)
Sets whether this resource is published to server or not.
void set_base_type(M2MBase::BaseType type)
Sets the base type for an object.
void set_under_observation(bool observed, M2MObservationHandler *handler)
Sets the object under observation.
static uint8_t * alloc_copy(const uint8_t *source, uint32_t size)
Allocate (size) amount of memory, copy size bytes into it.
M2MBase::Operation operation() const
Returns the operation type of the object.
Observation
Enum to define observation level.
Definition: m2mbase.h:74
GET and PUT operations allowed.
Definition: m2mbase.h:116
Definition: m2mobjectinstance.h:42
virtual sn_coap_hdr_s * handle_get_request(nsdl_s *nsdl, sn_coap_hdr_s *received_coap_header, M2MObservationHandler *observation_handler=NULL)
Handles GET request for the registered objects.
Only POST operation allowed.
Definition: m2mbase.h:117
BaseType
Enum to define the type of object.
Definition: m2mbase.h:61
M2MBase::lwm2m_parameters_s * get_lwm2m_parameters() const
Returns the resource structure.
uint16_t observation_number() const
Returns the observation number.
bool register_uri()
Returns whether this resource is published to server or not.
Only GET operation allowed.
Definition: m2mbase.h:114
GET, PUT and DELETE operations allowed.
Definition: m2mbase.h:124
Definition: m2mbase.h:127
Definition: m2mstringbuffer.h:30
bool is_under_observation() const
Returns whether this resource is under observation or not.
header for StringBuffer.
virtual ~M2MBase()
Destructor.
virtual sn_coap_hdr_s * handle_put_request(nsdl_s *nsdl, sn_coap_hdr_s *received_coap_header, M2MObservationHandler *observation_handler, bool &execute_value_updated)
Handles PUT request for the registered objects.
LwM2M parameters.
Definition: m2mbase.h:199
Definition: m2mbase.h:120
header for M2MReportObserver
Unsupported.
Definition: m2mbase.h:92
virtual void set_observation_handler(M2MObservationHandler *handler)=0
Sets the observation handler.
PUT and DELETE operations allowed.
Definition: m2mbase.h:123
virtual bool observation_to_be_sent(const m2m::Vector< uint16_t > &changed_instance_ids, uint16_t obs_number, bool send_object=false)
An observation callback to be sent to the server due to a change in the observed parameter.
CoAP response code values.
static void memory_free(void *ptr)
Memory free functions required for libCoap.
M2MReportHandler * create_report_handler()
Create Report Handler object.
static bool is_blockwise_needed(const nsdl_s *nsdl, uint32_t payload_len)
Checks whether blockwise is needed to send resource value to server.
bool is_auto_observable() const
Returns the auto observation status of the object.
void set_notification_msgid(uint16_t msgid) m2m_deprecated
Sets the notification message id. This is used to map RESET and EMPTY ACK messages.
DataType
Enum defining a resource data type.
Definition: m2mbase.h:98
Definition: m2mbase.h:119
bool set_value_updated_function(value_updated_callback callback)
Sets the function that is executed when this object receives a PUT or POST command.
Header for function pointer classes.
Definition: m2mreportobserver.h:27
const char * uri_path() const
Returns the path of the object.
Mode mode() const
Returns the mode of the resource.
void set_interface_description(const String &description)
Sets the interface description of the object.
Only DELETE operation allowed.
Definition: m2mbase.h:121
virtual sn_coap_hdr_s * handle_post_request(nsdl_s *nsdl, sn_coap_hdr_s *received_coap_header, M2MObservationHandler *observation_handler, bool &execute_value_updated, sn_nsdl_addr_s *address=NULL)
Handles GET request for the registered objects.
GET and DELETE operations allowed.
Definition: m2mbase.h:122
bool is_readable() const
Returns get operation allow state.
File defining all system build time configuration used by mbed-client.
A simple C++ Vector class, used as replacement for std::vector.
Definition: m2mvector.h:29
coap_response_code_e
Definition: coap_response.h:26
uint16_t coap_content_type() const
Returns the CoAP content type of the object.
void cancel_observation(M2MBase::MessageDeliveryStatus status=M2MBase::MESSAGE_STATUS_UNSUBSCRIBED, bool notify=true)
Cancels the ongoing observation.
Dynamic resource.
Definition: m2mbase.h:91
bool read_write_callback_set
If set, all the read and write operations are handled in callbacks and the resource value is not stor...
Definition: m2mbase.h:220
void set_instance_id(const uint16_t instance_id)
Sets the instance ID of the object.
virtual M2MBase * get_parent() const
Returns the owner object. Can return NULL if the object has no parent.
void set_auto_observable(bool auto_observable)
Sets the object to be auto-observable.
uint16_t get_notification_msgid() const m2m_deprecated
Returns the notification message id.
M2MReportHandler * report_handler() const
Returns the Report Handler object.
Definition: m2mresource.h:38
struct M2MBase::lwm2m_parameters lwm2m_parameters_s
LwM2M parameters.
Only PUT operation allowed.
Definition: m2mbase.h:115
void set_operation(M2MBase::Operation operation)
Sets the operation type for an object.
void send_message_delivery_status(const M2MBase &object, const MessageDeliveryStatus status, const MessageType type)
Executes the function that is set in "set_message_delivery_status_cb".
void set_observation_token(const uint8_t *token, const uint8_t length)
Sets the observation token value.
virtual void remove_observation_level(M2MBase::Observation observation_level)
Removes the observation level for the object.
virtual void add_observation_level(M2MBase::Observation observation_level)
Adds the observation level for the object.
const char * resource_type() const
Returns the resource type of the object.
M2MBase::Observation observation_level() const
Returns the observation level of the object.
Definition: m2minterfacefactory.h:36
bool free_on_delete
true if struct is dynamically allocated and it and its members (name) are to be freed on destructor...
Definition: m2mbase.h:213
static void * memory_alloc(uint32_t size)
Memory allocation required for libCoap.
Operation
Enum defining an operation that can be supported by a given resource.
Definition: m2mbase.h:112
void execute_value_updated(const String &name)
Calls the function that is set in the "set_value_updated_function".
void set_coap_content_type(const uint16_t content_type)
Sets the CoAP content type of the object.
Definition: coap_response.h:30
virtual M2MObservationHandler * observation_handler() const =0
Returns the Observation Handler object.
No operations allowed.
Definition: m2mbase.h:113
void handle_observation(nsdl_s *nsdl, const sn_coap_hdr_s &received_coap_header, sn_coap_hdr_s &coap_response, M2MObservationHandler *observation_handler, sn_coap_msg_code_e &response_code)
Handles subscription request.
MessageDeliveryStatus
Enum defining an status codes that can happen when sending confirmable message.
Definition: m2mbase.h:141
void set_confirmable(bool confirmable)
Sets how the notification is sent. By default confirmable CoAP message type is used.
virtual void set_resource_type(const String &resource_type)
Sets the resource type of the object.
void clear_notification_delivery_status() m2m_deprecated
Clears the notification send status to initial state.
Definition: functionpointer.h:113
Parameter identifier.
void set_max_age(const uint32_t max_age)
Sets the max age for the resource value to be cached.
void start_observation(const sn_coap_hdr_s &received_coap_header, M2MObservationHandler *observation_handler)
Start the observation.
Definition: m2mbase.h:126
static char * alloc_string_copy(const char *source)
Allocate and make a copy of given zero terminated string. This is functionally equivalent with strdup...
Definition: m2mbase.h:128