libcoap 4.3.4
Cache Support

API for Cache-Key and Cache-Entry. More...

+ Collaboration diagram for Cache Support:

Typedefs

typedef void(* coap_cache_app_data_free_callback_t) (void *data)
 Callback to free off the app data when the cache-entry is being deleted / freed off. More...
 
typedef enum coap_cache_session_based_t coap_cache_session_based_t
 
typedef enum coap_cache_record_pdu_t coap_cache_record_pdu_t
 

Enumerations

enum  coap_cache_session_based_t { COAP_CACHE_NOT_SESSION_BASED , COAP_CACHE_IS_SESSION_BASED }
 
enum  coap_cache_record_pdu_t { COAP_CACHE_NOT_RECORD_PDU , COAP_CACHE_RECORD_PDU }
 

Functions

coap_cache_key_tcoap_cache_derive_key (const coap_session_t *session, const coap_pdu_t *pdu, coap_cache_session_based_t session_based)
 Calculates a cache-key for the given CoAP PDU. More...
 
coap_cache_key_tcoap_cache_derive_key_w_ignore (const coap_session_t *session, const coap_pdu_t *pdu, coap_cache_session_based_t session_based, const uint16_t *ignore_options, size_t ignore_count)
 Calculates a cache-key for the given CoAP PDU. More...
 
void coap_delete_cache_key (coap_cache_key_t *cache_key)
 Delete the cache-key. More...
 
int coap_cache_ignore_options (coap_context_t *context, const uint16_t *options, size_t count)
 Define the CoAP options that are not to be included when calculating the cache-key. More...
 
coap_cache_entry_tcoap_new_cache_entry (coap_session_t *session, const coap_pdu_t *pdu, coap_cache_record_pdu_t record_pdu, coap_cache_session_based_t session_based, unsigned int idle_time)
 Create a new cache-entry hash keyed by cache-key derived from the PDU. More...
 
void coap_delete_cache_entry (coap_context_t *context, coap_cache_entry_t *cache_entry)
 Remove a cache-entry from the hash list and free off all the appropriate contents apart from app_data. More...
 
coap_cache_entry_tcoap_cache_get_by_key (coap_context_t *context, const coap_cache_key_t *cache_key)
 Searches for a cache-entry identified by cache_key. More...
 
coap_cache_entry_tcoap_cache_get_by_pdu (coap_session_t *session, const coap_pdu_t *pdu, coap_cache_session_based_t session_based)
 Searches for a cache-entry corresponding to pdu. More...
 
const coap_pdu_tcoap_cache_get_pdu (const coap_cache_entry_t *cache_entry)
 Returns the PDU information stored in the coap_cache entry. More...
 
void coap_cache_set_app_data (coap_cache_entry_t *cache_entry, void *data, coap_cache_app_data_free_callback_t callback)
 Stores data with the given cache entry. More...
 
void * coap_cache_get_app_data (const coap_cache_entry_t *cache_entry)
 Returns any application-specific data that has been stored with cache_entry using the function coap_cache_set_app_data(). More...
 

Detailed Description

API for Cache-Key and Cache-Entry.

See https://rfc-editor.org/rfc/rfc7252#section-5.4.2

Typedef Documentation

◆ coap_cache_app_data_free_callback_t

typedef void(* coap_cache_app_data_free_callback_t) (void *data)

Callback to free off the app data when the cache-entry is being deleted / freed off.

Parameters
dataThe app data to be freed off.

Definition at line 35 of file coap_cache.h.

◆ coap_cache_record_pdu_t

◆ coap_cache_session_based_t

Enumeration Type Documentation

◆ coap_cache_record_pdu_t

Enumerator
COAP_CACHE_NOT_RECORD_PDU 
COAP_CACHE_RECORD_PDU 

Definition at line 42 of file coap_cache.h.

◆ coap_cache_session_based_t

Enumerator
COAP_CACHE_NOT_SESSION_BASED 
COAP_CACHE_IS_SESSION_BASED 

Definition at line 37 of file coap_cache.h.

Function Documentation

◆ coap_cache_derive_key()

coap_cache_key_t * coap_cache_derive_key ( const coap_session_t session,
const coap_pdu_t pdu,
coap_cache_session_based_t  session_based 
)

Calculates a cache-key for the given CoAP PDU.

See https://rfc-editor.org/rfc/rfc7252#section-5.4.2 for an explanation of CoAP cache keys.

Specific CoAP options can be removed from the cache-key. Examples of this are the Block1 and Block2 options - which make no real sense including them in a client or server environment, but should be included in a proxy caching environment where things are cached on a per block basis. This is done globally by calling the coap_cache_ignore_options() function.

NOTE: The returned cache-key needs to be freed off by the caller by calling coap_cache_delete_key().

Parameters
sessionThe session to add into cache-key if session_based is set.
pduThe CoAP PDU for which a cache-key is to be calculated.
session_basedCOAP_CACHE_IS_SESSION_BASED if session based cache-key, else COAP_CACHE_NOT_SESSION_BASED.
Returns
The returned cache-key or NULL if failure.

◆ coap_cache_derive_key_w_ignore()

coap_cache_key_t * coap_cache_derive_key_w_ignore ( const coap_session_t session,
const coap_pdu_t pdu,
coap_cache_session_based_t  session_based,
const uint16_t *  ignore_options,
size_t  ignore_count 
)

