riot-ci/RIOT
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

net/nanocoap: rename Options APIs for clarity

Browse Source
This commit is contained in:
Ken Bannister 2019-02-10 08:26:14 -05:00
parent bcb2fa464d
commit 9ce19a9bea
1 changed files with 15 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
sys/include/net/nanocoap.h
View File

@ -62,13 +62,13 @@
* option with the provided value.
*
* For a response with additional CoAP options, start by calling
* coap_build_reply(). Then choose either the minimal API or the struct-based
* coap_build_reply(). Then choose either the Buffer API or the Packet
* API to write the rest of the response. See the instructions in the section
* _Write Options and Payload_ below.
*
* ## Client Operation ##
*
* Choose either the minimal API or the struct-based API to write a request.
* Choose either the Buffer API or the Packet API to write a request.
* Follow the instructions in the section _Write Options and Payload_ below.
*
* To send the message and await the response, see nanocoap_request() as well
@ -85,12 +85,12 @@
*
* nanocoap provides two APIs for writing CoAP options:
*
* - **minimal API** requires only a reference to the buffer for the message.
* - **Buffer API** requires only a reference to the buffer for the message.
* However, the caller must provide the last option number written as well as
* the buffer position. The caller is primarily responsible for tracking and
* managing the space remaining in the buffer.
*
* - **struct-based API** uses a coap_pkt_t struct to conveniently track each
* - **Packet API** uses a coap_pkt_t struct to conveniently track each
* option as it is written and prepare for any payload. The caller must monitor
* space remaining in the buffer; however, the API *will not* write past the
* end of the buffer, and returns -ENOSPC when it is full.
@ -99,14 +99,14 @@
* caller must write options in order by option number (see "CoAP option
* numbers" in [CoAP defines](group__net__coap.html)).
*
* ### Minimal API ###
* ### Buffer API ###
*
* Before starting, ensure the CoAP header has been initialized with
* coap_build_hdr(). For a response, coap_build_reply() includes a call to
* coap_build_hdr(). Use the returned length to track the next position in the
* buffer to write and remaining length.
*
* Next, use the functions in the _Minimal API Options_ section to write each
* Next, use the functions in the _Buffer API Options_ section to write each
* option. These functions require the position in the buffer to start writing,
* and return the number of bytes written.
*
@ -116,13 +116,13 @@
* If there is a payload, append a payload marker (0xFF). Then write the
* payload to within the maximum length remaining in the buffer.
*
* ### Struct-based API ###
* ### Packet API ###
*
* As with the minimal API, first ensure the CoAP header has been initialized
* As with the Buffer API, first ensure the CoAP header has been initialized
* with coap_build_hdr(). Then use coap_pkt_init() to initialize the coap_pkt_t
* struct.
*
* Next, write any options with the functions in the _Struct-based API Options_
* Next, write any options with the functions in the _Packet API Options_
* section. When all options have been added, call coap_opt_finish().
*
* @note You must ensure the buffer has enough space remaining to write each
@ -332,7 +332,7 @@ extern const unsigned coap_resources_numof;
/**
* @name Functions -- Header attributes read/write
* @name Functions -- Header Read/Write
*
* Includes message ID, code, type, token, CoAP version
*/
@ -504,7 +504,7 @@ static inline void coap_hdr_set_type(coap_hdr_t *hdr, unsigned type)
/**
* @name Functions -- Options read
* @name Functions -- Options Read
*
* Read options from a parsed packet.
*/
@ -747,9 +747,9 @@ static inline unsigned coap_szx2size(unsigned szx)
/**
* @name Functions -- Struct-based Options API
* @name Functions -- Options Write Packet API
*
* Use a coap_pkt_t struct to write PDU contents.
* Use a coap_pkt_t struct to manage writing Options to the PDU.
*/
/**
* @brief Encode the given uint option into pkt
@ -838,9 +838,9 @@ ssize_t coap_opt_finish(coap_pkt_t *pkt, uint16_t flags);
/**
* @name Functions -- Minimal API Options
* @name Functions -- Options Write Buffer API
*
* Buffer Write API functions specific to options.
* Write PDU Options directly to the array of bytes for a message.
*/
/**@{*/
/**