CoAP struct-based Options API

[kb2ma]

nanocoap and gcoap's APIs, particularly for CoAP Option handling, have developed as needed. Recently #8772 reworked how options are referenced in the coap_pkt_t struct for scalability. In addition the number of Option API functions has grown to the point where they make up a significant portion of the overall API. This issue describes how we plan to update the APIs to accommodate these changes.

#9085 introduced a more convenient, struct-based API for writing CoAP Options. It also introduced a more structured naming scheme to manage the large number of convenience functions for these options, for example in #8920 for string-based options.

The struct-based API also brings the nanocoap and gcoap APIs much closer together. In fact the gcoap API becomes mostly convenience/sugar on the struct-based API. See API Options for details.

The table below shows the steps to fully incorporate the struct-based Options API. See the project page for implementation status.

Subject	Library	Description
API definition and 'add' functions	nanocoap	Use a coap_pkt_t when build a message and add coap_opt_add_xxx() functions.
'add' option functions	gcoap	Use coap_opt_add_xxx() functions within gcoap
uint option functions	nanocoap	Create coap_opt_add_xxx(), coap_opt_put_xxx(), and coap_get_xxx() functions for uint-based options, like Content-Format
string option functions	nanocoap	Create coap_opt_add_xxx(), coap_opt_put_xxx(), and coap_get_xxx() functions for string-based options, like Uri-Path and Uri-Query; adapt #8920
module level documentation	nanocoap	Document the API and provide direction on how to use it. See doc page for the concept.
API update for 'finish' functions	gcoap	Deprecate use of gcoap_finish() after payload is written, in favor of coap_opt_finish() before payload is written. Simplifies implementation and removes gcoap-specific code.

[kYc0o]

@kb2ma would you mind to have "ticks" on the related PRs in the description? This way the progress can be seen in a more abstract view.

[kb2ma]

I tried to include ticks in the table, but can't figure out how to do it, so used strikethrough instead to show completion. Which is more important, the ticks or the table?

[kYc0o]

Ok I see, of course the table is more important! No doubt about it. I'll then link this issue to the project and add the ticks there.

Thanks for tackling this!

[miri64]

How about a project to organize this and have an overview? I did the same for 6Lo refactoring

[kb2ma]

How about a project to organize this and have an overview?

Thanks @kYc0o, and nice idea, @miri64! I'll keep this issue but focus it on Options and remove the PR references. I'll create a project for the Options work and include a link to this issue. I'll also remove the references to confirmable messaging, Observe, and Block. Those really are part of the Network Stack High Layers project.

[kb2ma]

No thanks on the ticks. This issue is almost ready to be closed. We are of course always happy to receive feedback or improvements on the feature itself.

[kb2ma]

Done! Thanks to everyone for helping with the migration. Once gcoap_add_string() and gcoap_finish() are actually removed, gcoap.h will contain only functions that are specific to gcoap, mostly how it sends and receives messages.

[leandrolanzieri]

@kb2ma can the related GitHub project be closed?

[kb2ma]

Leaving the project open was an oversight; thanks for noticing. I just closed it.