gcoap.h

gcoap definition

GCOAP_MEMO_UNUSED

This memo is unused. 

1
(0)
GCOAP_MEMO_WAIT

Request sent; awaiting response. 

1
(1)
GCOAP_MEMO_RESP

Got response. 

1
(2)
GCOAP_MEMO_TIMEOUT

Timeout waiting for response. 

1
(3)
GCOAP_MEMO_ERR

Error processing response packet. 

1
(4)
GCOAP_OBS_MEMO_UNUSED

This memo is unused. 

1
(0)
GCOAP_OBS_MEMO_IDLE

Registration OK; no current activity. 

1
(1)
GCOAP_OBS_MEMO_PENDING

Resource changed; notification pending. 

1
(2)
GCOAP_OBS_INIT_OK
1
(0)
GCOAP_OBS_INIT_ERR
1
(-1)
GCOAP_OBS_INIT_UNUSED
1
(-2)
GCOAP_MSG_QUEUE_SIZE

Size for module message queue. 

1
(4)
GCOAP_PORT

Server port; use RFC 7252 default if not defined. 

1
(5683)
GCOAP_PDU_BUF_SIZE

Size of the buffer used to build a CoAP request or response. 

1
(128)
GCOAP_REQ_WAITING_MAX

Maximum number of requests awaiting a response. 

1
(2)
GCOAP_TOKENLEN_MAX

Maximum length in bytes for a token. 

1
(8)
GCOAP_HEADER_MAXLEN

Maximum length in bytes for a header, including the token. 

