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 The coap_register_response_handler() function defines a request’s
60 response handler for traffic associated with the context. The
61 application can use this for handling any response packets, including
62 sending a RST packet if this response was unexpected. If handler is
63 NULL, then the handler is de-registered.
64 The handler function prototype is defined as:
66 typedef void (*coap_response_handler_t)(coap_context_t *context,
68 coap_session_t *session,
69 coap_pdu_t *sent,
70 coap_pdu_t *received,
71 const coap_tid_t id);
72 The coap_register_nack_handler() function defines a request’s negative
74 response handler for traffic associated with the context. If handler is
75 NULL, then the handler is de-registered.
76 The handler function prototype is defined as:
78 typedef void (*coap_nack_handler_t)(coap_context_t *context,
80 coap_session_t *session,
81 coap_pdu_t *sent,
82 coap_nack_reason_t reason,
83 const coap_tid_t id);
84 The coap_register_ping_handler() function defines a handler for
86 tracking CoAP ping traffic associated with the context. If handler is
87 NULL, then the handler is de-registered.
88 The handler function prototype is defined as:
90 typedef void (*coap_ping_handler_t)(coap_context_t *context,
92 coap_session_t *session,
93 coap_pdu_t *received,
94 const coap_tid_t id);
95 The coap_register_pong_handler() function defines a handler for
97 tracking CoAP TCP ping response traffic associated with the context. If
98 handler is NULL, then the handler is de-registered.
99 The handler function prototype is defined as:
101 typedef void (*coap_pong_handler_t)(coap_context_t *context,
103 coap_session_t *session,
104 coap_pdu_t *received,
105 const coap_tid_t id);
106 The coap_register_event_handler() function defines a handler for
108 tracking (D)TLS events associated with the context. If handler is NULL,
109 then the handler is de-registered.
110 The handler function prototype is defined as:
112 typedef void (*coap_event_handler_t)(coap_context_t *context,
114 coap_event_t event,
115 coap_session_t *session);
116 Events can be one of the following
118 /**
120 * (D)TLS events for COAP_PROTO_DTLS and COAP_PROTO_TLS
121 */
122 COAP_EVENT_DTLS_CLOSED 0x0000
123 COAP_EVENT_DTLS_CONNECTED 0x01DE
124 COAP_EVENT_DTLS_RENEGOTIATE 0x01DF
125 COAP_EVENT_DTLS_ERROR 0x0200
126 /**
127 * TCP events for COAP_PROTO_TCP and COAP_PROTO_TLS
128 */
129 COAP_EVENT_TCP_CONNECTED 0x1001
130 COAP_EVENT_TCP_CLOSED 0x1002
131 COAP_EVENT_TCP_FAILED 0x1003
132 /**
133 * CSM exchange events for reliable protocols only
134 */
135 COAP_EVENT_SESSION_CONNECTED 0x2001
136 COAP_EVENT_SESSION_CLOSED 0x2002
137 COAP_EVENT_SESSION_FAILED 0x2003
138
140 GET Resource Callback Handler
141 #include <coap2/coap.h>
143 void
145 hnd_get_time(coap_context_t *context, coap_resource_t *resource,
146 coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
147 coap_string_t *query, coap_pdu_t *response) {
148 unsigned char buf[40];
150 size_t len;
151 time_t now;
152 /* ... Additional analysis code for resource, request pdu etc. ... */
154 /* After analysis, generate a suitable response */
156 /* Note that token, if set, is already in the response pdu */
158 now = time(NULL);
160 if (query != NULL && coap_string_equal(query, coap_make_str_const("secs"))) {
162 /* Output secs since Jan 1 1970 */
163 len = snprintf((char *)buf, sizeof(buf), "%lu", now);
164 }
165 else {
166 /* Output human-readable time */
167 struct tm *tmp;
168 tmp = gmtime(&now);
169 if (!tmp) {
170 /* If 'now' is not valid */
171 response->code = COAP_RESPONSE_CODE(404);
172 return;
173 }
174 len = strftime((char *)buf, sizeof(buf), "%b %d %H:%M:%S", tmp);
175 }
176 /*
177 * Invoke coap_add_data_blocked_response() to do all the hard work.
178 *
179 * Define the format - COAP_MEDIATYPE_TEXT_PLAIN - to add in
180 * Define how long this response is valid for (secs) - 1 - to add in.
181 *
182 * OBSERVE Option added internally if needed within the function
183 * BLOCK2 Option added internally if output too large
184 * ETAG Option added internally
185 */
186 coap_add_data_blocked_response(resource, session, request, response, token,
187 COAP_MEDIATYPE_TEXT_PLAIN, 1,
188 len,
189 buf);
190 /*
192 * As resource->code has been updated in coap_add_data_blocked_response(),
193 * the response pdu will be transmitted by the underlying library.
194 */
195 }
197 Packet Response Handler
199 #include <coap2/coap.h>
201 static void
203 response_handler(coap_context_t *ctx, coap_session_t *session,
204 coap_pdu_t *sent, coap_pdu_t *received, const coap_tid_t id) {
205 coap_pdu_t *pdu = NULL;
207 coap_opt_t *block_opt;
208 coap_opt_iterator_t opt_iter;
209 unsigned char buf[4];
210 size_t len;
211 unsigned char *databuf;
212 coap_tid_t tid;
213 /* check if this is a response to our original request */
215 if (!check_token(received)) {
216 /* drop if this was just some message, or send RST in case of notification */
217 if (!sent && (received->type == COAP_MESSAGE_CON ||
218 received->type == COAP_MESSAGE_NON))
219 coap_send_rst(session, received);
220 return;
221 }
222 if (received->type == COAP_MESSAGE_RST) {
224 info("got RST\n");
225 return;
226 }
227 /* Output the received data, if any */
229 if (COAP_RESPONSE_CLASS(received->code) == 2) {
230 /* Additional code to deal with the response */
231 }
233 return;
234 }
236
238 coap_resource(3)
239
241 See "RFC7252: The Constrained Application Protocol (CoAP)" for further
242 information.
243
245 Please report bugs on the mailing list for libcoap:
246 libcoap-developers@lists.sourceforge.net
247
249 The libcoap project <libcoap-developers@lists.sourceforge.net>
250coap_handler 4.2.0 03/02/2019 COAP_HANDLER(3)