libcoap 4.3.2rc2

Typedefs | Enumerations | Functions
Cache Support
Application API

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

## 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_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. More...
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. 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_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. 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_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`. More...
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`. More...
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. 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

  data | The app data to be freed off.

Definition at line 35 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 42 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 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

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

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

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

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