Provided by: libcoap3_4.3.1-2_amd64 bug

NAME

       coap_resource, coap_resource_init, coap_resource_unknown_init,
       coap_resource_unknown_init2, coap_resource_proxy_uri_init, coap_resource_proxy_uri_init2,
       coap_add_resource, coap_delete_resource, coap_resource_set_mode,
       coap_resource_set_userdata, coap_resource_get_userdata,
       coap_resource_release_userdata_handler, coap_resource_get_uri_path - Work with CoAP
       resources

SYNOPSIS

       #include <coap3/coap.h>

       coap_resource_t *coap_resource_init(coap_str_const_t *uri_path, int flags);

       coap_resource_t *coap_resource_unknown_init(coap_method_handler_t put_handler);

       coap_resource_t *coap_resource_unknown_init2(coap_method_handler_t put_handler, int
       flags);

       coap_resource_t *coap_resource_proxy_uri_init(coap_method_handler_t proxy_handler, size_t
       host_name_count, const char *host_name_list[]);

       coap_resource_t *coap_resource_proxy_uri_init2(coap_method_handler_t proxy_handler, size_t
       host_name_count, const char *host_name_list[], int flags);

       void coap_add_resource(coap_context_t *context, coap_resource_t *resource);

       int coap_delete_resource(coap_context_t *context, coap_resource_t *resource);

       void coap_resource_set_mode(coap_resource_t *resource, int mode);

       void coap_resource_set_userdata(coap_resource_t *resource, void *data);

       void *coap_resource_get_userdata(coap_resource_t *resource);

       void coap_resource_release_userdata_handler(coap_context_t *context,
       coap_resource_release_userdata_handler_t callback);

       coap_str_const_t *coap_resource_get_uri_path(coap_resource_t *resource);

       For specific (D)TLS library support, link with -lcoap-3-notls, -lcoap-3-gnutls,
       -lcoap-3-openssl, -lcoap-3-mbedtls or -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to
       get the default (D)TLS library support.

DESCRIPTION

       CoAP Resources on a CoAP Server need to be created and updated etc. The URI in the request
       packet defines the resource to work with, with possibly the Query referring to a
       sub-resource.

       When resources are configured on the CoAP server, the URI to match against in the request
       packet is specified.

       Callback Handlers are then added to the resource to handle the different request methods.
       See coap_register_request_handler(3) for further information.

       Adding Attributes allows textual information to be added to the resource which can then be
       reported back to any client doing a "GET .well-known/core" request. See coap_add_attr(3)
       for further information.

       If an incoming packet request matches a resource’s URI and Method, then the appropriate
       callback resource handler is invoked to process the packet which should then update a
       suitable response packet for returning back to the requester.

       There is support for handling incoming packets where the URI is unknown (no specific
       resource has been created). This could, for example, happen when a PUT request is trying
       to create a new resource. It is the responsibility of the unknown resource callback
       handler to either create a new resource for the URI or just manage things separately.

       CoAP Observe (RFC 7641) is not supported for unknown resources, so a new resource with GET
       handler must be created by the unknown resource callback handle matching the URI which
       then can be Observable.

       There is support for handling incoming proxy based requests using the Proxy-Uri or
       Proxy-Scheme options.

