'\" t
.\"     Title: coap_observe
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 10/28/2023
.\"    Manual: libcoap Manual
.\"    Source: coap_observe 4.3.4
.\"  Language: English
.\"
.TH "COAP_OBSERVE" "3" "10/28/2023" "coap_observe 4\&.3\&.4" "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_observe, coap_resource_set_get_observable, coap_resource_notify_observers, coap_cancel_observe, coap_session_set_no_observe_cancel \- Work with CoAP observe 
.SH "SYNOPSIS"
.sp
\fB#include <coap3/coap\&.h>\fR
.sp
\fBvoid coap_resource_set_get_observable(coap_resource_t *\fR\fB\fIresource\fR\fR\fB, int \fR\fB\fImode\fR\fR\fB);\fR
.sp
\fBint coap_resource_notify_observers(coap_resource_t *\fR\fB\fIresource\fR\fR\fB, const coap_string_t *\fR\fB\fIquery\fR\fR\fB);\fR
.sp
\fBint coap_cancel_observe(coap_session_t *\fR\fB\fIsession\fR\fR\fB, coap_binary_t *\fR\fB\fItoken\fR\fR\fB, coap_pdu_type_t \fR\fB\fImessage_type\fR\fR\fB);\fR
.sp
\fBvoid coap_session_set_no_observe_cancel(coap_session_t *\fR\fB\fIsession\fR\fR\fB);\fR
.sp
For specific (D)TLS library support, link with \fB\-lcoap\-3\-notls\fR, \fB\-lcoap\-3\-gnutls\fR, \fB\-lcoap\-3\-openssl\fR, \fB\-lcoap\-3\-mbedtls\fR or \fB\-lcoap\-3\-tinydtls\fR\&. Otherwise, link with \fB\-lcoap\-3\fR to get the default (D)TLS library support\&.
.SH "DESCRIPTION"
.sp
RFC7641 extends the CoAP protocol to be able to monitor the state of a resource over time\&.
.sp
This enables clients to "observe" resources with a defined query, i\&.e\&., to retrieve a representation of a resource and keep this representation updated by the server over a period of time\&.
.sp
The server has to flag a resource as "observable", and then the client has to request in a GET request that it wants to observe this resource by the use of the COAP_OPTION_OBSERVE Option with a value of COAP_OBSERVE_ESTABLISH\&. Optionally, the client can specify query options for the resource, or by using a FETCH request instead of a GET to define a query (RFC8132)\&.
.sp
To remove the "observe" subscription, the client has to issue a GET (or FETCH) request with the COAP_OPTION_OBSERVE Option with a value of COAP_OBSERVE_CANCEL using the same token and other options used for making the initial "observe" request\&. Alternatively, "observe" can be cancelled using \fBcoap_cancel_observe\fR() instead\&.
.sp
The underlying library adds in and removes "subscribers" to "observe" the resource as appropriate in the server side logic\&.
.sp
\fBNOTE:\fR COAP_RESOURCE_MAX_SUBSCRIBER may have been defined to limit the number of subscribers to a resource when libcoap was built\&.
.sp
Within the server application, it needs to determine that there is a change of state of the resource under observation, and then cause the CoAP library layer to initiate a "fake GET/FETCH request" so that an observe GET/FETCH response gets sent back to all the clients that are observing the resource\&. The appropriate GET/FETCH handler within the server application is called to fill in the response packet with the appropriate information\&. This "fake GET/FETCH request" is triggered by a call to \fBcoap_resource_notify_observers\fR()\&.
.sp
The call to \fBcoap_io_process\fR() in the main server application i/o loop will do all the necessary processing of sending any outstanding "fake GET/FETCH requests"\&.
.sp
Whenever the server sends a copy of the state of the "observed" resource to the client, it will use the same token used by the client when the client requested the "observe" (or the last token used for a FETCH that spans multiple blocks)\&. The client will receive this observe response in the handler defined by \fBcoap_register_response_handler\fR(3) (with the token updated to the initial token used by the client application for a large FETCH)\&. It is the responsibility of the client application to match the supplied token and update the appropriate internal information\&.
.SH "FUNCTIONS"
.sp
\fBFunction: coap_resource_set_get_observable()\fR
.sp
The \fBcoap_resource_set_get_observable\fR() function enables or disables the observable status of the \fIresource\fR by the setting of \fImode\fR\&. If \fImode\fR is 1, then the \fIresource\fR is observable\&. If \fImode\fR is 0, then the \fIresource\fR is no longer observable\&.
.sp
\fBNOTE:\fR It is not possible for the Unknown Resource, created by \fBcoap_resource_unknown_init\fR(3), to be observable as the Uri\-Path is not known when libcoap creates a "fake GET/FETCH request"\&. The Unknown Resource PUT handler must create a new resource and mark the resource as "observable" if a specific resource needs to be observable\&. The application must then manage the deletion of the resource at the appropriate time\&.
.sp
\fBNOTE:\fR The type (confirmable or non\-confirmable) of the triggered observe GET response is determined not by the initial GET/FETCH request, but independently by the server as per "RFC7641 3\&.5\&. Transmission"\&. This is controlled by the flags (one of COAP_RESOURCE_FLAGS_NOTIFY_NON, COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS or COAP_RESOURCE_FLAGS_NOTIFY_CON) used when creating the resource using \fBcoap_resource_init\fR(3)\&.
.sp
\fBNOTE:\fR Furthermore, the server must send at least one "observe" response as confirmable, when generally sending non\-confirmable, at least every 24 hours as per "RFC7641 4\&.5\&. Transmission"\&. Libcoap automatically handles this by sending every fifth (COAP_OBS_MAX_NON) response as a confirmable response for detection that the client is still responding unless if COAP_RESOURCE_FLAGS_NOTIFY_NON_ALWAYS is set, which is a "RFC7641 4\&.5\&. Transmission" violation, where non\-confirmable "observe" responses are always sent as required by some higher layer protocols\&.
.sp
\fBFunction: coap_resource_notify_observers()\fR
.sp
The \fBcoap_resource_notify_observers\fR() function needs to be called whenever the server application determines that there has been a change to the state of \fIresource\fR\&. The \fIquery\fR parameter is obsolete and ignored\&.
.sp
\fBFunction: coap_cancel_observe()\fR
.sp
The \fBcoap_cancel_observe\fR() function can be used by the client to cancel an observe request that is being tracked\&. This will cause the appropriate PDU to be sent to the server to cancel the observation, based on the \fIsession\fR and \fItoken\fR used to set up the observe and the PDU is of type \fImessage_type\fR (use COAP_MESSAGE_NON or COAP_MESSAGE_CON)\&.
.sp
\fBFunction: coap_session_set_no_observe_cancel()\fR
.sp
The \fBcoap_session_set_no_observe_cancel\fR() function can be called by the client to disable calling \fBcoap_cancel_observe\fR() when the \fIsession\fR is being closed down / freed off\&. \fBcoap_cancel_observe\fR() can still be called directly by the client application\&.
.SH "RETURN VALUES"
.sp
\fBcoap_resource_notify_observers\fR() returns 0 if not observable or no observers, 1 on success\&.
.sp
\fBcoap_cancel_observe\fR() returns 0 on failure, 1 on success\&.
.SH "EXAMPLES"
.sp
\fBSimple Time Server\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include <coap3/coap\&.h>

