SDK  2.1.4 [async]
CloudBackend Software Development Kit - SDK API for C++
cbe::CloudBackend Class Reference

The session that holds the connection with the cloud. More...

#include <CloudBackend.h>

Public Types

using LogInDelegatePtr = delegate::LogInDelegatePtr
 
using CreateAccountDelegatePtr = delegate::CreateAccountDelegatePtr
 
using CloudBackendListenerDelegatePtr = std::shared_ptr< delegate::CloudBackendListenerDelegate >
 
using ListenerHandle = std::uint64_t
 Handle identifying a registered Listener.
 
using QueryDelegatePtr = delegate::QueryDelegatePtr
 
using QueryJoinDelegatePtr = delegate::QueryJoinDelegatePtr
 

Public Member Functions

ListenerHandle addListener (CloudBackendListenerDelegatePtr listener)
 Listen for changes to specific items. More...
 
void removeListener (ListenerHandle handle)
 Delete a specific listener. More...
 
cbe::QueryChain query (ContainerId containerId, QueryDelegatePtr queryDelegate)
 Select Item's of a container (table). More...
 
cbe::QueryChain query (ContainerId containerId, Filter filter, QueryDelegatePtr queryDelegate)
 Select Item's of a container (table) with a filter (where). More...
 
cbe::QueryChainExt query (ContainerId containerId, QueryJoinDelegatePtr queryJoinDelegate)
 Join multiple tables. More...
 
cbe::QueryChainExt query (ContainerId containerId, Filter filter, QueryJoinDelegatePtr queryJoinDelegate)
 Join multiple tables using filter (where). More...
 
cbe::QueryChain queryWithPath (std::string relativePath, cbe::ContainerId queryRoot, QueryDelegatePtr delegate)
 Queries items of a container with a given path. More...
 
cbe::QueryChain queryWithPath (std::string relativePath, QueryDelegatePtr delegate)
 Queries items of a container with a given path relative the home root container. More...
 
cbe::QueryResult search (std::string tags, cbe::ContainerId containerId, QueryDelegatePtr delegate)
 Select Object's with specified key/values. More...
 
cbe::QueryResult search (cbe::Filter filter, cbe::ContainerId containerId, QueryDelegatePtr delegate)
 Select Object's with specified key/values using filter. More...
 
bool clearCache ()
 Clear the local cache. More...
 
cbe::Account account ()
 Returns an account object with information on the user. More...
 
std::string version () const
 Returns the version number of the SDK. More...
 
cbe::GroupManager groupManager ()
 Gets the group manager. More...
 
cbe::ShareManager shareManager ()
 Gets the share manager. More...
 
cbe::PublishManager publishManager ()
 Gets the publish manager. More...
 
void terminate ()
 Terminates the CloudBackend service. More...
 
cbe::SubscribeManager subscribeManager ()
 Gets the subscribe manager. More...
 
 CloudBackend (cbe::DefaultCtor)
 Default constructor. More...
 
 operator bool () const
 Checks if the current instance is real. More...
 

Static Public Member Functions

static cbe::CloudBackend logIn (const std::string &username, const std::string &password, const std::string &tenant, const std::string &client, LogInDelegatePtr delegate)
 Logs in to the CloudBackend service. More...
 
static cbe::UserId createAccount (const std::string &username, const std::string &password, const std::string &email, const std::string &firstName, const std::string &lastName, const std::string &tenant, const std::string &client, CreateAccountDelegatePtr delegate)
 Creates a user account. More...
 
static cbe::Container castContainer (cbe::Item item)
 Casts an item to a container. More...
 
static cbe::Object castObject (cbe::Item item)
 Casts an item to an object. More...
 

Detailed Description

The session that holds the connection with the cloud.

It ensures the connection is authenticated.

Member Typedef Documentation

◆ CloudBackendListenerDelegatePtr

◆ CreateAccountDelegatePtr

