libcoap 4.3.2rc2

Data Structures | Macros | Functions
PDU
Libcoap Internal API

Internal API for PDUs. More...

## Data Structures
struct | coap_pdu_t
| structure for CoAP PDUs More...

## Macros
#define | COAP_DEFAULT_VERSION 1 /* version of CoAP supported */
#define | COAP_MESSAGE_SIZE_OFFSET_TCP8 13
#define | COAP_MESSAGE_SIZE_OFFSET_TCP16 269 /* 13 + 256 */
#define | COAP_MESSAGE_SIZE_OFFSET_TCP32 65805 /* 269 + 65536 */
#define | COAP_MAX_MESSAGE_SIZE_TCP0 (COAP_MESSAGE_SIZE_OFFSET_TCP8-1) /* 12 */
#define | COAP_MAX_MESSAGE_SIZE_TCP8 (COAP_MESSAGE_SIZE_OFFSET_TCP16-1) /* 268 */
#define | COAP_MAX_MESSAGE_SIZE_TCP16 (COAP_MESSAGE_SIZE_OFFSET_TCP32-1) /* 65804 */
#define | COAP_MAX_MESSAGE_SIZE_TCP32 (COAP_MESSAGE_SIZE_OFFSET_TCP32+0xFFFFFFFF)
#define | COAP_TOKEN_EXT_1B_TKL 13
#define | COAP_TOKEN_EXT_2B_TKL 14
#define | COAP_TOKEN_EXT_1B_BIAS 13
#define | COAP_TOKEN_EXT_2B_BIAS 269 /* 13 + 256 */
#define | COAP_DROPPED_RESPONSE -2
| Indicates that a response is suppressed. More...
#define | COAP_PDU_DELAYED -3
#define | COAP_PAYLOAD_START 0xFF /* payload marker */
#define | COAP_PDU_IS_EMPTY(pdu) ((pdu)->code == 0)
#define | COAP_PDU_IS_REQUEST(pdu) (!COAP_PDU_IS_EMPTY(pdu) && (pdu)->code < 32)
#define | COAP_PDU_IS_RESPONSE(pdu) ((pdu)->code >= 64 && (pdu)->code < 224)
#define | COAP_PDU_IS_SIGNALING(pdu) ((pdu)->code >= 224)
#define | COAP_PDU_MAX_UDP_HEADER_SIZE 4
#define | COAP_PDU_MAX_TCP_HEADER_SIZE 6

## Functions
int | coap_pdu_resize (coap_pdu_t *pdu, size_t new_size)
| Dynamically grows the size of `pdu` to `new_size`. More...
int | coap_pdu_check_resize (coap_pdu_t *pdu, size_t new_size)
| Dynamically grows the size of `pdu` to `new_size` if needed. More...
size_t | coap_pdu_parse_header_size (coap_proto_t proto, const uint8_t *data)
| Interprets `data` to determine the number of bytes in the header. More...
size_t | coap_pdu_parse_size (coap_proto_t proto, const uint8_t *data, size_t length)
| Parses `data` to extract the message size. More...
int | coap_pdu_parse_header (coap_pdu_t *pdu, coap_proto_t proto)
| Decode the protocol specific header for the specified PDU. More...
int | coap_pdu_parse_opt (coap_pdu_t *pdu)
| Verify consistency in the given CoAP PDU structure and locate the data. More...
void | coap_pdu_clear (coap_pdu_t *pdu, size_t size)
| Clears any contents from `pdu` and resets `used_size`, and `data` pointers. More...
size_t | coap_add_option_internal (coap_pdu_t *pdu, coap_option_num_t number, size_t len, const uint8_t *data)
| Adds option of given `number` to `pdu` that is passed as first parameter. More...
int | coap_remove_option (coap_pdu_t *pdu, coap_option_num_t number)
| Removes (first) option of given number from the `pdu`. More...
size_t | coap_insert_option (coap_pdu_t *pdu, coap_option_num_t number, size_t len, const uint8_t *data)
| Inserts option of given number in the `pdu` with the appropriate data. More...
size_t | coap_update_option (coap_pdu_t *pdu, coap_option_num_t number, size_t len, const uint8_t *data)
| Updates existing first option of given number in the `pdu` with the new data. More...
size_t | coap_pdu_encode_header (coap_pdu_t *pdu, coap_proto_t proto)
| Compose the protocol specific header for the specified PDU. More...
int | coap_update_token (coap_pdu_t *pdu, size_t len, const uint8_t *data)
| Updates token in `pdu` with length `len` and `data`. More...
int | coap_option_check_repeatable (coap_option_num_t number)
| Check whether the option is allowed to be repeated or not. More...

