IoTivity-Lite
oc_cloud.h File Reference
#include "oc_client_state.h"
#include "oc_export.h"
#include "oc_link.h"
#include "oc_ri.h"
#include "oc_session_events.h"
#include "oc_uuid.h"
#include "util/oc_compiler.h"
#include "util/oc_endpoint_address.h"
#include "util/oc_features.h"

Typedefs

typedef void(* oc_cloud_cb_t) (struct oc_cloud_context_t *ctx, oc_cloud_status_t status, void *user_data)
 A function pointer for handling the cloud status. More...
 
typedef struct oc_cloud_context_t oc_cloud_context_t
 
typedef bool(* oc_cloud_on_keepalive_response_cb_t) (bool response_received, uint64_t *next_ping, uint16_t *next_ping_timeout, void *user_data)
 Callback invoked by the cloud manager when cloud change state to logged in or a keepalive response is received. More...
 
typedef bool(* oc_cloud_schedule_action_cb_t) (oc_cloud_action_t action, uint8_t retry_count, uint64_t *delay, uint16_t *timeout, void *user_data)
 Callback invoked by the cloud manager when the cloud wants to schedule an action. More...
 
typedef enum oc_cps_t oc_cps_t
 

Enumerations

enum  oc_cloud_action_t { OC_CLOUD_ACTION_UNKNOWN = 0 , OC_CLOUD_ACTION_REGISTER = 1 , OC_CLOUD_ACTION_LOGIN = 2 , OC_CLOUD_ACTION_REFRESH_TOKEN = 3 }
 Enumeration defining cloud actions. More...
 
enum  oc_cloud_error_t {
  CLOUD_OK = 0 , CLOUD_ERROR_RESPONSE = 1 , CLOUD_ERROR_CONNECT = 2 , CLOUD_ERROR_REFRESH_ACCESS_TOKEN = 3 ,
  CLOUD_ERROR_UNAUTHORIZED = 4
}
 
enum  oc_cloud_status_t {
  OC_CLOUD_INITIALIZED = 0 , OC_CLOUD_REGISTERED = 1 << 0 , OC_CLOUD_LOGGED_IN = 1 << 1 , OC_CLOUD_TOKEN_EXPIRY = 1 << 2 ,
  OC_CLOUD_REFRESHED_TOKEN = 1 << 3 , OC_CLOUD_LOGGED_OUT = 1 << 4 , OC_CLOUD_FAILURE = 1 << 5 , OC_CLOUD_DEREGISTERED = 1 << 6
}
 Cloud connection status. More...
 
enum  oc_cps_t {
  OC_CPS_UNINITIALIZED = 0 , OC_CPS_READYTOREGISTER , OC_CPS_REGISTERING , OC_CPS_REGISTERED ,
  OC_CPS_FAILED , OC_CPS_DEREGISTERING
}
 

Functions

const char * oc_cloud_action_to_str (oc_cloud_action_t action) 1
 Convert cloud action to a string representation. More...
 
int oc_cloud_add_resource (oc_resource_t *resource)
 Publish resource to cloud. More...
 
oc_endpoint_address_t * oc_cloud_add_server_address (oc_cloud_context_t *ctx, const char *uri, size_t uri_len, oc_uuid_t sid)
 Allocate and add an endpoint address to the list of cloud server addresses. More...
 
void oc_cloud_context_clear (oc_cloud_context_t *ctx, bool dump_async)
 Remove cloud context values, disconnect, and stop the cloud manager, without releasing the context. More...
 
void oc_cloud_delete_resource (oc_resource_t *resource)
 Unpublish resource from cloud. More...
 
int oc_cloud_deregister (oc_cloud_context_t *ctx, oc_cloud_cb_t cb, void *data)
 Send request to deregister device from cloud. More...
 
int oc_cloud_discover_resources (const oc_cloud_context_t *ctx, oc_discovery_all_handler_t handler, void *user_data)
 
const oc_string_toc_cloud_get_access_token (const oc_cloud_context_t *ctx)
 Get the access token from cloud context. More...
 
