IoTivity-Lite
Client side

Client side support functions. More...

Modules

 Asserting roles
 Asserting roles support functions.
 

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)
 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, 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, 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, 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_put (void)
 Dispatch the CoAP PUT 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, 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...
 
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.

Function Documentation

◆ oc_close_session()

void oc_close_session ( oc_endpoint_t endpoint)

close the tls session on the indicated endpoint

Parameters
endpointendpoint 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]urithe uri of the resource
[in]endpointthe endpoint of the server
[in]querya query parameter that will be sent to the server's oc_request_callback_t.
[in]handlerfunction invoked once the client has received the servers response to the DELETE request
[in]qosthe quality of service current options are HIGH_QOS or LOW_QOS
[in]user_datacontext 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 
)

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)
{
PRINT("GET_light:\n");
oc_rep_t *rep = data->payload;
while (rep != NULL) {
PRINT("key %s, value ", oc_string(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(server_uri, server_ep, NULL, &get_switch, LOW_QOS, NULL);
Parameters
[in]urithe uri of the resource
[in]endpointthe endpoint of the server
[in]querya query parameter that will be sent to the server's oc_request_callback_t.
[in]handlerfunction invoked once the client has received the servers response to the GET request
[in]qosthe quality of service current options are HIGH_QOS or LOW_QOS
[in]user_datacontext pointer that will be sent to the oc_response_handler_t
Returns
True if the client successfully dispatched the CoAP GET request

◆ 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]rtthe resource type the client is trying to discover
[in]handlerthe oc_discovery_handler_t that will be called once a server containing the resource type is discovered
[in]user_datacontext 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]handlerthe oc_discovery_all_handler_t that will be called once a server is discovered
[in]user_datacontext 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,
oc_endpoint_t endpoint,
void *  user_data 
)

Discover all resources in a specific endpoint.

Parameters
handlerThe callback for discovered resources. Must not be NULL.
endpointEndpoint at which to discover resources. Must not be NULL.
user_dataCallback 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,
oc_endpoint_t endpoint,
void *  user_data 
)

Discover resources in a specific endpoint.

Parameters
rtResource type query to discover.
handlerThe callback for discovered resources. Must not be NULL.
endpointEndpoint at which to discover resources. Must not be NULL.
user_dataCallback 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]urithe uri for multicast command to be used
[in]querythe query of the multicast command
[in]handlerfunction invoked once the client has received the servers response to the discovery request
[in]user_datacontext 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,
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]urithe uri of the resource
[in]endpointthe endpoint of the server
[in]querya query parameter that will be sent to the server's oc_request_callback_t.
[in]handlerfunction invoked once the client has received the servers response to the POST request
[in]qosthe quality of service current options are HIGH_QOS or LOW_QOS
[in]user_datacontext 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_put

Returns
True if the client successfully dispatched the CoAP POST request
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_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]rtthe resource type the client is trying to discover
[in]handlerthe oc_discovery_handler_t that will be called once a server containing the resource type is discovered
[in]user_datacontext 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]handlerthe oc_discovery_all_handler_t that will be called once a server is discovered
[in]user_datacontext 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]urithe uri for multicast command to be used
[in]querythe query of the multicast command
[in]handlerfunction invoked once the client has received the servers response to the discovery request
[in]user_datacontext 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]rtthe resource type the client is trying to discover
[in]handlerthe oc_discovery_handler_t that will be called once a server containing the resource type is discovered
[in]user_datacontext 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]handlerthe oc_discovery_all_handler_t that will be called once a server is discovered
[in]user_datacontext 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]urithe uri for multicast command to be used
[in]querythe query of the multicast command
[in]handlerfunction invoked once the client has received the servers response to the discovery request
[in]user_datacontext 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]endpointthe endpoint list to free

◆ 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_set_boolean(root, value, true);
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]urithe uri of the resource
[in]endpointthe endpoint of the server
[in]querya query parameter that will be sent to the server's oc_request_callback_t.
[in]handlerfunction invoked once the client has received the servers response to the POST request
[in]qosthe quality of service current options are HIGH_QOS or LOW_QOS
[in]user_datacontext 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_set_boolean(root, value, true);
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]urithe uri of the resource
[in]endpointthe endpoint of the server
[in]querya query parameter that will be sent to the server's oc_request_callback_t.
[in]handlerfunction invoked once the client has received the servers response to the PUT request
[in]qosthe quality of service current options are HIGH_QOS or LOW_QOS
[in]user_datacontext 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,
oc_endpoint_t endpoint,
uint16_t  timeout_seconds,
oc_response_handler_t  handler,
void *  user_data 
)

send CoAP ping over the TCP connection

Parameters
custodycustody on/off
endpointendpoint to be used
timeout_secondstimeout for the ping
handlerthe response handler
user_datathe 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]responsethe 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]urithe uri of the resource being observed
[in]endpointthe endpoint of the server
Returns
True if the client successfully dispatched the CaAP stop observer request
oc_client_response_t
Client response information.
Definition: oc_client_state.h:50
oc_string
#define oc_string(ocstring)
cast oc_string to string
Definition: oc_helpers.h:42
oc_rep_set_boolean
#define oc_rep_set_boolean(object, key, value)
Add an boolean value to the cbor object under the key name Example:
Definition: oc_rep.h:191
oc_rep_end_root_object
#define oc_rep_end_root_object()
End the root object.
Definition: oc_rep.h:355
oc_client_response_t::code
oc_status_t code
status of the response
Definition: oc_client_state.h:59
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.
oc_rep_start_root_object
#define oc_rep_start_root_object()
This macro has been replaced with oc_rep_begin_root_object.
Definition: oc_rep.h:339
OC_STATUS_CHANGED
@ OC_STATUS_CHANGED
Changed.
Definition: oc_ri.h:64
LOW_QOS
@ LOW_QOS
non-confirmable messages
Definition: oc_client_state.h:43
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)
Issue a GET request to obtain the current value of all properties a resource.
oc_client_response_t::payload
oc_rep_t * payload
response payload, interpreted as cbor
Definition: oc_client_state.h:52
oc_do_put
bool oc_do_put(void)
Dispatch the CoAP PUT request.
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.