Merge pull request #744 from mrdeep1/cache_caution

Caching: Highlight requirements ignoring certain CoAP Options

examples/coap-server.c

@@ -498,6 +498,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,
@@ -1436,6 +1439,9 @@ hnd_put_post(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,

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,