1COAP_HANDLER(3)                 libcoap Manual                 COAP_HANDLER(3)
2
3
4

NAME

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

SYNOPSIS

12       #include <coap3/coap.h>
13
14       void coap_register_handler(coap_resource_t *resource, coap_request_t
15       method, coap_method_handler_t handler);
16
17       void coap_register_response_handler(coap_context_t *context,
18       coap_response_handler_t handler);
19
20       void coap_register_nack_handler(coap_context_t *context,
21       coap_nack_handler_t handler);
22
23       void coap_register_ping_handler(coap_context_t *context,
24       coap_ping_handler_t handler);
25
26       void coap_register_pong_handler(coap_context_t *context,
27       coap_pong_handler_t handler);
28
29       void coap_register_event_handler(coap_context_t *context,
30       coap_event_handler_t handler);
31
32       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

DESCRIPTION

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
43           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
51       The method handler function prototype is defined as:
52
53           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
59       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
63       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
69       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
75       The response handler function prototype is defined as:
76
77           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
82           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
87       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
93       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
97       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
101       The nack handler function prototype is defined as:
102
103           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
108       NACKs can be one of the following
109
110           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
116       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
120       The ping handler function prototype is defined as:
121
122           typedef void (*coap_ping_handler_t)(coap_session_t *session,
123                                               const coap_pdu_t *received,
124                                               const coap_mid_t mid);
125
126       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
130       The pong handler function prototype is defined as:
131
132           typedef void (*coap_pong_handler_t)(coap_session_t *session,
133                                               const coap_pdu_t *received,
134                                               const coap_mid_t mid);
135
136       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
140       The event handler function prototype is defined as:
141
142           typedef void (*coap_event_handler_t)(coap_session_t *session,
143                                                const coap_event_t event);
144
145       Events can be one of the following
146
147           /**
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

EXAMPLES

168       GET Resource Callback Handler
169
170           #include <coap3/coap.h>
171
172           #include <stdio.h>
173
174           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
178             unsigned char buf[40];
179             size_t len;
180             time_t now;
181
182             /* ... Additional analysis code for resource, request pdu etc.  ... */
183
184             /* After analysis, generate a suitable response */
185
186             now = time(NULL);
187
188             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
219           }
220
221       Packet Response Handler
222
223           #include <coap3/coap.h>
224
225           static int check_token(coap_pdu_t *received) {
226             /* Remove (void) definition if variable is used */
227             (void)received;
228
229             /* Code to validate the token is what we expect */
230
231             return 1;
232           }
233
234           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
244             /* 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
255             if (rcv_type == COAP_MESSAGE_RST) {
256               coap_log(LOG_INFO, "got RST\n");
257               return COAP_RESPONSE_OK;
258             }
259
260             /* Output the received data, if any */
261             if (COAP_RESPONSE_CLASS(rcv_code) == 2) {
262               /* Additional code to deal with the response */
263
264             }
265             return COAP_RESPONSE_OK;
266
267           }
268

SEE ALSO

270       coap_block(3), coap_observe(3) and coap_resource(3)
271

FURTHER INFORMATION

273       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
274       information.
275

BUGS

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

AUTHORS

282       The libcoap project <libcoap-developers@lists.sourceforge.net>
283
284
285
286coap_handler 4.3.0                01/20/2022                   COAP_HANDLER(3)
Impressum