1
(sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
GCOAP_TOKENLEN

Length in bytes for a token; use 2 if not defined. 

1
(2)
GCOAP_PAYLOAD_MARKER

Marks the boundary between header and payload. 

1
(0xFF)
GCOAP_SEND_LIMIT_NON

Value for send_limit in request memo when non-confirmable type. 

1
(-1)
GCOAP_RECV_TIMEOUT

Time in usec that the event loop waits for an incoming CoAP message. 

1
(1 * US_PER_SEC)
GCOAP_NON_TIMEOUT

Default time to wait for a non-confirmable response [in usec]. 

1
(5000000U)

Set to 0 to disable timeout.

GCOAP_MSG_TYPE_TIMEOUT

Identifies waiting timed out for a response to a sent message. 

1
(0x1501)
GCOAP_MSG_TYPE_INTR

Identifies a request to interrupt listening for an incoming message on a sock. 

1
(0x1502)

Allows the event loop to process IPC messages.

GCOAP_OBS_CLIENTS_MAX

Maximum number of Observe clients; use 2 if not defined. 

1
(2)
GCOAP_OBS_REGISTRATIONS_MAX

Maximum number of registrations for Observable resources; use 2 if not defined. 

1
(2)
GCOAP_OBS_VALUE_WIDTH

Width in bytes of the Observe option value for a notification. 

1
(3)

This width is used to determine the length of the ‘tick’ used to measure the time between observable changes to a resource. A tick is expressed internally as GCOAP_OBS_TICK_EXPONENT, which is the base-2 log value of the tick length in microseconds.

The canonical setting for the value width is 3 (exponent 5), which results in a tick length of 32 usec, per sec. 3.4, 4.4 of the RFC. Width 2 (exponent 16) results in a tick length of ~65 msec, and width 1 (exponent 24) results in a tick length of ~17 sec.

The tick length must be short enough so that the Observe value strictly increases for each new notification. The purpose of the value is to allow a client to detect message reordering within the network latency period (128 sec). For resources that change only slowly, the reduced message length is useful when packet size is limited.

GCOAP_OBS_TICK_EXPONENT

See GCOAP_OBS_VALUE_WIDTH. 

1
(5)
GCOAP_STACK_SIZE

Stack size for module thread. 

1
2
(THREAD_STACKSIZE_DEFAULT + DEBUG_EXTRA_STACKSIZE \
                          + sizeof(coap_pkt_t))
GCOAP_RESEND_BUFS_MAX

Count of PDU buffers available for resending confirmable messages. 

1
(1)
struct gcoap_listener gcoap_listener_t

A modular collection of resources for a server.

void(* gcoap_resp_handler_t()

Handler function for a server response, including the state for the originating request.

If request timed out, the packet header is for the request.

kernel_types.h::kernel_pid_t gcoap_init(void)

Initializes the gcoap thread and device.

Must call once before first use.

Return values

  • PID of the gcoap thread on success.
  • -EEXIST, if thread already has been created.
  • -EINVAL, if the IP port already is in use.
void gcoap_register_listener(gcoap.h::gcoap_listener_t * listener)

Starts listening for resource paths.

Parameters

listener:Listener containing the resources.

int gcoap_req_init(coap_pkt_t * pdu, uint8_t * buf, msp430_types.h::size_t len, unsigned code, const char * path)

Initializes a CoAP request PDU on a buffer.

Parameters

pdu:Request metadata
buf:Buffer containing the PDU
len:Length of the buffer
code:Request code: GCOAP_[GET|POST|PUT|DELETE]
path:Resource path, must start with ‘/’

Return values

  • 0 on success
  • < 0 on error
msp430_types.h::ssize_t gcoap_finish(coap_pkt_t * pdu, msp430_types.h::size_t payload_len, unsigned format)

Finishes formatting a CoAP PDU after the payload has been written.

Assumes the PDU has been initialized with a gcoap_xxx_init() function, like gcoap.h::gcoap_req_init().

Parameters

pdu:Request metadata
payload_len:Length of the payload, or 0 if none
format:Format code for the payload; use COAP_FORMAT_NONE if not specified

Return values

  • size of the PDU
  • < 0 on error
msp430_types.h::ssize_t gcoap_request(coap_pkt_t * pdu, uint8_t * buf, msp430_types.h::size_t len, unsigned code, char * path)

Writes a complete CoAP request PDU when there is not a payload.

Parameters

pdu:Request metadata
buf:Buffer containing the PDU
len:Length of the buffer
code:Request code: GCOAP_[GET|POST|PUT|DELETE]
path:Resource path, must start with ‘/’

Return values

  • size of the PDU within the buffer
  • < 0 on error
msp430_types.h::size_t gcoap_req_send2(const uint8_t * buf, msp430_types.h::size_t len, const sock/udp.h::sock_udp_ep_t * remote, gcoap.h::gcoap_resp_handler_t resp_handler)

Sends a buffer containing a CoAP request to the provided endpoint.

Parameters

buf:Buffer containing the PDU
len:Length of the buffer
remote:Destination for the packet
resp_handler:Callback when response received, may be NULL

Return values

  • length of the packet
  • 0 if cannot send
msp430_types.h::size_t gcoap_req_send(const uint8_t * buf, msp430_types.h::size_t len, const ipv6_addr_t * addr, uint16_t port, gcoap.h::gcoap_resp_handler_t resp_handler)

Sends a buffer containing a CoAP request to the provided host/port.

Please use gcoap.h::gcoap_req_send2() instead

Parameters

buf:Buffer containing the PDU
len:Length of the buffer
addr:Destination for the packet
port:Port at the destination
resp_handler:Callback when response received, may be NULL

Return values

  • length of the packet
  • 0 if cannot send
int gcoap_resp_init(coap_pkt_t * pdu, uint8_t * buf, msp430_types.h::size_t len, unsigned code)

Initializes a CoAP response packet on a buffer.

Initializes payload location within the buffer based on packet setup.

Parameters

pdu:Response metadata
buf:Buffer containing the PDU
len:Length of the buffer
code:Response code

Return values

  • 0 on success
  • < 0 on error
msp430_types.h::ssize_t gcoap_response(coap_pkt_t * pdu, uint8_t * buf, msp430_types.h::size_t len, unsigned code)

Writes a complete CoAP response PDU when there is no payload.

Parameters

pdu:Response metadata
buf:Buffer containing the PDU
len:Length of the buffer
code:Response code

Return values

  • size of the PDU within the buffer
  • < 0 on error
int gcoap_obs_init(coap_pkt_t * pdu, uint8_t * buf, msp430_types.h::size_t len, const coap_resource_t * resource)

Initializes a CoAP Observe notification packet on a buffer, for the observer registered for a resource.

First verifies that an observer has been registered for the resource.

Parameters

pdu:Notification metadata
buf:Buffer containing the PDU
len:Length of the buffer
resource:Resource for the notification

Return values

  • GCOAP_OBS_INIT_OK on success
  • GCOAP_OBS_INIT_ERR on error
  • GCOAP_OBS_INIT_UNUSED if no observer for resource
msp430_types.h::size_t gcoap_obs_send(const uint8_t * buf, msp430_types.h::size_t len, const coap_resource_t * resource)

Sends a buffer containing a CoAP Observe notification to the observer registered for a resource.

Assumes a single observer for a resource.

Parameters

buf:Buffer containing the PDU
len:Length of the buffer
resource:Resource to send

Return values

  • length of the packet
  • 0 if cannot send
uint8_t gcoap_op_state(void)

Provides important operational statistics.

Useful for monitoring.

Return values

  • count of unanswered requests
int gcoap_get_resource_list(void * buf, msp430_types.h::size_t maxlen, uint8_t cf)

Get the resource list, currently only CoRE Link Format (COAP_FORMAT_LINK) supported.

If buf := NULL, nothing will be written but the size of the resulting resource list is computed and returned.

Parameters

buf:output buffer to write resource list into, my be NULL
maxlen:length of buf, ignored if buf is NULL
cf:content format to use for the resource list, currently only COAP_FORMAT_LINK supported

add support for JSON CoRE Link Format

add support for ‘CBOR CoRE Link Format`

Return values

  • the number of bytes written to buf
  • -1 on error
int gcoap_add_qstring(coap_pkt_t * pdu, const char * key, const char * val)

Adds a single Uri-Query option to a CoAP request.

To add multiple Uri-Query options, simply call this function multiple times. The Uri-Query options will be added in the order those calls.

Parameters

pdu:The package that is being build
key:Key to add to the query string
val:Value to assign to key (may be NULL)

Return values

  • overall length of new query string
  • -1 on error
struct gcoap_listener

A modular collection of resources for a server.

const coap_resource_t * resources

First element in the array of resources; must order alphabetically.

msp430_types.h::size_t resources_len

Length of array.

struct gcoap_listener * next

Next listener in list.

struct gcoap_resend_t

Extends request memo for resending a confirmable request.

uint8_t * pdu_buf

Buffer containing the PDU.

msp430_types.h::size_t pdu_len

Length of pdu_buf.

struct gcoap_request_memo_t

Memo to handle a response for a request.

unsigned state

State of this memo, a GCOAP_MEMO…

int send_limit

Remaining resends, 0 if none; GCOAP_SEND_LIMIT_NON if non-confirmable.

uint8_t hdr_buf()

Copy of PDU header, if no resends.

gcoap_resend_t data

Endpoint and PDU buffer, for resend.

union gcoap_request_memo_t::@187 msg

Request message data; if confirmable, supports resending message.

sock/udp.h::sock_udp_ep_t remote_ep

Remote endpoint.

gcoap.h::gcoap_resp_handler_t resp_handler

Callback for the response.

xtimer.h::xtimer_t response_timer

Limits wait for response.

msg_t timeout_msg

For response timer.

struct gcoap_observe_memo_t

Memo for Observe registration and notifications.

sock/udp.h::sock_udp_ep_t * observer

Client endpoint; unused if null.

const coap_resource_t * resource

Entity being observed.

uint8_t token()

Client token for notifications.

unsigned token_len

Actual length of token attribute.