1 /* 2 * resource.h -- generic resource handling 3 * 4 * Copyright (C) 2010,2011,2014-2021 Olaf Bergmann <bergmann@tzi.org> 5 * 6 * SPDX-License-Identifier: BSD-2-Clause 7 * 8 * This file is part of the CoAP library libcoap. Please see README for terms 9 * of use. 10 */ 11 12 /** 13 * @file resource.h 14 * @brief Generic resource handling 15 */ 16 17 #ifndef COAP_RESOURCE_H_ 18 #define COAP_RESOURCE_H_ 19 20 #ifndef COAP_RESOURCE_CHECK_TIME 21 /** The interval in seconds to check if resources have changed. */ 22 #define COAP_RESOURCE_CHECK_TIME 2 23 #endif /* COAP_RESOURCE_CHECK_TIME */ 24 25 #include "async.h" 26 #include "block.h" 27 #include "str.h" 28 #include "pdu.h" 29 #include "net.h" 30 #include "subscribe.h" 31 32 /** 33 * @defgroup coap_resource Resource Configuraton 34 * API functions for setting up resources 35 * @{ 36 */ 37 38 /** 39 * Definition of message handler function 40 */ 41 typedef void (*coap_method_handler_t) 42 (coap_resource_t *, 43 coap_session_t *, 44 const coap_pdu_t * /* request */, 45 const coap_string_t * /* query string */, 46 coap_pdu_t * /* response */); 47 48 #define COAP_ATTR_FLAGS_RELEASE_NAME 0x1 49 #define COAP_ATTR_FLAGS_RELEASE_VALUE 0x2 50 51 /** The URI passed to coap_resource_init() is free'd by coap_delete_resource(). */ 52 #define COAP_RESOURCE_FLAGS_RELEASE_URI 0x1 53 54 /** 55 * Notifications will be sent non-confirmable by default. RFC 7641 Section 4.5 56 * https://tools.ietf.org/html/rfc7641#section-4.5 57 * Libcoap will always send every fifth packet as confirmable. 58 */ 59 #define COAP_RESOURCE_FLAGS_NOTIFY_NON 0x0 60 61 /** 62 * Notifications will be sent confirmable. RFC 7641 Section 4.5 63 * https://tools.ietf.org/html/rfc7641#section-4.5 64 */ 65 #define COAP_RESOURCE_FLAGS_NOTIFY_CON 0x2 66 67 /** 68 * Notifications will always be sent non-confirmable. This is in 69 * violation of RFC 7641 Section 4.5 70 * https://tools.ietf.org/html/rfc7641#section-4.5 71 * but required by the DOTS signal channel protocol which needs to operate in 72 * lossy DDoS attack environments. 73 * https://tools.ietf.org/html/rfc8782#section-4.4.2.1 74 */ 75 #define COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS 0x4 76 77 /** 78 * Creates a new resource object and initializes the link field to the string 79 * @p uri_path. This function returns the new coap_resource_t object. 80 * 81 * If the string is going to be freed off by coap_delete_resource() when 82 * COAP_RESOURCE_FLAGS_RELEASE_URI is set in @p flags, then either the 's' 83 * variable of coap_str_const_t has to point to constant text, or point to data 84 * within the allocated coap_str_const_t parameter. 85 * 86 * @param uri_path The string URI path of the new resource. 87 * @param flags Flags for memory management (in particular release of 88 * memory). Possible values:@n 89 * 90 * COAP_RESOURCE_FLAGS_RELEASE_URI 91 * If this flag is set, the URI passed to 92 * coap_resource_init() is free'd by 93 * coap_delete_resource()@n 94 * 95 * COAP_RESOURCE_FLAGS_NOTIFY_CON 96 * If this flag is set, coap-observe notifications 97 * will be sent confirmable by default.@n 98 * 99 * COAP_RESOURCE_FLAGS_NOTIFY_NON (default) 100 * If this flag is set, coap-observe notifications 101 * will be sent non-confirmable by default.@n 102 * 103 * If flags is set to 0 then the 104 * COAP_RESOURCE_FLAGS_NOTIFY_NON is considered. 105 * 106 * @return A pointer to the new object or @c NULL on error. 107 */ 108 coap_resource_t *coap_resource_init(coap_str_const_t *uri_path, 109 int flags); 110 111 112 /** 113 * Creates a new resource object for the unknown resource handler with support 114 * for PUT. 115 * 116 * In the same way that additional handlers can be added to the resource 117 * created by coap_resource_init() by using coap_register_handler(), POST, 118 * GET, DELETE etc. handlers can be added to this resource. It is the 119 * responsibility of the application to manage the unknown resources by either 120 * creating new resources with coap_resource_init() (which should have a 121 * DELETE handler specified for the resource removal) or by maintaining an 122 * active resource list. 123 * 124 * Note: There can only be one unknown resource handler per context - attaching 125 * a new one overrides the previous definition. 126 * 127 * Note: It is not possible to observe the unknown resource with a GET request 128 * - a separate resource needs to be reated by the PUT (or POST) handler, 129 * and make that resource observable. 130 * 131 * This function returns the new coap_resource_t object. 132 * 133 * @param put_handler The PUT handler to register with @p resource for 134 * unknown Uri-Path. 135 * 136 * @return A pointer to the new object or @c NULL on error. 137 */ 138 coap_resource_t *coap_resource_unknown_init(coap_method_handler_t put_handler); 139 140 /** 141 * Creates a new resource object for handling proxy URIs. 142 * This function returns the new coap_resource_t object. 143 * 144 * Note: There can only be one proxy resource handler per context - attaching 145 * a new one overrides the previous definition. 146 * 147 * @param handler The PUT/POST/GET etc. handler that handles all request types. 148 * @param host_name_count The number of provided host_name_list entries. A 149 * minimum of 1 must be provided. 150 * @param host_name_list Array of depth host_name_count names that this proxy 151 * is known by. 152 * 153 * @return A pointer to the new object or @c NULL on error. 154 */ 155 coap_resource_t *coap_resource_proxy_uri_init(coap_method_handler_t handler, 156 size_t host_name_count, const char *host_name_list[]); 157 158 /** 159 * Returns the resource identified by the unique string @p uri_path. If no 160 * resource was found, this function returns @c NULL. 161 * 162 * @param context The context to look for this resource. 163 * @param uri_path The unique string uri of the resource. 164 * 165 * @return A pointer to the resource or @c NULL if not found. 166 */ 167 coap_resource_t *coap_get_resource_from_uri_path(coap_context_t *context, 168 coap_str_const_t *uri_path); 169 170 /** 171 * Get the uri_path from a @p resource. 172 * 173 * @param resource The CoAP resource to check. 174 * 175 * @return The uri_path if it exists or @c NULL otherwise. 176 */ 177 coap_str_const_t* coap_resource_get_uri_path(coap_resource_t *resource); 178 179 /** 180 * Sets the notification message type of resource @p resource to given 181 * @p mode 182 183 * @param resource The resource to update. 184 * @param mode Must be one of @c COAP_RESOURCE_FLAGS_NOTIFY_NON 185 * or @c COAP_RESOURCE_FLAGS_NOTIFY_CON. 186 */ 187 void coap_resource_set_mode(coap_resource_t *resource, int mode); 188 189 /** 190 * Sets the user_data. The user_data is exclusively used by the library-user 191 * and can be used as user defined context in the handler functions. 192 * 193 * @param resource Resource to attach the data to 194 * @param data Data to attach to the user_data field. This pointer is 195 * only used for storage, the data remains under user control 196 */ 197 void coap_resource_set_userdata(coap_resource_t *resource, void *data); 198 199 /** 200 * Gets the user_data. The user_data is exclusively used by the library-user 201 * and can be used as context in the handler functions. 202 * 203 * @param resource Resource to retrieve the user_data from 204 * 205 * @return The user_data pointer 206 */ 207 void *coap_resource_get_userdata(coap_resource_t *resource); 208 209 /** 210 * Definition of release resource user_data callback function 211 */ 212 typedef void (*coap_resource_release_userdata_handler_t)(void *user_data); 213 214 /** 215 * Defines the context wide callback to use to when the resource is deleted 216 * to release the data held in the resource's user_data. 217 * 218 * @param context The context to associate the release callback with 219 * @param callback The callback to invoke when the resource is deleted or NULL 220 * 221 */ 222 void coap_resource_release_userdata_handler(coap_context_t *context, 223 coap_resource_release_userdata_handler_t callback); 224 225 /** 226 * Registers the given @p resource for @p context. The resource must have been 227 * created by coap_resource_init() or coap_resource_unknown_init(), the 228 * storage allocated for the resource will be released by coap_delete_resource(). 229 * 230 * @param context The context to use. 231 * @param resource The resource to store. 232 */ 233 void coap_add_resource(coap_context_t *context, coap_resource_t *resource); 234 235 /** 236 * Deletes a resource identified by @p resource. The storage allocated for that 237 * resource is freed, and removed from the context. 238 * 239 * @param context The context where the resources are stored. 240 * @param resource The resource to delete. 241 * 242 * @return @c 1 if the resource was found (and destroyed), 243 * @c 0 otherwise. 244 */ 245 int coap_delete_resource(coap_context_t *context, coap_resource_t *resource); 246 247 /** 248 * Registers the specified @p handler as message handler for the request type @p 249 * method 250 * 251 * @param resource The resource for which the handler shall be registered. 252 * @param method The CoAP request method to handle. 253 * @param handler The handler to register with @p resource. 254 */ 255 void coap_register_handler(coap_resource_t *resource, 256 coap_request_t method, 257 coap_method_handler_t handler); 258 259 /** 260 * Registers a new attribute with the given @p resource. As the 261 * attribute's coap_str_const_ fields will point to @p name and @p value the 262 * caller must ensure that these pointers are valid during the 263 * attribute's lifetime. 264 265 * If the @p name and/or @p value string is going to be freed off at attribute 266 * removal time by the setting of COAP_ATTR_FLAGS_RELEASE_NAME or 267 * COAP_ATTR_FLAGS_RELEASE_VALUE in @p flags, then either the 's' 268 * variable of coap_str_const_t has to point to constant text, or point to data 269 * within the allocated coap_str_const_t parameter. 270 * 271 * @param resource The resource to register the attribute with. 272 * @param name The attribute's name as a string. 273 * @param value The attribute's value as a string or @c NULL if none. 274 * @param flags Flags for memory management (in particular release of 275 * memory). Possible values:@n 276 * 277 * COAP_ATTR_FLAGS_RELEASE_NAME 278 * If this flag is set, the name passed to 279 * coap_add_attr_release() is free'd 280 * when the attribute is deleted@n 281 * 282 * COAP_ATTR_FLAGS_RELEASE_VALUE 283 * If this flag is set, the value passed to 284 * coap_add_attr_release() is free'd 285 * when the attribute is deleted@n 286 * 287 * @return A pointer to the new attribute or @c NULL on error. 288 */ 289 coap_attr_t *coap_add_attr(coap_resource_t *resource, 290 coap_str_const_t *name, 291 coap_str_const_t *value, 292 int flags); 293 294 /** 295 * Returns @p resource's coap_attr_t object with given @p name if found, @c NULL 296 * otherwise. 297 * 298 * @param resource The resource to search for attribute @p name. 299 * @param name Name of the requested attribute as a string. 300 * @return The first attribute with specified @p name or @c NULL if none 301 * was found. 302 */ 303 coap_attr_t *coap_find_attr(coap_resource_t *resource, 304 coap_str_const_t *name); 305 306 /** 307 * Returns @p attribute's value. 308 * 309 * @param attribute Pointer to attribute. 310 * 311 * @return Attribute's value or @c NULL. 312 */ 313 coap_str_const_t *coap_attr_get_value(coap_attr_t *attribute); 314 315 /** 316 * Status word to encode the result of conditional print or copy operations such 317 * as coap_print_link(). The lower 28 bits of coap_print_status_t are used to 318 * encode the number of characters that has actually been printed, bits 28 to 31 319 * encode the status. When COAP_PRINT_STATUS_ERROR is set, an error occurred 320 * during output. In this case, the other bits are undefined. 321 * COAP_PRINT_STATUS_TRUNC indicates that the output is truncated, i.e. the 322 * printing would have exceeded the current buffer. 323 */ 324 typedef unsigned int coap_print_status_t; 325 326 #define COAP_PRINT_STATUS_MASK 0xF0000000u 327 #define COAP_PRINT_OUTPUT_LENGTH(v) ((v) & ~COAP_PRINT_STATUS_MASK) 328 #define COAP_PRINT_STATUS_ERROR 0x80000000u 329 #define COAP_PRINT_STATUS_TRUNC 0x40000000u 330 331 /** 332 * Writes a description of this resource in link-format to given text buffer. @p 333 * len must be initialized to the maximum length of @p buf and will be set to 334 * the number of characters actually written if successful. This function 335 * returns @c 1 on success or @c 0 on error. 336 * 337 * @param resource The resource to describe. 338 * @param buf The output buffer to write the description to. 339 * @param len Must be initialized to the length of @p buf and 340 * will be set to the length of the printed link description. 341 * @param offset The offset within the resource description where to 342 * start writing into @p buf. This is useful for dealing 343 * with the Block2 option. @p offset is updated during 344 * output as it is consumed. 345 * 346 * @return If COAP_PRINT_STATUS_ERROR is set, an error occured. Otherwise, 347 * the lower 28 bits will indicate the number of characters that 348 * have actually been output into @p buffer. The flag 349 * COAP_PRINT_STATUS_TRUNC indicates that the output has been 350 * truncated. 351 */ 352 coap_print_status_t coap_print_link(const coap_resource_t *resource, 353 unsigned char *buf, 354 size_t *len, 355 size_t *offset); 356 357 /** @} */ 358 359 /** 360 * Returns the resource identified by the unique string @p uri_path. If no 361 * resource was found, this function returns @c NULL. 362 * 363 * @param context The context to look for this resource. 364 * @param uri_path The unique string uri of the resource. 365 * 366 * @return A pointer to the resource or @c NULL if not found. 367 */ 368 coap_resource_t *coap_get_resource_from_uri_path(coap_context_t *context, 369 coap_str_const_t *uri_path); 370 371 /** 372 * @deprecated use coap_resource_notify_observers() instead. 373 */ 374 COAP_DEPRECATED int 375 coap_resource_set_dirty(coap_resource_t *r, 376 const coap_string_t *query); 377 378 #endif /* COAP_RESOURCE_H_ */ 379