gcoap.h File Reference

gcoap definition More...

Detailed Description

gcoap definition

Author

Ken Bannister kb2ma.nosp@m.@run.nosp@m.box.c.nosp@m.om

Hauke Petersen hauke.nosp@m..pet.nosp@m.ersen.nosp@m.@fu-.nosp@m.berli.nosp@m.n.de

Definition in file gcoap.h.

#include <stdint.h>
#include "event/callback.h"
#include "event/timeout.h"
#include "net/ipv6/addr.h"
#include "net/sock/udp.h"
#include "net/nanocoap.h"
#include "net/nanocoap/cache.h"
#include "timex.h"

Include dependency graph for gcoap.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	coap_link_encoder_ctx_t
	Context information required to write a resource link. More...
struct	gcoap_socket_t
	CoAP socket to handle multiple transport types. More...
struct	gcoap_listener
	A modular collection of resources for a server. More...
struct	gcoap_resend_t
	Extends request memo for resending a confirmable request. More...
struct	gcoap_request_memo
	Memo to handle a response for a request. More...
struct	gcoap_observe_memo_t
	Memo for Observe registration and notifications. More...

Macros
#define	CONFIG_GCOAP_PORT   (5683)
	Server port; use RFC 7252 default if not defined.
#define	CONFIG_GCOAPS_PORT   (5684)
	Secure Server port; use RFC 7252 default if not defined.
#define	CONFIG_GCOAP_DTLS_HANDSHAKE_TIMEOUT_MSEC   (3 * MS_PER_SEC)
	Timeout for the DTLS handshake process.
#define	CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS   (1)
	Number of minimum available sessions.
#define	CONFIG_GCOAP_DTLS_MINIMUM_AVAILABLE_SESSIONS_TIMEOUT_MSEC   (15 * MS_PER_SEC)
	Timeout for freeing up a session when minimum number of available sessions is not given.
#define	CONFIG_GCOAP_PDU_BUF_SIZE   (128)
	Size of the buffer used to build a CoAP request or response.
#define	CONFIG_GCOAP_REQ_WAITING_MAX   (2)
	Maximum number of requests awaiting a response.
#define	GCOAP_TOKENLEN_MAX   (8)
	Maximum length in bytes for a token.
#define	GCOAP_HEADER_MAXLEN   (sizeof(coap_hdr_t) + GCOAP_TOKENLEN_MAX)
	Maximum length in bytes for a header, including the token.
#define	CONFIG_GCOAP_TOKENLEN   (2)
	Length in bytes for a token.
#define	GCOAP_PAYLOAD_MARKER   (0xFF)
	Marks the boundary between header and payload.
#define	CONFIG_GCOAP_NO_AUTO_INIT   0
	Disables gcoap startup during system auto init.
#define	GCOAP_SEND_LIMIT_NON   (-1)
	Value for send_limit in request memo when non-confirmable type.
#define	CONFIG_GCOAP_NO_RETRANS_BACKOFF
	Turns off retransmission backoff when defined (undefined per default)
#define	CONFIG_GCOAP_NON_TIMEOUT_MSEC   (5000U)
	Default time to wait for a non-confirmable response [in msec].
#define	CONFIG_GCOAP_OBS_CLIENTS_MAX   (2)
	Maximum number of Observe clients.
#define	CONFIG_GCOAP_OBS_NOTIFIERS_MAX   (2)
	Maximum number of local notifying endpoint addresses.
#define	CONFIG_GCOAP_OBS_REGISTRATIONS_MAX   (2)
	Maximum number of registrations for Observable resources.
#define	CONFIG_GCOAP_OBS_VALUE_WIDTH   (3)
	Width in bytes of the Observe option value for a notification.
#define	CONFIG_GCOAP_RESEND_BUFS_MAX   (1)
	Count of PDU buffers available for resending confirmable messages.

Typedefs
typedef ssize_t(*	gcoap_link_encoder_t) (const coap_resource_t *resource, char *buf, size_t maxlen, coap_link_encoder_ctx_t *context)
	Handler function to write a resource link.
typedef struct gcoap_listener	gcoap_listener_t
	Forward declaration of the gcoap listener state container.
typedef int(*	gcoap_request_matcher_t) (gcoap_listener_t *listener, const coap_resource_t **resource, coap_pkt_t *pdu)
	Handler function for the request matcher strategy.
typedef struct gcoap_request_memo	gcoap_request_memo_t
	Forward declaration of the request memo type.
typedef void(*	gcoap_resp_handler_t) (const gcoap_request_memo_t *memo, coap_pkt_t *pdu, const sock_udp_ep_t *remote)
	Handler function for a server response, including the state for the originating request.

Enumerations
enum	gcoap_socket_type_t { GCOAP_SOCKET_TYPE_UNDEF = 0x0 , GCOAP_SOCKET_TYPE_UDP = 0x1 , GCOAP_SOCKET_TYPE_DTLS = 0x2 }
	CoAP socket types. More...

Functions
kernel_pid_t	gcoap_init (void)
	Initializes the gcoap thread and device.
