Client side

Client side support functions. More...

Functions
void	oc_close_session (const oc_endpoint_t *endpoint)
	close the tls session on the indicated endpoint More...
bool	oc_do_delete (const char *uri, const 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_delete_with_timeout (const char *uri, const oc_endpoint_t *endpoint, const char *query, uint16_t timeout_seconds, 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, const oc_endpoint_t *endpoint, const char *query, oc_response_handler_t handler, oc_qos_t qos, void *user_data)
	Issue a GET request to obtain the current value of all properties a resource. More...
bool	oc_do_get_with_timeout (const char *uri, const oc_endpoint_t *endpoint, const char *query, uint16_t timeout_seconds, oc_response_handler_t handler, oc_qos_t qos, void *user_data)
	Issue a GET request to obtain the current value of all properties a resource. More...
bool	oc_do_ip_discovery (const char *rt, oc_discovery_handler_t handler, void *user_data)
	Discover all servers that have a resource type. More...
bool	oc_do_ip_discovery_all (oc_discovery_all_handler_t handler, void *user_data)
	Discover all servers. More...
bool	oc_do_ip_discovery_all_at_endpoint (oc_discovery_all_handler_t handler, const oc_endpoint_t *endpoint, void *user_data)
	Discover all resources in a specific endpoint. More...
bool	oc_do_ip_discovery_at_endpoint (const char *rt, oc_discovery_handler_t handler, const oc_endpoint_t *endpoint, void *user_data)
	Discover resources in a specific endpoint. More...
bool	oc_do_ip_multicast (const char *uri, const char *query, oc_response_handler_t handler, void *user_data)
	invoke multicast discovery of devices More...
bool	oc_do_observe (const char *uri, const 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. More...
bool	oc_do_post_with_timeout (uint16_t timeout_seconds)
	Dispatch the CoAP POST request. More...
bool	oc_do_put (void)
	Dispatch the CoAP PUT request. More...
bool	oc_do_put_with_timeout (uint16_t timeout_seconds)
	Dispatch the CoAP POST request. More...
bool	oc_do_realm_local_ipv6_discovery (const char *rt, oc_discovery_handler_t handler, void *user_data)
	Discover all servers that have a resource type using the realm-local scope. More...
bool	oc_do_realm_local_ipv6_discovery_all (oc_discovery_all_handler_t handler, void *user_data)
	Discover all servers using the realm-local scope. More...
bool	oc_do_realm_local_ipv6_multicast (const char *uri, const char *query, oc_response_handler_t handler, void *user_data)
	invoke multicast discovery of devices on IPV6 realm local scope More...
bool	oc_do_site_local_ipv6_discovery (const char *rt, oc_discovery_handler_t handler, void *user_data)
	Discover all servers that have a resource type using the site-local scope. More...
bool	oc_do_site_local_ipv6_discovery_all (oc_discovery_all_handler_t handler, void *user_data)
	Discover all servers using the realm-local scope. More...
bool	oc_do_site_local_ipv6_multicast (const char *uri, const char *query, oc_response_handler_t handler, void *user_data)
	invoke multicast discovery of devices on IPV6 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_post (const char *uri, const 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, const 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...
bool	oc_send_ping (bool custody, const 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, const oc_endpoint_t *endpoint)
	Unsubscribe for notifications from a resource. More...

Detailed Description

Client side support functions.

Function Documentation

oc_close_session()

void oc_close_session

(

const 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,
		const 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	function invoked once the client has received the servers response to the DELETE request (cannot be NULL)
[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 CoAP DELETE request

oc_do_delete_with_timeout()

bool oc_do_delete_with_timeout	(	const char *	uri,
		const oc_endpoint_t *	endpoint,
		const char *	query,
		uint16_t	timeout_seconds,
		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]	timeout_seconds	timeout for the get
[in]	handler	function invoked once the client has received the servers response to the DELETE request (cannot be NULL)
[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 CoAP DELETE

Note

If a response is not received before timeout_seconds expires then the response handler is invoked with OC_REQUEST_TIMEOUT code

oc_do_get()

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

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

Example:

statuc bool value;
 
static void
get_light(oc_client_response_t *data)
{
  OC_PRINTF("GET_light:\n");
  oc_rep_t *rep = data->payload;
  while (rep != NULL) {
    OC_PRINTF("key %s, value ", oc_string(rep->name));
    switch (rep->type) {
    case OC_REP_BOOL:
      OC_PRINTF("%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(server_uri, server_ep, NULL, &get_switch, LOW_QOS, 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]	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_get_with_timeout()

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

Issue a GET request to obtain the current value of all properties 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]	timeout_seconds	timeout for the get
[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]	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

Note

If a response is not received before timeout_seconds expires then the response handler is invoked with OC_REQUEST_TIMEOUT code

oc_do_ip_discovery()

bool oc_do_ip_discovery	(	const char *	rt,
		oc_discovery_handler_t	handler,
		void *	user_data
	)

Discover all servers that have a resource type.

The discovery request will make a muli-cast request to the IPv6 link-local multicast address scope and over IPv4.

Multicast discovery over IPv4 will only happen if the stack is built with the OC_IPV4 build flag.

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

Parameters

[in]	rt	the resource type the client is trying to discover
[in]	handler	the oc_discovery_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_do_ip_discovery_all()

bool oc_do_ip_discovery_all	(	oc_discovery_all_handler_t	handler,
		void *	user_data
	)

Discover all servers.

The discovery request will make a muli-cast request to the IPv6 link-local multicast address scope and over IPv4.

Multicast discovery over IPv4 will only happen if the stack is built with the OC_IPV4 build flag.

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

Parameters

[in]	handler	the oc_discovery_all_handler_t that will be called once a server is discovered
[in]	user_data	context pointer that is passed to the oc_discovery_all_handler_t.

Returns

true on success

oc_do_ip_discovery_all_at_endpoint()

bool oc_do_ip_discovery_all_at_endpoint	(	oc_discovery_all_handler_t	handler,
		const oc_endpoint_t *	endpoint,
		void *	user_data
	)

Discover all resources in a specific endpoint.

Parameters

handler	The callback for discovered resources. Must not be NULL.
endpoint	Endpoint at which to discover resources. Must not be NULL.
user_data	Callback parameter for user defined value.

Returns

Returns true if it successfully makes and dispatches a coap packet.

oc_do_ip_discovery_at_endpoint()

bool oc_do_ip_discovery_at_endpoint	(	const char *	rt,
		oc_discovery_handler_t	handler,
		const oc_endpoint_t *	endpoint,
		void *	user_data
	)

Discover resources in a specific endpoint.

Parameters

rt	Resource type query to discover.
handler	The callback for discovered resources. Must not be NULL.
endpoint	Endpoint at which to discover resources. Must not be NULL.
user_data	Callback parameter for user defined value.

Returns

Returns true if it successfully makes and dispatches a coap packet.

oc_do_ip_multicast()

bool oc_do_ip_multicast	(	const char *	uri,
		const char *	query,
		oc_response_handler_t	handler,
		void *	user_data
	)

invoke multicast discovery of devices

Parameters

[in]	uri	the uri for multicast command to be used
[in]	query	the query of the multicast command
[in]	handler	function invoked once the client has received the servers response to the discovery request
[in]	user_data	context pointer that will be sent to the oc_response_handler_t

Returns

True if the client successfully dispatched the multicast discovery request

oc_do_observe()

bool oc_do_observe	(	const char *	uri,
		const 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.

Before the POST request is dispatched it must be initialized using oc_init_post

Returns

True if the client successfully dispatched the CoAP POST request

See also

oc_init_post

oc_do_post_with_timeout()

bool oc_do_post_with_timeout

(

uint16_t

timeout_seconds

)

Dispatch the CoAP POST request.

Note

Before the POST request is dispatched it must be initialized using oc_init_post

Parameters

[in]

timeout_seconds

timeout for the POST response

Returns

True if the client successfully dispatched the CoAP POST request

Note

If a response is not received before timeout_seconds expires then the response handler is invoked with OC_REQUEST_TIMEOUT code

See also

oc_init_post

oc_do_put()

bool oc_do_put

(

void

)

Dispatch the CoAP PUT request.

Before the PUT request is dispatched it must be initialized using oc_init_put

Returns

True if the client successfully dispatched the CoAP request

See also

oc_init_put

oc_do_put_with_timeout()

bool oc_do_put_with_timeout

(

uint16_t

timeout_seconds

)

Dispatch the CoAP POST request.

Before the POST request is dispatched it must be initialized using oc_init_put.

Parameters

[in]

timeout_seconds

timeout for the PUT response

Returns

True if the client successfully dispatched the CoAP PUT request

Note

If a response is not received before timeout_seconds expires then the response handler is invoked with OC_REQUEST_TIMEOUT code

See also

oc_init_put

oc_do_realm_local_ipv6_discovery()

bool oc_do_realm_local_ipv6_discovery	(	const char *	rt,
		oc_discovery_handler_t	handler,
		void *	user_data
	)

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

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

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

Parameters

[in]	rt	the resource type the client is trying to discover
[in]	handler	the oc_discovery_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_do_realm_local_ipv6_discovery_all()

bool oc_do_realm_local_ipv6_discovery_all	(	oc_discovery_all_handler_t	handler,
		void *	user_data
	)

Discover all servers using the realm-local scope.

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

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

Parameters

[in]	handler	the oc_discovery_all_handler_t that will be called once a server is discovered
[in]	user_data	context pointer that is passed to the oc_discovery_all_handler_t.

Returns

true on success

oc_do_realm_local_ipv6_multicast()

bool oc_do_realm_local_ipv6_multicast	(	const char *	uri,
		const char *	query,
		oc_response_handler_t	handler,
		void *	user_data
	)

invoke multicast discovery of devices on IPV6 realm local scope

Parameters

[in]	uri	the uri for multicast command to be used
[in]	query	the query of the multicast command
[in]	handler	function invoked once the client has received the servers response to the discovery request
[in]	user_data	context pointer that will be sent to the oc_response_handler_t

Returns

True if the client successfully dispatched the multicast discovery request

oc_do_site_local_ipv6_discovery()

bool oc_do_site_local_ipv6_discovery	(	const char *	rt,
		oc_discovery_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 muli-cast request to the IPv6 site-local multicast address scope. The address scope is the domain in which the multicast discovery packet should be propagated.

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

Parameters

[in]	rt	the resource type the client is trying to discover
[in]	handler	the oc_discovery_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_do_site_local_ipv6_discovery_all()

bool oc_do_site_local_ipv6_discovery_all	(	oc_discovery_all_handler_t	handler,
		void *	user_data
	)

Discover all servers using the realm-local scope.

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

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

Parameters

[in]	handler	the oc_discovery_all_handler_t that will be called once a server is discovered
[in]	user_data	context pointer that is passed to the oc_discovery_all_handler_t.

Returns

true on success

oc_do_site_local_ipv6_multicast()

bool oc_do_site_local_ipv6_multicast	(	const char *	uri,
		const char *	query,
		oc_response_handler_t	handler,
		void *	user_data
	)

invoke multicast discovery of devices on IPV6 site local scope

Parameters

[in]	uri	the uri for multicast command to be used
[in]	query	the query of the multicast command
[in]	handler	function invoked once the client has received the servers response to the discovery request
[in]	user_data	context pointer that will be sent to the oc_response_handler_t

Returns

True if the client successfully dispatched the multicast discovery request

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_post()

bool oc_init_post	(	const char *	uri,
		const 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_start_root_object();
  oc_rep_set_boolean(root, value, true);
  oc_rep_end_root_object();
  if (oc_do_put())
    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,
		const 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_start_root_object();
  oc_rep_set_boolean(root, value, true);
  oc_rep_end_root_object();
  if (oc_do_put())
    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

oc_init_post

oc_send_ping()

bool oc_send_ping	(	bool	custody,
		const 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 on success

false otherwise

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,
		const 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