Calculates a cache-key for the given CoAP PDU.

See https://rfc-editor.org/rfc/rfc7252#section-5.4.2 for an explanation of CoAP cache keys.

Specific CoAP options can be removed from the cache-key. Examples of this are the Block1 and Block2 options - which make no real sense including them in a client or server environment, but should be included in a proxy caching environment where things are cached on a per block basis. This is done individually by specifying cache_ignore_count and cache_ignore_options .

NOTE: The returned cache-key needs to be freed off by the caller by calling coap_cache_delete_key().

Parameters
sessionThe session to add into cache-key if session_based is set.
pduThe CoAP PDU for which a cache-key is to be calculated.
session_basedCOAP_CACHE_IS_SESSION_BASED if session based cache-key, else COAP_CACHE_NOT_SESSION_BASED.
ignore_optionsThe array of options to ignore.
ignore_countThe number of options to ignore.
Returns
The returned cache-key or NULL if failure.

◆ coap_cache_get_app_data()

void * coap_cache_get_app_data ( const coap_cache_entry_t cache_entry)

Returns any application-specific data that has been stored with cache_entry using the function coap_cache_set_app_data().

This function will return NULL if no data has been stored.

Parameters
cache_entryThe CoAP cache entry.
Returns
The data pointer previously stored or NULL if no data stored.

◆ coap_cache_get_by_key()

coap_cache_entry_t * coap_cache_get_by_key ( coap_context_t context,
const coap_cache_key_t cache_key 
)

Searches for a cache-entry identified by cache_key.

This function returns the corresponding cache-entry or NULL if not found.

Parameters
contextThe context to use.
cache_keyThe cache-key to get the hashed coap-entry.
Returns
The cache-entry for cache_key or NULL if not found.

◆ coap_cache_get_by_pdu()

coap_cache_entry_t * coap_cache_get_by_pdu ( coap_session_t session,
const coap_pdu_t pdu,
coap_cache_session_based_t  session_based 
)

Searches for a cache-entry corresponding to pdu.

This function returns the corresponding cache-entry or NULL if not found.

Parameters
sessionThe session to use.
pduThe CoAP request to search for.
session_basedCOAP_CACHE_IS_SESSION_BASED if session based cache-key to be used, else COAP_CACHE_NOT_SESSION_BASED.
Returns
The cache-entry for request or NULL if not found.

◆ coap_cache_get_pdu()

const coap_pdu_t * coap_cache_get_pdu ( const coap_cache_entry_t cache_entry)

Returns the PDU information stored in the coap_cache entry.

Parameters
cache_entryThe CoAP cache entry.
Returns
The PDU information stored in the cache_entry or NULL if the PDU was not initially copied.

◆ coap_cache_ignore_options()

int coap_cache_ignore_options ( coap_context_t context,
const uint16_t *  options,
size_t  count 
)

Define the CoAP options that are not to be included when calculating the cache-key.

Options that are defined as Non-Cache and the Observe option are always ignored.

Parameters
contextThe context to save the ignored options information in.
optionsThe array of options to ignore.
countThe number of options to ignore. Use 0 to reset the options matching.
Returns
1 if successful, else 0.

◆ coap_cache_set_app_data()

void coap_cache_set_app_data ( coap_cache_entry_t cache_entry,
void *  data,
coap_cache_app_data_free_callback_t  callback 
)

Stores data with the given cache entry.

This function overwrites any value that has previously been stored with cache_entry.

Parameters
cache_entryThe CoAP cache entry.
dataThe data pointer to store with wih the cache entry. Note that this data must be valid during the lifetime of cache_entry.
callbackThe callback to call to free off this data when the cache-entry is deleted, or NULL if not required.

◆ coap_delete_cache_entry()

void coap_delete_cache_entry ( coap_context_t context,
coap_cache_entry_t cache_entry 
)

Remove a cache-entry from the hash list and free off all the appropriate contents apart from app_data.

Parameters
contextThe context to use.
cache_entryThe cache-entry to remove.
+ Here is the caller graph for this function:

◆ coap_delete_cache_key()

void coap_delete_cache_key ( coap_cache_key_t cache_key)

Delete the cache-key.

Parameters
cache_keyThe cache-key to delete.

◆ coap_new_cache_entry()

coap_cache_entry_t * coap_new_cache_entry ( coap_session_t session,
const coap_pdu_t pdu,
coap_cache_record_pdu_t  record_pdu,
coap_cache_session_based_t  session_based,
unsigned int  idle_time 
)

Create a new cache-entry hash keyed by cache-key derived from the PDU.

If session_based is set, then this cache-entry will get deleted when the session is freed off. If record_pdu is set, then the copied PDU will get freed off when this cache-entry is deleted.

The cache-entry is maintained on a context hash list.

Parameters
sessionThe session to use to derive the context from.
pduThe pdu to use to generate the cache-key.
record_pduCOAP_CACHE_RECORD_PDU if to take a copy of the PDU for later use, else COAP_CACHE_NOT_RECORD_PDU.
session_basedCOAP_CACHE_IS_SESSION_BASED if to associate this cache-entry with the the session (which is embedded in the cache-entry), else COAP_CACHE_NOT_SESSION_BASED.
idle_timeIdle time in seconds before cache-entry is expired. If set to 0, it does not expire (but will get deleted if the session is deleted and it is session_based).
Returns
The returned cache-key or NULL if failure.