Persist observe: Support tracking observe information over server res…

…tarts

Add in optional callbacks for when observe subscriptions start and stop.

Add in optional callbacks for when the observe counter is updated (can be
ratelimited) for a resource as well as track when a resource is deleted.

Add is support for new functions

coap_persist_observe() for server to add in tracked observe information.

coap_resource_set_observe_num() to update observe counter from tracked
information.

coap_observe_track() to define the optional callback functions.

coap-server has -t option to track observe information (most of the code
updates).

UDP sessions supported, as well as OSCORE over UDP.

Documentation updated

include/coap3/coap_net_internal.h

@@ -19,6 +19,7 @@
 #define COAP_NET_INTERNAL_H_
 
 #include "coap_internal.h"
+#include "coap_subscribe.h"
 
 /**
  * @ingroup internal_api
@@ -95,11 +96,26 @@ struct coap_context_t {
 #endif /* HAVE_OSCORE */
 
 #if COAP_CLIENT_SUPPORT
-  coap_response_handler_t response_handler;
+  coap_response_handler_t response_handler; /**< Called when a response is
+                                                 received */
 #endif /* COAP_CLIENT_SUPPORT */
-  coap_nack_handler_t nack_handler;
-  coap_ping_handler_t ping_handler;
-  coap_pong_handler_t pong_handler;
+  coap_nack_handler_t nack_handler; /**< Called when a response issue has
+                                         occurred */
+  coap_ping_handler_t ping_handler; /**< Called when a CoAP ping is received */
+  coap_pong_handler_t pong_handler; /**< Called when a ping response
+                                         is received */
+
+  coap_observe_added_t observe_added; /**< Called when there is a new observe
+                                           subscription request */
+  coap_observe_deleted_t observe_deleted; /**< Called when there is a observe
+                                           subscription de-register request */
+  void *observe_user_data; /**< App provided data for use in observe_added or
+                                observe_deleted */
+  uint32_t observe_save_freq; /**< How frequently to update observe value */
+  coap_save_observe_value_t save_observe_value; /**< Callback to save observe
+                                                     value when updated */
+  coap_del_observe_value_t del_observe_value; /**< Invoked when as resource
+                                                   is deleted */
 
   /**
    * Callback function that is used to signal events to the

include/coap3/coap_subscribe.h

@@ -60,9 +60,121 @@ void coap_resource_set_get_observable(coap_resource_t *resource, int mode);
  *
  * @return         @c 1 if the Observe has been triggered, @c 0 otherwise.
  */
