1 /* 2 * coap_subscribe.h -- subscription handling for CoAP 3 * see RFC7641 4 * 5 * Copyright (C) 2010-2012,2014-2023 Olaf Bergmann <bergmann@tzi.org> 6 * 7 * SPDX-License-Identifier: BSD-2-Clause 8 * 9 * This file is part of the CoAP library libcoap. Please see README for terms 10 * of use. 11 */ 12 13 /** 14 * @file coap_subscribe.h 15 * @brief Defines the application visible subscribe information 16 */ 17 18 #ifndef COAP_SUBSCRIBE_H_ 19 #define COAP_SUBSCRIBE_H_ 20 21 /** 22 * @ingroup application_api 23 * @defgroup observe Resource Observation 24 * API for interfacing with the observe handling (RFC7641) 25 * @{ 26 */ 27 28 /** 29 * The value COAP_OBSERVE_ESTABLISH in a GET/FETCH request option 30 * COAP_OPTION_OBSERVE indicates a new observe relationship for (sender 31 * address, token) is requested. 32 */ 33 #define COAP_OBSERVE_ESTABLISH 0 34 35 /** 36 * The value COAP_OBSERVE_CANCEL in a GET/FETCH request option 37 * COAP_OPTION_OBSERVE indicates that the observe relationship for (sender 38 * address, token) must be cancelled. 39 */ 40 #define COAP_OBSERVE_CANCEL 1 41 42 /** 43 * Set whether a @p resource is observable. If the resource is observable 44 * and the client has set the COAP_OPTION_OBSERVE in a request packet, then 45 * whenever the state of the resource changes (a call to 46 * coap_resource_trigger_observe()), an Observer response will get sent. 47 * 48 * @param resource The CoAP resource to use. 49 * @param mode @c 1 if Observable is to be set, @c 0 otherwise. 50 * 51 */ 52 void coap_resource_set_get_observable(coap_resource_t *resource, int mode); 53 54 /** 55 * Initiate the sending of an Observe packet for all observers of @p resource, 56 * optionally matching @p query if not NULL 57 * 58 * @param resource The CoAP resource to use. 59 * @param query The Query to match against or NULL 60 * 61 * @return @c 1 if the Observe has been triggered, @c 0 otherwise. 62 */ 63 int coap_resource_notify_observers(coap_resource_t *resource, 64 const coap_string_t *query); 65 66 /** 67 * Callback handler definition called when a new observe has been set up, 68 * as defined in coap_persist_track_funcs(). 69 * 70 * @param session The current session. 71 * @param observe_key The pointer to the subscription. 72 * @param e_proto The CoAP protocol in use for the session / endpoint. 73 * @param e_listen_addr The IP/port that the endpoint is listening on. 74 * @param s_addr_info Local / Remote IP addresses. ports etc. of session. 75 * @param raw_packet L7 packet as seen on the wire (could be concatenated if 76 * Block1 FETCH is being used). 77 * @param oscore_info Has OSCORE information if OSCORE is protecting the 78 * session or NULL if OSCORE is not in use. 79 * @param user_data Application provided information from 80 * coap_persist_track_funcs(). 81 * 82 * @return @c 1 if success else @c 0. 83 */ 84 typedef int (*coap_observe_added_t)(coap_session_t *session, 85 coap_subscription_t *observe_key, 86 coap_proto_t e_proto, 87 coap_address_t *e_listen_addr, 88 coap_addr_tuple_t *s_addr_info, 89 coap_bin_const_t *raw_packet, 90 coap_bin_const_t *oscore_info, 91 void *user_data); 92 93 /** 94 * Callback handler definition called when an observe is being removed, 95 * as defined in coap_persist_track_funcs(). 96 * 97 * @param session The current session. 98 * @param observe_key The pointer to the subscription. 99 * @param user_data Application provided information from 100 * coap_persist_track_funcs(). 101 * 102 * @return @c 1 if success else @c 0. 103 */ 104 typedef int (*coap_observe_deleted_t)(coap_session_t *session, 105 coap_subscription_t *observe_key, 106 void *user_data); 107 108 /** 109 * Callback handler definition called when an observe unsolicited response is 110 * being sent, as defined in coap_persist_track_funcs(). 111 * 112 * Note: This will only get called every save_freq as defined by 113 * coap_persist_track_funcs(). 114 * 115 * @param context The current CoAP context. 116 * @param resource_name The uri path name of the resource. 117 * @param observe_num The current observe value just sent. 118 * @param user_data Application provided information from 119 * coap_persist_track_funcs(). 120 * 121 * @return @c 1 if success else @c 0. 122 */ 123 typedef int (*coap_track_observe_value_t)(coap_context_t *context, 124 coap_str_const_t *resource_name, 125 uint32_t observe_num, 126 void *user_data); 127 128 /** 129 * Callback handler definition called when a dynamic resource is getting 130 * created, as defined in coap_persist_track_funcs(). 131 * 132 * @param session The current CoAP session. 133 * @param resource_name The uri path name of the resource. 134 * @param raw_packet L7 packet as seen on the wire (could be concatenated if 135 * Block1 PUT/POST/FETCH used to create resource). 136 * @param user_data Application provided information from 137 * coap_persist_track_funcs(). 138 * 139 * @return @c 1 if success else @c 0. 140 */ 141 typedef int (*coap_dyn_resource_added_t)(coap_session_t *session, 142 coap_str_const_t *resource_name, 143 coap_bin_const_t *raw_packet, 144 void *user_data); 145 146 /** 147 * Callback handler definition called when resource is removed, 148 * as defined in coap_persist_track_funcs(). 149 * 150 * This will remove any dynamic resources that are being tracked as well 151 * as any observe value tracking. 152 * 153 * @param context The current CoAP context. 154 * @param resource_name The uri path name of the resource. 155 * @param user_data Application provided information from 156 * coap_persist_track_funcs(). 157 * 158 * @return @c 1 if success else @c 0. 159 */ 160 typedef int (*coap_resource_deleted_t)(coap_context_t *context, 161 coap_str_const_t *resource_name, 162 void *user_data); 163 164 /** 165 * Set up callbacks to handle persist tracking so on a coap-server inadvertent 166 * restart, existing observe subscriptions can continue. 167 * 168 * @param context The current CoAP context. 169 * @param observe_added Called when a new observe subscription is set up. 170 * @param observe_deleted Called when a observe subscription is de-registered. 171 * @param track_observe_value Called every @p save_freq so current observe 172 * value can be tracked. 173 * @param dyn_resource_added Called whan a dynamic resource is created from the 174 * 'unknown' resource for tracking. 175 * @param resource_deleted Called when a resource is removed. 176 * @param save_freq Frequency of change of observe value for calling 177 * @p save_observe_value 178 * @param user_data App defined data (can be NULL) passed into various 179 * callbacks. 180 */ 181 void coap_persist_track_funcs(coap_context_t *context, 182 coap_observe_added_t observe_added, 183 coap_observe_deleted_t observe_deleted, 184 coap_track_observe_value_t track_observe_value, 185 coap_dyn_resource_added_t dyn_resource_added, 186 coap_resource_deleted_t resource_deleted, 187 uint32_t save_freq, 188 void *user_data); 189 190 /** 191 * Set up an active subscription for an observe that was previously active 192 * over a coap-server inadvertant restart. 193 * 194 * Only UDP sessions currently supported. 195 * 196 * @param context The context that the session is to be associated with. 197 * @param e_proto The CoAP protocol in use for the session / endpoint. 198 * @param e_listen_addr The IP/port that the endpoint is listening on. 199 * @param s_addr_info Local / Remote IP addresses. ports etc. of previous 200 * session. 201 * @param raw_packet L7 packet as seen on the wire (could be concatenated if 202 * Block1 FETCH is being used). 203 * @param oscore_info Has OSCORE information if OSCORE is protecting the 204 * session or NULL if OSCORE is not in use. 205 * 206 * @return ptr to subscription if success else @c NULL. 207 */ 208 coap_subscription_t *coap_persist_observe_add(coap_context_t *context, 209 coap_proto_t e_proto, 210 const coap_address_t *e_listen_addr, 211 const coap_addr_tuple_t *s_addr_info, 212 const coap_bin_const_t *raw_packet, 213 const coap_bin_const_t *oscore_info); 214 215 /** 216 * Start up persist tracking using the libcoap module. If the files already 217 * exist with saved data, then this information is used in building back 218 * up the persist information. 219 * 220 * @param context The current CoAP context. 221 * @param dyn_resource_save_file File where dynamically created resource 222 * information is stored or NULL if not required. 223 * @param observe_save_file File where observe information is stored or NULL 224 * if not required. 225 * @param obs_cnt_save_file File where resource observe counter information 226 * is stored or NULL if not required. 227 * @param save_freq Frequency of change of observe value for calling 228 * the save observe counter logic. 229 * 230 * @return @c 1 if success else @c 0. 231 */ 232 int coap_persist_startup(coap_context_t *context, 233 const char *dyn_resource_save_file, 234 const char *observe_save_file, 235 const char *obs_cnt_save_file, 236 uint32_t save_freq); 237 238 /** 239 * Stop tracking persist information, leaving the current persist information 240 * in the files defined in coap_persist_startup(). It is then safe to call 241 * coap_free_context() to close the application down cleanly. 242 * 243 * Alternatively, if coap_persist_track_funcs() was called, then this will 244 * disable all the callbacks, as well as making sure that no 4.04 is sent out 245 * for any active observe subscriptions when the resource is deleted after 246 * subsequently calling coap_free_context(). 247 * 248 * @param context The context that tracking information is to be stopped on. 249 */ 250 void coap_persist_stop(coap_context_t *context); 251 252 /** 253 * Sets the current observe number value. 254 255 * @param resource The resource to update. 256 * @param observe_num The value to set the observe number to. 257 */ 258 void coap_persist_set_observe_num(coap_resource_t *resource, 259 uint32_t observe_num); 260 261 /** @} */ 262 263 #endif /* COAP_SUBSCRIBE_H_ */ 264