◆ LogInDelegatePtr

Pointer to cbe::delegate::LogInDelegate() that is passed into asynchronous version of method logIn()

◆ QueryDelegatePtr

◆ QueryJoinDelegatePtr

Constructor & Destructor Documentation

◆ CloudBackend()

cbe::CloudBackend::CloudBackend ( cbe::DefaultCtor  )

Default constructor.

Construct a new object with the DefaultCtor to enable the operator bool() test

Member Function Documentation

◆ account()

cbe::Account cbe::CloudBackend::account ( )

Returns an account object with information on the user.

Returns
cbe::Account

◆ addListener()

ListenerHandle cbe::CloudBackend::addListener ( CloudBackendListenerDelegatePtr  listener)

Listen for changes to specific items.

Adds a listener that will receive updates as changes occur on the account.

Note
removeListener() should always be called when no longer using the delegate.
Parameters
listenerDelegate is a shared pointer to the class delegate::CloudBackendListenerDelegate that the user has implemented
Returns
Handle identifying the registration of the listener.
To be used when de-registering with method removeListener(ListenerHandle).

◆ castContainer()

static cbe::Container cbe::CloudBackend::castContainer ( cbe::Item  item)
static

Casts an item to a container.

Pointer to cbe::delegate::QueryDelegate that is passed into asynchronous version of method search()

If the provided cbe::Item "item" is not a cbe::Container "container", an empty container instance is returned

◆ castObject()

static cbe::Object cbe::CloudBackend::castObject ( cbe::Item  item)
static

Casts an item to an object.

If the provided cbe::Item "item" is not a cbe::Object "object", an empty object instance is returned

◆ clearCache()

bool cbe::CloudBackend::clearCache ( )

Clear the local cache.

Use if there is a local SDK memory issue.

Returns
true success
false failed

◆ createAccount()

static cbe::UserId cbe::CloudBackend::createAccount ( const std::string &  username,
const std::string &  password,
const std::string &  email,
const std::string &  firstName,
const std::string &  lastName,
const std::string &  tenant,
const std::string &  client,
CreateAccountDelegatePtr  delegate 
)
static

Creates a user account.

This method is only granted to the tenant administrator.

Asynchronous version of this service function.

Parameters
usernameUsername for the new account
passwordPassword for the new account
emailEmail address to owner of the new account
firstNameFirst name of the owner of the new account
lastNameLast name of the owner of the new account
tenantThe identifier for the tenant, formerly known as source.
clientDescribing platform running the software. Names defined by the tenant administrator.
delegatePointer to a delegate::CreateAccountDelegate instance that is implemented by the user.

◆ groupManager()

cbe::GroupManager cbe::CloudBackend::groupManager ( )

Gets the group manager.

Returns
cbe::GroupManager

◆ logIn()

static cbe::CloudBackend cbe::CloudBackend::logIn ( const std::string &  username,
const std::string &  password,
const std::string &  tenant,
const std::string &  client,
LogInDelegatePtr  delegate 
)
static

Logs in to the CloudBackend service.

When finished with the usage of the CloudBackend service, call method CloudBackend::terminate() in all cases.

The authentication to the account is determined by username, password and tenant.

Asynchronous version of this service function.

Parameters
usernameName of the user to be signed in.
passwordPassword for the user to be signed in.
tenantThe identifier for the tenant, formerly known as source.
clientIdentifier of what type of client the program is running on. This is used by the tenant for statistics and selective communication with the users. The tenant administrator defines what client names to use.
delegatePointer to a be::CloudBackend::LogInDelegate() instance that is implemented by the user to receive the response of this login request.
This is accomplished in terms of the LogInDelegate callback functions onLogInSuccess() and onLogInError().