-int
-coap_resource_notify_observers(coap_resource_t *resource,
-                               const coap_string_t *query);
+int coap_resource_notify_observers(coap_resource_t *resource,
+                                   const coap_string_t *query);
+
+/**
+ * Callback handler definition called when a new observe has been set up.
+ *
+ * @param session The current session.
+ * @param observe_key The pointer to the subscription.
+ * @param e_proto The CoAP protocol in use for the session / endpoint.
+ * @param e_listen_addr The IP/port tthat the endpoint is listening on.
+ * @param s_addr_info Local / Remote IP addresses. ports etc. of session.
+ * @param raw_packet L7 packet as seen on the wire (could be concatenated if
+ *                   Block1 FETCH is being used.
+ * @param oscore_info Has OSCORE information if OSCORE is protecting the
+ *                    session or NULL if OSCORE is not in use.
+ * @param user_data Application provided information from coap_observe_track().
+ *
+ * @return @c 1 if success else @c 0.
+ */
+typedef int (*coap_observe_added_t)(coap_session_t *session,
+                                    coap_subscription_t *observe_key,
+                                    coap_proto_t e_proto,
+                                    coap_address_t *e_listen_addr,
+                                    coap_addr_tuple_t *s_addr_info,
+                                    coap_bin_const_t *raw_packet,
+                                    coap_bin_const_t *oscore_info,
+                                    void *user_data);
+
+/**
+ * Callback handler definition called when an observe is being removed.
+ *
+ * @param session The current session.
+ * @param observe_key The pointer to the subscription.
+ * @param user_data Application provided information from coap_observe_track().
+ *
+ * @return @c 1 if success else @c 0.
+ */
+typedef int (*coap_observe_deleted_t)(coap_session_t *session,
+                                      coap_subscription_t *observe_key,
+                                      void *user_data);
+
+/**
+ * Callback handler definition called when an observe unsolicited response is
+ * being set.
+ * Note: This will only get called every save_freq as defined by
+ * coap_observe_track().
+ *
+ * @param resource_name The uri path name of the resource.
+ * @param user_data Application provided information from coap_observe_track().
+ * @param observe_num The current observe value just sent.
+ *
+ * @return @c 1 if success else @c 0.
+ */
+typedef int (*coap_save_observe_value_t)(coap_str_const_t *resource_name,
+                                         void *user_data,
+                                         uint32_t observe_num);
+
+/**
+ * Callback handler definition called when resource is removed that has been
+ * observed.
+ *
+ * @param resource_name The uri path name of the resource.
+ * @param user_data Application provided information from coap_observe_track().
+ *
+ * @return @c 1 if success else @c 0.
+ */
+typedef int (*coap_del_observe_value_t)(coap_str_const_t *resource_name,
+                                        void *user_data);
+
+/**
+ * Set up callbacks to handle observe tracking so on a coap-server inadvertant
+ * restart existing observe subscriptions can continue.
+ *
+ * @param context The current CoAP context.
+ * @param observe_added Called when a new observe subscription is set up.
+ * @param observe_deleted Called when a observe subscription is de-registered.
+ * @param save_observe_value Called every @p save_freq so current observe value
+ *                           can be tracked.
+ * @param del_observe_value Called when a resource is removed.
+ * @param save_freq Frequency of change of observe value for calling
+ *                  @p save_observe_value
+ * @param user_data App defined data (can be NULL) passed into various
+ *                  callbacks.
+ */
+void coap_observe_track(coap_context_t *context,
+                           coap_observe_added_t observe_added,
+                           coap_observe_deleted_t observe_deleted,
+                           coap_save_observe_value_t save_observe_value,
+                           coap_del_observe_value_t del_observe_value,
+                           uint32_t save_freq,
+                           void *user_data);
+
+/**
+ * Set up an active subscription for an observe that was previously active
+ * over a coap-server inadvertant restart.
+ *
+ * @param context The context that the session is to be associated with.
+ * @param e_proto The CoAP protocol in use for the session / endpoint.
+ * @param e_listen_addr The IP/port tthat the endpoint is listening on.
+ * @param s_addr_info Local / Remote IP addresses. ports etc. of previous
+ *                    session.
+ * @param raw_packet L7 packet as seen on the wire (could be concatenated if
+ *                   Block1 FETCH is being used.
+ * @param oscore_info Has OSCORE information if OSCORE is protecting the
+ *                    session or NULL if OSCORE is not in use.
+ *
+ * @return ptr to subscription if success else @c NULL.
+ */
+coap_subscription_t *coap_persist_observe(coap_context_t *context,
+                                          coap_proto_t e_proto,
+                                          const coap_address_t *e_listen_addr,
+                                          const coap_addr_tuple_t *s_addr_info,
+                                          const coap_bin_const_t *raw_packet,
+                                          const coap_bin_const_t *oscore_info);
+
 
 /** @} */
 

include/coap3/resource.h

@@ -22,13 +22,6 @@
 #define COAP_RESOURCE_CHECK_TIME 2
 #endif /* COAP_RESOURCE_CHECK_TIME */
 
-#include "coap_async.h"
-#include "block.h"
-#include "coap_str.h"
-#include "pdu.h"
-#include "coap_net.h"
-#include "coap_subscribe.h"
-
 /**
  * @ingroup application_api
  * @defgroup coap_resource Resource Configuraton
@@ -312,6 +305,15 @@ coap_str_const_t* coap_resource_get_uri_path(coap_resource_t *resource);
  */
 void coap_resource_set_mode(coap_resource_t *resource, int mode);
 