const oc_string_toc_cloud_get_authorization_provider_name (const oc_cloud_context_t *ctx)
 Get the authorization provider name from cloud context. More...
 
oc_cloud_context_t * oc_cloud_get_context (size_t device)
 Get cloud context for device. More...
 
size_t oc_cloud_get_device (const oc_cloud_context_t *ctx)
 Get device index from cloud context. More...
 
int oc_cloud_get_identity_cert_chain (const oc_cloud_context_t *ctx)
 Get selected identity certificate chain to establish TLS connection. More...
 
oc_cloud_on_status_change_t oc_cloud_get_on_status_change (const oc_cloud_context_t *ctx)
 Get the callback function invoked on status change. More...
 
oc_cps_t oc_cloud_get_provisioning_status (const oc_cloud_context_t *ctx)
 Get current cloud provisiong status. More...
 
const oc_string_toc_cloud_get_refresh_token (const oc_cloud_context_t *ctx)
 Get the refresh token from cloud context. More...
 
const oc_endpoint_toc_cloud_get_server (const oc_cloud_context_t *ctx)
 Get the active OCF cloud server. More...
 
const oc_uuid_t * oc_cloud_get_server_id (const oc_cloud_context_t *ctx)
 Get the identity of the OCF Cloud. More...
 
oc_session_state_t oc_cloud_get_server_session_state (const oc_cloud_context_t *ctx)
 Get session state of the active cloud server. More...
 
const oc_string_toc_cloud_get_server_uri (const oc_cloud_context_t *ctx)
 Get the URL of the OCF Cloud. More...
 
uint8_t oc_cloud_get_status (const oc_cloud_context_t *ctx)
 Get current cloud status. More...
 
int oc_cloud_get_token_expiry (const oc_cloud_context_t *ctx)
 Get access token expiration (in seconds). More...
 
const oc_string_toc_cloud_get_user_id (const oc_cloud_context_t *ctx)
 Get the OCF Cloud User identifier. More...
 
void oc_cloud_iterate_server_addresses (const oc_cloud_context_t *ctx, oc_endpoint_addresses_iterate_fn_t fn, void *data)
 Iterate over cloud server addresses. More...
 
int oc_cloud_login (oc_cloud_context_t *ctx, oc_cloud_cb_t cb, void *data)
 Send request to sign in the device to the cloud. More...
 
int oc_cloud_logout (oc_cloud_context_t *ctx, oc_cloud_cb_t cb, void *data)
 Send request to sign out the device to the cloud. More...
 
bool oc_cloud_manager_is_started (const oc_cloud_context_t *ctx)
 Check if the cloud registration process is started. More...
 
void oc_cloud_manager_restart (oc_cloud_context_t *ctx)
 Restart cloud registration process with the current configuration. More...
 
int oc_cloud_manager_start (oc_cloud_context_t *ctx, oc_cloud_cb_t cb, void *data)
 Start cloud registration process. More...
 
int oc_cloud_manager_stop (oc_cloud_context_t *ctx)
 Stop cloud registration process, remove related pending delayed callbacks and clean-up data. More...
 
void oc_cloud_manager_stop_v1 (oc_cloud_context_t *ctx, bool resetConfiguration)
 Stop cloud registration process, remove related pending delayed callbacks and clean-up data. More...
 
int oc_cloud_provision_conf_resource (oc_cloud_context_t *ctx, const char *server, const char *access_token, const char *server_id, const char *auth_provider)
 Configure cloud properties. More...
 
int oc_cloud_publish_resources (size_t device)
 Republish previously published devices. More...
 
int oc_cloud_refresh_token (oc_cloud_context_t *ctx, oc_cloud_cb_t cb, void *data)
 Send request to refresh the device access token to the cloud. More...
 
int oc_cloud_register (oc_cloud_context_t *ctx, oc_cloud_cb_t cb, void *data)
 Send request to register device to cloud. More...
 
