request-tag: Add in support for sending Request-Tag option with every…

… request

If multiple requests (apart from DELETE) are sent at the same time to
the same resource, and the responses need to make use of the Block2 option,
there is no way for the server to differentiate between which block set a
request (if there is a resource content change) is for unless a Request-Tag
is used.

Disable this functionality by setting COAP_BLOCK_NO_PREEMPTIVE_RTAG when
calling coap_context_set_block_mode().  Request-Tag will still be sent
with any request that includes Block1 option.

examples/coap-client.c

@@ -556,7 +556,7 @@ usage(const char *program, const char *version) {
      "\t-K interval\tSend a ping after interval seconds of inactivity\n"
      "\t-L value\tSum of one or more COAP_BLOCK_* flag valuess for block\n"
      "\t       \t\thandling methods. Default is 1 (COAP_BLOCK_USE_LIBCOAP)\n"
-     "\t       \t\t(Sum of one or more of 1,2,4 and 8)\n"
+     "\t       \t\t(Sum of one or more of 1,2 and 16)\n"
      "\t-N     \t\tSend NON-confirmable message\n"
      "\t-O num,text\tAdd option num with contents text to request. If the\n"
      "\t       \t\ttext begins with 0x, then the hex text (two [0-9a-f] per\n"

include/coap3/block.h

@@ -60,6 +60,7 @@ typedef struct {
 
 #define COAP_BLOCK_USE_LIBCOAP  0x01 /* Use libcoap to do block requests */
 #define COAP_BLOCK_SINGLE_BODY  0x02 /* Deliver the data as a single body */
+#define COAP_BLOCK_NO_PREEMPTIVE_RTAG 0x10 /* Don't use pre-emptive Request-Tags */
 
 /**
  * Returns the value of the least significant byte of a Block option @p opt.

include/coap3/coap_block_internal.h

@@ -70,8 +70,11 @@ typedef struct coap_l_block2_t {
   coap_resource_t *resource; /**< associated resource */
   coap_string_t *query;  /**< Associated query for the resource */
   uint64_t etag;         /**< ETag value */
-  coap_time_t maxage_expire; /**< When this entry expires */
   coap_pdu_code_t request_method; /**< Method used to request this data */
+  uint8_t rtag_set;      /**< Set if RTag is in receive PDU */
+  uint8_t rtag_length;   /**< RTag length */
+  uint8_t rtag[8];       /**< RTag for block checking */
+  coap_time_t maxage_expire; /**< When this entry expires */
 } coap_l_block2_t;
 
 /**
@@ -192,6 +195,11 @@ int coap_handle_request_put_block(coap_context_t *context,
                                   coap_string_t *query,
                                   coap_method_handler_t h,
                                   int *added_block);
+
+coap_lg_xmit_t * coap_find_lg_xmit_response(const coap_session_t *session,
+                                            const coap_pdu_t *request,
+                                            const coap_resource_t *resource,
+                                            const coap_string_t *query);
 #endif /* COAP_SERVER_SUPPORT */
 
 #if COAP_CLIENT_SUPPORT
@@ -216,15 +224,17 @@ int coap_block_check_lg_xmit_timeouts(coap_session_t *session,
  * The function checks that the code in a newly formed lg_xmit created by
  * coap_add_data_large_response() is updated.
  *
- * @param session  The session
- * @param response The response PDU to to check
- * @param resource The requested resource
- * @param query    The requested query
- * @param request_method The requested method
+ * @param session  The session.
+ * @param request  The request PDU to to check.
+ * @param response The response PDU to to update with response->code.
+ * @param resource The requested resource.
+ * @param query    The requested query.
  */
-void coap_check_code_lg_xmit(coap_session_t *session, coap_pdu_t *response,
-                             coap_resource_t *resource, coap_string_t *query,
-                             coap_pdu_code_t request_method);
+void coap_check_code_lg_xmit(const coap_session_t *session,
+                             const coap_pdu_t *request,
+                             coap_pdu_t *response,
+                             const coap_resource_t *resource,
+                             const coap_string_t *query);
 
 /** @} */
 

man/coap-client.txt.in

@@ -143,8 +143,9 @@ OPTIONS - General
    Sum of one or more COAP_BLOCK_* flag values for different block handling
    methods. Default is 1 (COAP_BLOCK_USE_LIBCOAP).
 
-     COAP_BLOCK_USE_LIBCOAP  1
-     COAP_BLOCK_SINGLE_BODY  2
+     COAP_BLOCK_USE_LIBCOAP         1
+     COAP_BLOCK_SINGLE_BODY         2
+     COAP_BLOCK_NO_PREEMPTIVE_RTAG 16
 
 *-N* ::
    Send NON-confirmable message. If option *-N* is not specified, a

man/coap_block.txt.in

@@ -138,40 +138,49 @@ session _block_mode_.
 
 [source, c]
 ----
-#define COAP_BLOCK_USE_LIBCOAP  0x01 /* Use libcoap to do block requests */
-#define COAP_BLOCK_SINGLE_BODY  0x02 /* Deliver the data as a single body */
+#define COAP_BLOCK_USE_LIBCOAP        0x01 /* Use libcoap to do block requests */
+#define COAP_BLOCK_SINGLE_BODY        0x02 /* Deliver the data as a single body */
+#define COAP_BLOCK_NO_PREEMPTIVE_RTAG 0x10 /* Don't use pre-emptive Request-Tags */
 ----
 _block_mode_ is an or'd set of zero or more COAP_BLOCK_* definitions.
 
-If COAP_BLOCK_USE_LIBCOAP is not set, then everything works as per Option 1
+If *COAP_BLOCK_USE_LIBCOAP* is not set, then everything works as per Option 1
 above.
 
-If COAP_BLOCK_SINGLE_BODY is set, then the entire body of data is presented to
+If *COAP_BLOCK_SINGLE_BODY* is set, then the entire body of data is presented to
 the receiving handler, otherwise each individual block is presented on arrival.
 To obtain the data, length and current offset, *coap_get_data_large*() must
 be used instead of *coap_get_data*().  It may be appropriate not to set
-COAP_BLOCK_SINGLE_BODY if there are RAM limitations.
+*COAP_BLOCK_SINGLE_BODY* if there are RAM limitations.
 
 *NOTE:* It is the responsibility of the receiving application to re-assemble
 the _data_ as appropriate (e.g., using *coap_block_build_body*()) if
-COAP_BLOCK_SINGLE_BODY is not set.
+*COAP_BLOCK_SINGLE_BODY* is not set.
 
-*NOTE:* If COAP_BLOCK_SINGLE_BODY is not set, then the CoAP server on receiving
+*NOTE:* If *COAP_BLOCK_SINGLE_BODY* is not set, then the CoAP server on
+receiving
 request data that is split over multiple data blocks must respond with
 COAP_RESPONSE_CODE_CONTINUE 2.31 (Continue) response code if the received data
 is not for the final block, otherwise a COAP_RESPONSE_CODE_CREATED 2.01
 (Created) or COAP_RESPONSE_CODE_CHANGED 2.04 (Changed) should be returned.
 
-If COAP_BLOCK_USE_LIBCOAP is set, then any PDUs presented to the application
+If *COAP_BLOCK_USE_LIBCOAP* is set, then any PDUs presented to the application
 handlers will get the tokens set back to the initiating token so that requests
 can be matched with responses even if different tokens had to be used for the
-series of packet interchanges.  Furthermore, if COAP_BLOCK_SINGLE_BODY is set,
+series of packet interchanges.  Furthermore, if *COAP_BLOCK_SINGLE_BODY* is set,
 then the PDU that presents the entire body will have any BlockX option removed.
 
-*NOTE:* COAP_BLOCK_USE_LIBCOAP must be set if libcoap is to do all the
+*NOTE:* *COAP_BLOCK_USE_LIBCOAP* must be set if libcoap is to do all the
 block tracking and requesting, otherwise the application will have to do all
 of this work (the default if *coap_context_set_block_mode*() is not called).
 
+If *COAP_BLOCK_NO_PREEMPTIVE_RTAG* is set, then Request-Tag options are only
+sent when a large amount of data is being sent to the server using the Block1
+option.  Otherwise, a Request-Tag option is sent with any request (apart from
+DELETE) on the off chance that there may be multiple Block2 based
+responses for multiple requests to the same resource that need to be
+differentiated between.
+
 *Function: coap_add_data_large_request()*
 
 The *coap_add_data_large_request*() function is similar to *coap_add_data*(),
@@ -517,9 +526,9 @@ FURTHER INFORMATION
 -------------------
 See
 
-"RFC7252: The Constrained Application Protocol (CoAP)"
+"https://tools.ietf.org/html/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]"
 
-"RFC7959: Block-Wise Transfers in the Constrained Application Protocol (CoAP)"
+"https://tools.ietf.org/html/rfc7959[RFC7959: Block-Wise Transfers in the Constrained Application Protocol (CoAP)]"
 
 for further information.