FUNCTIONS

       Function: coap_resource_init()

       The coap_resource_init() function returns a newly created resource of type coap_resource_t
       * . uri_path specifies the uri string path to match against. Normally there is no need for
       the leading / - e.g. just "full/path/for/resource". flags is used to define whether the
       resource is of type Confirmable Message or Non-Confirmable Message for any "observe"
       responses. See coap_observe(3). flags can be one of the following definitions ored
       together.

       COAP_RESOURCE_FLAGS_NOTIFY_NON          Set the notification message
                                               type to non-confirmable for any
                                               trigggered "observe" responses
                                               with type set to confirmable
                                               every 5 packets as required by
                                               RFC7641 section-4.5.

       COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS   Set the notification message
                                               type to always non-confirmable
                                               for any trigggered "observe"
                                               responses. This should only be
                                               used if a upper layer protocol
                                               requires it.

       COAP_RESOURCE_FLAGS_NOTIFY_CON          Set the notification message
                                               type to confirmable for any
                                               trigggered "observe" responses.

       COAP_RESOURCE_FLAGS_RELEASE_URI         Free off the coap_str_const_t
                                               for uri_path when the resource
                                               is deleted.

       NOTE: The following flags are only tested against if coap_mcast_per_resource() has been
       called. If coap_mcast_per_resource() has not been called, then all resources have
       multicast support, libcoap adds in random delays to the responses, and 4.xx / 5.xx
       responses are dropped.

       COAP_RESOURCE_FLAGS_HAS_MCAST_SUPPORT             This resource has support for
                                                         multicast requests.

       COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_DELAYS          Disable libcoap library from
                                                         adding in delays to multicast
                                                         requests before releasing the
                                                         response back to the client. It
                                                         is then the responsibility of
                                                         the app to delay the responses
                                                         for multicast requests. See
                                                         https://datatracker.ietf.org/doc/html/rfc7252#section-8.2.
                                                         However, the pseudo resource for
                                                         ".well-known/core" always has
                                                         multicast support enabled.

       COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_05   Enable libcoap library suppression of 205 multicast
                                                         responses that are empty (overridden by RFC7969
                                                         No-Response option) for multicast requests.

       COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_XX   Enable libcoap library suppressing 2.xx multicast
                                                         responses (overridden by RFC7969 No-Response option) for
                                                         multicast requests.

       COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_4_XX   Disable libcoap library suppressing 4.xx multicast
                                                         responses (overridden by RFC7969 No-Response option) for
                                                         multicast requests.

       COAP_RESOURCE_FLAGS_LIB_DIS_MCAST_SUPPRESS_5_XX   Disable libcoap library suppressing 5.xx multicast
                                                         responses (overridden by RFC7969 No-Response option) for
                                                         multicast requests.

       NOTE: uri_path, if not 7 bit readable ASCII, binary bytes must be hex encoded according to
       the rules defined in RFC3968 Section 2.1.

       Function: coap_resource_unknown_init()

       The coap_resource_unknown_init() function returns a newly created resource of type
       coap_resource_t *. put_handler is automatically added to the resource to handle PUT
       requests to resources that are unknown. Additional handlers can be added to this resource
       if required.

       Function: coap_resource_unknown_init2()

       The coap_resource_unknown_init2() function returns a newly created resource of type
       coap_resource_t *. put_handler is automatically added to the resource to handle PUT
       requests to resources that are unknown. Additional handlers can be added to this resource
       if required. flags can be zero or more COAP_RESOURCE_FLAGS MCAST definitions.

       Function: coap_resource_proxy_uri_init()

       The coap_resource_proxy_uri_init() function returns a newly created resource of type
       coap_resource_t *. proxy_handler is automatically added to the resource to handle
       PUT/POST/GET etc. requests that use the Proxy-Uri option. There is no need to add explicit
       request type handlers. One or more names by which the proxy is known by (IP address, DNS
       name etc.) must be supplied in the array defined by host_name_list[] which has a count of
       host_name_count. This is used to check whether the current endpoint is the proxy target
       address, or the request has to be passed on to an upstream server.

       Function: coap_resource_proxy_uri_init2()

       The coap_resource_proxy_uri_init2() function returns a newly created resource of type
       coap_resource_t *. proxy_handler is automatically added to the resource to handle
       PUT/POST/GET etc. requests that use the Proxy-Uri option. There is no need to add explicit
       request type handlers. One or more names by which the proxy is known by (IP address, DNS
       name etc.) must be supplied in the array defined by host_name_list[] which has a count of
       host_name_count. This is used to check whether the current endpoint is the proxy target
       address, or the request has to be passed on to an upstream server. flags can be zero or
       more COAP_RESOURCE_FLAGS MCAST definitions.

       Function: coap_add_resource()

       The coap_add_resource() function registers the given resource with the context. The
       resource must have been created by coap_resource_init(), coap_resource_unknown_init(),
       coap_resource_unknown_init2(), coap_resource_proxy_uri_init() or
       coap_resource_proxy_uri_init2(). The storage allocated for the resource will be released
       by coap_delete_resource().

       As the uri_path of the resource has to be unique across all of the resources associated
       with a context, coap_add_resource() will delete any previous resource with the same
       uri_path before adding in the new resource.

       Function: coap_delete_resource()

       The coap_delete_resource() function deletes a resource identified by resource. The context
       parameter is ignored. The storage allocated for that resource is freed, along with any
       attributes associated with the resource.

       Function: coap_resource_set_mode()

       The coap_resource_set_mode() changes the notification message type of resource to the
       given mode which must be one of COAP_RESOURCE_FLAGS_NOTIFY_NON,
       COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS or COAP_RESOURCE_FLAGS_NOTIFY_CON.

       Function: coap_resource_set_userdata()

       The coap_resource_set_userdata() function allows a pointer to user data to be associated
       with a resource that can accessed in any callback that includes resource as a parameter.

       NOTE: data must point to a static, or allocated, block of memory.

       Function: coap_resource_get_userdata()

       The coap_resource_get_userdata() function obtains the user data pointer from the resource
       that had previously been set up by coap_resource_set_userdata().

       Function: coap_resource_release_userdata_handler()

       The coap_resource_release_userdata_handler() function defines the context wide callback
       handler to call to release the allocated user data that has been added to the resource
       using coap_resource_set_userdata() when the resource is deleted. callback can be NULL
       (which is the default) if nothing needs to be freed off.

       Function: coap_resource_get_uri_path()

       The coap_resource_get_uri_path() function is used to obtain the UriPath of the resource
       definion.

