Client side

Client side support functions. More...

Functions
void	oc_close_session (oc_endpoint_t *endpoint)
	close the tls session on the indicated endpoint More...
bool	oc_do_delete (const char *uri, oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, void *user_data)
	Issue a DELETE request to delete a resource. More...
bool	oc_do_get (const char *uri, oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, void *user_data)
	issues a get request with accept-content CBOR More...
bool	oc_do_get_ex (const char *uri, oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, oc_content_format_t content, oc_content_format_t accept, void *user_data)
	Issue a GET request to obtain the current value of all properties a resource. More...
bool	oc_do_multicast_update (void)
	initiate the multi-cast update More...
bool	oc_do_observe (const char *uri, oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, void *user_data)
	Dispatch a GET request with the CoAP Observe option to subscribe for notifications from a resource. More...
bool	oc_do_post (void)
	Dispatch the CoAP POST request wiht content type and accept type CBOR. More...
bool	oc_do_post_ex (oc_content_format_t content, oc_content_format_t accept)
	Dispatch the CoAP POST request. More...
bool	oc_do_put (void)
	Dispatch the CoAP PUT request wiht content type and accept type CBOR. More...
bool	oc_do_put_ex (oc_content_format_t content, oc_content_format_t accept)
	Dispatch the CoAP PUT request. More...
bool	oc_do_wk_discovery_all (const char *uri_query, int scope, oc_discovery_all_handler_t handler, void *user_data)
	Discover all servers that have a resource type using the site-local scope. More...
void	oc_free_server_endpoints (oc_endpoint_t *endpoint)
	Free a list of endpoints from the oc_endpoint_t. More...
bool	oc_init_multicast_update (oc_endpoint_t *mcast, const char *uri, const char *query)
	initialize the multicast update More...
bool	oc_init_post (const char *uri, oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, void *user_data)
	Prepare the stack to issue a POST request. More...
bool	oc_init_put (const char *uri, oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, void *user_data)
	Prepare the stack to issue a PUT request. More...
int	oc_lf_get_entry_param (const char *payload, int payload_len, int entry, const char *param, const char **p_out, int *p_len)
	link format parser, retrieve a parameter value More...
int	oc_lf_get_entry_uri (const char *payload, int payload_len, int entry, const char **uri, int *uri_len)
	link format parser, retrieve the URL of an entry. More...
int	oc_lf_number_of_entries (const char *payload, int payload_len)
	link format parser, retrieve the number of entries in a response More...
bool	oc_send_ping (bool custody, oc_endpoint_t *endpoint, uint16_t timeout_seconds, oc_response_handler_t handler, void *user_data)
	send CoAP ping over the TCP connection More...
