commit 98f930c793c0eca9bfc9d3d166989b1f79c3bf53
author Stuart Longland <stuartl@vrt.com.au> Fri Feb 28 00:46:43 2020 -0500
committer GitHub <noreply@github.com> Thu Feb 27 21:46:43 2020 -0800
tree 9c127aff4eadf45ef534ecf13797ce3aeeae91d0
parent 904719079d82fe4e43164359e9039fb6c991af3c

[coap] add support for RFC7641 (#4396)

* [coap] Add option scanning functions

In a few places in the OpenThread code-base, the following construct is
seen:

```
    otCoapOptionIterator iterator;
    otCoapOptionIteratorInit(&iterator, message);

    for (const otCoapOption *opt = otCoapOptionIteratorGetFirstOption(&iterator);
                             opt != NULL;
                             opt = otCoapOptionIteratorGetNextOption(&iterator))
    {
        if (opt->mNumber == OT_COAP_OPTION_DESIREDOPTION)
        {
            doSomethingWith(opt);
            break;
        }
    }
```

or its equivalent.  In cases where multiple options are sought, the
above is still the better approach (using a `switch` statement), but
otherwise this seems repetitive.

`otCoapOptionIteratorGetFirstOptionMatching` basically implements the
above loop, returning the first option that matches.  This same code can
also be used for testing for presence too by comparing the resultant
pointer to the `NULL` singleton.

For completeness in cases where a software developer may want to
*resume* looking for further matching options,
`otCoapOptionIteratorGetNextOptionMatching` is also provided.

* [coap] Add function for decoding Uint options

To properly implement features such as RFC7641 and RFC7959, one must be
able to decode unsigned integer options.  It seems silly to have an
encoder but not a decoder, so here is the missing piece.

Future considerations may be a `uint32_t` version since the majority of
use cases do not call for a `uint64_t`; the type was chosen since it was
the most general case.

* [coap] Reference the RFC for the Observe option.

For the sake of completeness, reference the relevant RFC in the
documentation so that developers can read up more on how it should work.

* [coap] Add mObserve flag to metadata.

When we're implementing observations, a few exceptions to the usual CoAP
conventions apply, notably:

- when we receive the initial reply, the request is _not_ finished, we
  will receive subsequent requests until we tell the server to stop.
- when we send a confirmable notification, the observing client will
  reply with an `ACK` with no further traffic: we need to differentiate
  this from an empty `ACK` to a request meaning we should expect a reply
  later.

While we could just repeatedly scan for the `Observe` option on the
request, that is wasteful in terms of processing time.  This allows us
to scan the request just once, and set a single-bit flag to save
processing later.

* [coap] Don't expect traffic after ACK to notification

If the client sends an empty `ACK` in reply to a confirmable RFC7641
notification, we will _NOT_ see further replies with additional
information.  Consider the notification as acknowledged and pass the
details back to the application.

* [coap] Pass through notifications to handler

Ensure that all notifications sent by the CoAP server are passed back to
the application's CoAP request handler.  When we receive the first one,
the request continues -- it does not finish until the server drops the
`Observe` flag or we tell the server to stop.

* [coap] Disable expiry timer once subscribed

If a request carries `Observe=0` and we receive the first reply, ignore
future time-out events as the transaction will finish only when
explicitly terminated.

* [coap] Support eager subscription cancellation

A CoAP client may signal its intention to unsubscribe from a resource by
sending a `GET` request with a token matching that of the original
request and setting the `Observe` option to the value 1.

In the event the application does this, we should pick this up and
cancel the pending transaction locally.  The handler will be notified of
this by a final call where `aError=OT_ERROR_NONE` and no message given.

* [cli] Add RFC7641 support to CLI example

As an aide to those developing code that uses RFC7641, implement an
example client and server that supports this feature.