bool oc_cloud_remove_server_address (oc_cloud_context_t *ctx, const oc_endpoint_address_t *ea)
 Remove an endpoint address from the list of cloud server addresses. More...
 
bool oc_cloud_select_server_address (oc_cloud_context_t *ctx, const oc_endpoint_address_t *ea)
 Select an address from the list of cloud server addresses. More...
 
const oc_endpoint_address_t * oc_cloud_selected_server_address (const oc_cloud_context_t *ctx)
 Get the selected cloud server address. More...
 
void oc_cloud_set_identity_cert_chain (oc_cloud_context_t *ctx, int selected_identity_cred_id)
 Set identity certificate chain to establish TLS connection. More...
 
void oc_cloud_set_keepalive (oc_cloud_context_t *ctx, oc_cloud_on_keepalive_response_cb_t on_keepalive_response, void *user_data)
 Set keepalive parameters for the cloud manager. More...
 
void oc_cloud_set_on_status_change (oc_cloud_context_t *ctx, oc_cloud_on_status_change_t status_change)
 Set the callback function invoked on status change. More...
 
void oc_cloud_set_published_resources_ttl (oc_cloud_context_t *ctx, uint32_t ttl)
 Set Time to Live value in the provided cloud context. More...
 
void oc_cloud_set_schedule_action (oc_cloud_context_t *ctx, oc_cloud_schedule_action_cb_t on_schedule_action, void *user_data)
 Set a custom scheduler for actions in the cloud manager. More...
 

Typedef Documentation

◆ oc_cloud_cb_t

typedef void(* oc_cloud_cb_t) (struct oc_cloud_context_t *ctx, oc_cloud_status_t status, void *user_data)

A function pointer for handling the cloud status.

Parameters
ctxCloud context (cannot be NULL)
statusCurrent status of the cloud.
user_dataUser data

◆ oc_cloud_on_keepalive_response_cb_t

typedef bool(* oc_cloud_on_keepalive_response_cb_t) (bool response_received, uint64_t *next_ping, uint16_t *next_ping_timeout, void *user_data)

Callback invoked by the cloud manager when cloud change state to logged in or a keepalive response is received.

Parameters
response_receivedKeepalive response received, true if received, otherwise false
next_pingDelay in milliseconds before next keepalive ping
next_ping_timeoutTimeout in seconds for next keepalive ping
user_dataUser data passed from the caller
Returns
true if the cloud manager should continue sending keepalive pings, false if cloud manager should consider the connection lost

◆ oc_cloud_schedule_action_cb_t

typedef bool(* oc_cloud_schedule_action_cb_t) (oc_cloud_action_t action, uint8_t retry_count, uint64_t *delay, uint16_t *timeout, void *user_data)

Callback invoked by the cloud manager when the cloud wants to schedule an action.

Parameters
actionCloud action to schedule.
retry_countRetries count - 0 means the first attempt to perform the action.
delayDelay the action in milliseconds before executing it.
timeoutTimeout in seconds for the action.
user_dataUser data passed from the caller.
Returns
true if the cloud manager should continue to schedule the action, false if the cloud manager should stop for OC_CLOUD_ACTION_REGISTER or restart for other actions.

Enumeration Type Documentation

◆ oc_cloud_action_t

Enumeration defining cloud actions.

Enumerator
OC_CLOUD_ACTION_UNKNOWN 

Unknown cloud action.

OC_CLOUD_ACTION_REGISTER 

Cloud registration action.

OC_CLOUD_ACTION_LOGIN 

Cloud login action.

OC_CLOUD_ACTION_REFRESH_TOKEN 

Cloud token refresh action.

◆ oc_cloud_status_t

Cloud connection status.

Function Documentation

◆ oc_cloud_action_to_str()

const char* oc_cloud_action_to_str ( oc_cloud_action_t  action)

Convert cloud action to a string representation.

Parameters
actionCloud action to convert.
Returns
const char* String representation of the cloud action.

◆ oc_cloud_add_resource()

int oc_cloud_add_resource ( oc_resource_t resource)

Publish resource to cloud.