RETURN VALUES

       The coap_resource_init(), coap_resource_unknown_init(), coap_resource_unknown_init2(),
       coap_resource_proxy_uri_init() and coap_resource_proxy_uri_init2() functions return a
       newly created resource or NULL if there is a malloc failure.

       The coap_delete_resource() function return 0 on failure (resource not found), 1 on
       success.

       The coap_resource_get_userdata() function returns the value previously set by the
       coap_resource_set_userdata() function or NULL.

       The coap_resource_get_uri_path() function returns the uri_path or NULL if there was a
       failure.

EXAMPLES

       Fixed Resources Set Up

           #include <coap3/coap.h>

           #define INDEX "This is an example server using libcoap\n"

           static void
           hnd_get_index(coap_resource_t *resource, coap_session_t *session,
           const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
             unsigned char buf[3];
             /* Remove (void) definition if variable is used */
             (void)resource;
             (void)session;
             (void)request;
             (void)query;

             coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);

             coap_add_option(response,
                             COAP_OPTION_CONTENT_TYPE,
                             coap_encode_var_safe(buf, sizeof(buf),
                                                  COAP_MEDIATYPE_TEXT_PLAIN),
                             buf);

             coap_add_option(response,
                             COAP_OPTION_MAXAGE,
                             coap_encode_var_safe(buf, sizeof(buf), 0x2ffff), buf);

             coap_add_data(response, strlen(INDEX), (const uint8_t *)INDEX);

             coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
           }

           static void
           hnd_delete_time(coap_resource_t *resource, coap_session_t *session,
           const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
             /* Remove (void) definition if variable is used */
             (void)resource;
             (void)session;
             (void)request;
             (void)query;

             /* .. code .. */

             coap_pdu_set_code(response, COAP_RESPONSE_CODE_DELETED);
           }

           static void
           hnd_get_time(coap_resource_t *resource, coap_session_t *session,
           const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
             /* Remove (void) definition if variable is used */
             (void)resource;
             (void)session;
             (void)request;
             (void)query;
             (void)response;

             /* .. code .. */

             coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
           }

           static void
           hnd_put_time(coap_resource_t *resource, coap_session_t *session,
           const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
             /* Remove (void) definition if variable is used */
             (void)resource;
             (void)session;
             (void)request;
             (void)query;
             (void)response;

             /* .. code .. */

             coap_pdu_set_code(response, COAP_RESPONSE_CODE_CHANGED);
           }

           static void
           init_resources(coap_context_t *ctx) {

             coap_resource_t *r;

             /* Create a resource to return general information */
             r = coap_resource_init(NULL, 0);
             coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get_index);

             /* Document resource for '.well-known/core' request */
             coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
             coap_add_attr(r, coap_make_str_const("title"),
                           coap_make_str_const("\"General Info\""), 0);

             coap_add_resource(ctx, r);

             /* Create a resource to return return or update time */
             r = coap_resource_init(coap_make_str_const("time"),
                                    COAP_RESOURCE_FLAGS_NOTIFY_CON);
             coap_resource_set_get_observable(r, 1);
             coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get_time);
             coap_register_request_handler(r, COAP_REQUEST_PUT, hnd_put_time);
             coap_register_request_handler(r, COAP_REQUEST_DELETE, hnd_delete_time);

             /* Document resource for 'time' request */
             coap_add_attr(r, coap_make_str_const("ct"), coap_make_str_const("0"), 0);
             coap_add_attr(r, coap_make_str_const("title"),
                           coap_make_str_const("\"Internal Clock\""), 0);
             coap_add_attr(r, coap_make_str_const("rt"), coap_make_str_const("\"secs\""),
                           0);
             coap_add_attr(r, coap_make_str_const("if"), coap_make_str_const("\"clock\""),
                           0);

             coap_add_resource(ctx, r);

           }

       Dynamic Resources Set Up

           #include <coap3/coap.h>

           /* Regular DELETE handler - used by resources created by the
            * Unknown Resource PUT handler */

           static void
           hnd_delete(coap_resource_t *resource, coap_session_t *session,
           const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
             /* Remove (void) definition if variable is used */
             (void)session;
             (void)request;
             (void)query;
             (void)response;

             /* .. code .. */

             /* Dynamic resource no longer required - delete it */
             coap_delete_resource(NULL, resource);

             coap_pdu_set_code(response, COAP_RESPONSE_CODE_DELETED);
           }

           /* Regular GET handler - used by resources created by the
            * Unknown Resource PUT handler */

           static void
           hnd_get(coap_resource_t *resource, coap_session_t *session,
           const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {

             coap_str_const_t *get_uri_path;

             /* Remove (void) definition if variable is used */
             (void)resource;
             (void)session;
             (void)request;
             (void)query;

             /*
              * Get the specific resource being requested to determine what the response is
              * The uri_path string is a const pointer
              */

             get_uri_path = coap_resource_get_uri_path(resource);

             /* .. code .. */

             coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
           }

           /* Regular PUT handler - used by resources created by the
            * Unknown Resource PUT handler */

           static void
           hnd_put(coap_resource_t *resource, coap_session_t *session,
           const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
             /* Remove (void) definition if variable is used */
             (void)resource;
             (void)session;
             (void)query;

             coap_string_t *put_uri_path;
             size_t length;
             const uint8_t *data;
             size_t offset;
             size_t total;
             int new_resource = 0;

             /* get the uri_path */
             put_uri_path = coap_get_uri_path(request);
             if (!put_uri_path) {
               coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
               return;
             }
             coap_get_data_large(request, &length, &data, &offset, &total);

             /* .. code .. */

             /* Need to do this as coap_get_uri_path() created it */
             coap_delete_string(put_uri_path);

             if (length + offset < total)
               coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTINUE);
             else if (new_resource)
               coap_pdu_set_code(response, COAP_RESPONSE_CODE_CREATED);
             else
               coap_pdu_set_code(response, COAP_RESPONSE_CODE_CHANGED);
           }

           static int
           check_url_fn(coap_string_t *uri_path, uint8_t code) {
             /* Remove (void) definition if variable is used */
             (void)uri_path;
             (void)code;

             /* Code to determine whether the uri is valid or not */

             return 1;
           }

           /* Unknown Resource PUT handler */

           static void
           hnd_put_unknown(coap_resource_t *resource, coap_session_t *session,
           const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {
             /* Remove (void) definition if variable is used */
             (void)resource;
             coap_pdu_code_t req_code = coap_pdu_get_code(request);

             coap_resource_t *r;
             coap_string_t *uri_path;

             /* get the uri_path - which will get used by coap_resource_init() */
             uri_path = coap_get_uri_path(request);
             if (!uri_path) {
               coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
               return;
             }

             /* Check if new URI Path is valid */
             if (!check_url_fn (uri_path, req_code)) {
               coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
               coap_delete_string(uri_path);
               return;
             }

             /*
              * Create a resource to handle the new URI
              * uri_path will get deleted when the resource is removed
              */
             r = coap_resource_init((coap_str_const_t*)uri_path,
                   COAP_RESOURCE_FLAGS_RELEASE_URI | COAP_RESOURCE_FLAGS_NOTIFY_NON);
             coap_register_request_handler(r, COAP_REQUEST_PUT, hnd_put);
             coap_register_request_handler(r, COAP_REQUEST_DELETE, hnd_delete);
             /* We possibly want to Observe the GETs */
             coap_resource_set_get_observable(r, 1);
             coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get);
             coap_add_resource(coap_session_get_context(session), r);

             /* Do the PUT for this first call */
             hnd_put(r, session, request, query, response);

             return;

           }

           /* Initialize single Unknown Resource PUT handler */

           static void
           init_resources(coap_context_t *ctx) {

             coap_resource_t *r;

             /* Create a resource to handle PUTs to unknown URIs */
             r = coap_resource_unknown_init2(hnd_put_unknown, 0);
             /*
              * Additional handlers can be added - for example
              *  coap_register_request_handler(r, COAP_REQUEST_POST, hnd_post_unknown);
              *  coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get_unknown);
              *  coap_register_request_handler(r, COAP_REQUEST_DELETE, hnd_delete_unknown);
              */
             coap_add_resource(ctx, r);

           }

SEE ALSO

       coap_attribute(3), coap_context(3), coap_handler(3) and coap_observe(3)

FURTHER INFORMATION

       See "RFC7252: The Constrained Application Protocol (CoAP)" for further information.

BUGS

       Please report bugs on the mailing list for libcoap:
       libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
       https://github.com/obgm/libcoap/issues

AUTHORS

       The libcoap project <libcoap-developers@lists.sourceforge.net>