1COAP_HANDLER(3) libcoap Manual COAP_HANDLER(3)
2
6 coap_handler, coap_register_handler, coap_register_response_handler,
7 coap_register_nack_handler, coap_register_ping_handler,
8 coap_register_pong_handler, coap_register_event_handler - work with
9 CoAP handlers
10
12 #include <coap2/coap.h>
13 void coap_register_handler(coap_resource_t *resource, unsigned char
15 method, coap_method_handler_t handler);
16 void coap_register_response_handler(coap_context_t *context,
18 coap_response_handler_t handler);
19 void coap_register_nack_handler(coap_context_t *context,
21 coap_nack_handler_t handler);
22 void coap_register_ping_handler(coap_context_t *context,
24 coap_ping_handler_t handler);
25 void coap_register_pong_handler(coap_context_t *context,
27 coap_pong_handler_t handler);
28 void coap_register_event_handler(coap_context_t *context,
30 coap_event_handler_t handler);
31 Link with -lcoap-2, -lcoap-2-gnutls, -lcoap-2-openssl or
33 -lcoap-2-tinydtls depending on your (D)TLS library type.
34
36 The coap_register_handler() function registers a callback handler
37 handler that is called when there is a URI match against the resource
38 and there is a method (e.g. PUT, POST etc.) match. method can be one of
39 the following.
40 COAP_REQUEST_GET
42 COAP_REQUEST_POST
43 COAP_REQUEST_PUT
44 COAP_REQUEST_DELETE
45 COAP_REQUEST_FETCH
46 COAP_REQUEST_PATCH
47 COAP_REQUEST_IPATCH
48 The handler function prototype is defined as:
50 typedef void (*coap_method_handler_t)(coap_context_t *context,
52 coap_resource_t *resource,
53 coap_session_t *session,
54 coap_pdu_t *incoming_pdu,
55 coap_string_t *token,
56 coap_string_t *query,
57 coap_pdu_t *response_pdu);
58 NOTE: incoming_pdu will be NULL for the GET Handler if this is an
60 internally generated Observe Response. coap_find_observer() can be used
61 to determine the subscription information in this case.
62 The coap_register_response_handler() function defines a request’s
64 response handler for traffic associated with the context. The
65 application can use this for handling any response packets, including
66 sending a RST packet if this response was unexpected. If handler is
67 NULL, then the handler is de-registered.
68 The handler function prototype is defined as:
70 typedef void (*coap_response_handler_t)(coap_context_t *context,
72 coap_session_t *session,
73 coap_pdu_t *sent,
74 coap_pdu_t *received,
75 const coap_tid_t id);
76 NOTE: sent will only be non NULL when the request PDU is Confirmable
78 and this is an ACK or RST response to the request. In general, matching
79 of Requests and Responses whould be done generating unique Tokens for
80 each Request and then matching up based on the Token in received
81 Response.
82 The coap_register_nack_handler() function defines a request’s negative
84 response handler for traffic associated with the context. If handler is
85 NULL, then the handler is de-registered.
86 The handler function prototype is defined as:
88 typedef void (*coap_nack_handler_t)(coap_context_t *context,
90 coap_session_t *session,
91 coap_pdu_t *sent,
92 coap_nack_reason_t reason,
93 const coap_tid_t id);
94 NACKs can be one of the following
96 COAP_NACK_TOO_MANY_RETRIES
98 COAP_NACK_NOT_DELIVERABLE
99 COAP_NACK_RST
100 COAP_NACK_TLS_FAILED
101 COAP_NACK_ICMP_ISSUE
102 The coap_register_ping_handler() function defines a handler for
104 tracking receipt of CoAP ping traffic associated with the context. If
105 handler is NULL, then the handler is de-registered.
106 The handler function prototype is defined as:
108 typedef void (*coap_ping_handler_t)(coap_context_t *context,
110 coap_session_t *session,
111 coap_pdu_t *received,
112 const coap_tid_t id);
113 The coap_register_pong_handler() function defines a handler for
115 tracking receipt of CoAP ping response traffic associated with the
116 context. If handler is NULL, then the handler is de-registered.
117 The handler function prototype is defined as:
119 typedef void (*coap_pong_handler_t)(coap_context_t *context,
121 coap_session_t *session,
122 coap_pdu_t *received,
123 const coap_tid_t id);
124 The coap_register_event_handler() function defines a handler for
126 tracking (D)TLS events associated with the context. If handler is NULL,
127 then the handler is de-registered.
128 The handler function prototype is defined as:
130 typedef void (*coap_event_handler_t)(coap_context_t *context,
132 coap_event_t event,
133 coap_session_t *session);
134 Events can be one of the following
136 /**
138 * (D)TLS events for COAP_PROTO_DTLS and COAP_PROTO_TLS
139 */
140 COAP_EVENT_DTLS_CLOSED 0x0000
141 COAP_EVENT_DTLS_CONNECTED 0x01DE
142 COAP_EVENT_DTLS_RENEGOTIATE 0x01DF
143 COAP_EVENT_DTLS_ERROR 0x0200
144 /**
145 * TCP events for COAP_PROTO_TCP and COAP_PROTO_TLS
146 */
147 COAP_EVENT_TCP_CONNECTED 0x1001
148 COAP_EVENT_TCP_CLOSED 0x1002
149 COAP_EVENT_TCP_FAILED 0x1003
150 /**
151 * CSM exchange events for reliable protocols only
152 */
153 COAP_EVENT_SESSION_CONNECTED 0x2001
154 COAP_EVENT_SESSION_CLOSED 0x2002
155 COAP_EVENT_SESSION_FAILED 0x2003
156
158 GET Resource Callback Handler
159 #include <coap2/coap.h>
161 void
163 hnd_get_time(coap_context_t *context, coap_resource_t *resource,
164 coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
165 coap_string_t *query, coap_pdu_t *response) {
166 unsigned char buf[40];
168 size_t len;
169 time_t now;
170 /* ... Additional analysis code for resource, request pdu etc. ... */
172 /* After analysis, generate a suitable response */
174 /* Note that token, if set, is already in the response pdu */
176 now = time(NULL);
178 if (query != NULL && coap_string_equal(query, coap_make_str_const("secs"))) {
180 /* Output secs since Jan 1 1970 */
181 len = snprintf((char *)buf, sizeof(buf), "%lu", now);
182 }
183 else {
184 /* Output human-readable time */
185 struct tm *tmp;
186 tmp = gmtime(&now);
187 if (!tmp) {
188 /* If 'now' is not valid */
189 response->code = COAP_RESPONSE_CODE(404);
190 return;
191 }
192 len = strftime((char *)buf, sizeof(buf), "%b %d %H:%M:%S", tmp);
193 }
194 /*
195 * Invoke coap_add_data_blocked_response() to do all the hard work.
196 *
197 * Define the format - COAP_MEDIATYPE_TEXT_PLAIN - to add in
198 * Define how long this response is valid for (secs) - 1 - to add in.
199 *
200 * OBSERVE Option added internally if needed within the function
201 * BLOCK2 Option added internally if output too large
202 * ETAG Option added internally
203 */
204 coap_add_data_blocked_response(resource, session, request, response, token,
205 COAP_MEDIATYPE_TEXT_PLAIN, 1,
206 len,
207 buf);
208 /*
210 * As resource->code has been updated in coap_add_data_blocked_response(),
211 * the response pdu will be transmitted by the underlying library.
212 */
213 }
215 Packet Response Handler
217 #include <coap2/coap.h>
219 static void
221 response_handler(coap_context_t *ctx, coap_session_t *session,
222 coap_pdu_t *sent, coap_pdu_t *received, const coap_tid_t id) {
223 coap_pdu_t *pdu = NULL;
225 coap_opt_t *block_opt;
226 coap_opt_iterator_t opt_iter;
227 unsigned char buf[4];
228 size_t len;
229 unsigned char *databuf;
230 coap_tid_t tid;
231 /* check if this is a response to our original request */
233 if (!check_token(received)) {
234 /* drop if this was just some message, or send RST in case of notification */
235 if (!sent && (received->type == COAP_MESSAGE_CON ||
236 received->type == COAP_MESSAGE_NON))
237 coap_send_rst(session, received);
238 return;
239 }
240 if (received->type == COAP_MESSAGE_RST) {
242 info("got RST\n");
243 return;
244 }
245 /* Output the received data, if any */
247 if (COAP_RESPONSE_CLASS(received->code) == 2) {
248 /* Additional code to deal with the response */
249 }
251 return;
252 }
254
256 coap_observe(3) and coap_resource(3)
257
259 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
260 information.
261
263 Please report bugs on the mailing list for libcoap:
264 libcoap-developers@lists.sourceforge.net
265
267 The libcoap project <libcoap-developers@lists.sourceforge.net>
268coap_handler 4.2.1 01/26/2021 COAP_HANDLER(3)