libcoap  4.1.1
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
Data Structures | Macros | Typedefs | Functions
pdu.h File Reference
#include "config.h"
#include "coap_list.h"
#include "uri.h"

Go to the source code of this file.

Data Structures

struct  coap_hdr_t
 
struct  coap_option
 Structures for more convenient handling of options. More...
 
struct  coap_pdu_t
 Header structure for CoAP PDUs. More...
 

Macros

#define COAP_DEFAULT_RESPONSE_TIMEOUT   2 /* response timeout in seconds */
 
#define COAP_DEFAULT_MAX_RETRANSMIT   4 /* max number of retransmissions */
 
#define COAP_DEFAULT_PORT   5683 /* CoAP default UDP port */
 
#define COAP_DEFAULT_MAX_AGE   60 /* default maximum object lifetime in seconds */
 
#define COAP_MAX_PDU_SIZE   1400 /* maximum size of a CoAP PDU */
 
#define COAP_DEFAULT_VERSION   1 /* version of CoAP supported */
 
#define COAP_DEFAULT_SCHEME   "coap" /* the default scheme for CoAP URIs */
 
#define COAP_DEFAULT_URI_WELLKNOWN   ".well-known/core"
 well-known resources URI More...
 
#define COAP_DEFAULT_WKC_HASHKEY   "\345\130\144\245"
 
#define COAP_MESSAGE_CON   0 /* confirmable message (requires ACK/RST) */
 
#define COAP_MESSAGE_NON   1 /* non-confirmable message (one-shot message) */
 
#define COAP_MESSAGE_ACK   2 /* used to acknowledge confirmable messages */
 
#define COAP_MESSAGE_RST   3 /* indicates error in received messages */
 
#define COAP_REQUEST_GET   1
 
#define COAP_REQUEST_POST   2
 
#define COAP_REQUEST_PUT   3
 
#define COAP_REQUEST_DELETE   4
 
#define COAP_OPTION_IF_MATCH   1 /* C, opaque, 0-8 B, (none) */
 
#define COAP_OPTION_URI_HOST   3 /* C, String, 1-255 B, destination address */
 
#define COAP_OPTION_ETAG   4 /* E, opaque, 1-8 B, (none) */
 
#define COAP_OPTION_IF_NONE_MATCH   5 /* empty, 0 B, (none) */
 
#define COAP_OPTION_URI_PORT   7 /* C, uint, 0-2 B, destination port */
 
#define COAP_OPTION_LOCATION_PATH   8 /* E, String, 0-255 B, - */
 
#define COAP_OPTION_URI_PATH   11 /* C, String, 0-255 B, (none) */
 
#define COAP_OPTION_CONTENT_FORMAT   12 /* E, uint, 0-2 B, (none) */
 
#define COAP_OPTION_CONTENT_TYPE   COAP_OPTION_CONTENT_FORMAT
 
#define COAP_OPTION_MAXAGE   14 /* E, uint, 0--4 B, 60 Seconds */
 
#define COAP_OPTION_URI_QUERY   15 /* C, String, 1-255 B, (none) */
 
#define COAP_OPTION_ACCEPT   17 /* C, uint, 0-2 B, (none) */
 
#define COAP_OPTION_LOCATION_QUERY   20 /* E, String, 0-255 B, (none) */
 
#define COAP_OPTION_PROXY_URI   35 /* C, String, 1-1034 B, (none) */
 
#define COAP_OPTION_PROXY_SCHEME   39 /* C, String, 1-255 B, (none) */
 
#define COAP_OPTION_SIZE1   60 /* E, uint, 0-4 B, (none) */
 
#define COAP_OPTION_OBSERVE   6 /* E, empty/uint, 0 B/0-3 B, (none) */
 
#define COAP_OPTION_SUBSCRIPTION   COAP_OPTION_OBSERVE
 
#define COAP_OPTION_BLOCK2   23 /* C, uint, 0--3 B, (none) */
 
#define COAP_OPTION_BLOCK1   27 /* C, uint, 0--3 B, (none) */
 