Function checks that resource is contained in list of published or to-be published resources. If it is, the function does nothing. If it is not, then the resource is added to the to-be published resources list and a publish request with this list is sent to the cloud server.

Parameters
resourcethe resource to be published

◆ oc_cloud_context_clear()

void oc_cloud_context_clear ( oc_cloud_context_t *  ctx,
bool  dump_async 
)

Remove cloud context values, disconnect, and stop the cloud manager, without releasing the context.

Parameters
ctxCloud context to clear, must not be NULL.
dump_asyncIf true, store the context to storage in an asynchronous manner; otherwise, perform the dump while executing this function.

◆ oc_cloud_delete_resource()

void oc_cloud_delete_resource ( oc_resource_t resource)

Unpublish resource from cloud.

Parameters
resourcethe resource to be unpublished

◆ oc_cloud_deregister()

int oc_cloud_deregister ( oc_cloud_context_t *  ctx,
oc_cloud_cb_t  cb,
void *  data 
)

Send request to deregister device from cloud.

Note
If the device is not signed in then the request requires additional data. If the request becomes larger than is allowed because of this then this call will attempt to sign in to avoid sending this additional data.
Parameters
ctxcloud context
cbcallback function invoked on status change
datauser data provided to the status change function
Returns
int 0 on success
int -1 on error
Note
oc_cloud_deregister shouldn't be called when oc_cloud_login or oc_cloud_refresh_token have been invoked and haven't yet received a response.
See also
oc_cloud_login
oc_cloud_refresh_token

◆ oc_cloud_get_access_token()

const oc_string_t* oc_cloud_get_access_token ( const oc_cloud_context_t *  ctx)

Get the access token from cloud context.

Access token is returned by an Authorisation Provider or an OCF Cloud.

Parameters
ctxcloud context (cannot be NULL)
Returns
access token
See also
at property in the cloud configuration resource

◆ oc_cloud_get_authorization_provider_name()

const oc_string_t* oc_cloud_get_authorization_provider_name ( const oc_cloud_context_t *  ctx)

Get the authorization provider name from cloud context.

The name of the Authorization Provider through which access token was obtained.

Parameters
ctxcloud context (cannot be NULL)
Returns
auth provider ID
See also
apn property in the cloud configuration resource

◆ oc_cloud_get_context()

oc_cloud_context_t* oc_cloud_get_context ( size_t  device)

Get cloud context for device.

◆ oc_cloud_get_device()

size_t oc_cloud_get_device ( const oc_cloud_context_t *  ctx)

Get device index from cloud context.

Parameters
ctxcloud context (cannot be NULL)
Returns
size_t device index

◆ oc_cloud_get_identity_cert_chain()

int oc_cloud_get_identity_cert_chain ( const oc_cloud_context_t *  ctx)

Get selected identity certificate chain to establish TLS connection.

Parameters
ctxCloud context to update, must not be NULL.
Returns
Selected identity certificate chain id. -1 means any.

◆ oc_cloud_get_on_status_change()

oc_cloud_on_status_change_t oc_cloud_get_on_status_change ( const oc_cloud_context_t *  ctx)

Get the callback function invoked on status change.

◆ oc_cloud_get_provisioning_status()

oc_cps_t oc_cloud_get_provisioning_status ( const oc_cloud_context_t *  ctx)

Get current cloud provisiong status.

Parameters
ctxcloud context (cannot be NULL)
Returns
oc_cps_t current provisioning status
See also
cps property in the cloud configuration resource

◆ oc_cloud_get_refresh_token()

const oc_string_t* oc_cloud_get_refresh_token ( const oc_cloud_context_t *  ctx)

Get the refresh token from cloud context.

Refresh token is used to obtain a new access token when the current access token expires.

Parameters
ctxcloud context (cannot be NULL)
Returns
refresh token

◆ oc_cloud_get_server()

const oc_endpoint_t* oc_cloud_get_server ( const oc_cloud_context_t *  ctx)

Get the active OCF cloud server.

