1 /* coap_cache.h -- Caching of CoAP requests 2 * 3 * Copyright (C) 2020 Olaf Bergmann <bergmann@tzi.org> 4 * 5 * SPDX-License-Identifier: BSD-2-Clause 6 * 7 * This file is part of the CoAP library libcoap. Please see 8 * README for terms of use. 9 */ 10 11 /** 12 * @file coap_cache.h 13 * @brief Provides a simple cache request storage for CoAP requests 14 */ 15 16 #ifndef COAP_CACHE_H_ 17 #define COAP_CACHE_H_ 18 19 #include "coap_forward_decls.h" 20 21 /** 22 * @defgroup cache Cache Support 23 * API functions for CoAP Caching 24 * @{ 25 */ 26 27 /** 28 * Callback to free off the app data when the cache-entry is 29 * being deleted / freed off. 30 * 31 * @param data The app data to be freed off. 32 */ 33 typedef void (*coap_cache_app_data_free_callback_t)(void *data); 34 35 typedef enum coap_cache_session_based_t { 36 COAP_CACHE_NOT_SESSION_BASED, 37 COAP_CACHE_IS_SESSION_BASED 38 } coap_cache_session_based_t; 39 40 typedef enum coap_cache_record_pdu_t { 41 COAP_CACHE_NOT_RECORD_PDU, 42 COAP_CACHE_RECORD_PDU 43 } coap_cache_record_pdu_t; 44 45 /** 46 * Calculates a cache-key for the given CoAP PDU. See 47 * https://tools.ietf.org/html/rfc7252#section-5.6 48 * for an explanation of CoAP cache keys. 49 * 50 * Specific CoAP options can be removed from the cache-key. Examples of 51 * this are the BLOCK1 and BLOCK2 options - which make no real sense including 52 * them in a client or server environment, but should be included in a proxy 53 * caching environment where things are cached on a per block basis. 54 * This is done globally by calling the coap_cache_ignore_options() 55 * function. 56 * 57 * NOTE: The returned cache-key needs to be freed off by the caller by 58 * calling coap_cache_delete_key(). 59 * 60 * @param session The session to add into cache-key if @p session_based 61 * is set. 62 * @param pdu The CoAP PDU for which a cache-key is to be 63 * calculated. 64 * @param session_based COAP_CACHE_IS_SESSION_BASED if session based 65 * cache-key, else COAP_CACHE_NOT_SESSION_BASED. 66 * 67 * @return The returned cache-key or @c NULL if failure. 68 */ 69 coap_cache_key_t *coap_cache_derive_key(const coap_session_t *session, 70 const coap_pdu_t *pdu, 71 coap_cache_session_based_t session_based); 72 73 /** 74 * Calculates a cache-key for the given CoAP PDU. See 75 * https://tools.ietf.org/html/rfc7252#section-5.6 76 * for an explanation of CoAP cache keys. 77 * 78 * Specific CoAP options can be removed from the cache-key. Examples of 79 * this are the BLOCK1 and BLOCK2 options - which make no real sense including 80 * them in a client or server environment, but should be included in a proxy 81 * caching environment where things are cached on a per block basis. 82 * This is done individually by specifying @p cache_ignore_count and 83 * @p cache_ignore_options . 84 * 85 * NOTE: The returned cache-key needs to be freed off by the caller by 86 * calling coap_cache_delete_key(). 87 * 88 * @param session The session to add into cache-key if @p session_based 89 * is set. 90 * @param pdu The CoAP PDU for which a cache-key is to be 91 * calculated. 92 * @param session_based COAP_CACHE_IS_SESSION_BASED if session based 93 * cache-key, else COAP_CACHE_NOT_SESSION_BASED. 94 * @param ignore_options The array of options to ignore. 95 * @param ignore_count The number of options to ignore. 96 * 97 * @return The returned cache-key or @c NULL if failure. 98 */ 99 coap_cache_key_t *coap_cache_derive_key_w_ignore(const coap_session_t *session, 100 const coap_pdu_t *pdu, 101 coap_cache_session_based_t session_based, 102 const uint16_t *ignore_options, 103 size_t ignore_count); 104 105 /** 106 * Delete the cache-key. 107 * 108 * @param cache_key The cache-key to delete. 109 */ 110 void coap_delete_cache_key(coap_cache_key_t *cache_key); 111 112 /** 113 * Define the CoAP options that are not to be included when calculating 114 * the cache-key. Options that are defined as Non-Cache and the Observe 115 * option are always ignored. 116 * 117 * @param context The context to save the ignored options information in. 118 * @param options The array of options to ignore. 119 * @param count The number of options to ignore. Use 0 to reset the 120 * options matching. 121 * 122 * @return @return @c 1 if successful, else @c 0. 123 */ 124 int coap_cache_ignore_options(coap_context_t *context, 125 const uint16_t *options, size_t count); 126 127 /** 128 * Create a new cache-entry hash keyed by cache-key derived from the PDU. 129 * 130 * If @p session_based is set, then this cache-entry will get deleted when 131 * the session is freed off. 132 * If @p record_pdu is set, then the copied PDU will get freed off when 133 * this cache-entry is deleted. 134 * 135 * The cache-entry is maintained on a context hash list. 136 * 137 * @param session The session to use to derive the context from. 138 * @param pdu The pdu to use to generate the cache-key. 139 * @param record_pdu COAP_CACHE_RECORD_PDU if to take a copy of the PDU for 140 * later use, else COAP_CACHE_NOT_RECORD_PDU. 141 * @param session_based COAP_CACHE_IS_SESSION_BASED if to associate this 142 * cache-entry with the the session (which is embedded 143 * in the cache-entry), else COAP_CACHE_NOT_SESSION_BASED. 144 * @param idle_time Idle time in seconds before cache-entry is expired. 145 * If set to 0, it does not expire (but will get 146 * deleted if the session is deleted and it is session_based). 147 * 148 * @return The returned cache-key or @c NULL if failure. 149 */ 150 coap_cache_entry_t *coap_new_cache_entry(coap_session_t *session, 151 const coap_pdu_t *pdu, 152 coap_cache_record_pdu_t record_pdu, 153 coap_cache_session_based_t session_based, 154 unsigned int idle_time); 155 156 /** 157 * Remove a cache-entry from the hash list and free off all the appropriate 158 * contents apart from app_data. 159 * 160 * @param context The context to use. 161 * @param cache_entry The cache-entry to remove. 162 */ 163 void coap_delete_cache_entry(coap_context_t *context, 164 coap_cache_entry_t *cache_entry); 165 166 /** 167 * Searches for a cache-entry identified by @p cache_key. This 168 * function returns the corresponding cache-entry or @c NULL 169 * if not found. 170 * 171 * @param context The context to use. 172 * @param cache_key The cache-key to get the hashed coap-entry. 173 * 174 * @return The cache-entry for @p cache_key or @c NULL if not found. 175 */ 176 coap_cache_entry_t *coap_cache_get_by_key(coap_context_t *context, 177 const coap_cache_key_t *cache_key); 178 179 /** 180 * Searches for a cache-entry corresponding to @p pdu. This 181 * function returns the corresponding cache-entry or @c NULL if not 182 * found. 183 * 184 * @param session The session to use. 185 * @param pdu The CoAP request to search for. 186 * @param session_based COAP_CACHE_IS_SESSION_BASED if session based 187 * cache-key to be used, else COAP_CACHE_NOT_SESSION_BASED. 188 * 189 * @return The cache-entry for @p request or @c NULL if not found. 190 */ 191 coap_cache_entry_t *coap_cache_get_by_pdu(coap_session_t *session, 192 const coap_pdu_t *pdu, 193 coap_cache_session_based_t session_based); 194 195 /** 196 * Returns the PDU information stored in the @p coap_cache entry. 197 * 198 * @param cache_entry The CoAP cache entry. 199 * 200 * @return The PDU information stored in the cache_entry or NULL 201 * if the PDU was not initially copied. 202 */ 203 const coap_pdu_t *coap_cache_get_pdu(const coap_cache_entry_t *cache_entry); 204 205 /** 206 * Stores @p data with the given cache entry. This function 207 * overwrites any value that has previously been stored with @p 208 * cache_entry. 209 * 210 * @param cache_entry The CoAP cache entry. 211 * @param data The data pointer to store with wih the cache entry. Note that 212 * this data must be valid during the lifetime of @p cache_entry. 213 * @param callback The callback to call to free off this data when the 214 * cache-entry is deleted, or @c NULL if not required. 215 */ 216 void coap_cache_set_app_data(coap_cache_entry_t *cache_entry, void *data, 217 coap_cache_app_data_free_callback_t callback); 218 219 /** 220 * Returns any application-specific data that has been stored with @p 221 * cache_entry using the function coap_cache_set_app_data(). This function will 222 * return @c NULL if no data has been stored. 223 * 224 * @param cache_entry The CoAP cache entry. 225 * 226 * @return The data pointer previously stored or @c NULL if no data stored. 227 */ 228 void *coap_cache_get_app_data(const coap_cache_entry_t *cache_entry); 229 230 /** @} */ 231 232 #endif /* COAP_CACHE_H */ 233