'\" t .\" Title: coap_handler .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 05/14/2022 .\" Manual: libcoap Manual .\" Source: coap_handler 4.2.1 .\" Language: English .\" .TH "COAP_HANDLER" "3" "05/14/2022" "coap_handler 4\&.2\&.1" "libcoap Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" coap_handler, coap_register_handler, coap_register_response_handler, coap_register_nack_handler, coap_register_ping_handler, coap_register_pong_handler, coap_register_event_handler \- work with CoAP handlers .SH "SYNOPSIS" .sp \fB#include \fR .sp \fBvoid coap_register_handler(coap_resource_t *\fR\fB\fIresource\fR\fR\fB, unsigned char \fR\fB\fImethod\fR\fR\fB, coap_method_handler_t \fR\fB\fIhandler\fR\fR\fB);\fR .sp \fBvoid coap_register_response_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_response_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR; .sp \fBvoid coap_register_nack_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_nack_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR; .sp \fBvoid coap_register_ping_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_ping_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR; .sp \fBvoid coap_register_pong_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_pong_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR; .sp \fBvoid coap_register_event_handler(coap_context_t *\fR\fB\fIcontext\fR\fR\fB, coap_event_handler_t \fR\fB\fIhandler\fR\fR\fB)\fR; .sp Link with \fB\-lcoap\-2\fR, \fB\-lcoap\-2\-gnutls\fR, \fB\-lcoap\-2\-openssl\fR or \fB\-lcoap\-2\-tinydtls\fR depending on your (D)TLS library type\&. .SH "DESCRIPTION" .sp The \fBcoap_register_handler\fR() function registers a callback handler \fIhandler\fR that is called when there is a URI match against the \fIresource\fR and there is a \fImethod\fR (e\&.g\&. PUT, POST etc\&.) match\&. \fImethod\fR can be one of the following\&. .sp .if n \{\ .RS 4 .\} .nf COAP_REQUEST_GET COAP_REQUEST_POST COAP_REQUEST_PUT COAP_REQUEST_DELETE COAP_REQUEST_FETCH COAP_REQUEST_PATCH COAP_REQUEST_IPATCH .fi .if n \{\ .RE .\} .sp The handler function prototype is defined as: .sp .if n \{\ .RS 4 .\} .nf typedef void (*coap_method_handler_t)(coap_context_t *context, coap_resource_t *resource, coap_session_t *session, coap_pdu_t *incoming_pdu, coap_string_t *token, coap_string_t *query, coap_pdu_t *response_pdu); .fi .if n \{\ .RE .\} .sp \fBNOTE:\fR \fIincoming_pdu\fR will be NULL for the GET Handler if this is an internally generated Observe Response\&. \fBcoap_find_observer()\fR can be used to determine the subscription information in this case\&. .sp The \fBcoap_register_response_handler\fR() function defines a request\(cqs response \fIhandler\fR for traffic associated with the \fIcontext\fR\&. The application can use this for handling any response packets, including sending a RST packet if this response was unexpected\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&. .sp The handler function prototype is defined as: .sp .if n \{\ .RS 4 .\} .nf typedef void (*coap_response_handler_t)(coap_context_t *context, coap_session_t *session, coap_pdu_t *sent, coap_pdu_t *received, const coap_tid_t id); .fi .if n \{\ .RE .\} .sp \fBNOTE:\fR \fIsent\fR will only be non NULL when the request PDU is Confirmable and this is an ACK or RST response to the request\&. In general, matching of Requests and Responses whould be done generating unique Tokens for each Request and then matching up based on the Token in \fIreceived\fR Response\&. .sp The \fBcoap_register_nack_handler\fR() function defines a request\(cqs negative response \fIhandler\fR for traffic associated with the \fIcontext\fR\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&. .sp The handler function prototype is defined as: .sp .if n \{\ .RS 4 .\} .nf typedef void (*coap_nack_handler_t)(coap_context_t *context, coap_session_t *session, coap_pdu_t *sent, coap_nack_reason_t reason, const coap_tid_t id); .fi .if n \{\ .RE .\} .sp NACKs can be one of the following .sp .if n \{\ .RS 4 .\} .nf COAP_NACK_TOO_MANY_RETRIES COAP_NACK_NOT_DELIVERABLE COAP_NACK_RST COAP_NACK_TLS_FAILED COAP_NACK_ICMP_ISSUE .fi .if n \{\ .RE .\} .sp The \fBcoap_register_ping_handler\fR() function defines a \fIhandler\fR for tracking receipt of CoAP ping traffic associated with the \fIcontext\fR\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&. .sp The handler function prototype is defined as: .sp .if n \{\ .RS 4 .\} .nf typedef void (*coap_ping_handler_t)(coap_context_t *context, coap_session_t *session, coap_pdu_t *received, const coap_tid_t id); .fi .if n \{\ .RE .\} .sp The \fBcoap_register_pong_handler\fR() function defines a \fIhandler\fR for tracking receipt of CoAP ping response traffic associated with the \fIcontext\fR\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&. .sp The handler function prototype is defined as: .sp .if n \{\ .RS 4 .\} .nf typedef void (*coap_pong_handler_t)(coap_context_t *context, coap_session_t *session, coap_pdu_t *received, const coap_tid_t id); .fi .if n \{\ .RE .\} .sp The \fBcoap_register_event_handler\fR() function defines a \fIhandler\fR for tracking (D)TLS events associated with the \fIcontext\fR\&. If \fIhandler\fR is NULL, then the handler is de\-registered\&. .sp The handler function prototype is defined as: .sp .if n \{\ .RS 4 .\} .nf typedef void (*coap_event_handler_t)(coap_context_t *context, coap_event_t event, coap_session_t *session); .fi .if n \{\ .RE .\} .sp Events can be one of the following .sp .if n \{\ .RS 4 .\} .nf /** * (D)TLS events for COAP_PROTO_DTLS and COAP_PROTO_TLS */ COAP_EVENT_DTLS_CLOSED 0x0000 COAP_EVENT_DTLS_CONNECTED 0x01DE COAP_EVENT_DTLS_RENEGOTIATE 0x01DF COAP_EVENT_DTLS_ERROR 0x0200 /** * TCP events for COAP_PROTO_TCP and COAP_PROTO_TLS */ COAP_EVENT_TCP_CONNECTED 0x1001 COAP_EVENT_TCP_CLOSED 0x1002 COAP_EVENT_TCP_FAILED 0x1003 /** * CSM exchange events for reliable protocols only */ COAP_EVENT_SESSION_CONNECTED 0x2001 COAP_EVENT_SESSION_CLOSED 0x2002 COAP_EVENT_SESSION_FAILED 0x2003 .fi .if n \{\ .RE .\} .SH "EXAMPLES" .sp \fBGET Resource Callback Handler\fR .sp .if n \{\ .RS 4 .\} .nf #include void hnd_get_time(coap_context_t *context, coap_resource_t *resource, coap_session_t *session, coap_pdu_t *request, coap_string_t *token, coap_string_t *query, coap_pdu_t *response) { unsigned char buf[40]; size_t len; time_t now; /* \&.\&.\&. Additional analysis code for resource, request pdu etc\&. \&.\&.\&. */ /* After analysis, generate a suitable response */ /* Note that token, if set, is already in the response pdu */ now = time(NULL); if (query != NULL && coap_string_equal(query, coap_make_str_const("secs"))) { /* Output secs since Jan 1 1970 */ len = snprintf((char *)buf, sizeof(buf), "%lu", now); } else { /* Output human\-readable time */ struct tm *tmp; tmp = gmtime(&now); if (!tmp) { /* If \*(Aqnow\*(Aq is not valid */ response\->code = COAP_RESPONSE_CODE(404); return; } len = strftime((char *)buf, sizeof(buf), "%b %d %H:%M:%S", tmp); } /* * Invoke coap_add_data_blocked_response() to do all the hard work\&. * * Define the format \- COAP_MEDIATYPE_TEXT_PLAIN \- to add in * Define how long this response is valid for (secs) \- 1 \- to add in\&. * * OBSERVE Option added internally if needed within the function * BLOCK2 Option added internally if output too large * ETAG Option added internally */ coap_add_data_blocked_response(resource, session, request, response, token, COAP_MEDIATYPE_TEXT_PLAIN, 1, len, buf); /* * As resource\->code has been updated in coap_add_data_blocked_response(), * the response pdu will be transmitted by the underlying library\&. */ } .fi .if n \{\ .RE .\} .sp \fBPacket Response Handler\fR .sp .if n \{\ .RS 4 .\} .nf #include static void response_handler(coap_context_t *ctx, coap_session_t *session, coap_pdu_t *sent, coap_pdu_t *received, const coap_tid_t id) { coap_pdu_t *pdu = NULL; coap_opt_t *block_opt; coap_opt_iterator_t opt_iter; unsigned char buf[4]; size_t len; unsigned char *databuf; coap_tid_t tid; /* check if this is a response to our original request */ if (!check_token(received)) { /* drop if this was just some message, or send RST in case of notification */ if (!sent && (received\->type == COAP_MESSAGE_CON || received\->type == COAP_MESSAGE_NON)) coap_send_rst(session, received); return; } if (received\->type == COAP_MESSAGE_RST) { info("got RST\en"); return; } /* Output the received data, if any */ if (COAP_RESPONSE_CLASS(received\->code) == 2) { /* Additional code to deal with the response */ } return; } .fi .if n \{\ .RE .\} .SH "SEE ALSO" .sp \fBcoap_observe\fR(3) and \fBcoap_resource\fR(3) .SH "FURTHER INFORMATION" .sp See "RFC7252: The Constrained Application Protocol (CoAP)" for further information\&. .SH "BUGS" .sp Please report bugs on the mailing list for libcoap: libcoap\-developers@lists\&.sourceforge\&.net .SH "AUTHORS" .sp The libcoap project