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"

Data Structures

struct  oc_cloud_keepalive_t
 Cloud keepalive configuration. More...
 

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 struct oc_cloud_keepalive_t oc_cloud_keepalive_t
 Cloud keepalive configuration. More...
 
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 struct oc_cloud_store_t oc_cloud_store_t
 
typedef enum oc_cps_t oc_cps_t
 

Enumerations

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

int oc_cloud_add_resource (oc_resource_t *resource)
 Publish resource to cloud. 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)
 
oc_cloud_context_t * oc_cloud_get_context (size_t device)
 Get cloud context for device. More...
 
int oc_cloud_get_identity_cert_chain (const oc_cloud_context_t *ctx)
 Get selected identity certificate chain to establish TLS connection. More...
 
int oc_cloud_get_token_expiry (const oc_cloud_context_t *ctx)
 
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...
 
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...
 
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...
 
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_published_resources_ttl (oc_cloud_context_t *ctx, uint32_t ttl)
 Set Time to Live value in the provided cloud context. 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_keepalive_t

Cloud keepalive configuration.

◆ 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

Enumeration Type Documentation

◆ oc_cloud_status_t

Cloud connection status.

Function Documentation

◆ 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_context()

oc_cloud_context_t* oc_cloud_get_context ( size_t  device)

Get cloud context for device.

◆ 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_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_restart()

void oc_cloud_manager_restart ( oc_cloud_context_t *  ctx)

Restart cloud registration process with the current configuration.

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 (cannot be NULL)
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 (cannot be NULL)
Returns
int 0 on success
int -1 on error

◆ 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_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.