1 /* 2 * coap_subscribe_internal.h -- Structures, Enums & Functions that are not 3 * exposed to application programming 4 * 5 * Copyright (C) 2010-2023 Olaf Bergmann <bergmann@tzi.org> 6 * 7 * SPDX-License-Identifier: BSD-2-Clause 8 * 9 * This file is part of the CoAP library libcoap. Please see README for terms 10 * of use. 11 */ 12 13 /** 14 * @file coap_subscribe_internal.h 15 * @brief CoAP subscribe internal information 16 */ 17 18 #ifndef COAP_SUBSCRIBE_INTERNAL_H_ 19 #define COAP_SUBSCRIBE_INTERNAL_H_ 20 21 #include "coap_internal.h" 22 23 #if COAP_SERVER_SUPPORT 24 25 /** 26 * @ingroup internal_api 27 * @defgroup subscribe_internal Observe Subscription 28 * Internal API for handling CoAP Observe Subscriptions (RFC7641) 29 * @{ 30 */ 31 32 /** 33 * Number of notifications that may be sent non-confirmable before a confirmable 34 * message is sent to detect if observers are alive. The maximum allowed value 35 * here is @c 255. 36 */ 37 #ifndef COAP_OBS_MAX_NON 38 #define COAP_OBS_MAX_NON 5 39 #endif /* COAP_OBS_MAX_NON */ 40 #if COAP_OBS_MAX_NON > 255 41 #error COAP_OBS_MAX_NON is too large 42 #endif /* COAP_OBS_MAX_NON > 255 */ 43 44 /** 45 * Number of different confirmable notifications that may fail (i.e. those 46 * that have hit MAX_RETRANSMIT multiple times) before an observer is removed. 47 * The maximum value for COAP_OBS_MAX_FAIL is @c 255. 48 */ 49 #ifndef COAP_OBS_MAX_FAIL 50 #define COAP_OBS_MAX_FAIL 1 51 #endif /* COAP_OBS_MAX_FAIL */ 52 #if COAP_OBS_MAX_FAIL > 255 53 #error COAP_OBS_MAX_FAIL is too large 54 #endif /* COAP_OBS_MAX_FAIL > 255 */ 55 56 /** Subscriber information */ 57 struct coap_subscription_t { 58 struct coap_subscription_t *next; /**< next element in linked list */ 59 struct coap_session_t *session; /**< subscriber session */ 60 61 uint8_t non_cnt; /**< up to 255 non-confirmable notifies allowed */ 62 uint8_t fail_cnt; /**< up to 255 confirmable notifies can fail */ 63 uint8_t dirty; /**< set if the notification temporarily could not be 64 * sent (in that case, the resource's partially 65 * dirty flag is set too) */ 66 coap_cache_key_t *cache_key; /** cache_key to identify requester */ 67 coap_pdu_t *pdu; /**< PDU to use for additional requests */ 68 }; 69 70 void coap_subscription_init(coap_subscription_t *); 71 72 /** 73 * Handles a failed observe notify. 74 * 75 * @param context The context holding the resource. 76 * @param session The session that the observe notify failed on. 77 * @param token The token used when the observe notify failed. 78 */ 79 void coap_handle_failed_notify(coap_context_t *context, 80 coap_session_t *session, 81 const coap_bin_const_t *token); 82 83 /** 84 * Checks all known resources to see if they are dirty and then notifies 85 * subscribed observers. 86 * 87 * @param context The context to check for dirty resources. 88 */ 89 void coap_check_notify(coap_context_t *context); 90 91 /** 92 * Adds the specified peer as observer for @p resource. The subscription is 93 * identified by the given @p token. This function returns the registered 94 * subscription information if the @p observer has been added, or @c NULL on 95 * error. 96 * 97 * @param resource The observed resource. 98 * @param session The observer's session 99 * @param token The token that identifies this subscription. 100 * @param pdu The requesting pdu. 101 * 102 * @return A pointer to the added/updated subscription 103 * information or @c NULL on error. 104 */ 105 coap_subscription_t *coap_add_observer(coap_resource_t *resource, 106 coap_session_t *session, 107 const coap_bin_const_t *token, 108 const coap_pdu_t *pdu); 109 110 /** 111 * Returns a subscription object for given @p peer. 112 * 113 * @param resource The observed resource. 114 * @param session The observer's session 115 * @param token The token that identifies this subscription or @c NULL for 116 * any token. 117 * @return A valid subscription if exists or @c NULL otherwise. 118 */ 119 coap_subscription_t *coap_find_observer(coap_resource_t *resource, 120 coap_session_t *session, 121 const coap_bin_const_t *token); 122 123 /** 124 * Flags that data is ready to be sent to observers. 125 * 126 * @param context The CoAP context to use. 127 * @param session The observer's session 128 * @param token The corresponding token that has been used for the 129 * subscription. 130 */ 131 void coap_touch_observer(coap_context_t *context, 132 coap_session_t *session, 133 const coap_bin_const_t *token); 134 135 /** 136 * Removes any subscription for @p observer from @p resource and releases the 137 * allocated storage. The result is @c 1 if an observation relationship with @p 138 * observer and @p token existed, @c 0 otherwise. 139 * 140 * @param resource The observed resource. 141 * @param session The observer's session. 142 * @param token The token that identifies this subscription or @c NULL for 143 * any token. 144 * @return @c 1 if the observer has been deleted, @c 0 otherwise. 145 */ 146 int coap_delete_observer(coap_resource_t *resource, 147 coap_session_t *session, 148 const coap_bin_const_t *token); 149 150 /** 151 * Removes any subscription for @p session and releases the allocated storage. 152 * 153 * @param context The CoAP context to use. 154 * @param session The observer's session. 155 */ 156 void coap_delete_observers(coap_context_t *context, coap_session_t *session); 157 158 /** 159 * Close down persist tracking, releasing any memory used. 160 * 161 * @param context The current CoAP context. 162 */ 163 void coap_persist_cleanup(coap_context_t *context); 164 165 /** @} */ 166 167 #endif /* COAP_SERVER_SUPPORT */ 168 #endif /* COAP_SUBSCRIBE_INTERNAL_H_ */ 169