void	oc_stop_multicast (oc_client_response_t *response)
	stop the multicast update (e.g. More...
bool	oc_stop_observe (const char *uri, oc_endpoint_t *endpoint)
	Unsubscribe for notifications from a resource. More...

Detailed Description

Client side support functions.

This module contains functions to communicate to a KNX server for an Client.

multicast

The multicast communication is for:

• Discovery

The multicast Discovery is issued is on CoAP .well-known/core The s-mode communication is performed at the (specific) group addresses.

unicast communication

The following functions can be used to communicate on CoAP level e.g. issuing:

• GET
• PUT
• POST
• DELETE functions. The functions are secured with OSCORE.

Function Documentation

oc_close_session()

void oc_close_session

(

oc_endpoint_t *

endpoint

)

close the tls session on the indicated endpoint

Parameters

endpoint

endpoint indicating a session

oc_do_delete()

bool oc_do_delete	(	const char *	uri,
		oc_endpoint_t *	endpoint,
		const char *	query,
		oc_response_handler_t	handler,
		oc_qos_t	qos,
		void *	user_data
	)

Issue a DELETE request to delete a resource.

Parameters

[in]	uri	The uri of the resource
[in]	endpoint	The endpoint of the server
[in]	query	a query parameter that will be sent to the server's oc_request_callback_t.
[in]	handler	The function invoked once the client has received the servers response to the DELETE request
[in]	qos	The quality of service current options are HIGH_QOS or LOW_QOS
[in]	user_data	The context pointer that will be sent to the oc_response_handler_t

Returns

True if the client successfully dispatched the CoAP DELETE request

oc_do_get()

bool oc_do_get	(	const char *	uri,
		oc_endpoint_t *	endpoint,
		const char *	query,
		oc_response_handler_t	handler,
		oc_qos_t	qos,
		void *	user_data
	)

issues a get request with accept-content CBOR

Parameters

uri	the uri to be used
endpoint	the endpoint of the device
query	the query
handler	the callback handler
qos	the qos type confirmable / not confirmable
user_data	the user data

Returns

true

false

See also

oc_do_get_ex

oc_do_get_ex()

bool oc_do_get_ex	(	const char *	uri,
		oc_endpoint_t *	endpoint,
		const char *	query,
		oc_response_handler_t	handler,
		oc_qos_t	qos,
		oc_content_format_t	content,
		oc_content_format_t	accept,
		void *	user_data
	)

Issue a GET request to obtain the current value of all properties a resource.

Example:

static bool value;
 
static void
get_light(oc_client_response_t *data)
{
  PRINT("GET_light:\n");
  oc_rep_t *rep = data->payload;
  while (rep != NULL) {
    PRINT("key %s, value ", oc_string_checked(rep->name));
    switch (rep->type) {
    case OC_REP_BOOL:
      PRINT("%d\n", rep->value.boolean);
      value = rep->value.boolean;
      break;
    default:
      break;
    }
    rep = rep->next;
  }
}
//the server uri and server endpoint obtained from oc_discovery_handler_t
// as a result of an oc_do_ip_discovery call
oc_do_get_ex(server_uri, server_ep, NULL, &get_switch, LOW_QOS,
  APPLICATION_CBOR, APPLICATION_CBOR, NULL);

Parameters

[in]	uri	the uri of the resource
[in]	endpoint	the endpoint of the server
[in]	query	a query parameter that will be sent to the server's oc_request_callback_t.
[in]	handler	function invoked once the client has received the servers response to the GET request
[in]	qos	the quality of service current options are HIGH_QOS or LOW_QOS
[in]	content	The content format of the request payload
[in]	accept	The content format of the response payload
[in]	user_data	context pointer that will be sent to the oc_response_handler_t

Returns

True if the client successfully dispatched the CoAP GET request

oc_do_multicast_update()

bool oc_do_multicast_update

(

void

)

initiate the multi-cast update

Returns

true

false

oc_do_observe()

bool oc_do_observe	(	const char *	uri,
		oc_endpoint_t *	endpoint,
		const char *	query,
		oc_response_handler_t	handler,
		oc_qos_t	qos,
		void *	user_data
	)

Dispatch a GET request with the CoAP Observe option to subscribe for notifications from a resource.

The oc_response_handler_t will be invoked each time upon receiving a notification.

The handler will continue to be invoked till oc_stop_observe() is called.

Parameters

[in]	uri	the uri of the resource
[in]	endpoint	the endpoint of the server
[in]	query	a query parameter that will be sent to the server's oc_request_callback_t.
[in]	handler	function invoked once the client has received the servers response to the POST request
[in]	qos	the quality of service current options are HIGH_QOS or LOW_QOS
[in]	user_data	context pointer that will be sent to the oc_response_handler_t

Returns

True if the client successfully dispatched the CaAP observer request

oc_do_post()

bool oc_do_post

(

void

)

Dispatch the CoAP POST request wiht content type and accept type CBOR.

Returns

true

false

See also

oc_do_post_ex

oc_do_post_ex()

bool oc_do_post_ex	(	oc_content_format_t	content,
		oc_content_format_t	accept
	)

Dispatch the CoAP POST request.

Parameters

content	The content format of the request payload
accept	The content format of the response payload

Returns

true if the client successfully dispatched the CoAP POST request

false

See also

oc_init_post

oc_do_put()

bool oc_do_put

(

void

)

Dispatch the CoAP PUT request wiht content type and accept type CBOR.

Returns

true

false

See also

oc_do_put_ex

oc_do_put_ex()

bool oc_do_put_ex	(	oc_content_format_t	content,
		oc_content_format_t	accept
	)

Dispatch the CoAP PUT request.

Parameters

content	The content format of the request payload
accept	The content format of the response payload

Returns

true if the client successfully dispatched the CoAP request

false

See also

oc_init_put

oc_do_wk_discovery_all()

bool oc_do_wk_discovery_all	(	const char *	uri_query,
		int	scope,
		oc_discovery_all_handler_t	handler,
		void *	user_data
	)

Discover all servers that have a resource type using the site-local scope.

The discovery request will make a multi-cast request to the IPv6 scope multi-cast address scope. The address scope is the domain in which the multi-cast discovery packet should be propagated.

Read RFC4291 and RFC7346 for more information about IPv6 Reference Scopes.

Parameters

[in]	uri_query	the query to be added the .well-known/core URI.
[in]	scope	the scope of the request, for example: 0x2
[in]	handler	the oc_discovery_all_handler_t that will be called once a server containing the resource type is discovered
[in]	user_data	context pointer that is passed to the oc_discovery_handler_t.

Returns

true on success

oc_free_server_endpoints()

void oc_free_server_endpoints

(

oc_endpoint_t *

endpoint

)

Free a list of endpoints from the oc_endpoint_t.

note: oc_endpoint_t is a linked list. This will walk the list an free all endpoints found in the list. Even if the list only consists of a single endpoint.

Parameters

[in,out]

endpoint

the endpoint list to free

oc_init_multicast_update()

bool oc_init_multicast_update	(	oc_endpoint_t *	mcast,
		const char *	uri,
		const char *	query
	)

initialize the multicast update

Parameters

mcast	the multicast address to be used
uri	the uri to be used
query	the query of uri

Returns

true

false

oc_init_post()

bool oc_init_post	(	const char *	uri,
		oc_endpoint_t *	endpoint,
		const char *	query,
		oc_response_handler_t	handler,
		oc_qos_t	qos,
		void *	user_data
	)

Prepare the stack to issue a POST request.

After oc_init_post has been called a CoAP message can be built using oc_rep_* functions. Then oc_do_post is called to dispatch the CoAP request.

Example:

static void
post_switch(oc_client_response_t *data)
{
  if (data->code == OC_STATUS_CHANGED)
    printf("POST response: CHANGED\n");
  else
    printf("POST response code %d\n", data->code);
}
 
if (oc_init_post(server_uri, server_ep, NULL, &put_switch, LOW_QOS, NULL)) {
  oc_rep_begin_root_object();
  oc_rep_set_boolean(root, value, true);
  oc_rep_end_root_object();
  if (oc_do_put(APPLICATION_CBOR, APPLICATION_CBOR))
    printf("Sent POST request\n");
  else
    printf("Could not send POST request\n");
} else
  printf("Could not init POST request\n");

Parameters

[in]	uri	the uri of the resource
[in]	endpoint	the endpoint of the server
[in]	query	a query parameter that will be sent to the server's oc_request_callback_t.
[in]	handler	function invoked once the client has received the servers response to the POST request
[in]	qos	the quality of service current options are HIGH_QOS or LOW_QOS
[in]	user_data	context pointer that will be sent to the oc_response_handler_t

Returns

True if the client successfully prepared the CoAP PUT request

See also

oc_do_post

oc_init_put

oc_init_put()

bool oc_init_put	(	const char *	uri,
		oc_endpoint_t *	endpoint,
		const char *	query,
		oc_response_handler_t	handler,
		oc_qos_t	qos,
		void *	user_data
	)

Prepare the stack to issue a PUT request.

After oc_init_put has been called a CoAP message can be built using oc_rep_* functions. Then oc_do_put is called to dispatch the CoAP request.

Example:

static void
put_switch(oc_client_response_t *data)
{
  if (data->code == OC_STATUS_CHANGED)
    printf("PUT response: CHANGED\n");
  else
    printf("PUT response code %d\n", data->code);
}
 
if (oc_init_put(server_uri, server_ep, NULL, &put_switch, LOW_QOS, NULL)) {
  oc_rep_begin_root_object();
  oc_rep_set_boolean(root, value, true);
  oc_rep_end_root_object();
  if (oc_do_put(APPLICATION_CBOR, APPLICATION_CBOR))
    printf("Sent PUT request\n");
  else
    printf("Could not send PUT request\n");
} else
  printf("Could not init PUT request\n");

Parameters

[in]	uri	the uri of the resource
[in]	endpoint	the endpoint of the server
[in]	query	a query parameter that will be sent to the server's oc_request_callback_t.
[in]	handler	function invoked once the client has received the servers response to the PUT request
[in]	qos	the quality of service current options are HIGH_QOS or LOW_QOS
[in]	user_data	context pointer that will be sent to the oc_response_handler_t

Returns

True if the client successfully prepared the CoAP PUT request

See also

oc_do_put_ex

oc_init_post

oc_lf_get_entry_param()

int oc_lf_get_entry_param	(	const char *	payload,
		int	payload_len,
		int	entry,
		const char *	param,
		const char **	p_out,
		int *	p_len
	)

link format parser, retrieve a parameter value

Parameters

payload	The link-format response
payload_len	The length of the response
entry	The index of entries, starting with 0.
param	The query parameter, e.g. "rt"
p_out	The pointer to store the value, e.g. "blah"
p_len	The length of the URI

Returns

int 1 success full

oc_lf_get_entry_uri()

int oc_lf_get_entry_uri	(	const char *	payload,
		int	payload_len,
		int	entry,
		const char **	uri,
		int *	uri_len
	)

link format parser, retrieve the URL of an entry.

Parameters

payload	The link-format response
payload_len	The length of the response
entry	The index of entries, starting with 0.
uri	The pointer to store the URI
uri_len	The length of the URI

Returns

int 1 success full

oc_lf_number_of_entries()

int oc_lf_number_of_entries	(	const char *	payload,
		int	payload_len
	)

link format parser, retrieve the number of entries in a response

Parameters

payload	The link-format response
payload_len	The length of the response

Returns

int amount of entries

oc_send_ping()

bool oc_send_ping	(	bool	custody,
		oc_endpoint_t *	endpoint,
		uint16_t	timeout_seconds,
		oc_response_handler_t	handler,
		void *	user_data
	)

send CoAP ping over the TCP connection

Parameters

custody	custody on/off
endpoint	endpoint to be used
timeout_seconds	timeout for the ping
handler	the response handler
user_data	the user data to be conveyed to the response handler

Returns

true

false

oc_stop_multicast()

void oc_stop_multicast

(

oc_client_response_t *

response

)

stop the multicast update (e.g.

do not handle the responses)

Parameters

[in]

response

the response that should not be handled.

oc_stop_observe()

bool oc_stop_observe	(	const char *	uri,
		oc_endpoint_t *	endpoint
	)

Unsubscribe for notifications from a resource.

Parameters

[in]	uri	the uri of the resource being observed
[in]	endpoint	the endpoint of the server

Returns

True if the client successfully dispatched the CaAP stop observer request