## Detailed Description

Internal API for PDUs.

## Macro Definition Documentation

## ◆ COAP_DEFAULT_VERSION

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

Definition at line 35 of file coap_pdu_internal.h.

## ◆ COAP_DROPPED_RESPONSE

#define COAP_DROPPED_RESPONSE -2

Indicates that a response is suppressed.

This will occur for error responses if the request was received via IP multicast.

Definition at line 83 of file coap_pdu_internal.h.

## ◆ COAP_MAX_MESSAGE_SIZE_TCP0

#define COAP_MAX_MESSAGE_SIZE_TCP0 (COAP_MESSAGE_SIZE_OFFSET_TCP8-1) /* 12 */

Definition at line 43 of file coap_pdu_internal.h.

## ◆ COAP_MAX_MESSAGE_SIZE_TCP16

#define COAP_MAX_MESSAGE_SIZE_TCP16 (COAP_MESSAGE_SIZE_OFFSET_TCP32-1) /* 65804 */

Definition at line 45 of file coap_pdu_internal.h.

## ◆ COAP_MAX_MESSAGE_SIZE_TCP32

#define COAP_MAX_MESSAGE_SIZE_TCP32 (COAP_MESSAGE_SIZE_OFFSET_TCP32+0xFFFFFFFF)

Definition at line 46 of file coap_pdu_internal.h.

## ◆ COAP_MAX_MESSAGE_SIZE_TCP8

#define COAP_MAX_MESSAGE_SIZE_TCP8 (COAP_MESSAGE_SIZE_OFFSET_TCP16-1) /* 268 */

Definition at line 44 of file coap_pdu_internal.h.

## ◆ COAP_MESSAGE_SIZE_OFFSET_TCP16

#define COAP_MESSAGE_SIZE_OFFSET_TCP16 269 /* 13 + 256 */

Definition at line 39 of file coap_pdu_internal.h.

## ◆ COAP_MESSAGE_SIZE_OFFSET_TCP32

#define COAP_MESSAGE_SIZE_OFFSET_TCP32 65805 /* 269 + 65536 */

Definition at line 40 of file coap_pdu_internal.h.

## ◆ COAP_MESSAGE_SIZE_OFFSET_TCP8

#define COAP_MESSAGE_SIZE_OFFSET_TCP8 13

Definition at line 38 of file coap_pdu_internal.h.

## ◆ COAP_PAYLOAD_START

#define COAP_PAYLOAD_START 0xFF /* payload marker */

Definition at line 87 of file coap_pdu_internal.h.

## ◆ COAP_PDU_DELAYED

#define COAP_PDU_DELAYED -3

Definition at line 85 of file coap_pdu_internal.h.

## ◆ COAP_PDU_IS_EMPTY

#define COAP_PDU_IS_EMPTY | ( |  | pdu | ) | ((pdu)->code == 0)

Definition at line 89 of file coap_pdu_internal.h.

## ◆ COAP_PDU_IS_REQUEST

#define COAP_PDU_IS_REQUEST | ( |  | pdu | ) | (!COAP_PDU_IS_EMPTY(pdu) && (pdu)->code < 32)

Definition at line 90 of file coap_pdu_internal.h.

## ◆ COAP_PDU_IS_RESPONSE

#define COAP_PDU_IS_RESPONSE | ( |  | pdu | ) | ((pdu)->code >= 64 && (pdu)->code < 224)

Definition at line 91 of file coap_pdu_internal.h.

## ◆ COAP_PDU_IS_SIGNALING

#define COAP_PDU_IS_SIGNALING | ( |  | pdu | ) | ((pdu)->code >= 224)

