Proxy

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_DYN_DEFINED = (1 << 8) }
	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.
COAP_API coap_proxy_entry_t *	coap_proxy_fwd_add_client_session (coap_session_t *session, const char *use_ip, uint16_t use_port, coap_proxy_server_list_t *server_list)
	Add a previously setup proxy-client session to use the proxy logic for forwarding subsequent dynamic proxy requests.

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 92 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 91 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 133 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 ]
COAP_PROXY_DYN_DEFINED	If COAP_PROXY_DYN_DEFINED set, then no new dynamic upstream servers will get automatically added. All dynamic upstream servers mut be pre-allocated by using coap_proxy_fwd_add_client_session(). [ 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 1816 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 1832 of file coap_proxy.c.

coap_proxy_fwd_add_client_session()

COAP_API coap_proxy_entry_t * coap_proxy_fwd_add_client_session	(	coap_session_t *	session,
		const char *	use_ip,
		uint16_t	use_port,
		coap_proxy_server_list_t *	server_list
	)

Add a previously setup proxy-client session to use the proxy logic for forwarding subsequent dynamic proxy requests.

The upstream server information is derived from session for the remote IP and use_port for the port, and proxy connection type is derived from server_list (track_client_session, and idle_timeout_secs are ignored and set to 0 and 0 respectively). type must contain at least COAP_PROXY_FWD_DYNAMIC, and server_list must be the same as used in coap_proxy_forward_request().

Parameters

session	The CoAP upstream proxy session previosly set up (e.g. via call-home).
use_ip	The IP address to match on incoming proxy requests. If NULL, then the IP address is determined from session.
use_port	The port number to match on incoming proxy requests. If 0, default port for protocol is used.
server_list	The upstream server connection characteristics.

Returns

the proxy entry on success in adding session to the proxy list of upstream servers, else NULL.

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 5260 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 1842 of file coap_proxy.c.