#include <stdio\&.h>

coap_resource_t *time_resource = NULL;

/* specific GET "time" handler, called from hnd_get_generic() */

static void
hnd_get_time(coap_resource_t *resource, coap_session_t *session,
const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {

  unsigned char buf[40];
  size_t len;
  time_t now;
  (void)resource;
  (void)session;

  /* \&.\&.\&. 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 */
      coap_pdu_set_code(response, COAP_RESPONSE_CODE_NOT_FOUND);
      return;
    }
    len = strftime((char *)buf, sizeof(buf), "%b %d %H:%M:%S", tmp);
  }
  coap_pdu_set_code(response, COAP_RESPONSE_CODE_CONTENT);
  /*
   * Invoke coap_add_data_large_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\&.
   * ETAG Option added internally with unique value as param set to 0
   *
   * OBSERVE Option added internally if needed within the function
   * BLOCK2 Option added internally if output too large
   * SIZE2 Option added internally
   */
  coap_add_data_large_response(resource, session, request, response,
                               query, COAP_MEDIATYPE_TEXT_PLAIN, 1, 0,
                               len,
                               buf, NULL, NULL);
}

/* Generic GET handler */

static void
hnd_get_generic(coap_resource_t *resource, coap_session_t *session,
const coap_pdu_t *request, const coap_string_t *query, coap_pdu_t *response) {

  coap_str_const_t *uri_path = coap_resource_get_uri_path(resource);

  if (!uri_path) {
    /* Unexpected Failure */
    coap_pdu_set_code(response, COAP_RESPONSE_CODE_BAD_REQUEST);
    return;
  }

  /* Is this the "time" resource" ? */
  if (coap_string_equal(uri_path, coap_make_str_const("time"))) {
    hnd_get_time(resource, session, request, query, response);
    return;
  }

  /* Other resources code */

  /* Failure response */
  coap_pdu_set_code(response, COAP_RESPONSE_CODE_BAD_REQUEST);
}

/* Initialize generic GET handler */

static void
init_resources(coap_context_t *ctx)
{

  coap_resource_t *r;

  /* Create a resource to return return or update time */
  r = coap_resource_init(coap_make_str_const("time"),
                         COAP_RESOURCE_FLAGS_NOTIFY_CON);

  /* We are using a generic GET handler here */
  coap_register_request_handler(r, COAP_REQUEST_GET, hnd_get_generic);

  coap_resource_set_get_observable(r, 1);

  coap_add_resource(ctx, r);
  time_resource = r;

}

