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