1 /* 2 * coap_subscribe_internal.h -- Structures, Enums & Functions that are not 3 * exposed to application programming 4 * 5 * Copyright (C) 2010-2021 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 /** 22 * @defgroup subscribe_internal Observe Subscription (Internal) 23 * CoAP Observe Subscription Structures, Enums and Functions that are not 24 * exposed to applications 25 * @{ 26 */ 27 28 #ifndef COAP_OBS_MAX_NON 29 /** 30 * Number of notifications that may be sent non-confirmable before a confirmable 31 * message is sent to detect if observers are alive. The maximum allowed value 32 * here is @c 15. 33 */ 34 #define COAP_OBS_MAX_NON 5 35 #endif /* COAP_OBS_MAX_NON */ 36 37 #ifndef COAP_OBS_MAX_FAIL 38 /** 39 * Number of confirmable notifications that may fail (i.e. time out without 40 * being ACKed) before an observer is removed. The maximum value for 41 * COAP_OBS_MAX_FAIL is @c 3. 42 */ 43 #define COAP_OBS_MAX_FAIL 3 44 #endif /* COAP_OBS_MAX_FAIL */ 45 46 /** Subscriber information */ 47 struct coap_subscription_t { 48 struct coap_subscription_t *next; /**< next element in linked list */ 49 struct coap_session_t *session; /**< subscriber session */ 50 51 unsigned int non_cnt:4; /**< up to 15 non-confirmable notifies allowed */ 52 unsigned int fail_cnt:2; /**< up to 3 confirmable notifies can fail */ 53 unsigned int dirty:1; /**< set if the notification temporarily could not be 54 * sent (in that case, the resource's partially 55 * dirty flag is set too) */ 56 coap_cache_key_t *cache_key; /** cache_key to identify requester */ 57 coap_pdu_t *pdu; /**< PDU to use for additional requests */ 58 }; 59 60 void coap_subscription_init(coap_subscription_t *); 61 62 /** 63 * Handles a failed observe notify. 64 * 65 * @param context The context holding the resource. 66 * @param session The session that the observe notify failed on. 67 * @param token The token used when the observe notify failed. 68 */ 69 void 70 coap_handle_failed_notify(coap_context_t *context, 71 coap_session_t *session, 72 const coap_binary_t *token); 73 74 /** 75 * Checks all known resources to see if they are dirty and then notifies 76 * subscribed observers. 77 * 78 * @param context The context to check for dirty resources. 79 */ 80 void coap_check_notify(coap_context_t *context); 81 82 /** 83 * Adds the specified peer as observer for @p resource. The subscription is 84 * identified by the given @p token. This function returns the registered 85 * subscription information if the @p observer has been added, or @c NULL on 86 * error. 87 * 88 * @param resource The observed resource. 89 * @param session The observer's session 90 * @param token The token that identifies this subscription. 91 * @param pdu The requesting pdu. 92 * 93 * @return A pointer to the added/updated subscription 94 * information or @c NULL on error. 95 */ 96 coap_subscription_t *coap_add_observer(coap_resource_t *resource, 97 coap_session_t *session, 98 const coap_binary_t *token, 99 const coap_pdu_t *pdu); 100 101 /** 102 * Returns a subscription object for given @p peer. 103 * 104 * @param resource The observed resource. 105 * @param session The observer's session 106 * @param token The token that identifies this subscription or @c NULL for 107 * any token. 108 * @return A valid subscription if exists or @c NULL otherwise. 109 */ 110 coap_subscription_t *coap_find_observer(coap_resource_t *resource, 111 coap_session_t *session, 112 const coap_binary_t *token); 113 114 /** 115 * Flags that data is ready to be sent to observers. 116 * 117 * @param context The CoAP context to use. 118 * @param session The observer's session 119 * @param token The corresponding token that has been used for the 120 * subscription. 121 */ 122 void coap_touch_observer(coap_context_t *context, 123 coap_session_t *session, 124 const coap_binary_t *token); 125 126 /** 127 * Removes any subscription for @p observer from @p resource and releases the 128 * allocated storage. The result is @c 1 if an observation relationship with @p 129 * observer and @p token existed, @c 0 otherwise. 130 * 131 * @param resource The observed resource. 132 * @param session The observer's session. 133 * @param token The token that identifies this subscription or @c NULL for 134 * any token. 135 * @return @c 1 if the observer has been deleted, @c 0 otherwise. 136 */ 137 int coap_delete_observer(coap_resource_t *resource, 138 coap_session_t *session, 139 const coap_binary_t *token); 140 141 /** 142 * Removes any subscription for @p session and releases the allocated storage. 143 * 144 * @param context The CoAP context to use. 145 * @param session The observer's session. 146 */ 147 void coap_delete_observers(coap_context_t *context, coap_session_t *session); 148 149 /** @} */ 150 151 #endif /* COAP_SUBSCRIBE_INTERNAL_H_ */ 152