#define COAP_MAX_OPT   63
 the highest option number we know More...
 
#define COAP_RESPONSE_CODE(N)   (((N)/100 << 5) | (N)%100)
 
#define COAP_RESPONSE_CLASS(C)   (((C) >> 5) & 0xFF)
 
#define COAP_ERROR_PHRASE_LENGTH   32
 maximum length of error phrase More...
 
#define COAP_RESPONSE_200   COAP_RESPONSE_CODE(200) /* 2.00 OK */
 
#define COAP_RESPONSE_201   COAP_RESPONSE_CODE(201) /* 2.01 Created */
 
#define COAP_RESPONSE_304   COAP_RESPONSE_CODE(203) /* 2.03 Valid */
 
#define COAP_RESPONSE_400   COAP_RESPONSE_CODE(400) /* 4.00 Bad Request */
 
#define COAP_RESPONSE_404   COAP_RESPONSE_CODE(404) /* 4.04 Not Found */
 
#define COAP_RESPONSE_405   COAP_RESPONSE_CODE(405) /* 4.05 Method Not Allowed */
 
#define COAP_RESPONSE_415   COAP_RESPONSE_CODE(415) /* 4.15 Unsupported Media Type */
 
#define COAP_RESPONSE_500   COAP_RESPONSE_CODE(500) /* 5.00 Internal Server Error */
 
#define COAP_RESPONSE_501   COAP_RESPONSE_CODE(501) /* 5.01 Not Implemented */
 
#define COAP_RESPONSE_503   COAP_RESPONSE_CODE(503) /* 5.03 Service Unavailable */
 
#define COAP_RESPONSE_504   COAP_RESPONSE_CODE(504) /* 5.04 Gateway Timeout */
 
#define COAP_RESPONSE_X_242   COAP_RESPONSE_CODE(402) /* Critical Option not supported */
 
#define COAP_MEDIATYPE_TEXT_PLAIN   0 /* text/plain (UTF-8) */
 
#define COAP_MEDIATYPE_APPLICATION_LINK_FORMAT   40 /* application/link-format */
 
#define COAP_MEDIATYPE_APPLICATION_XML   41 /* application/xml */
 
#define COAP_MEDIATYPE_APPLICATION_OCTET_STREAM   42 /* application/octet-stream */
 
#define COAP_MEDIATYPE_APPLICATION_RDF_XML   43 /* application/rdf+xml */
 
#define COAP_MEDIATYPE_APPLICATION_EXI   47 /* application/exi */
 
#define COAP_MEDIATYPE_APPLICATION_JSON   50 /* application/json */
 
#define COAP_MEDIATYPE_ANY   0xff /* any media type */
 
#define COAP_INVALID_TID   -1
 
#define COAP_MESSAGE_IS_EMPTY(MSG)   ((MSG)->code == 0)
 
#define COAP_MESSAGE_IS_REQUEST(MSG)
 
#define COAP_MESSAGE_IS_RESPONSE(MSG)   ((MSG)->code >= 64 && (MSG)->code <= 191)
 
#define COAP_OPT_LONG
 
#define COAP_OPT_END   0xF0 /* end marker */
 
#define COAP_PAYLOAD_START   0xFF /* payload marker */
 
#define COAP_OPTION_KEY(option)   (option).key
 
#define COAP_OPTION_LENGTH(option)   (option).length
 
#define COAP_OPTION_DATA(option)   ((unsigned char *)&(option) + sizeof(coap_option))
 
#define COAP_OPTION(node)   ((coap_option *)(node)->options)
 Options in coap_pdu_t are accessed with the macro COAP_OPTION. More...
 

Typedefs

typedef int coap_tid_t
 

Functions

char * coap_response_phrase (unsigned char code)
 Returns a human-readable response phrase for the specified CoAP response code. More...
 