Example
Async login
#include "cbe/CloudBackend.h"
~~~
#include <condition_variable>
#include <mutex>
~~~
int main() {
// First, declare and implement a LogInDelegate class
class MyLogInDelegate : public cbe::delegate::LogInDelegate {
std::mutex mutex{};
std::condition_variable conditionVariable{};
// Indicates operation completed - success or failure
bool called{};
public:
// Default construct this CloudBackend member. If the method
// onLogInSuccess() will not not be called, this default constructed state
// implies that this cloudBackend object is not valid due to a successful
// log in
// Default construct this cbe::delegate::Error member, If the method
// onLogInError() will not not be called, this default constructed state
// implies no error. Otherwise, thus error object will contain the error
// information.
// Implement the cbe::delegate::LogInDelegate interface callbacks (private
// cause they are only used by the SDK):
private:
// Callback called upon successful login.
void onLogInSuccess(cbe::CloudBackend&& cloudBackend) final {
{
std::lock_guard<std::mutex> lock(mutex);
// Put error member into the default constructed state to
// indicate success (i.e., no error)
// Change state of cloudBackend member to indicate success
this->cloudBackend = std::move(cloudBackend);
// Indicate operation completed, member cloudBackend non-default
// constructed state indicates success
called = true;
}
conditionVariable.notify_one();
}
// Callback called upon failed login.
void onLogInError(Error&& error, cbe::util::Context&& context) final {
{
std::lock_guard<std::mutex> lock(mutex);
// Put cloudBackend member into the default constructed state to
// indicate no-success
cloudBackend = cbe::CloudBackend{ cbe::DefaultCtor{} };
// Change state of error member to indicate failure
this->error = std::move(error);
// Indicate operation completed, member member cloudBackend default
// constructed state indicates failure
called = true;
}
conditionVariable.notify_one();
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
public:
void waitForRsp() {
std::unique_lock<std::mutex> lock(mutex);
conditionVariable.wait(lock, [this]{ return called; });
// Reset called flag, so current delegate instance can be reused
called = false;
}
}; // struct MyLogInDelegate
~~~
~~~
// Second, initiate the login:
static constexpr const char* const username = "~~~";
static constexpr const char* const password = "~~~";
static constexpr const char* const tenant = "~~~";
static constexpr const char* const client = "linux_desktop";
~~~
std::shared_ptr<MyLogInDelegate> myLogInDelegate =
std::make_shared<MyLogInDelegate>();
// Invoke the login (cast to return value to void to indicate is deliberately
// discarded)
cbe::CloudBackend cloudBackend = cbe::CloudBackend::logIn(username, password, tenant, client, myLogInDelegate);
// Await the login procedure to run to completion
myLogInDelegate->waitForRsp();
// Test if login failed
if (myLogInDelegate->error) {
std::cout << "Failed to login: error={" << myLogInDelegate->error << '}'
<< std::endl;
// Bail out!
~~~
}
// Since we have a complete CloudBackend object now, copy it from the delegate
cloudBackend = myLogInDelegate->cloudBackend;
// Dispose the delegate object, not needed anymore
myLogInDelegate.reset();
// Do your stuff
~~~
// End of program, tell cbe to terminate the session
cloudBackend.terminate();
}
The session that holds the connection with the cloud.
Definition: CloudBackend.h:47
static cbe::CloudBackend logIn(const std::string &username, const std::string &password, const std::string &tenant, const std::string &client, LogInDelegatePtr delegate)
Logs in to the CloudBackend service.
void terminate()
Terminates the CloudBackend service.
Definition: Error.h:14
Definition: LogInDelegate.h:25
DefaultCtor
Default constructor marker.
Definition: Types.h:204
Definition: Context.h:11

◆ operator bool()

cbe::CloudBackend::operator bool ( ) const
explicit

Checks if the current instance is real.

An "unreal" instance implies typically a failed login event.

Relies on the Default constructor CloudBackend(cbe::DefaultCtor)

Returns
true : is real
false : unreal; got nullptr; if current instance is unbound/undefined. I.e., if it is only default constructed.

◆ publishManager()

cbe::PublishManager cbe::CloudBackend::publishManager ( )

Gets the publish manager.

Returns
cbe::PublishManager

◆ query() [1/4]

cbe::QueryChain cbe::CloudBackend::query ( ContainerId  containerId,
Filter  filter,
QueryDelegatePtr  queryDelegate 
)

Select Item's of a container (table) with a filter (where).

Same as query(ContainerId,QueryDelegatePtr), but with an additional parameter filter.

Parameters
filterFilter specifying the constraints of the requested items.

◆ query() [2/4]

cbe::QueryChainExt cbe::CloudBackend::query ( ContainerId  containerId,
Filter  filter,
QueryJoinDelegatePtr  queryJoinDelegate 
)

Join multiple tables using filter (where).

Same as query(ContainerId,delegate::QueryJoinDelegatePtr), but with an additional Filter parameter filter.

Parameters
filterFilter specifying the constraints of the requested items.

◆ query() [3/4]

cbe::QueryChain cbe::CloudBackend::query ( ContainerId  containerId,
QueryDelegatePtr  queryDelegate 
)

Select Item's of a container (table).

Inquires for a set of Items from the provided Container, identified by containerId. Response is delivered asynchronously via the delegate::QueryDelegate callback interface passed in as argument via parameter queryDelegate .
This overload of join() accepting a QueryDelegate-pointer as parameter has two use cases:

  1. To make a solely query() call without an additional chained join()-call.
  2. To make a query() call with a desired chained join() call.
    In this latter case, the overloaded query()-functions: both accepting a QueryJoinDelegate as delegate argument, must be used.

Asynchronous version of this service function.

Parameters
containerIdId of the container which contents will inquired.
queryDelegatePointer to a QueryDelegate instance, implemented by the user, that receives the response of this query request.
I.e., either the QueryDelegate callback function onQuerySuccess() or onQueryError() will be called in the event of success, or failure respectively.

Example
Async query
~~~
std::shared_ptr<MyQueryDelegate> queryDelegate =
std::make_shared<MyQueryDelegate>();
const cbe::ContainerId myContainerId =
cloudBackend.account().rootContainer().id();
cloudBackend.query(myContainerId, queryDelegate);
queryDelegate->waitForRsp();
if (queryDelegate->errorInfo) {
std::cout << "Query failed:" << std::endl;
std::cout << "ErrorInfo = " << queryDelegate->errorInfo << std::endl;
} else {
queryDelegate->queryResult.getItemsSnapshot();
for (auto& item : itemsSnapshot) {
std::cout << item.name() << std::endl;
}
}
~~~
cbe::Container rootContainer() const
Returns the rootContainer for the account.
cbe::Account account()
Returns an account object with information on the user.
cbe::QueryChain query(ContainerId containerId, QueryDelegatePtr queryDelegate)
Select Item's of a container (table).
cbe::ItemId id() const
std::vector< Item > ItemsSnapshot
A vector of items to hold a snapshot.
Definition: QueryResult.h:61
std::uint64_t ContainerId
Unique Id of a cbe::Container.
Definition: Types.h:60
To use the code above, we must first login and then declare a QueryDelegate class.
See also:

◆ query() [4/4]

cbe::QueryChainExt cbe::CloudBackend::query ( ContainerId  containerId,
QueryJoinDelegatePtr  queryJoinDelegate 
)

Join multiple tables.

Same as query(ContainerId,delegate::QueryDelegatePtr), but with a QueryJoinDelegate as delegate, queryJoinDelegate.

See also
query(ContainerId,delegate::QueryDelegatePtr)
Parameters
queryJoinDelegatePointer to a QueryJoinDelegate instance, implemented by the user, that receives the response of this query request.
I.e., either its callback function onQueryJoinSuccess() or onQueryJoinError() will be called in the event of success or failure respectively.

◆ queryWithPath() [1/2]

cbe::QueryChain cbe::CloudBackend::queryWithPath ( std::string  relativePath,
cbe::ContainerId  queryRoot,
QueryDelegatePtr  delegate 
)

Queries items of a container with a given path.

Note
.. or . relative path options are not permitted.
Only top down search from start point, queryRoot id to downwards path in container tree.
Parameters
relativePathThe relative path from the queryRoot.
E.g.: /Documents/Pictures
from a queryRoot that has the nested containers Documents and Pictures.
queryRootThe container id forming the root of this query.
delegatePointer to a delegate::QueryDelegate instance that is implemented by the user.

◆ queryWithPath() [2/2]

cbe::QueryChain cbe::CloudBackend::queryWithPath ( std::string  relativePath,
QueryDelegatePtr  delegate 
)

Queries items of a container with a given path relative the home root container.

Same as queryWithPath(std::string, cbe::ContainerId, QueryDelegatePtr), but with the queryRoot parameter omitted. Instead, here the home root container is used as top container in the search tree.

◆ removeListener()

void cbe::CloudBackend::removeListener ( ListenerHandle  handle)

Delete a specific listener.

Removes a listener that will receive updates as changes occur on the account

Parameters
handleHandle previously retrieved from method addListener(CloudBackendListenerDelegatePtr).

◆ search() [1/2]

cbe::QueryResult cbe::CloudBackend::search ( cbe::Filter  filter,
cbe::ContainerId  containerId,
QueryDelegatePtr  delegate 
)

Select Object's with specified key/values using filter.

Pointer to cbe::delegate::QueryDelegate that is passed into asynchronous version of method search()

Search the whole container with sub-containers related to Objects in the container hierarchy structure.
E.g., Key = Name, Value Contract/Object/Song => Name:Contract1 .

Search handles tags in combination / conjunction of keys and/or key values separated by |.
E.g., Name:*|Country:Sweden|Country:Norway, this would search for objects with key Name of any value and where key Country is either Sweden or Norway.

See Filter.

Parameters
filteris a cbe::Filter on which you can set how you want data to be ordered when searching.
Remember to set the queryString to be keys/tags or key:value pairs that are separated by |.
containerIdis the ContainerId of the Container to start the search of Objects in.
E.g., if starting in the rootContainer, the whole account will be searched for matching tags, key/value's.
delegateis the callback pointer to where the API returns from either cache or Server.

◆ search() [2/2]

cbe::QueryResult cbe::CloudBackend::search ( std::string  tags,
cbe::ContainerId  containerId,
QueryDelegatePtr  delegate 
)

Select Object's with specified key/values.

Search the whole container for tags related to Objects in the container structure.
E.g., Key = Name, Value Contract/Object/Song => Name:Contract1 .

Search handles tags in combination / conjunction of keys and/or key values separated by |.
E.g., Name:*|Country:Sweden|Country:Norway.
This would search for objects with key Name of any value and where key Country is either Sweden or Norway.

Parameters
tagsIs a string of key tags or key:value pairs that are separated by |.
containerIdIs the cbe::ContainerId id of the rootContainer to start the search of objects in.
E.g., if starting in the rootContainer, the whole account will be searched for matching tags, key/value's.
delegateIs the callback pointer to where the API returns from either cache or Server.

◆ shareManager()

cbe::ShareManager cbe::CloudBackend::shareManager ( )

Gets the share manager.

Returns
cbe::ShareManager

◆ subscribeManager()

cbe::SubscribeManager cbe::CloudBackend::subscribeManager ( )

Gets the subscribe manager.

Returns
cbe::SubscribeManager

◆ terminate()

void cbe::CloudBackend::terminate ( )

Terminates the CloudBackend service.

Shall also be called in connection with a failed log in.

◆ version()

std::string cbe::CloudBackend::version ( ) const

Returns the version number of the SDK.

Returns
std::string

The documentation for this class was generated from the following file: