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       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
65       The handler function prototype is defined as:
66
67           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
73       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
77       The handler function prototype is defined as:
78
79           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
85       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
89       The handler function prototype is defined as:
90
91           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
96       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
100       The handler function prototype is defined as:
101
102           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
107       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
111       The handler function prototype is defined as:
112
113           typedef void (*coap_event_handler_t)(coap_context_t *context,
114                                                coap_event_t event,
115                                                coap_session_t *session);
116
117       Events can be one of the following
118
119           /**
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

EXAMPLES

140       GET Resource Callback Handler
141
142           #include <coap2/coap.h>
143
144           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
149             unsigned char buf[40];
150             size_t len;
151             time_t now;
152
153             /* ... Additional analysis code for resource, request pdu etc.  ... */
154
155             /* After analysis, generate a suitable response */
156
157             /* Note that token, if set, is already in the response pdu */
158
159             now = time(NULL);
160
161             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
191             /*
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
196           }
197
198       Packet Response Handler
199
200           #include <coap2/coap.h>
201
202           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
206             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
214             /* 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
223             if (received->type == COAP_MESSAGE_RST) {
224               info("got RST\n");
225               return;
226             }
227
228             /* Output the received data, if any */
229             if (COAP_RESPONSE_CLASS(received->code) == 2) {
230               /* Additional code to deal with the response */
231
232             }
233             return;
234
235           }
236

SEE ALSO

238       coap_resource(3)
239

FURTHER INFORMATION

241       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
242       information.
243

BUGS

245       Please report bugs on the mailing list for libcoap:
246       libcoap-developers@lists.sourceforge.net
247

AUTHORS

249       The libcoap project <libcoap-developers@lists.sourceforge.net>
250
251
252
253coap_handler 4.2.0                03/02/2019                   COAP_HANDLER(3)
Impressum