'\" t
.\" Title: coap_pdu_access
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 10/28/2023
.\" Manual: libcoap Manual
.\" Source: coap_pdu_access 4.3.4
.\" Language: English
.\"
.TH "COAP_PDU_ACCESS" "3" "10/28/2023" "coap_pdu_access 4\&.3\&.4" "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_access, coap_check_option, coap_decode_var_bytes, coap_decode_var_bytes8, coap_get_data, coap_opt_length, coap_opt_value, coap_option_filter_clear, coap_option_filter_get, coap_option_filter_set, coap_option_filter_unset, coap_option_iterator_init, coap_option_next, coap_pdu_get_code, coap_pdu_get_mid, coap_pdu_get_token, coap_pdu_get_type, coap_get_uri_path \- Accessing CoAP PDUs
.SH "SYNOPSIS"
.sp
\fB#include \fR
.sp
\fBcoap_opt_t *coap_check_option(const coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB, coap_option_num_t \fR\fB\fInumber\fR\fR\fB, coap_opt_iterator_t *\fR\fB\fIoi\fR\fR\fB);\fR
.sp
\fBunsigned int coap_decode_var_bytes(const uint8_t *\fR\fB\fIbuf\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB);\fR
.sp
\fBuint64_t coap_decode_var_bytes8(const uint8_t *\fR\fB\fIbuf\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB);\fR
.sp
\fBint coap_get_data(const coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB, size_t *\fR\fB\fIlength, const uint8_t **_data\fR\fR\fB);\fR
.sp
\fBuint32_t coap_opt_length(const coap_opt_t *\fR\fB\fIopt\fR\fR\fB);\fR
.sp
\fBconst uint8_t *coap_opt_value(const coap_opt_t *\fR\fB\fIopt\fR\fR\fB);\fR
.sp
\fBvoid coap_option_filter_clear(coap_opt_filter_t *\fR\fB\fIfilter\fR\fR\fB);\fR
.sp
\fBint coap_option_filter_get(coap_opt_filter_t *\fR\fB\fIfilter\fR\fR\fB, coap_option_num_t \fR\fB\fInumber\fR\fR\fB);\fR
.sp
\fBint coap_option_filter_set(coap_opt_filter_t *\fR\fB\fIfilter\fR\fR\fB, coap_option_num_t \fR\fB\fInumber\fR\fR\fB)\fR;
.sp
\fBint coap_option_filter_unset(coap_opt_filter_t *\fR\fB\fIfilter\fR\fR\fB, coap_option_num_t \fR\fB\fInumber\fR\fR\fB);\fR
.sp
\fBcoap_opt_iterator_t *coap_option_iterator_init(const coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB, coap_opt_iterator_t *\fR\fB\fIoi\fR\fR\fB, const coap_opt_filter_t *\fR\fB\fIfilter\fR\fR\fB);\fR
.sp
\fBcoap_opt_t *coap_option_next(coap_opt_iterator_t *\fR\fB\fIoi\fR\fR\fB);\fR
.sp
\fBcoap_pdu_code_t coap_pdu_get_code(const coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB);\fR
.sp
\fBcoap_mid_t coap_pdu_get_mid(const coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB);\fR
.sp
\fBcoap_bin_const_t coap_pdu_get_token(const coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB);\fR
.sp
\fBcoap_pdu_type_t coap_pdu_get_type(const coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB);\fR
.sp
\fBcoap_string_t *coap_get_uri_path(const coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB);\fR
.sp
For specific (D)TLS library support, link with \fB\-lcoap\-3\-notls\fR, \fB\-lcoap\-3\-gnutls\fR, \fB\-lcoap\-3\-openssl\fR, \fB\-lcoap\-3\-mbedtls\fR or \fB\-lcoap\-3\-tinydtls\fR\&. Otherwise, link with \fB\-lcoap\-3\fR to get the default (D)TLS library support\&.
.SH "DESCRIPTION"
.sp
The CoAP PDU is of the form
.sp
\-\-header\-\-|\-\-optional token\-\-|\-\-optional options\-\-|\-\-optional payload\-\-
.sp
The terminology used is taken mainly from "RFC7252 1\&.2\&. Terminology"\&.
.sp
The following functions provide access to the information held within different parts of a PDU\&.
.SH "PDU HEADER FUNCTIONS"
.sp
\fBFunction: coap_pdu_get_type()\fR
.sp
The \fBcoap_pdu_get_type\fR() function returns one of the messages types below from the PDU \fIpdu\fR header\&.
.sp
.if n \{\
.RS 4
.\}
.nf
COAP_MESSAGE_CON Type confirmable\&.
COAP_MESSAGE_NON Type non\-confirmable\&.
COAP_MESSAGE_ACK Type acknowledge
COAP_MESSAGE_RST Type reset\&.
.fi
.if n \{\
.RE
.\}
.sp
\fBNOTE:\fR For reliable messages RFC8323, this will always return COAP_MESSAGE_CON\&.
.sp
\fBFunction: coap_pdu_get_code()\fR
.sp
The \fBcoap_pdu_get_code\fR() function returns one of the codes below from the PDU \fIpdu\fR header\&. It is possible that new codes are added in over time\&.
.sp
.if n \{\
.RS 4
.\}
.nf
COAP_EMPTY_CODE 0\&.00
COAP_REQUEST_CODE_GET 0\&.01
COAP_REQUEST_CODE_POST 0\&.02
COAP_REQUEST_CODE_PUT 0\&.03
COAP_REQUEST_CODE_DELETE 0\&.04
COAP_REQUEST_CODE_FETCH 0\&.05
COAP_REQUEST_CODE_PATCH 0\&.06
COAP_REQUEST_CODE_IPATCH 0\&.07
COAP_RESPONSE_CODE_OK 2\&.00
COAP_RESPONSE_CODE_CREATED 2\&.01
COAP_RESPONSE_CODE_DELETED 2\&.02
COAP_RESPONSE_CODE_VALID 2\&.03
COAP_RESPONSE_CODE_CHANGED 2\&.04
COAP_RESPONSE_CODE_CONTENT 2\&.05
COAP_RESPONSE_CODE_CONTINUE 2\&.31
COAP_RESPONSE_CODE_BAD_REQUEST 4\&.00
COAP_RESPONSE_CODE_UNAUTHORIZED 4\&.01
COAP_RESPONSE_CODE_BAD_OPTION 4\&.02
COAP_RESPONSE_CODE_FORBIDDEN 4\&.03
COAP_RESPONSE_CODE_NOT_FOUND 4\&.04
COAP_RESPONSE_CODE_NOT_ALLOWED 4\&.05
COAP_RESPONSE_CODE_NOT_ACCEPTABLE 4\&.06
COAP_RESPONSE_CODE_INCOMPLETE 4\&.08
COAP_RESPONSE_CODE_CONFLICT 4\&.09
COAP_RESPONSE_CODE_PRECONDITION_FAILED 4\&.12
COAP_RESPONSE_CODE_REQUEST_TOO_LARGE 4\&.13
COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT 4\&.15
COAP_RESPONSE_CODE_UNPROCESSABLE 4\&.22
COAP_RESPONSE_CODE_TOO_MANY_REQUESTS 4\&.29
COAP_RESPONSE_CODE_INTERNAL_ERROR 5\&.00
COAP_RESPONSE_CODE_NOT_IMPLEMENTED 5\&.01
COAP_RESPONSE_CODE_BAD_GATEWAY 5\&.02
COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE 5\&.03
COAP_RESPONSE_CODE_GATEWAY_TIMEOUT 5\&.04
COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED 5\&.05
COAP_RESPONSE_CODE_HOP_LIMIT_REACHED 5\&.08
COAP_SIGNALING_CODE_CSM 7\&.01
COAP_SIGNALING_CODE_PING 7\&.02
COAP_SIGNALING_CODE_PONG 7\&.03
COAP_SIGNALING_CODE_RELEASE 7\&.04
COAP_SIGNALING_CODE_ABORT 7\&.05
.fi
.if n \{\
.RE
.\}
.sp
\fBNOTE:\fR For reliable messages "ttps://rfc\-editor\&.org/rfc/rfc8323[RFC8323], this will always return COAP_EMPTY_CODE\&.
.sp
\fBFunction: coap_pdu_get_mid()\fR
.sp
The \fBcoap_pdu_get_mid\fR() returns the message id from the PDU \fIpdu\fR header\&.
.sp
\fBNOTE:\fR For reliable messages RFC8323, this will always return 0\&.
.SH "PDU TOKEN FUNCTIONS"
.sp
\fBFunction: coap_pdu_get_token()\fR
.sp
The \fBcoap_pdu_get_token\fR() returns the token information held in the PDU \fIpdu\fR token which may be zero length\&.
.SH "PDU OPTIONS FUNCTIONS"
.sp
The following is the current list of options with their numeric value
.sp
.if n \{\
.RS 4
.\}
.nf
/*
* The C, U, and N flags indicate the properties
* Critical, Unsafe, and NoCacheKey, respectively\&.
* If U is set, then N has no meaning as per
* https://rfc\-editor\&.org/rfc/rfc7252#section\-5\&.10
* and is set to a \-\&.
* Separately, R is for the options that can be repeated
*
* The least significant byte of the option is set as followed
* as per https://rfc\-editor\&.org/rfc/rfc7252#section\-5\&.4\&.6
*
* 0 1 2 3 4 5 6 7
* \-\-+\-\-\-+\-\-\-+\-\-\-+\-\-\-+\-\-\-+\-\-\-+\-\-\-+
* | NoCacheKey| U | C |
* \-\-+\-\-\-+\-\-\-+\-\-\-+\-\-\-+\-\-\-+\-\-\-+\-\-\-+
*
* https://rfc\-editor\&.org/rfc/rfc8613#section\-4 goes on to define E, I and U
* properties Encrypted and Integrity Protected, Integrity Protected Only and
* Unprotected respectively\&. Integrity Protected Only is not currently used\&.
*
* An Option is tagged with CUNREIU with any of the letters replaced with _ if
* not set, or \- for N if U is set (see above) for aiding understanding of the
* Option\&.
*/
COAP_OPTION_IF_MATCH 1 /* C__RE__, opaque, 0\-8 B, RFC7252 */
COAP_OPTION_URI_HOST 3 /* CU\-___U, String, 1\-255 B, RFC7252 */
COAP_OPTION_ETAG 4 /* ___RE__, opaque, 1\-8 B, RFC7252 */
COAP_OPTION_IF_NONE_MATCH 5 /* C___E__, empty, 0 B, RFC7252 */
COAP_OPTION_OBSERVE 6 /* _U\-_E_U, empty/uint, 0 B/0\-3 B, RFC7641 */
COAP_OPTION_URI_PORT 7 /* CU\-___U, uint, 0\-2 B, RFC7252 */
COAP_OPTION_LOCATION_PATH 8 /* ___RE__, String, 0\-255 B, RFC7252 */
COAP_OPTION_OSCORE 9 /* C_____U, *, 0\-255 B, RFC8613 */
COAP_OPTION_URI_PATH 11 /* CU\-RE__, String, 0\-255 B, RFC7252 */
COAP_OPTION_CONTENT_FORMAT 12 /* ____E__, uint, 0\-2 B, RFC7252 */
/* COAP_OPTION_MAXAGE default 60 seconds if not set */
COAP_OPTION_MAXAGE 14 /* _U\-_E_U, uint, 0\-4 B, RFC7252 */
COAP_OPTION_URI_QUERY 15 /* CU\-RE__, String, 1\-255 B, RFC7252 */
COAP_OPTION_HOP_LIMIT 16 /* ______U, uint, 1 B, RFC8768 */
COAP_OPTION_ACCEPT 17 /* C___E__, uint, 0\-2 B, RFC7252 */
COAP_OPTION_LOCATION_QUERY 20 /* ___RE__, String, 0\-255 B, RFC7252 */
COAP_OPTION_BLOCK2 23 /* CU\-_E_U, uint, 0\-3 B, RFC7959 */
COAP_OPTION_BLOCK1 27 /* CU\-_E_U, uint, 0\-3 B, RFC7959 */
COAP_OPTION_SIZE2 28 /* __N_E_U, uint, 0\-4 B, RFC7959 */
COAP_OPTION_PROXY_URI 35 /* CU\-___U, String, 1\-1034 B, RFC7252 */
COAP_OPTION_PROXY_SCHEME 39 /* CU\-___U, String, 1\-255 B, RFC7252 */
COAP_OPTION_SIZE1 60 /* __N_E_U, uint, 0\-4 B, RFC7252 */
COAP_OPTION_NORESPONSE 258 /* _U\-_E_U, uint, 0\-1 B, RFC7967 */
.fi
.if n \{\
.RE
.\}
.sp
See FURTHER INFORMATION as to how to get the latest list\&.
.sp
\fBFunction: coap_check_option()\fR
.sp
The \fBcoap_check_option\fR() function is used to check whether the specified option \fInumber\fR is in the PDU \fIpdu\fR options\&. The option iterator \fIoi\fR is used as a scratch (does not need to be initialized) internal storage location while iterating through the options looking for the specific \fInumber\fR\&. If the \fInumber\fR is repeated in the \fIpdu\fR, only the first occurrence will be returned\&. If the option is not found, NULL is returned\&.
.sp
\fBFunction: coap_option_iterator_init()\fR
.sp
The \fBcoap_option_iterator_init\fR() function can be used to initialize option iterator \fIoi\fR, applying a filter \fIfilter\fR to indicate which options are to be ignored when iterating through the options\&. The \fIfilter\fR can be NULL (or COAP_OPT_ALL) if all of the options are required\&. To set up the filter otherwise, the following 4 functions are available\&.
.sp
\fBFunction: coap_option_filter_clear()\fR
.sp
The \fBcoap_option_filter_clear\fR() function initializes \fIfilter\fR to have no options set\&.
.sp
\fBFunction: coap_option_filter_get()\fR
.sp
The \fBcoap_option_filter_get\fR() function is used to check whether option \fInumber\fR is set in \fIfilter\fR\&.
.sp
\fBFunction: coap_option_filter_set()\fR
.sp
The \fBcoap_option_filter_set\fR() function is used to set option \fInumber\fR in \fIfilter\fR\&.
.sp
\fBFunction: coap_option_filter_unset()\fR
.sp
The \fBcoap_option_filter_unset\fR() function is used to remove option \fInumber\fR in \fIfilter\fR\&.
.sp
\fBFunction: coap_option_next()\fR
.sp
The \fBcoap_option_next\fR() function is then used following \fBcoap_option_iterator_init\fR() in a loop to return all the appropriate options until NULL is returned \- indicating the end of the available options\&. See EXAMPLES below for further information\&.
.sp
\fBFunction: coap_opt_length()\fR
.sp
The \fBcoap_opt_length\fR() function returns the length of the option \fIopt\fR (as returned by \fBcoap_check_option\fR() or \fBcoap_option_next\fR())\&.
.sp
\fBFunction: coap_opt_value()\fR
.sp
The \fBcoap_opt_value\fR() function returns a pointer to the start of the data for the option \fIopt\fR (as returned by \fBcoap_check_option\fR() or \fBcoap_option_next\fR())\&.
.sp
\fBFunction: coap_decode_var_bytes()\fR
.sp
The \fBcoap_decode_var_bytes\fR() function will decode an option value up to 4 bytes long from \fIbuf\fR and \fIlength\fR into an unsigned 32bit number\&.
.sp
\fBFunction: coap_decode_var_bytes8()\fR
.sp
The \fBcoap_decode_var_bytes8\fR() function will decode an option value up to 8 bytes long from \fIbuf\fR and \fIlength\fR into an unsigned 64bit number\&.
.sp
\fBFunction: coap_get_uri_path()\fR
.sp
The \fBcoap_get_uri_path\fR() function will abstract the uri path from the specified \fIpdu\fR options\&. The returned uri path will need to be freed off when no longer required\&.
.SH "PDU PAYLOAD FUNCTIONS"
.sp
\fBFunction: coap_get_data()\fR
.sp
The \fBcoap_get_data\fR() function is used abstract from the \fIpdu\fR payload information about the received data by updating \fIlength\fR with the length of data available, and \fIdata\fR with a pointer to where the data is located\&.
.sp
\fBNOTE:\fR This function has been updated by \fBcoap_get_data_large\fR() when large transfers may take place\&. See coap_block(3)\&.
.SH "RETURN VALUES"
.sp
\fBcoap_check_option\fR() and \fBcoap_option_next\fR() returns a coap_opt_t* or NULL if not found\&.
.sp
\fBcoap_decode_var_bytes\fR() and \fBcoap_decode_var_bytes8\fR() return the decoded value\&.
.sp
\fBcoap_pdu_get_code\fR(), \fBcoap_pdu_get_mid\fR(), \fBcoap_pdu_get_type\fR() return the appropriate value\&.
.sp
\fBcoap_option_filter_get\fR(), \fBcoap_option_filter_set\fR() and \fBcoap_option_filter_unset\fR() return 1 on success or 0 on failure\&.
.sp
\fBcoap_get_data\fR() returns 1 if data, else 0\&.
.sp
\fBcoap_opt_length\fR() returns the option length\&.
.sp
\fBcoap_opt_value\fR() returns a pointer to the start of the option value or NULL if error\&.
.sp
\fBcoap_option_iterator_init\fR() returns ap pointer to the provided iterator or NULL on error\&.
.sp
\fBcoap_pdu_get_token\fR() returns a pointer to the token in the pdu\&.
.sp
\fBcoap_get_uri_path\fR() returns an allocated pointer to the uri path in the pdu or NULL on error\&. This pointer will need to be freed off\&.
.SH "EXAMPLES"
.sp
\fBAbstract information from PDU\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#include
static void
get_pdu_information(coap_pdu_t *pdu) {
int ret;
/* Header variables */
coap_pdu_type_t pdu_type;
coap_pdu_code_t pdu_code;
coap_mid_t pdu_mid;
/* Token variables */
coap_bin_const_t pdu_token;
/* Option variables */
coap_opt_iterator_t opt_iter;
coap_opt_t *option;
coap_opt_filter_t ignore_options;
/* Data payload variables */
size_t pdu_data_length;
const uint8_t *pdu_data;
size_t pdu_data_offset;
size_t pdu_data_total_length;
/* Pull in the header information */
pdu_type = coap_pdu_get_type(pdu);
pdu_code = coap_pdu_get_code(pdu);
pdu_mid = coap_pdu_get_mid(pdu);
/* Pull in the token information */
pdu_token = coap_pdu_get_token(pdu);
/* Pull in the option information */
/* Specific option check */
option = coap_check_option(pdu, COAP_OPTION_OBSERVE, &opt_iter);
if (option) {
uint32_t value = coap_decode_var_bytes(coap_opt_value(option),
coap_opt_length(option));
coap_log_info("Option OBSERVE, value %u\en", value);
}
/* Iterate through all options */
coap_option_iterator_init(pdu, &opt_iter, COAP_OPT_ALL);
while ((option = coap_option_next(&opt_iter))) {
coap_log_info("A: Option %d, Length %u\en",
opt_iter\&.number, coap_opt_length(option));
}
/* Iterate through options, some ignored */
coap_option_filter_clear(&ignore_options);
coap_option_filter_set(&ignore_options, COAP_OPTION_OBSERVE);
coap_option_iterator_init(pdu, &opt_iter, &ignore_options);
while ((option = coap_option_next(&opt_iter))) {
coap_log_info("I: Option %d, Length %u\en",
opt_iter\&.number, coap_opt_length(option));
}
/* Pull in the payload information */
ret = coap_get_data(pdu, &pdu_data_length, &pdu_data);
/* or */
ret = coap_get_data_large(pdu, &pdu_data_length, &pdu_data,
&pdu_data_offset, &pdu_data_total_length);
}
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBcoap_block\fR(3) and \fBcoap_pdu_setup\fR(3)
.SH "FURTHER INFORMATION"
.sp
See
.sp
"RFC7252: The Constrained Application Protocol (CoAP)"
.sp
"RFC8613: Object Security for Constrained RESTful Environments (OSCORE)"
.sp
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 or raise an issue on GitHub at https://github\&.com/obgm/libcoap/issues
.SH "AUTHORS"
.sp
The libcoap project