mirror of
https://github.com/obgm/libcoap.git
synced 2026-11-13 03:40:40 +03:00
314 lines
9.4 KiB
Plaintext
314 lines
9.4 KiB
Plaintext
// -*- mode:doc; -*-
|
|
// vim: set syntax=asciidoc,tw=0:
|
|
|
|
coap_handler(3)
|
|
=================
|
|
:doctype: manpage
|
|
:man source: coap_handler
|
|
:man version: @PACKAGE_VERSION@
|
|
:man manual: libcoap Manual
|
|
|
|
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
|
|
|
|
SYNOPSIS
|
|
--------
|
|
*#include <coap@LIBCOAP_API_VERSION@/coap.h>*
|
|
|
|
*void coap_register_handler(coap_resource_t *_resource_, coap_request_t
|
|
_method_, coap_method_handler_t _handler_);*
|
|
|
|
*void coap_register_response_handler(coap_context_t *_context_,
|
|
coap_response_handler_t _handler_)*;
|
|
|
|
*void coap_register_nack_handler(coap_context_t *_context_,
|
|
coap_nack_handler_t _handler_)*;
|
|
|
|
*void coap_register_ping_handler(coap_context_t *_context_,
|
|
coap_ping_handler_t _handler_)*;
|
|
|
|
*void coap_register_pong_handler(coap_context_t *_context_,
|
|
coap_pong_handler_t _handler_)*;
|
|
|
|
*void coap_register_event_handler(coap_context_t *_context_,
|
|
coap_event_handler_t _handler_)*;
|
|
|
|
Link with *-lcoap-@LIBCOAP_API_VERSION@*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
|
|
*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*
|
|
or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls* depending on your (D)TLS library
|
|
type.
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The *coap_register_handler*() function registers a callback handler _handler_
|
|
that is called when there is a URI match against the _resource_ and there is
|
|
a _method_ (e.g. PUT, POST etc.) match. _method_ can be one of the following.
|
|
----
|
|
COAP_REQUEST_GET
|
|
COAP_REQUEST_POST
|
|
COAP_REQUEST_PUT
|
|
COAP_REQUEST_DELETE
|
|
COAP_REQUEST_FETCH
|
|
COAP_REQUEST_PATCH
|
|
COAP_REQUEST_IPATCH
|
|
----
|
|
|
|
The handler function prototype is defined as:
|
|
[source, c]
|
|
----
|
|
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);
|
|
----
|
|
|
|
*NOTE:* _incoming_pdu_ will be NULL for the GET Handler if this is an
|
|
internally generated Observe Response. *coap_find_observer()* can be used
|
|
to determine the subscription information in this case.
|
|
|
|
The *coap_register_response_handler*() function defines a request's response
|
|
_handler_ for traffic associated with the _context_. The application can use
|
|
this for handling any response packets, including sending a RST packet if this
|
|
response was unexpected. If _handler_ is NULL, then the handler is
|
|
de-registered.
|
|
|
|
The handler function prototype is defined as:
|
|
[source, c]
|
|
----
|
|
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);
|
|
----
|
|
|
|
*NOTE:* _sent_ 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 _received_ Response.
|
|
|
|
The *coap_register_nack_handler*() function defines a request's negative
|
|
response _handler_ for traffic associated with the _context_.
|
|
If _handler_ is NULL, then the handler is de-registered.
|
|
|
|
The handler function prototype is defined as:
|
|
[source, c]
|
|
----
|
|
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);
|
|
----
|
|
NACKs can be one of the following
|
|
----
|
|
COAP_NACK_TOO_MANY_RETRIES
|
|
COAP_NACK_NOT_DELIVERABLE
|
|
COAP_NACK_RST
|
|
COAP_NACK_TLS_FAILED
|
|
COAP_NACK_ICMP_ISSUE
|
|
----
|
|
|
|
The *coap_register_ping_handler*() function defines a _handler_ for tracking
|
|
receipt of CoAP ping traffic associated with the _context_. If _handler_ is
|
|
NULL, then the handler is de-registered.
|
|
|
|
The handler function prototype is defined as:
|
|
[source, c]
|
|
----
|
|
typedef void (*coap_ping_handler_t)(coap_context_t *context,
|
|
coap_session_t *session,
|
|
coap_pdu_t *received,
|
|
const coap_tid_t id);
|
|
----
|
|
|
|
The *coap_register_pong_handler*() function defines a _handler_ for tracking
|
|
receipt of CoAP ping response traffic associated with the _context_.
|
|
If _handler_ is NULL, then the handler is de-registered.
|
|
|
|
The handler function prototype is defined as:
|
|
[source, c]
|
|
----
|
|
typedef void (*coap_pong_handler_t)(coap_context_t *context,
|
|
coap_session_t *session,
|
|
coap_pdu_t *received,
|
|
const coap_tid_t id);
|
|
----
|
|
|
|
The *coap_register_event_handler*() function defines a _handler_ for tracking
|
|
(D)TLS events associated with the _context_. If _handler_ is NULL, then
|
|
the handler is de-registered.
|
|
|
|
The handler function prototype is defined as:
|
|
[source, c]
|
|
----
|
|
typedef void (*coap_event_handler_t)(coap_context_t *context,
|
|
coap_event_t event,
|
|
coap_session_t *session);
|
|
----
|
|
Events can be one of the following
|
|
----
|
|
/**
|
|
* (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
|
|
----
|
|
|
|
EXAMPLES
|
|
--------
|
|
*GET Resource Callback Handler*
|
|
|
|
[source, c]
|
|
----
|
|
#include <coap@LIBCOAP_API_VERSION@/coap.h>
|
|
|
|
#include <stdio.h>
|
|
|
|
static void
|
|
hnd_get_time(coap_context_t *context, coap_resource_t *resource,
|
|
coap_session_t *session, coap_pdu_t *request, coap_binary_t *token,
|
|
coap_string_t *query, coap_pdu_t *response) {
|
|
|
|
unsigned char buf[40];
|
|
size_t len;
|
|
time_t now;
|
|
/* Remove (void) definition if variable is used */
|
|
(void)context;
|
|
|
|
/* ... 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 'now' is not valid */
|
|
response->code = COAP_RESPONSE_CODE_NOT_FOUND;
|
|
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.
|
|
*/
|
|
|
|
}
|
|
----
|
|
*Packet Response Handler*
|
|
|
|
[source, c]
|
|
----
|
|
#include <coap@LIBCOAP_API_VERSION@/coap.h>
|
|
|
|
static int check_token(coap_pdu_t *received) {
|
|
/* Remove (void) definition if variable is used */
|
|
(void)received;
|
|
|
|
/* Code to validate the token is what we expect */
|
|
|
|
return 1;
|
|
}
|
|
|
|
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) {
|
|
/* Remove (void) definition if variable is used */
|
|
(void)ctx;
|
|
(void)id;
|
|
|
|
/* 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) {
|
|
coap_log(LOG_INFO, "got RST\n");
|
|
return;
|
|
}
|
|
|
|
/* Output the received data, if any */
|
|
if (COAP_RESPONSE_CLASS(received->code) == 2) {
|
|
/* Additional code to deal with the response */
|
|
|
|
}
|
|
return;
|
|
|
|
}
|
|
----
|
|
|
|
SEE ALSO
|
|
--------
|
|
*coap_observe*(3) and *coap_resource*(3)
|
|
|
|
FURTHER INFORMATION
|
|
-------------------
|
|
See "RFC7252: The Constrained Application Protocol (CoAP)" for further
|
|
information.
|
|
|
|
BUGS
|
|
----
|
|
Please report bugs on the mailing list for libcoap:
|
|
libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
|
|
https://github.com/obgm/libcoap/issues
|
|
|
|
AUTHORS
|
|
-------
|
|
The libcoap project <libcoap-developers@lists.sourceforge.net>
|