coap_pdu_tcoap_pdu_init (unsigned char type, unsigned char code, unsigned short id, size_t size)
 Creates a new CoAP PDU of given size (must be large enough to hold the basic CoAP message header (coap_hdr_t). More...
 
void coap_pdu_clear (coap_pdu_t *pdu, size_t size)
 Clears any contents from pdu and resets version field, length and data pointers. More...
 
coap_pdu_tcoap_new_pdu ()
 Creates a new CoAP PDU. More...
 
void coap_delete_pdu (coap_pdu_t *)
 
int coap_pdu_parse (unsigned char *data, size_t length, coap_pdu_t *result)
 Parses data into the CoAP PDU structure given in result. More...
 
int coap_add_token (coap_pdu_t *pdu, size_t len, const unsigned char *data)
 Adds token of length len to pdu. More...
 
size_t coap_add_option (coap_pdu_t *pdu, unsigned short type, unsigned int len, const unsigned char *data)
 Adds option of given type to pdu that is passed as first parameter. More...
 
unsigned char * coap_add_option_later (coap_pdu_t *pdu, unsigned short type, unsigned int len)
 Adds option of given type to pdu that is passed as first parameter, but does not write a value. More...
 
int coap_add_data (coap_pdu_t *pdu, unsigned int len, const unsigned char *data)
 Adds given data to the pdu that is passed as first parameter. More...
 
int coap_get_data (coap_pdu_t *pdu, size_t *len, unsigned char **data)
 Retrieves the length and data pointer of specified PDU. More...
 

Macro Definition Documentation

#define COAP_DEFAULT_MAX_AGE   60 /* default maximum object lifetime in seconds */

Definition at line 25 of file pdu.h.

#define COAP_DEFAULT_MAX_RETRANSMIT   4 /* max number of retransmissions */

Definition at line 23 of file pdu.h.

#define COAP_DEFAULT_PORT   5683 /* CoAP default UDP port */

Definition at line 24 of file pdu.h.

#define COAP_DEFAULT_RESPONSE_TIMEOUT   2 /* response timeout in seconds */

Definition at line 22 of file pdu.h.

#define COAP_DEFAULT_SCHEME   "coap" /* the default scheme for CoAP URIs */

Definition at line 31 of file pdu.h.

#define COAP_DEFAULT_URI_WELLKNOWN   ".well-known/core"

well-known resources URI

Definition at line 34 of file pdu.h.

#define COAP_DEFAULT_VERSION   1 /* version of CoAP supported */

Definition at line 30 of file pdu.h.

#define COAP_DEFAULT_WKC_HASHKEY   "\345\130\144\245"

Definition at line 38 of file pdu.h.

#define COAP_ERROR_PHRASE_LENGTH   32

maximum length of error phrase

Definition at line 110 of file pdu.h.

#define COAP_INVALID_TID   -1

Definition at line 156 of file pdu.h.

#define COAP_MAX_OPT   63

the highest option number we know

Definition at line 84 of file pdu.h.

#define COAP_MAX_PDU_SIZE   1400 /* maximum size of a CoAP PDU */

Definition at line 27 of file pdu.h.

#define COAP_MEDIATYPE_ANY   0xff /* any media type */

Definition at line 151 of file pdu.h.

#define COAP_MEDIATYPE_APPLICATION_EXI   47 /* application/exi */

Definition at line 146 of file pdu.h.

#define COAP_MEDIATYPE_APPLICATION_JSON   50 /* application/json */

Definition at line 147 of file pdu.h.

#define COAP_MEDIATYPE_APPLICATION_LINK_FORMAT   40 /* application/link-format */

Definition at line 142 of file pdu.h.

#define COAP_MEDIATYPE_APPLICATION_OCTET_STREAM   42 /* application/octet-stream */

Definition at line 144 of file pdu.h.

#define COAP_MEDIATYPE_APPLICATION_RDF_XML   43 /* application/rdf+xml */

Definition at line 145 of file pdu.h.

#define COAP_MEDIATYPE_APPLICATION_XML   41 /* application/xml */

Definition at line 143 of file pdu.h.

#define COAP_MEDIATYPE_TEXT_PLAIN   0 /* text/plain (UTF-8) */

Definition at line 141 of file pdu.h.

#define COAP_MESSAGE_ACK   2 /* used to acknowledge confirmable messages */

Definition at line 45 of file pdu.h.

#define COAP_MESSAGE_CON   0 /* confirmable message (requires ACK/RST) */

Definition at line 43 of file pdu.h.

#define COAP_MESSAGE_IS_EMPTY (   MSG)    ((MSG)->code == 0)

Definition at line 178 of file pdu.h.

#define COAP_MESSAGE_IS_REQUEST (   MSG)
Value:
&& ((MSG)->code < 32))
#define COAP_MESSAGE_IS_EMPTY(MSG)
Definition: pdu.h:178

