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.

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_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.

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.

void	coap_delete_cache_key (coap_cache_key_t *cache_key)
	Delete the cache-key.

COAP_API 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.

COAP_API 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.

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.

COAP_API 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`.

COAP_API 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`.

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.

COAP_DEPRECATED void	coap_cache_set_app_data (coap_cache_entry_t cache_entry, void data, coap_app_data_free_callback_t callback)
	Stores `data` with the given cache entry.

COAP_API void *	coap_cache_set_app_data2 (coap_cache_entry_t cache_entry, void data, coap_app_data_free_callback_t callback)
	Stores `data` with the given cache_entry, returning the previously stored value or NULL.

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().

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

data	The app data to be freed off.

Definition at line 39 of file coap_cache.h.

◆ coap_cache_record_pdu_t

typedef enum coap_cache_record_pdu_t coap_cache_record_pdu_t

◆ coap_cache_session_based_t

typedef enum coap_cache_session_based_t coap_cache_session_based_t

Enumeration Type Documentation

◆ coap_cache_record_pdu_t

enum coap_cache_record_pdu_t

Enumerator
COAP_CACHE_NOT_RECORD_PDU
COAP_CACHE_RECORD_PDU

Definition at line 46 of file coap_cache.h.

◆ coap_cache_session_based_t

enum coap_cache_session_based_t

Enumerator
COAP_CACHE_NOT_SESSION_BASED
COAP_CACHE_IS_SESSION_BASED

Definition at line 41 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

session	The session to add into cache-key if `session_based` is set.
pdu	The CoAP PDU for which a cache-key is to be calculated.
session_based	COAP_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

session	The session to add into cache-key if `session_based` is set.
pdu	The CoAP PDU for which a cache-key is to be calculated.
session_based	COAP_CACHE_IS_SESSION_BASED if session based cache-key, else COAP_CACHE_NOT_SESSION_BASED.
ignore_options	The array of options to ignore.
ignore_count	The 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_entry The CoAP cache entry.

Returns: The data pointer previously stored or NULL if no data stored.

◆ coap_cache_get_by_key()

COAP_API 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

context	The context to use.
cache_key	The 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_API 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

session	The session to use.
pdu	The CoAP request to search for.
session_based	COAP_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_entry The 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()

COAP_API 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

context	The context to save the ignored options information in.
options	The array of options to ignore.
count	The number of options to ignore. Use 0 to reset the options matching.

Returns: 1 if successful, else 0.

◆ coap_cache_set_app_data()

COAP_DEPRECATED void coap_cache_set_app_data	(	coap_cache_entry_t *	cache_entry,
		void *	data,
		coap_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.

Deprecated:: Use coap_cache_set_app_data2() instead.

Parameters

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

◆ coap_cache_set_app_data2()

COAP_API void * coap_cache_set_app_data2	(	coap_cache_entry_t *	cache_entry,
		void *	data,
		coap_app_data_free_callback_t	callback
	)

Stores data with the given cache_entry, returning the previously stored value or NULL.

The data callback can be defined if the data is to be released when the cache_entry is deleted.

Note: It is the responsibility of the caller to free off (if appropriate) any returned data.

Parameters

cache_entry	The CoAP cache entry.
data	The pointer to the data to store or NULL to just clear out the previous data.
callback	The optional release call-back for data on cache_entry removal or NULL.

Returns: The previous data (if any) stored in the cache_entry.

◆ 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

context	The context to use.
cache_entry	The 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_key The cache-key to delete.

◆ coap_new_cache_entry()

COAP_API 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

session	The session to use to derive the context from.
pdu	The pdu to use to generate the cache-key.
record_pdu	COAP_CACHE_RECORD_PDU if to take a copy of the PDU for later use, else COAP_CACHE_NOT_RECORD_PDU.
session_based	COAP_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_time	Idle 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.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ coap_cache_app_data_free_callback_t

◆ coap_cache_record_pdu_t

◆ coap_cache_session_based_t

Enumeration Type Documentation

◆ coap_cache_record_pdu_t

◆ coap_cache_session_based_t

Function Documentation

◆ coap_cache_derive_key()

◆ coap_cache_derive_key_w_ignore()

◆ coap_cache_get_app_data()

◆ coap_cache_get_by_key()

◆ coap_cache_get_by_pdu()

◆ coap_cache_get_pdu()

◆ coap_cache_ignore_options()

◆ coap_cache_set_app_data()

◆ coap_cache_set_app_data2()

◆ coap_delete_cache_entry()

◆ coap_delete_cache_key()

◆ coap_new_cache_entry()