reverse-proxy: Support for .well-known/core being passed

Move get_wkc_len() into hnd_get_wellknown_lkd() to simply document how
hnd_get_wellknown() should be done.

Revert out coap_register_print_wellknown_callback() changes as no
longer needed.

include/coap3/coap_net.h

@@ -37,7 +37,6 @@
 #include "coap_pdu.h"
 #include "coap_session.h"
 #include "coap_debug.h"
-#include "coap_resource.h"
 
 /**
  * @ingroup application_api
@@ -608,28 +607,6 @@ void coap_context_set_app_data(coap_context_t *context, void *data);
  */
 void *coap_context_get_app_data(const coap_context_t *context);
 
-/**
- * Definition of get .well-known/core string callback function
- */
-typedef coap_print_status_t (*coap_print_wellknown_t)(coap_context_t *context,
-                                                      coap_session_t *session,
-                                                      const coap_pdu_t *request,
-                                                      unsigned char *buf,
-                                                      size_t *buflen,
-                                                      size_t offset,
-                                                      const coap_string_t *query_filter);
-
-/**
- * Defines the callback that is called when the .well-known/core resource is requested.
- *
- * @param context  The context to associate the print_wellknown callback with
- * @param callback The callback to invoke when the .well-known/core resource is requested
- *                 or NULL to unregister a previously registered callback.
- *
- */
-void coap_register_print_wellknown_callback(coap_context_t *context,
-                                            coap_print_wellknown_t callback);
-
 /**@}*/
 
 /**

include/coap3/coap_net_internal.h

@@ -59,8 +59,6 @@ struct coap_context_t {
   coap_resource_release_userdata_handler_t release_userdata;
   /**< function to  release user_data
        when resource is deleted */
-  coap_print_wellknown_t print_wellknown_userdata; /**< custom response for
-                                                        well-known/core resource */
 #endif /* COAP_SERVER_SUPPORT */
 
 #if COAP_ASYNC_SUPPORT

include/coap3/coap_resource.h