Definition at line 179 of file pdu.h.

#define COAP_MESSAGE_IS_RESPONSE (   MSG)    ((MSG)->code >= 64 && (MSG)->code <= 191)

Definition at line 181 of file pdu.h.

#define COAP_MESSAGE_NON   1 /* non-confirmable message (one-shot message) */

Definition at line 44 of file pdu.h.

#define COAP_MESSAGE_RST   3 /* indicates error in received messages */

Definition at line 46 of file pdu.h.

#define COAP_OPT_END   0xF0 /* end marker */

Definition at line 186 of file pdu.h.

#define COAP_OPT_LONG
Value:
0x0F /* OC == 0b1111 indicates that the option list in a
* CoAP message is limited by 0b11110000 marker */

Definition at line 183 of file pdu.h.

#define COAP_OPTION (   node)    ((coap_option *)(node)->options)

Options in coap_pdu_t are accessed with the macro COAP_OPTION.

Definition at line 221 of file pdu.h.

#define COAP_OPTION_ACCEPT   17 /* C, uint, 0-2 B, (none) */

Definition at line 68 of file pdu.h.

#define COAP_OPTION_BLOCK1   27 /* C, uint, 0--3 B, (none) */

Definition at line 82 of file pdu.h.

#define COAP_OPTION_BLOCK2   23 /* C, uint, 0--3 B, (none) */

Definition at line 81 of file pdu.h.

#define COAP_OPTION_CONTENT_FORMAT   12 /* E, uint, 0-2 B, (none) */

Definition at line 64 of file pdu.h.

#define COAP_OPTION_CONTENT_TYPE   COAP_OPTION_CONTENT_FORMAT

Definition at line 65 of file pdu.h.

#define COAP_OPTION_DATA (   option)    ((unsigned char *)&(option) + sizeof(coap_option))

Definition at line 202 of file pdu.h.

#define COAP_OPTION_ETAG   4 /* E, opaque, 1-8 B, (none) */

Definition at line 59 of file pdu.h.

#define COAP_OPTION_IF_MATCH   1 /* C, opaque, 0-8 B, (none) */

Definition at line 57 of file pdu.h.

#define COAP_OPTION_IF_NONE_MATCH   5 /* empty, 0 B, (none) */

Definition at line 60 of file pdu.h.

#define COAP_OPTION_KEY (   option)    (option).key

Definition at line 200 of file pdu.h.

#define COAP_OPTION_LENGTH (   option)    (option).length

Definition at line 201 of file pdu.h.

#define COAP_OPTION_LOCATION_PATH   8 /* E, String, 0-255 B, - */

Definition at line 62 of file pdu.h.

#define COAP_OPTION_LOCATION_QUERY   20 /* E, String, 0-255 B, (none) */

Definition at line 69 of file pdu.h.

#define COAP_OPTION_MAXAGE   14 /* E, uint, 0--4 B, 60 Seconds */

Definition at line 66 of file pdu.h.

#define COAP_OPTION_OBSERVE   6 /* E, empty/uint, 0 B/0-3 B, (none) */

Definition at line 76 of file pdu.h.

#define COAP_OPTION_PROXY_SCHEME   39 /* C, String, 1-255 B, (none) */

Definition at line 71 of file pdu.h.

#define COAP_OPTION_PROXY_URI   35 /* C, String, 1-1034 B, (none) */

Definition at line 70 of file pdu.h.

#define COAP_OPTION_SIZE1   60 /* E, uint, 0-4 B, (none) */