Parameters
ctxcloud context (cannot be NULL)
Returns
oc_endpoint_t* pointer to the active cloud server
NULL if no cloud server is selected, or if the cloud manager has not been started
See also
oc_cloud_select_server_address
oc_cloud_get_server_uri

◆ oc_cloud_get_server_id()

const oc_uuid_t* oc_cloud_get_server_id ( const oc_cloud_context_t *  ctx)

Get the identity of the OCF Cloud.

Parameters
ctxcloud context (cannot be NULL)
Returns
identity of the OCF Cloud
See also
sid property in the cloud configuration resource

◆ oc_cloud_get_server_session_state()

oc_session_state_t oc_cloud_get_server_session_state ( const oc_cloud_context_t *  ctx)

Get session state of the active cloud server.

Parameters
ctxcloud context (cannot be NULL)
Returns
oc_session_state_t session state of the active cloud server
See also
oc_cloud_get_server

◆ oc_cloud_get_server_uri()

const oc_string_t* oc_cloud_get_server_uri ( const oc_cloud_context_t *  ctx)

Get the URL of the OCF Cloud.

Parameters
ctxcloud context (cannot be NULL)
Returns
cloud interface server URL
See also
cis property in the cloud configuration resource

◆ oc_cloud_get_status()

uint8_t oc_cloud_get_status ( const oc_cloud_context_t *  ctx)

Get current cloud status.

Parameters
ctxcloud context (cannot be NULL)
Returns
mask of oc_cloud_status_t values

◆ oc_cloud_get_token_expiry()

int oc_cloud_get_token_expiry ( const oc_cloud_context_t *  ctx)

Get access token expiration (in seconds).

◆ oc_cloud_get_user_id()

const oc_string_t* oc_cloud_get_user_id ( const oc_cloud_context_t *  ctx)

Get the OCF Cloud User identifier.

Parameters
ctxcloud context (cannot be NULL)
Returns
OCF Cloud User identifier
See also
uid property in the cloud configuration resource

◆ oc_cloud_login()

int oc_cloud_login ( oc_cloud_context_t *  ctx,
oc_cloud_cb_t  cb,
void *  data 
)

Send request to sign in the device to the cloud.

Parameters
ctxcloud context
cbcallback function invoked on status change
datauser data provided to the status change function
Returns
int 0 on success
int -1 on error

◆ oc_cloud_logout()

int oc_cloud_logout ( oc_cloud_context_t *  ctx,
oc_cloud_cb_t  cb,
void *  data 
)

Send request to sign out the device to the cloud.

Parameters
ctxcloud context
cbcallback function invoked on status change
datauser data provided to the status change function
Returns
int 0 on success
int -1 on error

◆ oc_cloud_manager_is_started()

bool oc_cloud_manager_is_started ( const oc_cloud_context_t *  ctx)

Check if the cloud registration process is started.

Parameters
ctxcloud context (cannot be NULL)
Returns
true if cloud registration process is started
false otherwise

◆ oc_cloud_manager_restart()

void oc_cloud_manager_restart ( oc_cloud_context_t *  ctx)

Restart cloud registration process with the current configuration.

Note
The cloud manager must be started before calling this function.
Parameters
ctxcloud context (cannot be NULL)

◆ oc_cloud_manager_start()

int oc_cloud_manager_start ( oc_cloud_context_t *  ctx,
oc_cloud_cb_t  cb,
void *  data 
)

Start cloud registration process.

Parameters
ctxcloud context
cbcallback function invoked on status change
datauser data provided to the status change function
Returns
int 0 on success
int -1 on error

◆ oc_cloud_manager_stop()

int oc_cloud_manager_stop ( oc_cloud_context_t *  ctx)

Stop cloud registration process, remove related pending delayed callbacks and clean-up data.

Parameters
ctxcloud context
Returns
int 0 on success
int -1 on error

◆ oc_cloud_manager_stop_v1()

void oc_cloud_manager_stop_v1 ( oc_cloud_context_t *  ctx,
bool  resetConfiguration 
)

Stop cloud registration process, remove related pending delayed callbacks and clean-up data.