@@ -150,6 +150,13 @@ typedef void (*coap_method_handler_t)(coap_resource_t *resource,
  */
 #define COAP_RESOURCE_FLAGS_OSCORE_ONLY 0x400
 
+/**
+ * Define this when invoking *coap_resource_unknown_init2*() if .well-known/core
+ * is to be passed to the unknown URI handler rather than processed locally.
+ * Used for easily passing on a request as a reverse-proxy request.
+ */
+#define COAP_RESOURCE_HANDLE_WELLKNOWN_CORE 0x800
+
 /**
  * Creates a new resource object and initializes the link field to the string
  * @p uri_path. This function returns the new coap_resource_t object.
@@ -497,8 +504,9 @@ coap_print_status_t coap_print_link(const coap_resource_t *resource,
 /**
  * Prints the names of all known resources for @p context to @p buf. This function
  * sets @p buflen to the number of bytes actually written and returns
- * @c 1 on success. On error, the value in @p buflen is undefined and
- * the return value will be @c 0.
+ * @c COAP_PRINT_STATUS_ERROR on error. On error, the value in @p buflen is undefined.
+ * Otherwise, the lower 28 bits are set to the number of bytes that have actually
+ * been written. COAP_PRINT_STATUS_TRUNC is set when the output has been truncated.
  *
  * @param context The context with the resource map.
  * @param buf     The buffer to write the result.

include/coap3/coap_resource_internal.h

@@ -185,8 +185,11 @@ void coap_delete_attr(coap_attr_t *attr);
 /**
  * Prints the names of all known resources for @p context to @p buf. This function
  * sets @p buflen to the number of bytes actually written and returns
- * @c 1 on success. On error, the value in @p buflen is undefined and
- * the return value will be @c 0.
+ * @c COAP_PRINT_STATUS_ERROR on error. On error, the value in @p buflen is undefined.
+ * Otherwise, the lower 28 bits are set to the number of bytes that have actually
+ * been written. COAP_PRINT_STATUS_TRUNC is set when the output has been truncated.
+ *
+ * Note: This function must be called in the locked state.
  *
  * @param context The context with the resource map.
  * @param buf     The buffer to write the result.

libcoap-3.map

@@ -202,7 +202,6 @@ global:
   coap_register_option;
   coap_register_ping_handler;
   coap_register_pong_handler;
-  coap_register_print_wellknown_callback;
   coap_register_request_handler;
   coap_register_response_handler;
   coap_resize_binary;

libcoap-3.sym

@@ -200,7 +200,6 @@ coap_register_nack_handler
 coap_register_option
 coap_register_ping_handler
 coap_register_pong_handler
-coap_register_print_wellknown_callback
 coap_register_request_handler
 coap_register_response_handler
 coap_resize_binary

man/coap_handler.txt.in

@@ -16,8 +16,7 @@ coap_register_response_handler,
 coap_register_nack_handler,
 coap_register_ping_handler,
 coap_register_pong_handler,
-coap_register_event_handler,
-coap_register_print_wellknown_callback
+coap_register_event_handler
 - Work with CoAP handlers
 
 SYNOPSIS
@@ -42,9 +41,6 @@ coap_pong_handler_t _handler_)*;
 *void coap_register_event_handler(coap_context_t *_context_,
 coap_event_handler_t _handler_)*;
 
-*void coap_register_print_wellknown_callback(coap_context_t *context,
-coap_print_wellknown_t callback);*
-
 For specific (D)TLS library support, link with
 *-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
 *-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*,
@@ -392,39 +388,6 @@ typedef enum {
 } coap_event_t;
 ----
 
-*Function: coap_register_print_wellknown_callback()*
-
-The *coap_register_print_wellknown_callback*() function registers a
-callback function that is called instead of the default *coap_print_wellknown*()
-function when the implicit .well-known/core resource is requested.
-
-The callback function prototype is defined as:
-[source, c]
-----
-/**
- * @param context The context with the resource map.
- * @param session The CoAP session.
- * @param buf The buffer to write the result.
- * @param buflen Must be initialized to the maximum length of buf and will be
- *			 	 set to the length of the well-known response on return.
- * @param offset The offset in bytes where the output shall start and is shifted
- * 				 accordingly with the characters that have been processed. This
- * 				 parameter is used to support the block option.
- * @param query_filter A filter query according to <a href="http://tools.ietf.org/html/draft-ietf-core-link-format-11#section-4.1">Link Format</a>
- *
- * @return COAP_PRINT_STATUS_ERROR on error. Otherwise, the lower 28 bits are
- *         set to the number of bytes that have actually been written to
- *         @p buf. COAP_PRINT_STATUS_TRUNC is set when the output has been
- *         truncated.
- */
-typedef coap_print_status_t (*coap_print_wellknown_t)(coap_context_t *context,
-                                                      coap_session_t *session,
-                                                      unsigned char *buf,
-                                                      size_t *buflen,
-                                                      size_t offset,
-                                                      const coap_string_t *query_filter);
-----
-
 EXAMPLES
 --------
 *GET Resource Callback Handler*

man/coap_resource.txt.in

@@ -155,13 +155,22 @@ to the request handler.
 *COAP_RESOURCE_FLAGS_OSCORE_ONLY*::
 Define this resource as an OSCORE enabled access only.
 
+*COAP_RESOURCE_HANDLE_WELLKNOWN_CORE*::
+Define this when invoking *coap_resource_unknown_init2*() if .well-known/core
+is to be passed to the unknown URI handler rather than processed locally.
+Used for easily passing on a request as a reverse-proxy request.
+
 *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.
 
 *NOTE:* The pseudo resource for ".well-known/core" always has multicast
-support enabled and is not configurable.
+support enabled and is not configurable. It is possible for a server to
+create a resource for ".well-known/core" that can then control the
+multicast support and the provided GET request handler can call
+*coap_print_wellknown*() to produce the same information as the pseudo
+resource.
 
 [horizontal]
 *COAP_RESOURCE_FLAGS_HAS_MCAST_SUPPORT*::
@@ -173,7 +182,7 @@ sending the response back to the client.  It is then the responsibility of
 the app to delay the responses for multicast requests. See
 "https://rfc-editor.org/rfc/rfc7252#section-8.2[RFC7252 8.2. Request/Response
 Layer]".
- However, the pseudo resource for ".well-known/core" always has multicast
+However, the pseudo resource for ".well-known/core" always has multicast
 support enabled.
 
 *COAP_RESOURCE_FLAGS_LIB_ENA_MCAST_SUPPRESS_2_05*::
@@ -302,6 +311,9 @@ identified by the unique string _uri_path_ associated with _context_.
 The *coap_print_wellknown*() function prints the names of all known resources
 of the given _context_ into _buf_ which has a maximum size of _buflen_. The
 first _offset_ bytes are skipped from the output to handle block transfers.
+Setting _offset_ to 0 means the entire (matching) information is output.
+Setting _offset_ to UINT_MAX skips, but calculates the size of, the (matching)
+output.
 The _query_filter_ is usually defined by the CoAP Uri-Query options as a query.
 
 RETURN VALUES