Account API

Functions for retrieving information about an Umbra account.

Classes

struct UmbraSceneDescription
Information about a scene.

Enums

enum UmbraRequestStatus { UmbraRequestStatus_Ok = 0, UmbraRequestStatus_InProgress, UmbraRequestStatus_ConnectionError, UmbraRequestStatus_BadKeyError, UmbraRequestStatus_LicenseExpiredError, UmbraRequestStatus_BadLicenseTypeError, UmbraRequestStatus_ReadError, UmbraRequestStatus_UnknownError, UmbraRequestStatus_Cancelled, UmbraRequestStatus_InvalidHandle }
Request status.

Typedefs

typedef struct UmbraAccount UmbraAccount
Opaque struct representing an Umbra user account.
typedef int UmbraRequestHandle
Opaque value representing an asynchronous request to the Umbra accounts API.
typedef void(* UmbraSceneCallback )(UmbraRequestHandle request, UmbraRequestStatus status, const char*error, UmbraSceneDescription*scenes, int numScenes, void*userData)
The function pointer type for scene list callbacks.

Functions

UmbraAccount* UmbraAccountConnect(UmbraClient* client, const char* apiKey)
Create an account object.
void UmbraAccountDisconnect(UmbraAccount* account)
Destroy an account object.
void UmbraAccountPump(UmbraAccount* account, int waitMs)
Work on pending asynchronous requests.
UmbraRequestHandle UmbraGetScenes(UmbraAccount* account, UmbraSceneCallback callback, void* userData)
Get the list of scenes owned by the account.
UmbraRequestStatus UmbraGetRequestStatus(UmbraAccount* account, UmbraRequestHandle request)
Get the status of a request.
void UmbraCancelRequest(UmbraAccount* account, UmbraRequestHandle request)
Cancel a request.

Enum details

enum UmbraRequestStatus

Request status.

Enumerators
UmbraRequestStatus_Ok

The request completed succcessfully.

UmbraRequestStatus_InProgress

The request is still in flight, and has neither succeeded nor failed.

UmbraRequestStatus_ConnectionError

Could not connect.

UmbraRequestStatus_BadKeyError

Invalid API key.

UmbraRequestStatus_LicenseExpiredError

Umbra license expired.

UmbraRequestStatus_BadLicenseTypeError
UmbraRequestStatus_ReadError
UmbraRequestStatus_UnknownError
UmbraRequestStatus_Cancelled

The request was cancelled.

UmbraRequestStatus_InvalidHandle

The handle does not match a pending request.

Typedef details

typedef void(*UmbraSceneCallback)(UmbraRequestHandle request, UmbraRequestStatus status, const char*error, UmbraSceneDescription*scenes, int numScenes, void*userData)

The function pointer type for scene list callbacks.

Function details

UmbraAccount* UmbraAccountConnect(UmbraClient* client, const char* apiKey)

Create an account object.

Parameters
client in An Umbra API client.
apiKey in The account's API key.
Returns An opaque object representing the account.

Create an object representing the account identified by the given API key.

void UmbraAccountDisconnect(UmbraAccount* account)

Destroy an account object.

Parameters
account in The account object.

void UmbraAccountPump(UmbraAccount* account, int waitMs)

Work on pending asynchronous requests.

Parameters
account in The account object.
waitMs in The amount of time to spend waiting for new work.

This function works on pending asynchronous requests, and waits for up to waitMs milliseconds for work to become available.

It should be called repeatedly until all requests are either completed or cancelled. For example, it could be called once per frame in a render loop with a small or zero waitMs. Alternatively, it could be called in a tight loop with a large waitMs if the application does not need to do anything else.

UmbraRequestHandle UmbraGetScenes(UmbraAccount* account, UmbraSceneCallback callback, void* userData)

Get the list of scenes owned by the account.

Parameters
account in An Umbra account.
callback in A function that is called when the request finishes.
userData in An arbitrary pointer that is passed to the callback.
Returns An opaque handle representing the request.

See UmbraSceneCallback for a complete description of the callback arguments.

UmbraRequestStatus UmbraGetRequestStatus(UmbraAccount* account, UmbraRequestHandle request)

Get the status of a request.

Parameters
account in The Umbra account object the request was started from.
request in The request handle.
Returns The request status.

void UmbraCancelRequest(UmbraAccount* account, UmbraRequestHandle request)

Cancel a request.

Parameters
account in The Umbra account object the request was started from.
request in The request handle.