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. * option with the provided value.
* *
* For a response with additional CoAP options, start by calling * 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 * API to write the rest of the response. See the instructions in the section
* _Write Options and Payload_ below. * _Write Options and Payload_ below.
* *
* ## Client Operation ## * ## 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. * Follow the instructions in the section _Write Options and Payload_ below.
* *
* To send the message and await the response, see nanocoap_request() as well * 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: * 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 * However, the caller must provide the last option number written as well as
* the buffer position. The caller is primarily responsible for tracking and * the buffer position. The caller is primarily responsible for tracking and
* managing the space remaining in the buffer. * 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 * 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 * space remaining in the buffer; however, the API *will not* write past the
* end of the buffer, and returns -ENOSPC when it is full. * 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 * caller must write options in order by option number (see "CoAP option
* numbers" in [CoAP defines](group__net__coap.html)). * numbers" in [CoAP defines](group__net__coap.html)).
* *
* ### Minimal API ### * ### Buffer API ###
* *
* Before starting, ensure the CoAP header has been initialized with * 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(). For a response, coap_build_reply() includes a call to
* coap_build_hdr(). Use the returned length to track the next position in the * coap_build_hdr(). Use the returned length to track the next position in the
* buffer to write and remaining length. * 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, * option. These functions require the position in the buffer to start writing,
* and return the number of bytes written. * and return the number of bytes written.
* *
@ -116,13 +116,13 @@
* If there is a payload, append a payload marker (0xFF). Then write the * If there is a payload, append a payload marker (0xFF). Then write the
* payload to within the maximum length remaining in the buffer. * 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 * with coap_build_hdr(). Then use coap_pkt_init() to initialize the coap_pkt_t
* struct. * 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(). * section. When all options have been added, call coap_opt_finish().
* *
* @note You must ensure the buffer has enough space remaining to write each * @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 * 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. * 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 * @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.
*/ */
/**@{*/ /**@{*/
/** /**