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 <coap3/coap.h>
13 void coap_register_handler(coap_resource_t *resource, coap_request_t
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 For specific (D)TLS library support, link with -lcoap-3-notls,
33 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
34 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
35 (D)TLS library support.
36
38 The coap_register_handler() function registers a callback handler
39 handler that is called when there is a URI match against the resource
40 and there is a method (e.g. PUT, POST etc.) match. method can be one of
41 the following.
42 COAP_REQUEST_GET
44 COAP_REQUEST_POST
45 COAP_REQUEST_PUT
46 COAP_REQUEST_DELETE
47 COAP_REQUEST_FETCH
48 COAP_REQUEST_PATCH
49 COAP_REQUEST_IPATCH
50 The method handler function prototype is defined as:
52 typedef void (*coap_method_handler_t)(coap_resource_t *resource,
54 coap_session_t *session,
55 const coap_pdu_t *incoming_pdu,
56 const 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_resource_get_uri_path() can
61 be used to determine the URI in this case.
62 NOTE: Any data associated with incoming_pdu is no longer be available
64 after exiting this function as incoming_pdu is deleted, unless
65 coap_add_data() was used to update response_pdu where a copy of the
66 data is taken. In particular incoming_pdu's data must not be used if
67 calling coap_add_data_large_response().
68 The coap_register_response_handler() function defines a request’s
70 response handler for traffic associated with the context. The
71 application can use this for handling any response packets, including
72 sending a RST packet if this response was unexpected. If handler is
73 NULL, then the handler is de-registered.
74 The response handler function prototype is defined as:
76 typedef enum coap_response_t {
78 COAP_RESPONSE_FAIL, /* Response not liked - send CoAP RST packet */
79 COAP_RESPONSE_OK /* Response is fine */
80 } coap_response_t;
81 typedef coap_response_t (*coap_response_handler_t)(coap_session_t *session,
83 const coap_pdu_t *sent,
84 const coap_pdu_t *received,
85 const coap_mid_t id);
86 NOTE: sent will only be non NULL when the request PDU is Confirmable
88 and this is an ACK or RST response to the request. In general, matching
89 of Requests and Responses whould be done by generating unique Tokens
90 for each Request and then matching up based on the Token in received
91 Response.
92 NOTE: If the returned value is COAP_RESPONSE_FAIL, then a CoAP RST
94 packet will get sent to the server by libcoap. The returned value of
95 COAP_RESPONSE_OK indicates that all is OK.
96 The coap_register_nack_handler() function defines a request’s negative
98 response handler for traffic associated with the context. If handler is
99 NULL, then the handler is de-registered.
100 The nack handler function prototype is defined as:
102 typedef void (*coap_nack_handler_t)(coap_session_t *session,
104 const coap_pdu_t *sent,
105 const coap_nack_reason_t reason,
106 const coap_mid_t mid);
107 NACKs can be one of the following
109 COAP_NACK_TOO_MANY_RETRIES
111 COAP_NACK_NOT_DELIVERABLE
112 COAP_NACK_RST
113 COAP_NACK_TLS_FAILED
114 COAP_NACK_ICMP_ISSUE
115 The coap_register_ping_handler() function defines a handler for
117 tracking receipt of CoAP ping traffic associated with the context. If
118 handler is NULL, then the handler is de-registered.
119 The ping handler function prototype is defined as:
121 typedef void (*coap_ping_handler_t)(coap_session_t *session,
123 const coap_pdu_t *received,
124 const coap_mid_t mid);
125 The coap_register_pong_handler() function defines a handler for
127 tracking receipt of CoAP ping response traffic associated with the
128 context. If handler is NULL, then the handler is de-registered.
129 The pong handler function prototype is defined as:
131 typedef void (*coap_pong_handler_t)(coap_session_t *session,
133 const coap_pdu_t *received,
134 const coap_mid_t mid);
135 The coap_register_event_handler() function defines a handler for
137 tracking (D)TLS events associated with the context. If handler is NULL,
138 then the handler is de-registered.
139 The event handler function prototype is defined as:
141 typedef void (*coap_event_handler_t)(coap_session_t *session,
143 const coap_event_t event);
144 Events can be one of the following
146 /**
148 * (D)TLS events for COAP_PROTO_DTLS and COAP_PROTO_TLS
149 */
150 COAP_EVENT_DTLS_CLOSED 0x0000
151 COAP_EVENT_DTLS_CONNECTED 0x01DE
152 COAP_EVENT_DTLS_RENEGOTIATE 0x01DF
153 COAP_EVENT_DTLS_ERROR 0x0200
154 /**
155 * TCP events for COAP_PROTO_TCP and COAP_PROTO_TLS
156 */
157 COAP_EVENT_TCP_CONNECTED 0x1001
158 COAP_EVENT_TCP_CLOSED 0x1002
159 COAP_EVENT_TCP_FAILED 0x1003
160 /**
161 * CSM exchange events for reliable protocols only
162 */
163 COAP_EVENT_SESSION_CONNECTED 0x2001
164 COAP_EVENT_SESSION_CLOSED 0x2002
165 COAP_EVENT_SESSION_FAILED 0x2003
166
168 GET Resource Callback Handler
169 #include <coap3/coap.h>
171 #include <stdio.h>
173 static void
175 hnd_get_time(coap_resource_t *resource, coap_session_t *session,
176 coap_pdu_t *request, coap_string_t *query, coap_pdu_t *response) {
177 unsigned char buf[40];
179 size_t len;
180 time_t now;
181 /* ... Additional analysis code for resource, request pdu etc. ... */
183 /* After analysis, generate a suitable response */
185 now = time(NULL);
187 if (query != NULL && coap_string_equal(query, coap_make_str_const("secs"))) {
189 /* Output secs since Jan 1 1970 */
190 len = snprintf((char *)buf, sizeof(buf), "%lu", now);
191 }
192 else {
193 /* Output human-readable time */
194 struct tm *tmp;
195 tmp = gmtime(&now);
196 if (!tmp) {
197 /* If 'now' is not valid */
198 coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
199 return;
200 }
201 len = strftime((char *)buf, sizeof(buf), "%b %d %H:%M:%S", tmp);
202 }
203 coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
204 /*
205 * Invoke coap_add_data_large_response() to do all the hard work.
206 *
207 * Define the format - COAP_MEDIATYPE_TEXT_PLAIN - to add in
208 * Define how long this response is valid for (secs) - 1 - to add in.
209 *
210 * OBSERVE Option added internally if needed within the function
211 * BLOCK2 Option added internally if output too large
212 * ETAG Option added internally
213 */
214 coap_add_data_large_response(resource, session, request, response,
215 query, COAP_MEDIATYPE_TEXT_PLAIN, 1, 0,
216 len,
217 buf, NULL, 0);
218 }
220 Packet Response Handler
222 #include <coap3/coap.h>
224 static int check_token(coap_pdu_t *received) {
226 /* Remove (void) definition if variable is used */
227 (void)received;
228 /* Code to validate the token is what we expect */
230 return 1;
232 }
233 static coap_response_t
235 response_handler(coap_context_t *ctx, coap_session_t *session,
236 coap_pdu_t *sent, coap_pdu_t *received, const coap_mid_t mid) {
237 /* Remove (void) definition if variable is used */
238 (void)ctx;
239 (void)session;
240 (void)mid;
241 coap_pdu_type_t rcv_type = coap_pdu_get_type(received);
242 coap_pdu_code_t rcv_code = coap_pdu_get_code(received);
243 /* check if this is a response to our original request */
245 if (!check_token(received)) {
246 /* drop if this was just some message, or send RST in case of notification */
247 if (!sent && (rcv_type == COAP_MESSAGE_CON ||
248 rcv_type == COAP_MESSAGE_NON)) {
249 /* Cause a CoAP RST to be sent */
250 return COAP_RESPONSE_FAIL;
251 }
252 return COAP_RESPONSE_OK;
253 }
254 if (rcv_type == COAP_MESSAGE_RST) {
256 coap_log(LOG_INFO, "got RST\n");
257 return COAP_RESPONSE_OK;
258 }
259 /* Output the received data, if any */
261 if (COAP_RESPONSE_CLASS(rcv_code) == 2) {
262 /* Additional code to deal with the response */
263 }
265 return COAP_RESPONSE_OK;
266 }
268
270 coap_block(3), coap_observe(3) and coap_resource(3)
271
273 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
274 information.
275
277 Please report bugs on the mailing list for libcoap:
278 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
279 https://github.com/obgm/libcoap/issues
280
282 The libcoap project <libcoap-developers@lists.sourceforge.net>
283coap_handler 4.3.0 07/22/2021 COAP_HANDLER(3)