Definition at line 92 of file coap_pdu_internal.h.

## ◆ COAP_PDU_MAX_TCP_HEADER_SIZE

#define COAP_PDU_MAX_TCP_HEADER_SIZE 6

Definition at line 95 of file coap_pdu_internal.h.

## ◆ COAP_PDU_MAX_UDP_HEADER_SIZE

#define COAP_PDU_MAX_UDP_HEADER_SIZE 4

Definition at line 94 of file coap_pdu_internal.h.

## ◆ COAP_TOKEN_EXT_1B_BIAS

#define COAP_TOKEN_EXT_1B_BIAS 13

Definition at line 56 of file coap_pdu_internal.h.

## ◆ COAP_TOKEN_EXT_1B_TKL

#define COAP_TOKEN_EXT_1B_TKL 13

Definition at line 54 of file coap_pdu_internal.h.

## ◆ COAP_TOKEN_EXT_2B_BIAS

#define COAP_TOKEN_EXT_2B_BIAS 269 /* 13 + 256 */

Definition at line 57 of file coap_pdu_internal.h.

## ◆ COAP_TOKEN_EXT_2B_TKL

#define COAP_TOKEN_EXT_2B_TKL 14

Definition at line 55 of file coap_pdu_internal.h.

## Function Documentation

## ◆ coap_add_option_internal()

size_t coap_add_option_internal | ( | coap_pdu_t * | pdu,
|  | coap_option_num_t | number,
|  | size_t | len,
|  | const uint8_t * | data
| ) |  |

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

The internal version of coap_add_option() may cause an `option` to be inserted, even if there is any data in the `pdu`.

Note: Where possible, the option `data` needs to be stripped of leading zeros (big endian) to reduce the amount of data needed in the PDU, as well as in some cases the maximum data size of an option can be exceeded if not stripped and hence be illegal. This is done by using coap_encode_var_safe() or coap_encode_var_safe8().

Parameters

  pdu | The PDU where the option is to be added.
  number | The number of the new option.
  len | The length of the new option.
  data | The data of the new option.

Returns
  The overall length of the option or `0` on failure.

Definition at line 701 of file coap_pdu.c.

## ◆ coap_insert_option()

size_t coap_insert_option | ( | coap_pdu_t * | pdu,
|  | coap_option_num_t | number,
|  | size_t | len,
|  | const uint8_t * | data
| ) |  |

Inserts option of given number in the `pdu` with the appropriate data.

The option will be inserted in the appropriate place in the options in the pdu.

Parameters

  pdu | The PDU where the option is to be inserted.
  number | The number of the new option.
  len | The length of the new option.
  data | The data of the new option.

Returns
  The overall length of the option or `0` on failure.

Definition at line 563 of file coap_pdu.c.

## ◆ coap_option_check_repeatable()

int coap_option_check_repeatable | ( | coap_option_num_t | number | ) |

Check whether the option is allowed to be repeated or not.

This function returns `0` if not repeatable or `1` if repeatable

Parameters

  number | The option number to check for repeatability.

Returns
  `0` if not repeatable or `1` if repeatable.

Definition at line 520 of file coap_pdu.c.

## ◆ coap_pdu_check_resize()

int coap_pdu_check_resize | ( | coap_pdu_t * | pdu,
|  | size_t | new_size
| ) |  |

Dynamically grows the size of `pdu` to `new_size` if needed.

The new size must not exceed the PDU's configured maximum size. On success, this function returns 1, otherwise 0.

Parameters

  pdu | The PDU to resize.
  new_size | The new size in bytes.

Returns
  1 if the operation succeeded, 0 otherwise.

Definition at line 287 of file coap_pdu.c.

## ◆ coap_pdu_clear()

void coap_pdu_clear | ( | coap_pdu_t * | pdu,
|  | size_t | size
| ) |  |

Clears any contents from `pdu` and resets `used_size`, 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().

Parameters

  pdu | The PDU to clear.
  size | The maximum size of the PDU.

Definition at line 42 of file coap_pdu.c.

## ◆ coap_pdu_encode_header()

