'\" t
.\" Title: coap_pdu_setup
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 05/14/2022
.\" Manual: libcoap Manual
.\" Source: coap_pdu_setup 4.2.1
.\" Language: English
.\"
.TH "COAP_PDU_SETUP" "3" "05/14/2022" "coap_pdu_setup 4\&.2\&.1" "libcoap Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
coap_pdu_setup, coap_pdu_init, coap_add_token, coap_new_optlist, coap_insert_optlist, coap_delete_optlist, coap_add_optlist_pdu, coap_add_option, coap_add_data \- Work with CoAP PDUs
.SH "SYNOPSIS"
.sp
\fB#include \fR
.sp
\fBcoap_pdu_t *coap_pdu_init(uint8_t \fR\fB\fItype\fR\fR\fB, uint8_t \fR\fB\fIcode\fR\fR\fB, uint16_t \fR\fB\fImessage_id\fR\fR\fB, size_t \fR\fB\fImax_size\fR\fR\fB);\fR
.sp
\fBint coap_add_token(coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB, const uint8_t *\fR\fB\fIdata\fR\fR\fB);\fR
.sp
\fBcoap_optlist_t *coap_new_optlist(uint16_t \fR\fB\fInumber\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB, const uint8_t *\fR\fB\fIdata\fR\fR\fB);\fR
.sp
\fBint coap_insert_optlist(coap_optlist_t **\fR\fB\fIoptlist_chain\fR\fR\fB, coap_optlist_t *\fR\fB\fIoptlist\fR\fR\fB);\fR
.sp
\fBvoid coap_delete_optlist(coap_optlist_t *\fR\fB\fIoptlist_chain\fR\fR\fB);\fR
.sp
\fBint coap_add_optlist_pdu(coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB, coap_optlist_t **\fR\fB\fIoptlist_chain\fR\fR\fB);\fR
.sp
\fBsize_t coap_add_option(coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB, uint16_t \fR\fB\fInumber\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB, const uint8_t *\fR\fB\fIdata\fR\fR\fB);\fR
.sp
\fBint coap_add_data(coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB, const uint8_t *\fR\fB\fIdata\fR\fR\fB);\fR
.sp
\fBvoid coap_add_data_blocked_response(coap_resource_t *\fR\fB\fIresource\fR\fR\fB, coap_session_t *\fR\fB\fIsession\fR\fR\fB, coap_pdu_t *\fR\fB\fIrequest\fR\fR\fB, coap_pdu_t *\fR\fB\fIresponse\fR\fR\fB, const coap_binary_t *\fR\fB\fItoken\fR\fR\fB, uint16_t \fR\fB\fImedia_type\fR\fR\fB, int \fR\fB\fImaxage\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB, const uint8_t\fR \fIdata\fR);
.sp
\fBunsigned int coap_encode_var_safe(uint8_t *\fR\fB\fIbuffer\fR\fR\fB, size_t \fR\fB\fIsize\fR\fR\fB, unsigned int \fR\fB\fIvalue\fR\fR\fB);\fR
.sp
\fBint coap_split_path(const uint8_t *\fR\fB\fIpath\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB, uint8_t *\fR\fB\fIbuffer\fR\fR\fB, size_t *\fR\fB\fIbuflen\fR\fR\fB);\fR
.sp
\fBint coap_split_query(const uint8_t *\fR\fB\fIquery\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB, uint8_t *\fR\fB\fIbuffer\fR\fR\fB, size_t *\fR\fB\fIbuflen\fR\fR\fB);\fR
.sp
Link with \fB\-lcoap\-2\fR, \fB\-lcoap\-2\-gnutls\fR, \fB\-lcoap\-2\-openssl\fR or \fB\-lcoap\-2\-tinydtls\fR depending on your (D)TLS library type\&.
.SH "DESCRIPTION"
.sp
The CoAP PDU is of the form
.sp
\-\-header\-\-|\-\-optional token\-\-|\-\-optional options\-\-|\-\-optional payload\-\-
.sp
The PDU must be built in the correct order, from left to right\&. In particular, the options need to be added in the correct numerical option order as they are stored in the PDU using relative numeric offsets from the previous option number\&.
.sp
There are option list functions available where options can be added to a chained list of options and then the chain list is sorted and then be added to the PDU\&.
.sp
Typically for clients, when creating a request, the PDU needs to be created before filling it with the appropriate information\&.
.sp
Typically with a server, the response PDU, with the optional token already added in, will already be created before the response handler is called, and the response PDU will need to be updated as appropriate starting with the optional options\&. Note that updating the response pdu\(cqs code variable will cause the response pdu to get transmitted\&. If code does not get updated, then the response pdu is freed off by the underlying library\&.
.sp
The \fBcoap_pdu_init\fR() function returns a newly created \fIPDU\fR of type \fIcoap_pdu_t\fR*\&. \fItype\fR is one of the following
.TS
tab(:);
lt lt
lt lt
lt lt
lt lt.
T{
.sp
\fBCOAP_MESSAGE_CON\fR
T}:T{
.sp
Set the \fIPDU\fR to be of type confirmable\&.
T}
T{
.sp
\fBCOAP_MESSAGE_NON\fR
T}:T{
.sp
Set the \fIPDU\fR to be of type non\-confirmable\&.
T}
T{
.sp
\fBCOAP_MESSAGE_ACK\fR
T}:T{
.sp
Set the \fIPDU\fR to be of type acknowledge (for internal use)\&.
T}
T{
.sp
\fBCOAP_MESSAGE_RST\fR
T}:T{
.sp
Set the \fIPDU\fR to be of type reset\&.
T}
.TE
.sp 1
.sp
The \fIcode\fR is one of the following
.TS
tab(:);
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt.
T{
.sp
\fBCOAP_REQUEST_GET\fR
T}:T{
.sp
Set the \fIPDU\fR request to be of type GET\&.
T}
T{
.sp
\fBCOAP_REQUEST_POST\fR
T}:T{
.sp
Set the \fIPDU\fR request to be of type POST\&.
T}
T{
.sp
\fBCOAP_REQUEST_PUT\fR
T}:T{
.sp
Set the \fIPDU\fR request to be of type PUT\&.
T}
T{
.sp
\fBCOAP_REQUEST_DELETE\fR
T}:T{
.sp
Set the \fIPDU\fR request to be of type DELETE\&.
T}
T{
.sp
\fBCOAP_REQUEST_FETCH\fR
T}:T{
.sp
Set the \fIPDU\fR request to be of type FETCH\&.
T}
T{
.sp
\fBCOAP_REQUEST_PATCH\fR
T}:T{
.sp
Set the \fIPDU\fR request to be of type PATCH\&.
T}
T{
.sp
\fBCOAP_REQUEST_IPATCH\fR
T}:T{
.sp
Set the \fIPDU\fR request to be of type IPATCH\&.
T}
.TE
.sp 1
.sp
The \fImessage_id\fR must be unique per request (which is not the same as the token), and must not be reused within EXCHANGE_LIFETIME (usually 247 seconds)\&. To automate this, the function coap_new_message_id(session) should be called\&.
.sp
The \fImax_size\fR parameter defines the maximum size of a \fIPDU\fR and is usually determined by calling coap_session_max_pdu_size(session);
.sp
The \fBcoap_add_token\fR() function adds in the specified token\(cqs \fIdata\fR of length \fIlength\fR to the PDU \fIpdu\fR\&. The maximum length of the token is 8 bytes\&. Adding the token must be done before any options or data are added\&. This function must only be called once per \fIpdu\fR, and must not be called in the appropriate response handler\&.
.sp
The \fBcoap_new_optlist\fR() function returns a newly created \fIoptlist\fR entry of type \fIcoap_optlist_t\fR*\&. The \fInumber\fR specifies which CoAP option is to be used, and is one of the COAP_OPTION_* definitions\&. The \fIlength\fR is the length of the data of the option, and \fIdata\fR points to the content of the option\&.
.sp
The following is the current list of options with their numeric value
.sp
.if n \{\
.RS 4
.\}
.nf
#define COAP_OPTION_IF_MATCH 1 /* opaque, 0\-8 B */
#define COAP_OPTION_URI_HOST 3 /* String, 1\-255 B */
#define COAP_OPTION_ETAG 4 /* opaque, 1\-8 B */
#define COAP_OPTION_IF_NONE_MATCH 5 /* empty, 0 B */
#define COAP_OPTION_OBSERVE 6 /* empty/uint, 0 B/0\-3 B */
#define COAP_OPTION_URI_PORT 7 /* uint, 0\-2 B */
#define COAP_OPTION_LOCATION_PATH 8 /* String, 0\-255 B */
#define COAP_OPTION_URI_PATH 11 /* String, 0\-255 B */
#define COAP_OPTION_CONTENT_FORMAT 12 /* uint, 0\-2 B */
#define COAP_OPTION_MAXAGE 14 /* uint, 0\-4 B, default 60 Seconds */
#define COAP_OPTION_URI_QUERY 15 /* String, 1\-255 B */
#define COAP_OPTION_ACCEPT 17 /* uint, 0\-2 B */
#define COAP_OPTION_LOCATION_QUERY 20 /* String, 0\-255 B */
#define COAP_OPTION_BLOCK2 23 /* uint, 0\-3 B */
#define COAP_OPTION_BLOCK1 27 /* uint, 0\-3 B */
#define COAP_OPTION_SIZE2 28 /* uint, 0\-4 B */
#define COAP_OPTION_PROXY_URI 35 /* String, 1\-1034 B */
#define COAP_OPTION_PROXY_SCHEME 39 /* String, 1\-255 B */
#define COAP_OPTION_SIZE1 60 /* uint, 0\-4 B */
#define COAP_OPTION_NORESPONSE 258 /* uint, 0\-1 B */
.fi
.if n \{\
.RE
.\}
.sp
See FURTHER INFORMATION as to how to get the latest list\&.
.sp
The \fBcoap_insert_optlist\fR() function adds the \fIoptlist\fR entry onto the \fIoptlist_chain\fR and then sorts the \fIoptlist_chain\fR before returning\&. The initial \fIoptlist_chain\fR entry needs to be set to NULL before this function is first called\&. The coap_delete_optlist() function has to be called to free off all the \fIoptlist_chain\fR entries\&.
.sp
The \fBcoap_delete_optlist\fR() function deletes and frees off all the optlist entries in the \fIoptlist_chain\fR\&.
.sp
The \fBcoap_add_optlist_pdu\fR() function sorts all of the entries in \fIoptlist_chain\fR into ascending option numeric order and adds all the entries to the \fIpdu\fR\&. This function does not free off the entries in \fIoptlist_chain\fR\&. This function must be called after adding any token and before adding in the payload data\&.
.sp
The \fBcoap_add_option\fR() function adds in the specified option of type \fInumber\fR with \fIdata\fR of length \fIlength\fR to the PDU \fIpdu\fR\&. It is critical that options are added to the \fIpdu\fR with \fInumber\fR either being the same or greater than the previous option \fInumber\fR that was added\&.
.sp
The \fBcoap_add_data\fR() function adds in the specified payload \fIdata\fR of length \fIlength\fR to the PDU \fIpdu\fR\&. Adding the payload data must be done after any token or options are added\&. This function must only be called once per \fIpdu\fR\&.
.sp
The \fBcoap_add_data_blocked_response\fR() function adds in the appropriate part of the payload \fIdata\fR of length \fIlength\fR to the PDU \fIpdu\fR\&. It should be used as a direct replacement for \fBcoap_add_data\fR() 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\(cqs GET response\&. The \fIresource\fR, \fIsession\fR, \fIrequest\fR, \fIresponse\fR and \fItoken\fR are the same parameters for the registered GET resource handler\&. The \fImedia_type\fR is for the format of the \fIdata\fR and \fImaxage\fR 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 \fIpdu\fR\&. 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\&.
.sp
The \fBcoap_encode_var_safe\fR() function encodes \fIvalue\fR into \fIbuffer\fR which has a size of \fIsize\fR in bytes\&. Normally, the \fIbuffer\fR size should be at least the sizeof(int) bytes unless you definitely know less space is required\&.
.sp
The \fBcoap_split_path\fR() function splits up \fIpath\fR of length \fIlength\fR and places the result in \fIbuffer\fR which has a size of \fIbuflen\fR\&. \fIbuflen\fR needs to be preset with the size of \fIbuffer\fR before the function call, and then \fIbuflen\fR is updated with the actual size of \fIbuffer\fR used\&.
.sp
The \fBcoap_split_query\fR() function splits up \fIquery\fR of length \fIlength\fR and places the result in \fIbuffer\fR which has a size of \fIbuflen\fR\&. \fIbuflen\fR needs to be preset with the size of \fIbuffer\fR before the function call, and then \fIbuflen\fR is updated with the actual size of \fIbuffer\fR used\&.
.SH "RETURN VALUES"
.sp
The \fBcoap_pdu_init\fR() function returns a newly created \fIPDU\fR or NULL if there is a malloc or parameter failure\&.
.sp
The \fBcoap_new_optlist\fR() function returns a newly created \fIoptlist\fR or NULL if there is a malloc failure\&.
.sp
The \fBcoap_add_token\fR(), \fBcoap_insert_optlist\fR(), \fBcoap_delete_optlist\fR(), \fBcoap_add_optlist_pdu\fR() and \fBcoap_add_data\fR() functions return 0 on failure, 1 on success\&.
.sp
The \fBcoap_add_optlist\fR() function returns either the length of the option or 0 on failure\&.
.sp
The \fBcoap_encode_var_safe\fR() function returns either the length of bytes encoded or 0 on failure\&.
.SH "EXAMPLES"
.sp
\fBSetup PDU and Transmit\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include
static int token = 0;
int
build_send_pdu(coap_context_t *context, coap_session_t *session,
uint8_t msgtype, uint8_t request_code, const char *uri, const char *query,
unsigned char *data, size_t length, int observe) {
coap_pdu_t *pdu;
(void)context;
char buf[1024];
size_t buflen;
char *sbuf = buf;
int res;
coap_optlist_t *optlist_chain = NULL;
/* Create the pdu with the appropriate options */
pdu = coap_pdu_init(msgtype, request_code, coap_new_message_id(session),
coap_session_max_pdu_size(session));
if (!pdu)
return 0;
/*
* Create uniqueness token for this request for handling unsolicited /
* delayed responses
*/
token++;
if (!coap_add_token(pdu, sizeof(token), (unsigned char*)&token)) {
coap_log(LOG_DEBUG, "cannot add token to request\en");
goto error;
}
if (uri) {
/* Add in the URI options */
buflen = sizeof(buf);
res = coap_split_path((const uint8_t*)uri, strlen(uri), sbuf, &buflen);
while (res\-\-) {
if (!coap_insert_optlist(&optlist_chain,
coap_new_optlist(COAP_OPTION_URI_PATH,
coap_opt_length(sbuf), coap_opt_value(sbuf))))
goto error;
sbuf += coap_opt_size(sbuf);
}
}
if (query) {
/* Add in the QUERY options */
buflen = sizeof(buf);
res = coap_split_query((const uint8_t*)query, strlen(query), sbuf, &buflen);
while (res\-\-) {
if (!coap_insert_optlist(&optlist_chain,
coap_new_optlist(COAP_OPTION_URI_QUERY,
coap_opt_length(sbuf), coap_opt_value(sbuf))))
goto error;
sbuf += coap_opt_size(sbuf);
}
}
if (request_code == COAP_REQUEST_GET && observe) {
/* Indicate that we want to observe this resource */
if (!coap_insert_optlist(&optlist_chain,
coap_new_optlist(COAP_OPTION_OBSERVE,
COAP_OBSERVE_ESTABLISH, NULL)))
goto error;
}
/* \&.\&.\&. Other code / options etc\&. \&.\&.\&. */
/* Add in all the options (after internal sorting) to the pdu */
if (!coap_add_optlist_pdu(pdu, &optlist_chain))
goto error;
if (data && length) {
/* Add in the specified data */
if (!coap_add_data(pdu, length, data))
goto error;
}
if (coap_send(session, pdu) == COAP_INVALID_TID)
goto error;
return 1;
error:
if (pdu)
coap_pdu_delete(pdu);
return 0;
}
.fi
.if n \{\
.RE
.\}
.sp
\fBResource Handler Response PDU Update\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include
static void
hnd_get_time(coap_context_t *context, coap_resource_t *resource,
coap_session_t *session, coap_pdu_t *request, coap_string_t *token,
coap_string_t *query, coap_pdu_t *response) {
unsigned char buf[40];
size_t len;
time_t now;
/* \&.\&.\&. Additional analysis code for resource, request pdu etc\&. \&.\&.\&. */
/* After analysis, generate a suitable response */
/* Note that token, if set, is already in the response pdu */
now = time(NULL);
if (query != NULL && coap_string_equal(query, coap_make_str_const("secs"))) {
/* Output secs since Jan 1 1970 */
len = snprintf((char *)buf, sizeof(buf), "%lu", now);
}
else {
/* Output human\-readable time */
struct tm *tmp;
tmp = gmtime(&now);
if (!tmp) {
/* If \*(Aqnow\*(Aq is not valid */
response\->code = COAP_RESPONSE_CODE(404);
return;
}
len = strftime((char *)buf, sizeof(buf), "%b %d %H:%M:%S", tmp);
}
/*
* Invoke coap_add_data_blocked_response() to do all the hard work\&.
*
* Define the format \- COAP_MEDIATYPE_TEXT_PLAIN \- to add in
* Define how long this response is valid for (secs) \- 1 \- to add in\&.
*
* OBSERVE Option added internally if needed within the function
* BLOCK2 Option added internally if output too large
* ETAG Option added internally
*/
coap_add_data_blocked_response(resource, session, request, response, token,
COAP_MEDIATYPE_TEXT_PLAIN, 1,
len,
buf);
/*
* As resource\->code has been updated in coap_add_data_blocked_response(),
* the response pdu will be transmitted by the underlying library\&.
*/
}
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBcoap_observe\fR(3), \fBcoap_resource\fR(3)
.SH "FURTHER INFORMATION"
.sp
See "RFC7252: The Constrained Application Protocol (CoAP)" for further information\&.
.sp
See https://www\&.iana\&.org/assignments/core\-parameters/core\-parameters\&.xhtml#option\-numbers for the current set of defined CoAP Options\&.
.SH "BUGS"
.sp
Please report bugs on the mailing list for libcoap: libcoap\-developers@lists\&.sourceforge\&.net
.SH "AUTHORS"
.sp
The libcoap project