API for Proxies. More...

Collaboration diagram for Proxy:

Data Structures
struct	coap_proxy_server_t

struct	coap_proxy_server_list_t

Macros
#define	COAP_PROXY_OLD_MASK 0x07
	Space used in coap_proxy_t for old types.

#define	COAP_PROXY_NEW_MASK 0x38
	Space used in coap_proxy_t for new types.

Typedefs
typedef struct coap_proxy_server_t	coap_proxy_server_t

typedef struct coap_proxy_server_list_t	coap_proxy_server_list_t

typedef coap_pdu_t (	coap_proxy_response_handler_t) (coap_session_t session, const coap_pdu_t sent, coap_pdu_t received, coap_cache_key_t cache_key)
	Proxy response handler that is used as callback held in coap_context_t.

Enumerations
enum	coap_proxy_t { COAP_PROXY_REVERSE , COAP_PROXY_REVERSE_STRIP , COAP_PROXY_FORWARD , COAP_PROXY_FORWARD_STRIP , COAP_PROXY_DIRECT , COAP_PROXY_DIRECT_STRIP , COAP_PROXY_FORWARD_DYNAMIC = COAP_PROXY_DIRECT , COAP_PROXY_FORWARD_DYNAMIC_STRIP = COAP_PROXY_DIRECT_STRIP , COAP_PROXY_REV = (1 << 3) , COAP_PROXY_FWD_STATIC = (2 << 3) , COAP_PROXY_FWD_DYNAMIC = (3 << 3) , COAP_PROXY_BIT_STRIP = (1 << 6) , COAP_PROXY_BIT_MCAST = (1 << 7) }
	coap_proxy_t Proxy definitions. More...

Functions
void	coap_register_proxy_response_handler (coap_context_t *context, coap_proxy_response_handler_t handler)
	Registers a new message handler that is called whenever a response is received by the proxy logic.

int	coap_verify_proxy_scheme_supported (coap_uri_scheme_t scheme)
	Verify that the CoAP Scheme is supported for an ongoing proxy connection.

COAP_API int	coap_proxy_forward_request (coap_session_t req_session, const coap_pdu_t request, coap_pdu_t response, coap_resource_t resource, coap_cache_key_t cache_key, coap_proxy_server_list_t server_list)
	Forward incoming request upstream to the next proxy/server.

coap_response_t COAP_API	coap_proxy_forward_response (coap_session_t rsp_session, const coap_pdu_t received, coap_cache_key_t **cache_key)
	Forward the returning response back to the appropriate client.

COAP_API coap_session_t *	coap_new_client_session_proxy (coap_context_t context, coap_proxy_server_list_t server_list)
	Creates a new client session to use the proxy logic going to the defined upstream server.

Detailed Description

API for Proxies.

Macro Definition Documentation

◆ COAP_PROXY_NEW_MASK

#define COAP_PROXY_NEW_MASK 0x38

Space used in coap_proxy_t for new types.

Definition at line 85 of file coap_proxy.h.

◆ COAP_PROXY_OLD_MASK

#define COAP_PROXY_OLD_MASK 0x07

Space used in coap_proxy_t for old types.

Definition at line 84 of file coap_proxy.h.

Typedef Documentation

◆ coap_proxy_response_handler_t

typedef coap_pdu_t *(* coap_proxy_response_handler_t) (coap_session_t *session, const coap_pdu_t *sent, coap_pdu_t *received, coap_cache_key_t *cache_key)

Proxy response handler that is used as callback held in coap_context_t.

Parameters

session	CoAP session.
sent	The PDU that was transmitted.
received	The response PDU that was received, or returned from cache.
cache_key	Updated with the cache key pointer provided to coap_proxy_forward_request(). The caller should delete this cache key (unless the client request set up an Observe and there will be unsolicited responses).

Returns: The PDU to be sent back to the client (usually received) or NULL if error. If NULL, this will cause sending a RST packet to the upstream server if the received PDU is a CON or NON. If the returned PDU is not received or NULL, then received must be freed off in the handler.

Definition at line 126 of file coap_proxy.h.

◆ coap_proxy_server_list_t

typedef struct coap_proxy_server_list_t coap_proxy_server_list_t

◆ coap_proxy_server_t

typedef struct coap_proxy_server_t coap_proxy_server_t

Enumeration Type Documentation

◆ coap_proxy_t

enum coap_proxy_t

coap_proxy_t Proxy definitions.

0x00000007 Old 4.3.5 mappings for backward compatability. 0x00000038 New type mappings. 0xffffffc0 Bitwise optional actions.

Three types of proxy. reverse Traffic forward to internal set of servers. forward-static Traffic forwarded to defined set of servers. forward-dynamic Traffic forwarded to host defined by Proxy-Uri / Proxy-Scheme options. Additional options for each proxy type. strip Remove Proxy-Uri and/or Proxy-Scheme options. mcast Support forward-dynamic traffic to multicast addresses.