Definition at line 72 of file pdu.h.

#define COAP_OPTION_SUBSCRIPTION   COAP_OPTION_OBSERVE

Definition at line 77 of file pdu.h.

#define COAP_OPTION_URI_HOST   3 /* C, String, 1-255 B, destination address */

Definition at line 58 of file pdu.h.

#define COAP_OPTION_URI_PATH   11 /* C, String, 0-255 B, (none) */

Definition at line 63 of file pdu.h.

#define COAP_OPTION_URI_PORT   7 /* C, uint, 0-2 B, destination port */

Definition at line 61 of file pdu.h.

#define COAP_OPTION_URI_QUERY   15 /* C, String, 1-255 B, (none) */

Definition at line 67 of file pdu.h.

#define COAP_PAYLOAD_START   0xFF /* payload marker */

Definition at line 188 of file pdu.h.

#define COAP_REQUEST_DELETE   4

Definition at line 53 of file pdu.h.

#define COAP_REQUEST_GET   1

Definition at line 50 of file pdu.h.

#define COAP_REQUEST_POST   2

Definition at line 51 of file pdu.h.

#define COAP_REQUEST_PUT   3

Definition at line 52 of file pdu.h.

#define COAP_RESPONSE_200   COAP_RESPONSE_CODE(200) /* 2.00 OK */

Definition at line 122 of file pdu.h.

#define COAP_RESPONSE_201   COAP_RESPONSE_CODE(201) /* 2.01 Created */

Definition at line 123 of file pdu.h.

#define COAP_RESPONSE_304   COAP_RESPONSE_CODE(203) /* 2.03 Valid */

Definition at line 124 of file pdu.h.

#define COAP_RESPONSE_400   COAP_RESPONSE_CODE(400) /* 4.00 Bad Request */

Definition at line 125 of file pdu.h.

#define COAP_RESPONSE_404   COAP_RESPONSE_CODE(404) /* 4.04 Not Found */

Definition at line 126 of file pdu.h.

#define COAP_RESPONSE_405   COAP_RESPONSE_CODE(405) /* 4.05 Method Not Allowed */

Definition at line 127 of file pdu.h.

#define COAP_RESPONSE_415   COAP_RESPONSE_CODE(415) /* 4.15 Unsupported Media Type */

Definition at line 128 of file pdu.h.

#define COAP_RESPONSE_500   COAP_RESPONSE_CODE(500) /* 5.00 Internal Server Error */

Definition at line 129 of file pdu.h.

#define COAP_RESPONSE_501   COAP_RESPONSE_CODE(501) /* 5.01 Not Implemented */

Definition at line 130 of file pdu.h.

#define COAP_RESPONSE_503   COAP_RESPONSE_CODE(503) /* 5.03 Service Unavailable */

Definition at line 131 of file pdu.h.

#define COAP_RESPONSE_504   COAP_RESPONSE_CODE(504) /* 5.04 Gateway Timeout */

Definition at line 132 of file pdu.h.

#define COAP_RESPONSE_CLASS (   C)    (((C) >> 5) & 0xFF)

Definition at line 95 of file pdu.h.

#define COAP_RESPONSE_CODE (   N)    (((N)/100 << 5) | (N)%100)

Definition at line 92 of file pdu.h.

#define COAP_RESPONSE_X_242   COAP_RESPONSE_CODE(402) /* Critical Option not supported */

Definition at line 137 of file pdu.h.

Typedef Documentation

typedef int coap_tid_t

Definition at line 155 of file pdu.h.

Function Documentation

int coap_add_data ( coap_pdu_t pdu,
unsigned int  len,
const unsigned char *  data 
)

Adds given data to the pdu that is passed as first parameter.

Note that the PDU's data is destroyed by coap_add_option(). coap_add_data() must be called only once per PDU, otherwise the result is undefined.

Definition at line 238 of file pdu.c.

size_t coap_add_option ( coap_pdu_t pdu,
unsigned short  type,
unsigned int  len,
const unsigned char *  data 
)

