1 /* 2 * coap_event.h -- libcoap Event API 3 * 4 * Copyright (C) 2016 Olaf Bergmann <bergmann@tzi.org> 5 * Copyright (C) 2021-2023 Jon Shallow <supjps-libcoap@jpshallow.com> 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_event.h 15 * @brief Event handling 16 */ 17 18 #ifndef COAP_EVENT_H_ 19 #define COAP_EVENT_H_ 20 21 #include "libcoap.h" 22 23 /** 24 * @ingroup application_api 25 * @defgroup events Event Handling 26 * API for event delivery from lower-layer library functions. 27 * @{ 28 */ 29 30 /** 31 * Scalar type to represent different events, e.g. DTLS events or 32 * retransmission timeouts. 33 */ 34 typedef enum { 35 /* 36 * (D)TLS events for COAP_PROTO_DTLS and COAP_PROTO_TLS 37 */ 38 /** Triggerred when (D)TLS session closed */ 39 COAP_EVENT_DTLS_CLOSED = 0x0000, 40 /** Triggered when (D)TLS session connected */ 41 COAP_EVENT_DTLS_CONNECTED = 0x01DE, 42 /** Triggered when (D)TLS session renegotiated */ 43 COAP_EVENT_DTLS_RENEGOTIATE = 0x01DF, 44 /** Triggered when (D)TLS error occurs */ 45 COAP_EVENT_DTLS_ERROR = 0x0200, 46 47 /* 48 * TCP events for COAP_PROTO_TCP and COAP_PROTO_TLS 49 */ 50 /** Triggered when TCP layer connects */ 51 COAP_EVENT_TCP_CONNECTED = 0x1001, 52 /** Triggered when TCP layer is closed */ 53 COAP_EVENT_TCP_CLOSED = 0x1002, 54 /** Triggered when TCP layer fails for some reason */ 55 COAP_EVENT_TCP_FAILED = 0x1003, 56 57 /* 58 * CSM exchange events for reliable protocols only 59 */ 60 /** Triggered when TCP layer completes exchange of CSM information */ 61 COAP_EVENT_SESSION_CONNECTED = 0x2001, 62 /** Triggered when TCP layer closes following exchange of CSM information */ 63 COAP_EVENT_SESSION_CLOSED = 0x2002, 64 /** Triggered when TCP layer fails following exchange of CSM information */ 65 COAP_EVENT_SESSION_FAILED = 0x2003, 66 67 /* 68 * (Q-)Block errors 69 */ 70 /** Triggered when not all of a large body has been received */ 71 COAP_EVENT_PARTIAL_BLOCK = 0x3001, 72 /** Triggered when not all of a large body has been transmitted */ 73 COAP_EVENT_XMIT_BLOCK_FAIL = 0x3002, 74 75 /* 76 * Server session events 77 */ 78 /** 79 * Called in the CoAP IO loop if a new *server-side* session is created due 80 * to an incoming connection. 81 * 82 * Note that the session might not be a fully established connection yet, 83 * it might also refer to, e.g., a DTLS session in a handshake stage. 84 */ 85 COAP_EVENT_SERVER_SESSION_NEW = 0x4001, 86 87 /** 88 * Called in the CoAP IO loop if a server session is deleted (e.g., due to 89 * inactivity or because the maximum number of idle sessions was exceeded). 90 * 91 * The session will still contain valid data when the event handler is 92 * called. 93 */ 94 COAP_EVENT_SERVER_SESSION_DEL = 0x4002, 95 96 /* 97 * Message receive and transmit events 98 */ 99 /** Triggered when badly formatted packet received */ 100 COAP_EVENT_BAD_PACKET = 0x5001, 101 /** Triggered when a message is retransmitted */ 102 COAP_EVENT_MSG_RETRANSMITTED = 0x5002, 103 104 /* 105 * OSCORE events 106 */ 107 /** Triggered when there is an OSCORE decryption failure */ 108 COAP_EVENT_OSCORE_DECRYPTION_FAILURE = 0x6001, 109 /** Triggered when trying to use OSCORE to decrypt, but it is not enabled */ 110 COAP_EVENT_OSCORE_NOT_ENABLED, 111 /** Triggered when there is no OSCORE encrypted payload provided */ 112 COAP_EVENT_OSCORE_NO_PROTECTED_PAYLOAD, 113 /** Triggered when there is no OSCORE security definition found */ 114 COAP_EVENT_OSCORE_NO_SECURITY, 115 /** Triggered when there is an OSCORE internal error i.e malloc failed */ 116 COAP_EVENT_OSCORE_INTERNAL_ERROR, 117 /** Triggered when there is an OSCORE decode of OSCORE option failure */ 118 COAP_EVENT_OSCORE_DECODE_ERROR, 119 /* 120 * WebSocket events 121 */ 122 /** Triggered when there is an oversize WebSockets packet */ 123 COAP_EVENT_WS_PACKET_SIZE = 0x7001, 124 /** Triggered when the WebSockets layer is up */ 125 COAP_EVENT_WS_CONNECTED, 126 /** Triggered when the WebSockets layer is closed */ 127 COAP_EVENT_WS_CLOSED, 128 /* 129 * Keepalive events 130 */ 131 /** Triggered when no response to a keep alive (ping) packet */ 132 COAP_EVENT_KEEPALIVE_FAILURE = 0x8001, 133 } coap_event_t; 134 135 /** 136 * Type for event handler functions that can be registered with a CoAP 137 * context using the function coap_set_event_handler(). When called by 138 * the library, the first argument will be the current coap_session_t object 139 * which is associated with the original CoAP context. The second parameter 140 * is the event type. 141 */ 142 typedef int (*coap_event_handler_t)(coap_session_t *session, 143 const coap_event_t event); 144 145 /** 146 * Registers the function @p hnd as callback for events from the given 147 * CoAP context @p context. Any event handler that has previously been 148 * registered with @p context will be overwritten by this operation. 149 * 150 * @param context The CoAP context to register the event handler with. 151 * @param hnd The event handler to be registered. @c NULL if to be 152 * de-registered. 153 */ 154 void coap_register_event_handler(coap_context_t *context, 155 coap_event_handler_t hnd); 156 157 /** @} */ 158 159 /** 160 * Registers the function @p hnd as callback for events from the given 161 * CoAP context @p context. Any event handler that has previously been 162 * registered with @p context will be overwritten by this operation. 163 * 164 * @deprecated Use coap_register_event_handler() instead. 165 * 166 * @param context The CoAP context to register the event handler with. 167 * @param hnd The event handler to be registered. 168 */ 169 COAP_DEPRECATED 170 void coap_set_event_handler(coap_context_t *context, 171 coap_event_handler_t hnd); 172 173 /** 174 * Clears the event handler registered with @p context. 175 * 176 * @deprecated Use coap_register_event_handler() instead with NULL for handler. 177 * 178 * @param context The CoAP context whose event handler is to be removed. 179 */ 180 COAP_DEPRECATED 181 void coap_clear_event_handler(coap_context_t *context); 182 183 #endif /* COAP_EVENT_H */ 184