1 /* 2 * coap_event.h -- libcoap Event API 3 * 4 * Copyright (C) 2016 Olaf Bergmann <bergmann@tzi.org> 5 * 6 * SPDX-License-Identifier: BSD-2-Clause 7 * 8 * This file is part of the CoAP library libcoap. Please see README for terms 9 * of use. 10 */ 11 12 #ifndef COAP_EVENT_H_ 13 #define COAP_EVENT_H_ 14 15 #include "libcoap.h" 16 17 /** 18 * @defgroup events Event API 19 * API functions for event delivery from lower-layer library functions. 20 * @{ 21 */ 22 23 /** 24 * Scalar type to represent different events, e.g. DTLS events or 25 * retransmission timeouts. 26 */ 27 typedef unsigned int coap_event_t; 28 29 /** 30 * (D)TLS events for COAP_PROTO_DTLS and COAP_PROTO_TLS 31 */ 32 #define COAP_EVENT_DTLS_CLOSED 0x0000 33 #define COAP_EVENT_DTLS_CONNECTED 0x01DE 34 #define COAP_EVENT_DTLS_RENEGOTIATE 0x01DF 35 #define COAP_EVENT_DTLS_ERROR 0x0200 36 37 /** 38 * TCP events for COAP_PROTO_TCP and COAP_PROTO_TLS 39 */ 40 #define COAP_EVENT_TCP_CONNECTED 0x1001 41 #define COAP_EVENT_TCP_CLOSED 0x1002 42 #define COAP_EVENT_TCP_FAILED 0x1003 43 44 /** 45 * CSM exchange events for reliable protocols only 46 */ 47 #define COAP_EVENT_SESSION_CONNECTED 0x2001 48 #define COAP_EVENT_SESSION_CLOSED 0x2002 49 #define COAP_EVENT_SESSION_FAILED 0x2003 50 51 /** 52 * BLOCK2 receive errors 53 */ 54 #define COAP_EVENT_PARTIAL_BLOCK 0x3001 55 56 /** 57 * Type for event handler functions that can be registered with a CoAP 58 * context using the unction coap_set_event_handler(). When called by 59 * the library, the first argument will be the current coap_session_t object 60 * which is associated with the original CoAP context. The second parameter 61 * is the event type. 62 */ 63 typedef int (*coap_event_handler_t)(coap_session_t *session, 64 const coap_event_t event); 65 66 /** 67 * Registers the function @p hnd as callback for events from the given 68 * CoAP context @p context. Any event handler that has previously been 69 * registered with @p context will be overwritten by this operation. 70 * 71 * @param context The CoAP context to register the event handler with. 72 * @param hnd The event handler to be registered. @c NULL if to be 73 * de-registered. 74 */ 75 void coap_register_event_handler(coap_context_t *context, 76 coap_event_handler_t hnd); 77 78 /** @} */ 79 80 /** 81 * Registers the function @p hnd as callback for events from the given 82 * CoAP context @p context. Any event handler that has previously been 83 * registered with @p context will be overwritten by this operation. 84 * 85 * @deprecated Use coap_register_event_handler() instead. 86 * 87 * @param context The CoAP context to register the event handler with. 88 * @param hnd The event handler to be registered. 89 */ 90 COAP_DEPRECATED 91 void coap_set_event_handler(coap_context_t *context, 92 coap_event_handler_t hnd); 93 94 /** 95 * Clears the event handler registered with @p context. 96 * 97 * @deprecated Use coap_register_event_handler() instead with NULL for hnd. 98 * 99 * @param context The CoAP context whose event handler is to be removed. 100 */ 101 COAP_DEPRECATED 102 void coap_clear_event_handler(coap_context_t *context); 103 104 #endif /* COAP_EVENT_H */ 105