Enumerator
COAP_PROXY_REVERSE	Old - do not use - Act as a reverse proxy.
COAP_PROXY_REVERSE_STRIP	Old - do not use - Act as a reverse proxy, strip out proxy options.
COAP_PROXY_FORWARD	Old - do not use - Act as a forward-static proxy.
COAP_PROXY_FORWARD_STRIP	Old - do not use - Act as a forward-static proxy, strip out proxy options.
COAP_PROXY_DIRECT	Old - do not use - Act as a forward-dynamic proxy.
COAP_PROXY_DIRECT_STRIP	Old - do not use - Act as a forward-dynamic proxy, strip out proxy options.
COAP_PROXY_FORWARD_DYNAMIC	Old - do not use - Act as a forward-dynamic proxy.
COAP_PROXY_FORWARD_DYNAMIC_STRIP	Old - do not use - Act as a forward-dynamic proxy, strip out proxy options.
COAP_PROXY_REV	reverse proxy.
COAP_PROXY_FWD_STATIC	forward-static proxy.
COAP_PROXY_FWD_DYNAMIC	forward-dynamic proxy.
COAP_PROXY_BIT_STRIP	If COAP_PROXY_BIT_STRIP set, then remove any Proxy-Uri or Proxy-Scheme, else leave them.
COAP_PROXY_BIT_MCAST	If COAP_PROXY_BIT_MCAST set, then upstream servers can be multicast, else only unicast. [ Ignored if not COAP_PROXY_FWD_DYNAMIC ]

Definition at line 48 of file coap_proxy.h.

Function Documentation

◆ coap_new_client_session_proxy()

COAP_API coap_session_t * coap_new_client_session_proxy	(	coap_context_t *	context,
		coap_proxy_server_list_t *	server_list
	)

Creates a new client session to use the proxy logic going to the defined upstream server.

Note: If server_list contains more than one server, the first server is not always chosen.

Note: server_list must exist for the duration of the returned session as it is used for every coap_send() or coap_send_recv().

Note: Unless coap_send_recv() is used, the response is sent to the handler defined by coap_register_response_handler(), not to the handler defined by coap_register_proxy_response_handler().

Parameters

context	The CoAP context.
server_list	The upstream server list to connect to.

Returns: A new CoAP session or NULL if failed. Call coap_session_release() to free.

◆ coap_proxy_forward_request()

COAP_API int coap_proxy_forward_request	(	coap_session_t *	req_session,
		const coap_pdu_t *	request,
		coap_pdu_t *	response,
		coap_resource_t *	resource,
		coap_cache_key_t *	cache_key,
		coap_proxy_server_list_t *	server_list
	)

Forward incoming request upstream to the next proxy/server.

Possible scenarios: Acting as a reverse proxy - connect to defined internal server (possibly round robin load balancing over multiple servers). Acting as a forward-dynamic proxy - connect to host defined in Proxy-Uri or Proxy-Scheme with Uri-Host (and maybe Uri-Port). Acting as a forward-static proxy - connect to defined upstream server (possibly round robin load balancing over multiple servers).

A request that should go direct to this next proxy/server is not supported using this function - set up a new session using coap_new_client_session_proxy().

Parameters

req_session	The client session.
request	The client's request PDU.
response	The response PDU that will get sent back to the client.
resource	The resource associated with this request.
cache_key	A cache key generated from the request PDU or NULL.
server_list	The upstream server list to connect to.

Returns: 1 if success, or 0 if failure (response code set to appropriate value).

Definition at line 1681 of file coap_proxy.c.

◆ coap_proxy_forward_response()

coap_response_t COAP_API coap_proxy_forward_response	(	coap_session_t *	rsp_session,
		const coap_pdu_t *	received,
		coap_cache_key_t **	cache_key
	)

Forward the returning response back to the appropriate client.

Parameters

rsp_session	The upstream session receiving the response.
received	The received PDU.
cache_key	Updated with the cache key pointer provided to coap_proxy_forward_request(). The caller should delete this cache key (unless the client request set up an Observe and there will be unsolicited responses).

Returns: One of COAP_RESPONSE_FAIL or COAP_RESPONSE_OK.

Definition at line 1697 of file coap_proxy.c.

◆ coap_register_proxy_response_handler()

void coap_register_proxy_response_handler	(	coap_context_t *	context,
		coap_proxy_response_handler_t	handler
	)

Registers a new message handler that is called whenever a response is received by the proxy logic.

Note: If this is not defined, then the handler registered by coap_register_response_handler() will be used.

Parameters

context	The context to register the handler for.
handler	The response handler to register.

Definition at line 5170 of file coap_net.c.

◆ coap_verify_proxy_scheme_supported()

int coap_verify_proxy_scheme_supported ( coap_uri_scheme_t scheme )

Verify that the CoAP Scheme is supported for an ongoing proxy connection.

Parameters

scheme The CoAP scheme to check.

Returns: 1 if supported, or 0 if not supported.

Definition at line 1707 of file coap_proxy.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ COAP_PROXY_NEW_MASK

◆ COAP_PROXY_OLD_MASK

Typedef Documentation

◆ coap_proxy_response_handler_t

◆ coap_proxy_server_list_t

◆ coap_proxy_server_t

Enumeration Type Documentation

◆ coap_proxy_t

Function Documentation

◆ coap_new_client_session_proxy()

◆ coap_proxy_forward_request()

◆ coap_proxy_forward_response()

◆ coap_register_proxy_response_handler()

◆ coap_verify_proxy_scheme_supported()