COAP_HANDLER(3)

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 <coap2/coap.h> void coap_register_handler(coap_resource_t *resource, unsigned char 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-2, -lcoap-2-gnutls, -lcoap-2-openssl or -lcoap-2-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:
    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&#8217;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:
    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&#8217;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:
    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:
    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:
    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:
    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
#include <coap2/coap.h>
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 'now' 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.
   */
}
Packet Response Handler
#include <coap2/coap.h>
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\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

AUTHORS
The libcoap project <libcoap-developers@lists.sourceforge.net>