void	gcoap_register_listener (gcoap_listener_t *listener)
	Starts listening for resource paths.
const coap_resource_t *	gcoap_get_resource_by_path_iterator (const gcoap_listener_t **last_listener, const coap_resource_t *last_resource, const char *uri_path)
	Iterate through all registered listeners and check for a resource, matching by uri_path.
int	gcoap_req_init_path_buffer (coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, const char *path, size_t path_len)
	Initializes a CoAP request PDU on a buffer.
static int	gcoap_req_init (coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, const char *path)
	Initializes a CoAP request PDU on a buffer.
static ssize_t	gcoap_request (coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code, char *path)
	Writes a complete CoAP request PDU when there is not a payload.
ssize_t	gcoap_req_send (const uint8_t *buf, size_t len, const sock_udp_ep_t *remote, const sock_udp_ep_t *local, gcoap_resp_handler_t resp_handler, void *context, gcoap_socket_type_t tl_type)
	Sends a buffer containing a CoAP request to the provided endpoint.
static ssize_t	gcoap_req_send_tl (const uint8_t *buf, size_t len, const sock_udp_ep_t *remote, gcoap_resp_handler_t resp_handler, void *context, gcoap_socket_type_t tl_type)
	Sends a buffer containing a CoAP request to the provided endpoint.
int	gcoap_resp_init (coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code)
	Initializes a CoAP response packet on a buffer.
static ssize_t	gcoap_response (coap_pkt_t *pdu, uint8_t *buf, size_t len, unsigned code)
	Writes a complete CoAP response PDU when there is no payload.
int	gcoap_obs_init (coap_pkt_t *pdu, uint8_t *buf, size_t len, const coap_resource_t *resource)
	Initializes a CoAP Observe notification packet on a buffer, for the observer registered for a resource.
size_t	gcoap_obs_send (const uint8_t *buf, size_t len, const coap_resource_t *resource)
	Sends a buffer containing a CoAP Observe notification to the observer registered for a resource.
int	gcoap_obs_req_forget (const sock_udp_ep_t *remote, const uint8_t *token, size_t tokenlen)
	Forgets (invalidates) an existing observe request.
uint8_t	gcoap_op_state (void)
	Provides important operational statistics.
int	gcoap_get_resource_list (void *buf, size_t maxlen, uint8_t cf, gcoap_socket_type_t tl_type)
	Get the resource list, currently only CoRE Link Format (COAP_FORMAT_LINK) supported.
ssize_t	gcoap_encode_link (const coap_resource_t *resource, char *buf, size_t maxlen, coap_link_encoder_ctx_t *context)
	Writes a resource in CoRE Link Format to a provided buffer.
sock_dtls_t *	gcoap_get_sock_dtls (void)
	Get the underlying DTLS socket of gcoap.
static coap_hdr_t *	gcoap_request_memo_get_hdr (const gcoap_request_memo_t *memo)
	Get the header of a request from a gcoap_request_memo_t.

States for the memo used to track waiting for a response
#define	GCOAP_MEMO_UNUSED   (0)
	This memo is unused.
#define	GCOAP_MEMO_RETRANSMIT   (1)
	Request sent, retransmitting until response arrives.
#define	GCOAP_MEMO_WAIT   (2)
	Request sent; awaiting response.
#define	GCOAP_MEMO_RESP   (3)
	Got response.
#define	GCOAP_MEMO_TIMEOUT   (4)
	Timeout waiting for response.
#define	GCOAP_MEMO_ERR   (5)
	Error processing response packet.
#define	GCOAP_MEMO_RESP_TRUNC   (6)
	Got response, but it got truncated into the receive buffer that is now incomplete.

States for the memo used to track Observe registrations
#define	GCOAP_OBS_MEMO_UNUSED   (0)
	This memo is unused.
#define	GCOAP_OBS_MEMO_IDLE   (1)
	Registration OK; no current activity.
#define	GCOAP_OBS_MEMO_PENDING   (2)
	Resource changed; notification pending.

Return values for gcoap_obs_init()
See CONFIG_GCOAP_OBS_VALUE_WIDTH
#define	GCOAP_OBS_INIT_OK   (0)
#define	GCOAP_OBS_INIT_ERR   (-1)
#define	GCOAP_OBS_INIT_UNUSED   (-2)
#define	GCOAP_DTLS_EXTRA_STACKSIZE   (0)
	Stack size for module thread.
#define	GCOAP_VFS_EXTRA_STACKSIZE   (0)
	Extra stack for VFS operations.
#define	GCOAP_STACK_SIZE

Bitwise positional flags for encoding resource links
#define	COAP_LINK_FLAG_INIT_RESLIST   (1)
	initialize as for first resource in a list

Return values for resource related operations
#define	GCOAP_RESOURCE_FOUND   (0)
#define	GCOAP_RESOURCE_WRONG_METHOD   (1)
#define	GCOAP_RESOURCE_NO_PATH   (2)
#define	GCOAP_RESOURCE_ERROR   (3)