+/**
+ * Sets the current observe number value.
+
+ * @param resource The resource to update.
+ * @param observe_num The value to set the observe number to.
+ */
+void coap_resource_set_observe_num(coap_resource_t *resource,
+                                   uint32_t observe_num);
+
 /**
  * Sets the user_data. The user_data is exclusively used by the library-user
  * and can be used as user defined context in the handler functions.

include/oscore/oscore_cbor.h

@@ -69,6 +69,7 @@
 
 #define CBOR_FALSE 20
 #define CBOR_TRUE  21
+#define CBOR_NULL  22
 
 size_t oscore_cbor_put_nil(uint8_t **buffer, size_t *buf_size);
 

include/oscore/oscore_context.h

@@ -240,9 +240,9 @@ void oscore_log_char_value(coap_log_t level, const char *name,
  *
  * return The OSCORE context and @p recipient_ctx updated, or NULL is error.
  */
-oscore_ctx_t *oscore_find_context(coap_context_t *c_context,
-                                  coap_bin_const_t rcpkey_id,
-                                  coap_bin_const_t *ctxkey_id,
+oscore_ctx_t *oscore_find_context(const coap_context_t *c_context,
+                                  const coap_bin_const_t rcpkey_id,
+                                  const coap_bin_const_t *ctxkey_id,
                                   uint8_t *oscore_r2,
                                   oscore_recipient_ctx_t **recipient_ctx);
 

libcoap-3.map

@@ -143,6 +143,7 @@ global:
   coap_new_str_const;
   coap_new_string;
   coap_new_uri;
+  coap_observe_track;
   coap_opt_block_num;
   coap_opt_encode;
   coap_opt_encode_size;
@@ -171,6 +172,7 @@ global:
   coap_pdu_set_code;
   coap_pdu_set_mid;
   coap_pdu_set_type;
+  coap_persist_observe;
   coap_print_addr;
   coap_print_link;
   coap_prng;
@@ -197,6 +199,7 @@ global:
   coap_resource_set_dirty;
   coap_resource_set_get_observable;
   coap_resource_set_mode;
+  coap_resource_set_observe_num;
   coap_resource_set_userdata;
   coap_resource_unknown_init;
   coap_resource_unknown_init2;

libcoap-3.sym

@@ -141,6 +141,7 @@ coap_new_pdu
 coap_new_str_const
 coap_new_string
 coap_new_uri
+coap_observe_track
 coap_opt_block_num
 coap_opt_encode
 coap_opt_encode_size
@@ -169,6 +170,7 @@ coap_pdu_parse
 coap_pdu_set_code
 coap_pdu_set_mid
 coap_pdu_set_type
+coap_persist_observe
 coap_print_addr
 coap_print_link
 coap_prng
@@ -195,6 +197,7 @@ coap_resource_release_userdata_handler
 coap_resource_set_dirty
 coap_resource_set_get_observable
 coap_resource_set_mode
+coap_resource_set_observe_num
 coap_resource_set_userdata
 coap_resource_unknown_init
 coap_resource_unknown_init2

man/coap-client.txt.in

@@ -27,7 +27,7 @@ SYNOPSIS
               [*-P* scheme://addr[:port]] [*-T* token] [*-U*] [*-V* num]
               [*-X* size]
               [[*-h* match_hint_file] [*-k* key] [*-u* user]]
-              [[*-c* certfile] [*-j* keyfile] [-n] [*-C* cafile]
+              [[*-c* certfile] [*-j* keyfile] [*-n*] [*-C* cafile]
               [*-J* pkcs11_pin] [*-M* rpk_file] [*-R* trust_casfile]] URI
 
 For *coap-client* versions that use libcoap compiled for different

man/coap-server.txt.in

@@ -19,7 +19,8 @@ coap-server-notls
 
 SYNOPSIS
 --------
-*coap-server* [*-d* max] [*-e*] [*-g* group] [*-l* loss] [*-p* port] [-r]
+*coap-server* [*-d* max] [*-e*] [*-g* group] [*-l* loss] [*-p* port] [*-r*]
+              [*-t*]
               [*-v* num] [*-A* address] [*-E* oscore_conf_file[,seq_file]]
               [*-G* group_if] [*-L* value] [*-N*]
               [*-P* scheme://addr[:port],[name1[,name2..]]]
@@ -73,6 +74,10 @@ OPTIONS - General
    and '/.well-known/core' are enabled for multicast requests support,
    otherwise all resources are enabled.
 
+*-t* ::
+   Track resource's observe values so observe subscriptions can be
+   maintained over a server restart.
+
 *-v* num::
    The verbosity level to use (default 4, maximum is 8) for general
    CoAP logging.