Adds option of given type to pdu that is passed as first parameter.

coap_add_option() destroys the PDU's data, so coap_add_data() must be called after all options have been added. As coap_add_token() destroys the options following the token, the token must be added before coap_add_option() is called. This function returns the number of bytes written or 0 on error.

Adds option of given type to pdu that is passed as first parameter.

Definition at line 175 of file pdu.c.

unsigned char* coap_add_option_later ( coap_pdu_t pdu,
unsigned short  type,
unsigned int  len 
)

Adds option of given type to pdu that is passed as first parameter, but does not write a value.

It works like coap_add_option with respect to calling sequence (i.e. after token and before data). This function returns a memory address to which the option data has to be written before the PDU can be sent, or NULL on error.

Adds option of given type to pdu that is passed as first parameter, but does not write a value.

Definition at line 207 of file pdu.c.

int coap_add_token ( coap_pdu_t pdu,
size_t  len,
const unsigned char *  data 
)

Adds token of length len to pdu.

Adding the token destroys any following contents of the pdu. Hence options and data must be added after coap_add_token() has been called. In pdu, length is set to len + 4, and max_delta is set to 0. This funtion returns 0 on error or a value greater than zero on success.

Parameters
pduThe PDU where the token is to be added.
lenThe length of the new token.
dataThe token to add.
Returns
A value greater than zero on success, or 0 on error.

Definition at line 157 of file pdu.c.

void coap_delete_pdu ( coap_pdu_t )

Definition at line 143 of file pdu.c.

int coap_get_data ( coap_pdu_t pdu,
size_t *  len,
unsigned char **  data 
)

Retrieves the length and data pointer of specified PDU.

Returns 0 on error or 1 if *len and *data have correct values. Note that these values are destroyed with the pdu.

Definition at line 261 of file pdu.c.

coap_pdu_t* coap_new_pdu ( )

Creates a new CoAP PDU.

The object is created on the heap and must be released using coap_delete_pdu();

Deprecated:
This function allocates the maximum storage for each PDU. Use coap_pdu_init() instead.

Definition at line 126 of file pdu.c.

void coap_pdu_clear ( coap_pdu_t pdu,
size_t  size 
)

Clears any contents from pdu and resets version field, length and data pointers.

max_size is set to size, any other field is set to 0. Note that pdu must be a valid pointer to a coap_pdu_t object created e.g. by coap_pdu_init().

Definition at line 43 of file pdu.c.

coap_pdu_t* coap_pdu_init ( unsigned char  type,
unsigned char  code,
unsigned short  id,
size_t  size 
)

Creates a new CoAP PDU of given size (must be large enough to hold the basic CoAP message header (coap_hdr_t).

The function returns a pointer to the node coap_pdu_t object on success, or NULL on error. The storage allocated for the result must be released with coap_delete_pdu().

Parameters
typeThe type of the PDU (one of COAP_MESSAGE_CON, COAP_MESSAGE_NON, COAP_MESSAGE_ACK, COAP_MESSAGE_RST).
codeThe message code.
idThe message id to set or COAP_INVALID_TID if unknown.
sizeThe number of bytes to allocate for the actual message.
Returns
A pointer to the new PDU object or NULL on error.

Definition at line 82 of file pdu.c.

int coap_pdu_parse ( unsigned char *  data,
size_t  length,
coap_pdu_t result 
)

Parses data into the CoAP PDU structure given in result.

This function returns 0 on error or a number greater than zero on success.

Parameters
dataThe raw data to parse as CoAP PDU
lengthThe actual size of data
resultThe PDU structure to fill. Note that the structure must provide space for at least length bytes to hold the entire CoAP PDU.
Returns
A value greater than zero on success or 0 on error.

Definition at line 345 of file pdu.c.

char* coap_response_phrase ( unsigned char  code)

Returns a human-readable response phrase for the specified CoAP response code.

This function returns NULL if not found.

Parameters
codeThe response code for which the literal phrase should be retrieved.
Returns
A zero-terminated string describing the error, or NULL if not found.

Definition at line 310 of file pdu.c.