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 <coap2/coap.h>
13
14       void coap_register_handler(coap_resource_t *resource, unsigned char
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       Link with -lcoap-2, -lcoap-2-gnutls, -lcoap-2-openssl or
33       -lcoap-2-tinydtls depending on your (D)TLS library type.
34

DESCRIPTION

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
41           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
49       The handler function prototype is defined as:
50
51           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
59       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
63       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
69       The handler function prototype is defined as:
70
71           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
77       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
83       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
87       The handler function prototype is defined as:
88
89           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
95       NACKs can be one of the following
96
97           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
103       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
107       The handler function prototype is defined as:
108
109           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
114       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
118       The handler function prototype is defined as:
119
120           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
125       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
129       The handler function prototype is defined as:
130
131           typedef void (*coap_event_handler_t)(coap_context_t *context,
132                                                coap_event_t event,
133                                                coap_session_t *session);
134
135       Events can be one of the following
136
137           /**
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

EXAMPLES

158       GET Resource Callback Handler
159
160           #include <coap2/coap.h>
161
162           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
167             unsigned char buf[40];
168             size_t len;
169             time_t now;
170
171             /* ... Additional analysis code for resource, request pdu etc.  ... */
172
173             /* After analysis, generate a suitable response */
174
175             /* Note that token, if set, is already in the response pdu */
176
177             now = time(NULL);
178
179             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
209             /*
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
214           }
215
216       Packet Response Handler
217
218           #include <coap2/coap.h>
219
220           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
224             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
232             /* 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
241             if (received->type == COAP_MESSAGE_RST) {
242               info("got RST\n");
243               return;
244             }
245
246             /* Output the received data, if any */
247             if (COAP_RESPONSE_CLASS(received->code) == 2) {
248               /* Additional code to deal with the response */
249
250             }
251             return;
252
253           }
254

SEE ALSO

256       coap_observe(3) and coap_resource(3)
257

FURTHER INFORMATION

259       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
260       information.
261

BUGS

263       Please report bugs on the mailing list for libcoap:
264       libcoap-developers@lists.sourceforge.net
265

AUTHORS

267       The libcoap project <libcoap-developers@lists.sourceforge.net>
268
269
270
271coap_handler 4.2.1                07/28/2020                   COAP_HANDLER(3)
Impressum