From 164eef538b32c3e4a6e9b94cfd74015dcb72e352 Mon Sep 17 00:00:00 2001 From: Jon Shallow Date: Fri, 11 Jan 2019 16:39:02 +0000 Subject: [PATCH] Clarify coap_add_data_blocked_response() usage include/coap2/block.h man/coap_pdu_setup.txt.in Update documentation on coap_add_data_blocked_response() usage. --- include/coap2/block.h | 9 +++++---- man/coap_pdu_setup.txt.in | 10 ++++++++-- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/include/coap2/block.h b/include/coap2/block.h index 4c4bcde2..1e112e1c 100644 --- a/include/coap2/block.h +++ b/include/coap2/block.h @@ -139,9 +139,10 @@ int coap_add_block(coap_pdu_t *pdu, unsigned char block_szx); /** - * Adds the @p data to the @p response pdu. If blocks are - * required, then the appropriate block will be added and - * consequently sent. + * Adds the appropriate part of @p data to the @p response pdu. If blocks are + * required, then the appropriate block will be added to the PDU and sent. + * Adds a ETAG option that is the hash of the entire data if the data is to be + * split into blocks * Used by a GET request handler. * * @param resource The resource the data is associated with. @@ -153,7 +154,7 @@ int coap_add_block(coap_pdu_t *pdu, * @param maxage The maxmimum life of the data. If @c -1, then there * is no maxage. * @param length The total length of the data. - * @param data The data to transmit. + * @param data The entire data block to transmit. * */ void diff --git a/man/coap_pdu_setup.txt.in b/man/coap_pdu_setup.txt.in index 7cf4410a..03679356 100644 --- a/man/coap_pdu_setup.txt.in +++ b/man/coap_pdu_setup.txt.in @@ -181,14 +181,20 @@ The *coap_add_data*() function adds in the specified payload _data_ of length _length_ to the PDU _pdu_. Adding the payload data must be done after any token or options are added. This function must only be called once per _pdu_. -The *coap_add_data_blocked_response*() function added in the specified payload -_data_ of length _length_ to the PDU _pdu_. It also adds in the appropriate +The *coap_add_data_blocked_response*() function adds in the appropriate part +of the payload _data_ of length _length_ to the PDU _pdu_. It should be used +as a direct replacement for *coap_add_data*() if it is possible that the data +will not fit into a single pdu. It also adds in the appropriate CoAP options to handle Block-Wise transfer. This function is usually used for a server's GET response. The _resource_, _session_, _request_, _response_ and _token_ are the same parameters for the registered GET resource handler. The _media_type_ is for the format of the _data_ and _maxage_ defines the lifetime of the response. If set to -1, then the MAXAGE option does not get included. This function must only be called once per _pdu_. +It is the responsibility of the client to recognize that it has only +received a part of the data and request the next block (with the appropriate +Block options) from the server. Returning the next requested block is handled +by this function. The *coap_encode_var_safe*() function encodes _value_ into _buffer_ which has a size of _size_ in bytes. Normally, the _buffer_ size should be at least