coap_pdu.h

Go to the documentation of this file.

/*
 * coap_pdu.h -- CoAP message structure
 *
 * Copyright (C) 2010-2014 Olaf Bergmann <bergmann@tzi.org>
 * Copyright (C) 2021-2026 Jon Shallow <supjps-libcoap@jpshallow.com>
 *
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * This file is part of the CoAP library libcoap. Please see README for terms
 * of use.
 */

 
#ifndef COAP_PDU_H_
#define COAP_PDU_H_
 
#include "coap_option.h"
#include "coap_uri.h"
 
#ifdef WITH_LWIP
#include <lwip/pbuf.h>
#endif
 
#ifdef __cplusplus
extern "C" {
#endif

 
#define COAP_DEFAULT_PORT      5683 /* CoAP default UDP/TCP port */
#define COAPS_DEFAULT_PORT     5684 /* CoAP default UDP/TCP port for secure transmission */
#define COAP_DEFAULT_MAX_AGE     60 /* default maximum object lifetime in seconds */
#ifndef COAP_DEFAULT_MTU
#define COAP_DEFAULT_MTU       1152
#endif /* COAP_DEFAULT_MTU */
 
#define COAP_BERT_BASE 1152
 
#ifndef COAP_DEFAULT_HOP_LIMIT
#define COAP_DEFAULT_HOP_LIMIT       16
#endif /* COAP_DEFAULT_HOP_LIMIT */
 
#define COAP_DEFAULT_SCHEME  "coap" /* the default scheme for CoAP URIs */

#define COAP_DEFAULT_URI_WELLKNOWN ".well-known/core"
 
/* Extended Token constants */
#define COAP_TOKEN_DEFAULT_MAX 8
#if (UINT_MAX > 65804UL)
#define COAP_TOKEN_EXT_MAX 65804UL /* 13 + 256 + 65535 */
#else /* UINT_MAX < 65804UL */
#define COAP_TOKEN_EXT_MAX 4096
#endif /* UINT_MAX < 65804UL */
 
/* CoAP message types */

typedef enum coap_pdu_type_t {
  COAP_MESSAGE_CON,  /* 0 confirmable message (requires ACK/RST) */
  COAP_MESSAGE_NON,  /* 1 non-confirmable message (one-shot message) */
  COAP_MESSAGE_ACK,  /* 2 used to acknowledge confirmable messages */
  COAP_MESSAGE_RST   /* 3 indicates error in received messages */
} coap_pdu_type_t;

typedef enum coap_request_t {
  COAP_REQUEST_GET = 1,
  COAP_REQUEST_POST,      /* 2 */
  COAP_REQUEST_PUT,       /* 3 */
  COAP_REQUEST_DELETE,    /* 4 */
  COAP_REQUEST_FETCH,     /* 5 RFC 8132 */
  COAP_REQUEST_PATCH,     /* 6 RFC 8132 */
  COAP_REQUEST_IPATCH,    /* 7 RFC 8132 */
} coap_request_t;
 
/* CoAP result codes (HTTP-Code / 100 * 40 + HTTP-Code % 100) */
 
/* As of draft-ietf-core-coap-04, response codes are encoded to base
 * 32, i.e.  the three upper bits determine the response class while
 * the remaining five fine-grained information specific to that class.
 */
#define COAP_RESPONSE_CODE(N) (((N)/100 << 5) | (N)%100)
 
/* Determines the class of response code C */
#define COAP_RESPONSE_CLASS(C) (((C) >> 5) & 0xFF)
 
#ifndef SHORT_ERROR_RESPONSE
const char *coap_response_phrase(unsigned char code);
 
#define COAP_ERROR_PHRASE_LENGTH   32 
 
#else
#define coap_response_phrase(x) ((char *)NULL)
 
#define COAP_ERROR_PHRASE_LENGTH    0 
#endif /* SHORT_ERROR_RESPONSE */
 
#define COAP_SIGNALING_CODE(N) (((N)/100 << 5) | (N)%100)
 
typedef enum coap_pdu_signaling_proto_t {
  COAP_SIGNALING_CSM =     COAP_SIGNALING_CODE(701),
  COAP_SIGNALING_PING =    COAP_SIGNALING_CODE(702),
  COAP_SIGNALING_PONG =    COAP_SIGNALING_CODE(703),
  COAP_SIGNALING_RELEASE = COAP_SIGNALING_CODE(704),
  COAP_SIGNALING_ABORT =   COAP_SIGNALING_CODE(705),
} coap_pdu_signaling_proto_t;
 
/* CoAP media type encoding */
 
#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_APPLICATION_CBOR          60 /* application/cbor  */
#define COAP_MEDIATYPE_APPLICATION_CWT           61 /* application/cwt, RFC 8392  */
 
/* Content formats from RFC 7390 */
#define COAP_MEDIATYPE_APPLICATION_COAP_GROUP_JSON 256 /* application/coap-group+json */
 
/* Content formats from RFC 8152 */
#define COAP_MEDIATYPE_APPLICATION_COSE_SIGN     98 /* application/cose; cose-type="cose-sign"     */
#define COAP_MEDIATYPE_APPLICATION_COSE_SIGN1    18 /* application/cose; cose-type="cose-sign1"    */
#define COAP_MEDIATYPE_APPLICATION_COSE_ENCRYPT  96 /* application/cose; cose-type="cose-encrypt"  */
#define COAP_MEDIATYPE_APPLICATION_COSE_ENCRYPT0 16 /* application/cose; cose-type="cose-encrypt0" */
#define COAP_MEDIATYPE_APPLICATION_COSE_MAC      97 /* application/cose; cose-type="cose-mac"      */
#define COAP_MEDIATYPE_APPLICATION_COSE_MAC0     17 /* application/cose; cose-type="cose-mac0"     */
 
#define COAP_MEDIATYPE_APPLICATION_COSE_KEY     101 /* application/cose-key  */
#define COAP_MEDIATYPE_APPLICATION_COSE_KEY_SET 102 /* application/cose-key-set  */
 
/* Content formats from RFC 8428 */
#define COAP_MEDIATYPE_APPLICATION_SENML_JSON   110 /* application/senml+json  */
#define COAP_MEDIATYPE_APPLICATION_SENSML_JSON  111 /* application/sensml+json */
#define COAP_MEDIATYPE_APPLICATION_SENML_CBOR   112 /* application/senml+cbor  */
#define COAP_MEDIATYPE_APPLICATION_SENSML_CBOR  113 /* application/sensml+cbor */
#define COAP_MEDIATYPE_APPLICATION_SENML_EXI    114 /* application/senml-exi   */
#define COAP_MEDIATYPE_APPLICATION_SENSML_EXI   115 /* application/sensml-exi  */
#define COAP_MEDIATYPE_APPLICATION_SENML_XML    310 /* application/senml+xml   */
#define COAP_MEDIATYPE_APPLICATION_SENSML_XML   311 /* application/sensml+xml  */
 
/* Content formats from RFC 8782 */
#define COAP_MEDIATYPE_APPLICATION_DOTS_CBOR    271 /* application/dots+cbor */
 
/* Content formats from RFC 9200 */
#define COAP_MEDIATYPE_APPLICATION_ACE_CBOR      19 /* application/ace+cbor  */
 
/* Content formats from RFC9177 */
#define COAP_MEDIATYPE_APPLICATION_MB_CBOR_SEQ  272 /* application/missing-blocks+cbor-seq */
 
/* Content formats from RFC 8613 */
#define COAP_MEDIATYPE_APPLICATION_OSCORE     10001 /* application/oscore */

typedef int coap_mid_t;

#define COAP_INVALID_MID -1

#define COAP_INVALID_TID COAP_INVALID_MID

COAP_DEPRECATED typedef struct {
  coap_option_num_t key;           /* the option key (no delta coding) */
  unsigned int length;
} coap_option;
 
#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))
 
#ifdef WITH_LWIP
coap_pdu_t *coap_pdu_from_pbuf(struct pbuf *pbuf);
#endif

typedef enum coap_proto_t {
  COAP_PROTO_NONE = 0,
  COAP_PROTO_UDP,
  COAP_PROTO_DTLS,
  COAP_PROTO_TCP,
  COAP_PROTO_TLS,
  COAP_PROTO_WS,
  COAP_PROTO_WSS,
  COAP_PROTO_LAST
} coap_proto_t;

typedef enum coap_pdu_code_t {
  COAP_EMPTY_CODE          = 0,
 
  COAP_REQUEST_CODE_GET    = COAP_REQUEST_GET,
  COAP_REQUEST_CODE_POST   = COAP_REQUEST_POST,
  COAP_REQUEST_CODE_PUT    = COAP_REQUEST_PUT,
  COAP_REQUEST_CODE_DELETE = COAP_REQUEST_DELETE,
  COAP_REQUEST_CODE_FETCH  = COAP_REQUEST_FETCH,
  COAP_REQUEST_CODE_PATCH  = COAP_REQUEST_PATCH,
  COAP_REQUEST_CODE_IPATCH = COAP_REQUEST_IPATCH,
 
  COAP_RESPONSE_CODE_CREATED                    = COAP_RESPONSE_CODE(201),
  COAP_RESPONSE_CODE_DELETED                    = COAP_RESPONSE_CODE(202),
  COAP_RESPONSE_CODE_VALID                      = COAP_RESPONSE_CODE(203),
  COAP_RESPONSE_CODE_CHANGED                    = COAP_RESPONSE_CODE(204),
  COAP_RESPONSE_CODE_CONTENT                    = COAP_RESPONSE_CODE(205),
  COAP_RESPONSE_CODE_CONTINUE                   = COAP_RESPONSE_CODE(231),
  COAP_RESPONSE_CODE_BAD_REQUEST                = COAP_RESPONSE_CODE(400),
  COAP_RESPONSE_CODE_UNAUTHORIZED               = COAP_RESPONSE_CODE(401),
  COAP_RESPONSE_CODE_BAD_OPTION                 = COAP_RESPONSE_CODE(402),
  COAP_RESPONSE_CODE_FORBIDDEN                  = COAP_RESPONSE_CODE(403),
  COAP_RESPONSE_CODE_NOT_FOUND                  = COAP_RESPONSE_CODE(404),
  COAP_RESPONSE_CODE_NOT_ALLOWED                = COAP_RESPONSE_CODE(405),
  COAP_RESPONSE_CODE_NOT_ACCEPTABLE             = COAP_RESPONSE_CODE(406),
  COAP_RESPONSE_CODE_INCOMPLETE                 = COAP_RESPONSE_CODE(408),
  COAP_RESPONSE_CODE_CONFLICT                   = COAP_RESPONSE_CODE(409),
  COAP_RESPONSE_CODE_PRECONDITION_FAILED        = COAP_RESPONSE_CODE(412),
  COAP_RESPONSE_CODE_REQUEST_TOO_LARGE          = COAP_RESPONSE_CODE(413),
  COAP_RESPONSE_CODE_UNSUPPORTED_CONTENT_FORMAT = COAP_RESPONSE_CODE(415),
  COAP_RESPONSE_CODE_UNPROCESSABLE              = COAP_RESPONSE_CODE(422),
  COAP_RESPONSE_CODE_TOO_MANY_REQUESTS          = COAP_RESPONSE_CODE(429),
  COAP_RESPONSE_CODE_INTERNAL_ERROR             = COAP_RESPONSE_CODE(500),
  COAP_RESPONSE_CODE_NOT_IMPLEMENTED            = COAP_RESPONSE_CODE(501),
  COAP_RESPONSE_CODE_BAD_GATEWAY                = COAP_RESPONSE_CODE(502),
  COAP_RESPONSE_CODE_SERVICE_UNAVAILABLE        = COAP_RESPONSE_CODE(503),
  COAP_RESPONSE_CODE_GATEWAY_TIMEOUT            = COAP_RESPONSE_CODE(504),
  COAP_RESPONSE_CODE_PROXYING_NOT_SUPPORTED     = COAP_RESPONSE_CODE(505),
  COAP_RESPONSE_CODE_HOP_LIMIT_REACHED          = COAP_RESPONSE_CODE(508),
 
  COAP_SIGNALING_CODE_CSM                       = COAP_SIGNALING_CSM,
  COAP_SIGNALING_CODE_PING                      = COAP_SIGNALING_PING,
  COAP_SIGNALING_CODE_PONG                      = COAP_SIGNALING_PONG,
  COAP_SIGNALING_CODE_RELEASE                   = COAP_SIGNALING_RELEASE,
  COAP_SIGNALING_CODE_ABORT                     = COAP_SIGNALING_ABORT
} coap_pdu_code_t;
 
typedef enum {
  COAP_BOOL_FALSE,
  COAP_BOOL_TRUE
} coap_bool_t;

coap_pdu_t *coap_pdu_init(coap_pdu_type_t type, coap_pdu_code_t code,
                          coap_mid_t mid, size_t size);

COAP_API coap_pdu_t *coap_new_pdu(coap_pdu_type_t type, coap_pdu_code_t code,
                                  coap_session_t *session);

COAP_API void coap_delete_pdu(coap_pdu_t *pdu);

COAP_API coap_pdu_t *coap_pdu_duplicate(const coap_pdu_t *old_pdu,
                                        coap_session_t *session,
                                        size_t token_length,
                                        const uint8_t *token,
                                        coap_opt_filter_t *drop_options);

int coap_pdu_parse(coap_proto_t proto,
                   const uint8_t *data,
                   size_t length,
                   coap_pdu_t *pdu);

int coap_add_token(coap_pdu_t *pdu,
                   size_t len,
                   const uint8_t *data);

size_t coap_add_option(coap_pdu_t *pdu,
                       coap_option_num_t number,
                       size_t len,
                       const uint8_t *data);

int coap_add_data(coap_pdu_t *pdu,
                  size_t len,
                  const uint8_t *data);

uint8_t *coap_add_data_after(coap_pdu_t *pdu, size_t len);

int coap_get_data(const coap_pdu_t *pdu,
                  size_t *len,
                  const uint8_t **data);

int coap_get_data_large(const coap_pdu_t *pdu,
                        size_t *len,
                        const uint8_t **data,
                        size_t *offset,
                        size_t *total);

coap_pdu_code_t coap_pdu_get_code(const coap_pdu_t *pdu);

void coap_pdu_set_code(coap_pdu_t *pdu, coap_pdu_code_t code);

coap_pdu_type_t coap_pdu_get_type(const coap_pdu_t *pdu);

void coap_pdu_set_type(coap_pdu_t *pdu, coap_pdu_type_t type);

coap_bin_const_t coap_pdu_get_token(const coap_pdu_t *pdu);

coap_mid_t coap_pdu_get_mid(const coap_pdu_t *pdu);

void coap_pdu_set_mid(coap_pdu_t *pdu, coap_mid_t mid);

 
#ifdef __cplusplus
}
#endif
 
#endif /* COAP_PDU_H_ */