Parameters
ctxcloud context (cannot be NULL)
resetConfigurationif true, reset cloud configuration to default (cloud must be reconfigured by oc_cloud_provision_conf_resource or by updating the cloud resource); if false the previous cloud configuration is kept, but the cloud is reset to OC_CPS_REGISTERED state if it was registered or to OC_CPS_READYTOREGISTER otherwise

◆ oc_cloud_provision_conf_resource()

int oc_cloud_provision_conf_resource ( oc_cloud_context_t *  ctx,
const char *  server,
const char *  access_token,
const char *  server_id,
const char *  auth_provider 
)

Configure cloud properties.

Parameters
ctxCloud context to update (cannot be be NULL)
serverCloud server URL
access_tokenAccess token from an Authorisation Provider
server_idCloud server ID
auth_providerName of the Authorization Provider which provided the access token
Returns
0 on success
-1 on failure
Note
Cloud manager will be restarted if is was started previously

◆ oc_cloud_publish_resources()

int oc_cloud_publish_resources ( size_t  device)

Republish previously published devices.

Parameters
devicethe device index

◆ oc_cloud_refresh_token()

int oc_cloud_refresh_token ( oc_cloud_context_t *  ctx,
oc_cloud_cb_t  cb,
void *  data 
)

Send request to refresh the device access token to the cloud.

Parameters
ctxcloud context
cbcallback function invoked on status change
datauser data provided to the status change function
Returns
int 0 on success
int -1 on error

◆ oc_cloud_register()

int oc_cloud_register ( oc_cloud_context_t *  ctx,
oc_cloud_cb_t  cb,
void *  data 
)

Send request to register device to cloud.

Parameters
ctxcloud context
cbcallback function invoked on status change
datauser data provided to the status change function
Returns
int 0 on success
int -1 on error

◆ oc_cloud_set_identity_cert_chain()

void oc_cloud_set_identity_cert_chain ( oc_cloud_context_t *  ctx,
int  selected_identity_cred_id 
)

Set identity certificate chain to establish TLS connection.

Parameters
ctxCloud context to update, must not be NULL.
selected_identity_cred_idSelected identity certificate chain id. -1(default) means any.

◆ oc_cloud_set_keepalive()

void oc_cloud_set_keepalive ( oc_cloud_context_t *  ctx,
oc_cloud_on_keepalive_response_cb_t  on_keepalive_response,
void *  user_data 
)

Set keepalive parameters for the cloud manager.

Parameters
ctxCloud context to update, must not be NULL.
on_keepalive_responseCallback invoked by the cloud manager when cloud change state to logged in or a keepalive response is received.
user_dataUser data passed from the caller

◆ oc_cloud_set_on_status_change()

void oc_cloud_set_on_status_change ( oc_cloud_context_t *  ctx,
oc_cloud_on_status_change_t  status_change 
)

Set the callback function invoked on status change.

Parameters
ctxcloud context (cannot be NULL)
status_changecallback function invoked on status change with user data

◆ oc_cloud_set_published_resources_ttl()

void oc_cloud_set_published_resources_ttl ( oc_cloud_context_t *  ctx,
uint32_t  ttl 
)

Set Time to Live value in the provided cloud context.

Parameters
ctxCloud context to update, must not be NULL.
ttlTime to live value in seconds.

◆ oc_cloud_set_schedule_action()

void oc_cloud_set_schedule_action ( oc_cloud_context_t *  ctx,
oc_cloud_schedule_action_cb_t  on_schedule_action,
void *  user_data 
)

Set a custom scheduler for actions in the cloud manager.

By default, the cloud manager uses its own scheduler.

This function allows you to set a custom scheduler to define delay and timeout for actions.

Parameters
ctxCloud context to update. Must not be NULL.
on_schedule_actionCallback invoked by the cloud manager when the cloud wants to schedule an action.
user_dataUser data passed from the caller to be provided during the callback.
Note
The provided cloud context (ctx) must not be NULL.
See also
oc_cloud_schedule_action_cb_t