int
main(int argc, char *argv[]) {

  coap_context_t *ctx = NULL;
  coap_endpoint_t *ep = NULL;
  coap_address_t addr;
  unsigned wait_ms;
  struct timeval tv_last = {0, 0};

  /* Initialize libcoap library */
  coap_startup();

  /* Remove (void) definition if variable is used */
  (void)argc;
  (void)argv;

  memset (&tv_last, 0, sizeof(tv_last));

  /* Create the libcoap context */
  ctx = coap_new_context(NULL);
  if (!ctx) {
    exit(1);
  }
  /* See coap_block(3) */
  coap_context_set_block_mode(ctx,
                              COAP_BLOCK_USE_LIBCOAP | COAP_BLOCK_SINGLE_BODY);

  coap_address_init(&addr);
  addr\&.addr\&.sa\&.sa_family = AF_INET;
  addr\&.addr\&.sin\&.sin_port = ntohs(COAP_DEFAULT_PORT);
  ep = coap_new_endpoint(ctx, &addr, COAP_PROTO_UDP);

  /* Other Set up Code */

  init_resources(ctx);

  wait_ms = COAP_RESOURCE_CHECK_TIME * 1000;

  while (1) {
    int result = coap_io_process( ctx, wait_ms );
    if ( result < 0 ) {
      break;
    } else if ( result && (unsigned)result < wait_ms ) {
      /* decrement if there is a result wait time returned */
      wait_ms \-= result;
    } else {
      /*
       * result == 0, or result >= wait_ms
       * (wait_ms could have decremented to a small value, below
       * the granularity of the timer in coap_io_process() and hence
       * result == 0)
       */
      wait_ms = COAP_RESOURCE_CHECK_TIME * 1000;
    }
    if (time_resource) {
      struct timeval tv_now;
      if (gettimeofday (&tv_now, NULL) == 0) {
        if (tv_last\&.tv_sec != tv_now\&.tv_sec) {
          /* Happens once per second */
          tv_last = tv_now;
          coap_resource_notify_observers(time_resource, NULL);
        }
        /* need to wait until next second starts if wait_ms is too large */
        unsigned next_sec_ms = 1000 \- (tv_now\&.tv_usec / 1000);

        if (next_sec_ms && next_sec_ms < wait_ms)
          wait_ms = next_sec_ms;
      }
    }
  }
  coap_free_context(ctx);
  coap_cleanup();
  exit(0);

}
.fi
.if n \{\
.RE
.\}
.sp
\fBClient Observe Request Setup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include <coap3/coap\&.h>

/* Usually, requests are sent confirmable */

static unsigned char msgtype = COAP_MESSAGE_CON;

static unsigned int token = 0;

static coap_pdu_t *
coap_new_request(coap_context_t *context, coap_session_t *session, char request_code,
coap_optlist_t **options, unsigned char *data, size_t length, int observe) {

  coap_pdu_t *pdu;
  /* Remove (void) definition if variable is used */
  (void)context;

  /* Create the pdu with the appropriate options */
  pdu = coap_pdu_init(msgtype, request_code, coap_new_message_id(session),
                      coap_session_max_pdu_size(session));
  if (!pdu)
    return NULL;

  /*
   * Create uniqueness token for this request for handling unsolicited /
   * delayed responses
   */
  token++;
  if (!coap_add_token(pdu, sizeof(token), (unsigned char*)&token)) {
    coap_log_debug("cannot add token to request\en");
    goto error;
  }

  if (request_code == COAP_REQUEST_GET && observe) {
    /* Indicate that we want to observe this resource */
    if (!coap_insert_optlist(options,
                             coap_new_optlist(COAP_OPTION_OBSERVE,
                                         COAP_OBSERVE_ESTABLISH, NULL)))
      goto error;
  }

  /* \&.\&.\&. Other code / options etc\&. \&.\&.\&. */

  /* Add in all the options (after internal sorting) to the pdu */
  if (!coap_add_optlist_pdu(pdu, options))
    goto error;

  if (data && length) {
    /* Add in the specified data */
    if (!coap_add_data(pdu, length, data))
      goto error;
  }

  return pdu;

error:

  coap_delete_pdu(pdu);
  return NULL;

}
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBcoap_block\fR(3), \fBcoap_context\fR(3), \fBcoap_handler\fR(3), \fBcoap_init\fR(3), \fBcoap_pdu_setup\fR(3), \fBcoap_resource\fR(3) and \fBcoap_session\fR(3)
.SH "FURTHER INFORMATION"
.sp
See
.sp
"RFC7252: The Constrained Application Protocol (CoAP)"
.sp
"RFC7641: Observing Resources in the Constrained Application Protocol (CoAP)"
.sp
"RFC8132: PATCH and FETCH Methods for the Constrained Application Protocol (CoAP)"
.sp
for further information\&.
.SH "BUGS"
.sp
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
.SH "AUTHORS"
.sp
The libcoap project <libcoap\-developers@lists\&.sourceforge\&.net>