size_t coap_pdu_encode_header | ( | coap_pdu_t * | pdu,
|  | coap_proto_t | proto
| ) |  |

Compose the protocol specific header for the specified PDU.

Parameters

  pdu | A newly composed PDU.
  proto | The target wire protocol.

Returns
  Number of header bytes prepended before pdu->token or 0 on error.

Definition at line 1405 of file coap_pdu.c.

## ◆ coap_pdu_parse_header()

int coap_pdu_parse_header | ( | coap_pdu_t * | pdu,
|  | coap_proto_t | proto
| ) |  |

Decode the protocol specific header for the specified PDU.

Parameters

  pdu | A newly received PDU.
  proto | The target wire protocol.

Returns
  1 for success or 0 on error.

Definition at line 996 of file coap_pdu.c.

## ◆ coap_pdu_parse_header_size()

size_t coap_pdu_parse_header_size | ( | coap_proto_t | proto,
|  | const uint8_t * | data
| ) |  |

Interprets `data` to determine the number of bytes in the header.

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

Parameters

  proto | Session's protocol
  data | The first byte of raw data to parse as CoAP PDU.

Returns
  A value greater than zero on success or `0` on error.

Definition at line 914 of file coap_pdu.c.

## ◆ coap_pdu_parse_opt()

int coap_pdu_parse_opt | ( | coap_pdu_t * | pdu | ) |

Verify consistency in the given CoAP PDU structure and locate the data.

This function returns `0` on error or a number greater than zero on success. This function only parses the token and options, up to the payload start marker.

Parameters

  pdu | The PDU structure to check.

Returns
  1 on success or `0` on error.

Definition at line 1258 of file coap_pdu.c.

## ◆ coap_pdu_parse_size()

size_t coap_pdu_parse_size | ( | coap_proto_t | proto,
|  | const uint8_t * | data,
|  | size_t | length
| ) |  |

Parses `data` to extract the message size.

`length` must be at least coap_pdu_parse_header_size(proto, data). This function returns `0` on error or a number greater than zero on success.

Parameters

  proto | Session's protocol
  data | The raw data to parse as CoAP PDU.
  length | The actual size of `data`.

Returns
  PDU size including token on success or `0` on error.

Definition at line 944 of file coap_pdu.c.

## ◆ coap_pdu_resize()

int coap_pdu_resize | ( | coap_pdu_t * | pdu,
|  | size_t | new_size
| ) |  |

Dynamically grows the size of `pdu` to `new_size`.

The new size must not exceed the PDU's configure maximum size. On success, this function returns 1, otherwise 0.

Parameters

  pdu | The PDU to resize.
  new_size | The new size in bytes.

Returns
  1 if the operation succeeded, 0 otherwise.

Definition at line 245 of file coap_pdu.c.

## ◆ coap_remove_option()

int coap_remove_option | ( | coap_pdu_t * | pdu,
|  | coap_option_num_t | number
| ) |  |

Removes (first) option of given number from the `pdu`.

Parameters

  pdu | The PDU to remove the option from.
  number | The number of the CoAP option to remove (first only removed).

Returns
  `1` if success else `0` if error.

Definition at line 426 of file coap_pdu.c.

## ◆ coap_update_option()

size_t coap_update_option | ( | coap_pdu_t * | pdu,
|  | coap_option_num_t | number,
|  | size_t | len,
|  | const uint8_t * | data
| ) |  |

Updates existing first option of given number in the `pdu` with the new data.

Parameters

  pdu | The PDU where the option is to be updated.
  number | The number of the option to update (first only updated).
  len | The length of the updated option.
  data | The data of the updated option.

Returns
  The overall length of the updated option or `0` on failure.

Definition at line 651 of file coap_pdu.c.

## ◆ coap_update_token()

int coap_update_token | ( | coap_pdu_t * | pdu,
|  | size_t | len,
|  | const uint8_t * | data
| ) |  |

Updates token in `pdu` with length `len` and `data`.

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

Parameters

  pdu | The PDU where the token is to be updated.
  len | The length of the new token.
  data | The token to add.

Returns
  A value greater than zero on success, or `0` on error.

Definition at line 361 of file coap_pdu.c.