From 17aaa81b5ad32e5d0238d4b8f9097736a78a46d0 Mon Sep 17 00:00:00 2001 From: Jon Shallow Date: Fri, 20 Aug 2021 19:37:12 +0100 Subject: [PATCH] Caching: Highlight requirements ignoring certain CoAP Options When using the cache logic to build up the data of a body transferred over several blocks, the BLOCK options must be excluded when deriving the cache key. Update documentation reminding the user of the need to do this. --- examples/coap-server.c | 6 ++++++ man/coap_cache.txt.in | 18 +++++++++++++----- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/examples/coap-server.c b/examples/coap-server.c index b2ffebe8..65565420 100644 --- a/examples/coap-server.c +++ b/examples/coap-server.c @@ -495,6 +495,9 @@ hnd_put_example_data(coap_resource_t *resource, * o In a request carrying a Block1 Option, to indicate the current * estimate the client has of the total size of the resource * representation, measured in bytes ("size indication"). + * + * coap_cache_ignore_options() must have previously been called with at + * least COAP_OPTION_BLOCK1 set as the option value will change per block. */ coap_cache_entry_t *cache_entry = coap_cache_get_by_pdu(session, request, @@ -1429,6 +1432,9 @@ hnd_put(coap_resource_t *resource, * o In a request carrying a Block1 Option, to indicate the current * estimate the client has of the total size of the resource * representation, measured in bytes ("size indication"). + * + * coap_cache_ignore_options() must have previously been called with at + * least COAP_OPTION_BLOCK1 set as the option value will change per block. */ coap_cache_entry_t *cache_entry = coap_cache_get_by_pdu(session, request, diff --git a/man/coap_cache.txt.in b/man/coap_cache.txt.in index ee00f340..3980c462 100644 --- a/man/coap_cache.txt.in +++ b/man/coap_cache.txt.in @@ -145,7 +145,8 @@ time not being used before it gets deleted. If _idle_timeout_ is set to Entry is returned, or NULL on error. The *coap_delete_cache_entry*() function can be used to delete the Cache Entry -_cache_entry_. This will remove the Cache Entry from the hash lookup list and +_cache_entry_ held within _context_. This will remove the Cache Entry from +the hash lookup list and free off any internally held data. If the Cache Entry is session based, then it will automatically get deleted when the session is freed off or when the idle timeout expires. @@ -155,14 +156,18 @@ _context_ environment that has Cache Key _cache_key_. Returns NULL if the Cache Key was not found. The *coap_cache_get_by_pdu*() function will locate the Cache Entry held in the -_context_ environment that has a Cache Key derived from the _pdu_ and -whether _session_based_ or not. +_session_ environment that has a Cache Key derived from the _pdu_ and +whether _session_based_ or not. This function calls *coap_cache_derive_key*() +internally, and so normally *coap_cache_ignore_options*() would have +previously been called with COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2 to +ignore the values held within these options. The *coap_cache_get_pdu*() function returns the PDU that was stored with the Cache Entry when it was created with *coap_new_cache_entry*() and _record_pdu_ -was set. If a PDU was not initially stored, NULL is returned. + +was set to COAP_CACHE_RECORD_PDU. If a PDU was not initially stored, NULL is +returned. + *NOTE:* A copy of the returned PDU must be taken for using in sending a CoAP -packet. +packet using *coap_pdu_duplicate*(). The *coap_cache_set_app_data*() function is used to associate _data_ with the _cache_entry_. If _callback_ is not NULL, it points to a function to free off @@ -248,6 +253,9 @@ hnd_put_example_data(coap_context_t *ctx, * o In a request carrying a Block1 Option, to indicate the current * estimate the client has of the total size of the resource * representation, measured in bytes ("size indication"). + * + * coap_cache_ignore_options() must have previously been called with at + * least COAP_OPTION_BLOCK1 set as the option value will change per block. */ coap_cache_entry_t *cache_entry = coap_cache_get_by_pdu(session, request,