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

A collection of Item, can also represent a table or folder. More...

#include <Container.h>

Inheritance diagram for cbe::Container:
Collaboration diagram for cbe::Container:

Public Types

using CreateContainerDelegatePtr = delegate::CreateContainerDelegatePtr
 
using MoveDelegatePtr = delegate::container::MoveDelegatePtr
 
using RenameDelegatePtr = delegate::container::RenameDelegatePtr
 
using RemoveDelegatePtr = delegate::container::RemoveDelegatePtr
 
using CreateObjectDelegatePtr = delegate::CreateObjectDelegatePtr
 
using UploadDelegatePtr = delegate::UploadDelegatePtr
 
using QueryDelegatePtr = delegate::QueryDelegatePtr
 
using QueryJoinDelegatePtr = std::shared_ptr< delegate::QueryJoinDelegate >
 
using SetAclDelegatePtr = delegate::AclDelegatePtr
 
using GetAclDelegatePtr = delegate::AclDelegatePtr
 
using ShareDelegatePtr = delegate::ShareDelegatePtr
 
using UnShareDelegatePtr = std::shared_ptr< delegate::UnShareDelegate >
 
using PublishDelegatePtr = delegate::PublishDelegatePtr
 
using UnPublishDelegatePtr = delegate::UnPublishDelegatePtr
 
using UnSubscribeDelegatePtr = delegate::UnSubscribeDelegatePtr
 

Public Member Functions

cbe::Container createContainer (const std::string &name, CreateContainerDelegatePtr delegate)
 Create a container. More...
 
void move (cbe::ContainerId dstId, MoveDelegatePtr delegate)
 Move a container to a different parent. More...
 
void rename (const std::string &name, RenameDelegatePtr delegate)
 Change the name of the container. More...
 
void remove (RemoveDelegatePtr delegate)
 Delete the container. More...
 
cbe::Object createObject (std::string name, cbe::KeyValues keyValues, CreateObjectDelegatePtr delegate)
 Create a new object. More...
 
cbe::Object createObject (std::string name, CreateObjectDelegatePtr delegate)
 
cbe::Object upload (const std::string &filePath, UploadDelegatePtr delegate)
 Upload object to container with file given by filePath. More...
 
cbe::Object upload (const std::string &name, const std::string &path, UploadDelegatePtr delegate)
 Create an object in current container by uploading a file. More...
 
cbe::Object upload (const std::string &name, std::uint64_t length, const char *byteData, UploadDelegatePtr delegate)
 Upload from local memory to an object. More...
 
cbe::QueryChain query (QueryDelegatePtr queryDelegate)
 Select list of objects. More...
 
cbe::QueryChain query (Filter filter, QueryDelegatePtr delegate)
 Select list of objects using filter. More...
 
cbe::QueryChainExt query (delegate::QueryJoinDelegatePtr delegate)
 Select list of objects, for join. More...
 
cbe::QueryChainExt query (Filter filter, delegate::QueryJoinDelegatePtr delegate)
 Select list of objects using filter, for join. More...
 
cbe::QueryChain queryWithPath (std::string relativePath, QueryDelegatePtr delegate)
 Select list of objects in hierarchy. More...
 
cbe::QueryResult search (std::string tags, QueryDelegatePtr delegate)
 Search by tags. More...
 
cbe::QueryResult search (cbe::Filter filter, QueryDelegatePtr delegate)
 Search using filter. More...
 
void setAcl (cbe::AclMap aclMap, SetAclDelegatePtr delegate)
 set ACL. More...
 
void getAcl (GetAclDelegatePtr delegate)
 Retrieves its ACL map. More...
 
void share (cbe::UserId toUserGroup, std::string description, ShareDelegatePtr delegate)
 Make accessible by other user. More...
 
void unShare (cbe::ShareId shareId, UnShareDelegatePtr delegate)
 Revoke a previous share. More...
 
void publish (cbe::PublishAccess security, cbe::PublishVisibility privacy, std::string description, std::string password, PublishDelegatePtr delegate)
 Publishes a container and its content to any user. More...
 
void unPublish (UnPublishDelegatePtr delegate)
 UnPublishes this container. More...
 
void unSubscribe (UnSubscribeDelegatePtr delegate)
 UnSubscribes from this container. More...
 
 Container (cbe::DefaultCtor)
 
- Public Member Functions inherited from cbe::Item
cbe::ShareIds getShareIds () const
 
cbe::ShareId getShareFromUserId (cbe::UserId userId)
 
cbe::UserId getUserFromShareId (cbe::UserId shareId)
 
std::string aclTag () const
 
std::string description () const
 
cbe::ItemId id () const
 
cbe::ContainerId parentId () const
 
cbe::ContainerId oldParentId () const
 
std::string name () const
 
std::string path () const
 
cbe::UserId ownerId () const
 
cbe::ContainerId driveId () const
 
std::string username () const
 
bool idLoaded () const
 
bool dataLoaded () const
 
cbe::Date created () const
 
cbe::Date updated () const
 
cbe::Date deleted () const
 
cbe::ItemType type () const
 
bool hasPublished () const
 
Publish getPublished () const
 
bool hasSubscribe () const
 
Subscribe getSubscribe () const
 
bool operator< (const cbe::Item &rh) const
 
AclMap aclMap () const
 
 operator bool () const
 Checks if the inherited instance is real. More...
 

Friends

class Account
 
class CloudBackend
 
class Database
 
class Filter
 
class Group
 
class QueryChain
 

Additional Inherited Members

- Protected Member Functions inherited from cbe::Item
 Item (std::shared_ptr< Impl > pImpl)
 
template<class ImplT >
ImplT & castImpl () const
 

Detailed Description

A collection of Item, can also represent a table or folder.

Member Typedef Documentation

◆ CreateContainerDelegatePtr

Pointer to cbe::delegate::CreateContainerDelegate that is passed into asynchronous version of method createContainer()

◆ CreateObjectDelegatePtr

Pointer to cbe::delegate::CreateObjectDelegate that is passed into asynchronous version of method createObject()

◆ GetAclDelegatePtr

Pointer to cbe::delegate::AclDelegate that is passed into asynchronous version of method getAcl()

◆ MoveDelegatePtr

Pointer to cbe::delegate::MoveDelegate that is passed into asynchronous version of method move()

◆ PublishDelegatePtr

Pointer to cbe::delegate::PublishDelegate that is passed into asynchronous version of method publish()

◆ QueryDelegatePtr

Pointer to cbe::delegate::QueryDelegatePtr that is passed into asynchronous version of method query()

◆ QueryJoinDelegatePtr

Pointer to cbe::delegate::QueryJoinDelegate that is passed into asynchronous version of method query()

◆ RemoveDelegatePtr

Pointer to cbe::delegate::RemoveDelegate that is passed into asynchronous version of method remove()

◆ RenameDelegatePtr

Pointer to cbe::delegate::container::RenameDelegate that is passed into asynchronous version of method rename()

◆ SetAclDelegatePtr

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

◆ ShareDelegatePtr

Pointer to cbe::delegate::ShareDelegate that is passed into asynchronous version of method share()

◆ UnPublishDelegatePtr

Pointer to cbe::delegate::UnPublishDelegatePtr that is passed into asynchronous version of method unPublish()

◆ UnShareDelegatePtr

Pointer to cbe::delegate::UnShareDelegate that is passed into asynchronous version of method unShare()

◆ UnSubscribeDelegatePtr

Pointer to cbe::delegate::UnPublishDelegate that is passed into asynchronous version of method unPublish() Pointer to cbe::delegate::UnSubscribeDelegate that is passed into asynchronous version of method unSubscribe()

◆ UploadDelegatePtr

Member Function Documentation

◆ createContainer()

cbe::Container cbe::Container::createContainer ( const std::string &  name,
CreateContainerDelegatePtr  delegate 
)

Create a container.

Creates a container inside this container to be used for adding objects.

Parameters
nameName of the container to be created.
delegatePointer to a delegate::CreateContainerDelegate instance that is implemented by the user.

◆ createObject() [1/2]

cbe::Object cbe::Container::createObject ( std::string  name,
cbe::KeyValues  keyValues,
CreateObjectDelegatePtr  delegate 
)

Create a new object.

Creates an object with indexed tags or indexed tags + non indexed tags a.k.a. metadata, key/value pairs.

Parameters
nameName of the object.
keyValuesOptional map of key/value pairs (metadata).
delegatePointer to a delegate::CreateObjectDelegate instance that is implemented by the user.
Note
If an old object with the same name already exists that will be removed.
The object name may not contain characters < & : /
Any key name must start with a letter or _
The following key names are reserved and should not be used: category, content, id, link and date
Key names are case sensitive, hence variations with uppercase are permitted.

◆ createObject() [2/2]

cbe::Object cbe::Container::createObject ( std::string  name,
CreateObjectDelegatePtr  delegate 
)

Same as createObject(std::string, cbe::KeyValues, CreateObjectDelegatePtr), but without the keyValues parameter.

◆ getAcl()

void cbe::Container::getAcl ( GetAclDelegatePtr  delegate)

Retrieves its ACL map.

get the Access Control List ACL of the Container.

Parameters
delegatePointer to a delegate::AclDelegate instance that is implemented by the user.

◆ move()

void cbe::Container::move ( cbe::ContainerId  dstId,
MoveDelegatePtr  delegate 
)

Move a container to a different parent.

Used to move container with its content to user specified location e.g., other container or to root container.

Parameters
dstIdid of the container to which it should be moved to.
delegatePointer to a delegate::container::MoveDelegate instance that is implemented by the user.

◆ publish()

void cbe::Container::publish ( cbe::PublishAccess  security,
cbe::PublishVisibility  privacy,
std::string  description,
std::string  password,
PublishDelegatePtr  delegate 
)

Publishes a container and its content to any user.

Asynchronous version of this service function.

Can be revoked with unPublish()

Parameters
securityA cbe::PublishAccess enum
privacyA cbe::PublishVisibility enum
descriptionFree text
passwordPassword
delegatePointer to a delegate::PublishDelegate instance that is implemented by the user.

◆ query() [1/4]

cbe::QueryChainExt cbe::Container::query ( delegate::QueryJoinDelegatePtr  delegate)

Select list of objects, for join.

In line with function CloudBackend::query(ContainerId, delegate::QueryJoinDelegatePtr), but with its ContainerId parameter excluded.

See also
CloudBackend::query(ContainerId, delegate::QueryJoinDelegatePtr)

◆ query() [2/4]

cbe::QueryChainExt cbe::Container::query ( Filter  filter,
delegate::QueryJoinDelegatePtr  delegate 
)

Select list of objects using filter, for join.

In line with function CloudBackend::query(ContainerId, Filter, delegate::QueryJoinDelegatePtr), but with its ContainerId parameter excluded.

See also
CloudBackend::query(ContainerId, Filter, delegate::QueryJoinDelegatePtr)

◆ query() [3/4]

cbe::QueryChain cbe::Container::query ( Filter  filter,
QueryDelegatePtr  delegate 
)

Select list of objects using filter.

In line with function CloudBackend::query(ContainerId, Filter, QueryDelegatePtr), but with its ContainerId parameter excluded.

See also
CloudBackend::query(ContainerId, Filter, QueryDelegatePtr)

◆ query() [4/4]

cbe::QueryChain cbe::Container::query ( QueryDelegatePtr  queryDelegate)

Select list of objects.

In line with function CloudBackend::query(ContainerId, QueryDelegatePtr), but with its ContainerId parameter excluded.

See also
CloudBackend::query(ContainerId, QueryDelegatePtr)

◆ queryWithPath()

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

Select list of objects in hierarchy.

Pointer to cbe::delegate::queryWithPathDelegate that is passed into asynchronous version of method queryWithPath()

Queries the container with a given relative path, returns container with objects.
E.g. /Documents/Pictures will return objects and subContainers for Pictures.

Note
.. or . path options are not available, top down Paths in the container tree are available.
Parameters
relativePathcontainer path, e.g. /Documents/Pictures
delegatePointer to a delegate::QueryDelegate instance that is implemented by the user.

◆ remove()

void cbe::Container::remove ( RemoveDelegatePtr  delegate)

Delete the container.

Removes/deletes the container and all its content.

Parameters
delegatePointer to a delegate::container::RemoveDelegate instance that is implemented by the user.

◆ rename()

void cbe::Container::rename ( const std::string &  name,
RenameDelegatePtr  delegate 
)

Change the name of the container.

Rename the container.

Parameters
nameNew name of the container.
delegatePointer to a delegate::container::RenameDelegate instance that is implemented by the user.

◆ search() [1/2]

cbe::QueryResult cbe::Container::search ( cbe::Filter  filter,
QueryDelegatePtr  delegate 
)

Search using filter.

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.

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 |.
delegatePointer to a delegate::QueryDelegate instance that is implemented by the user.

◆ search() [2/2]

cbe::QueryResult cbe::Container::search ( std::string  tags,
QueryDelegatePtr  delegate 
)

Search by tags.

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

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 of conjunctions 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 |.
delegatePointer to a delegate::QueryDelegate instance that is implemented by the user.

◆ setAcl()

void cbe::Container::setAcl ( cbe::AclMap  aclMap,
SetAclDelegatePtr  delegate 
)

set ACL.

Set the Access Control List ACL for the container. For containers set does set the whole container tree, so all its sub items as well. Remember this is set and not update so every time you set all ids that should be there should be added.

Parameters
aclMapThe desired permissions for current container.
delegatePointer to a delegate::AclDelegate instance that is implemented by the user.

◆ share()

void cbe::Container::share ( cbe::UserId  toUserGroup,
std::string  description,
ShareDelegatePtr  delegate 
)

Make accessible by other user.

Shares a container and its content to a user. This provides the user the ability to access what has been shared to them via the listAvailableShares command. To allow users to view and change shared information see ACL .

Note
At present Sharing the container gives the user read permissions for the container and all its sub-items, this might change in the future.
Parameters
toUserGrouptakes a user id or group id to share to.
descriptionnames the specific share between you and the user/group.
delegatePointer to a delegate::ShareDelegate instance that is implemented by the user.

◆ unPublish()

void cbe::Container::unPublish ( UnPublishDelegatePtr  delegate)

UnPublishes this container.

Asynchronous version of this service function.

Revokes previous publish().

Parameters
delegateGets notified when the container has been unPublished (or if there was an error)

◆ unShare()

void cbe::Container::unShare ( cbe::ShareId  shareId,
UnShareDelegatePtr  delegate 
)

Revoke a previous share.

unShare the container to a specific shareId created when sharing. Each share is unique between user/group and the one sharing. This is represented with a unique share id.

Parameters
shareIdis as mentioned the unique id for a share between the owner and other user/group.
delegatePointer to a delegate::UnShareDelegate instance that is implemented by the user.

◆ unSubscribe()

void cbe::Container::unSubscribe ( UnSubscribeDelegatePtr  delegate)

UnSubscribes from this container.

Asynchronous version of this service function.

Revokes the subscription previously established with cbe::SubscribeManager::subscribe()

Parameters
delegateGets notified when the container has been unSubscribed (or if there was an error)

◆ upload() [1/3]

cbe::Object cbe::Container::upload ( const std::string &  filePath,
UploadDelegatePtr  delegate 
)

Upload object to container with file given by filePath.

See upload(const std::string&,const std::string& path,UploadDelegatePtr)

Parameters
filePathFully qualified file name. I.e., the path, relative or absolute, including file name.

Example
Async creation of a cbe::Object by using Container::upload()
#include "cbe/Object.h"
#include "cbe/Container.h"
#include "cbe/delegate/UploadDelegate.h"
#include <condition_variable>
#include <fstream> // std::ofstream
#include <mutex>
~~~
struct MyUploadDelegate : cbe::delegate::UploadDelegate {
std::mutex mutex{};
std::condition_variable conditionVariable{};
// Indicates operation completed - success or failure
bool called{};
// Default construct the result object. If the method
// onUploadSuccess() has not been called, this default constructed state
// implies that the object is not valid
void onUploadSuccess(cbe::Object&& object) final {
{
std::lock_guard<std::mutex> lock{mutex};
// Change state of object member to indicate success
this->object = std::move(object);
// Indicate operation completed, member object indicates success
called = true;
}
conditionVariable.notify_one();
}
void onUploadError(cbe::delegate::TransferError&& transferError,
cbe::util::Context&& context) final {
{
std::lock_guard<std::mutex> lock{mutex};
// Put object into the default constructed state to indicate no-success
// Indicate operation completed, member object indicates failure
called = true;
}
conditionVariable.notify_one();
}
cbe::Object 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;
// If object is still in its default constructed state, this implies a
// failed cbe::object::upload() operation
return object;
}
}; // struct MyUploadDelegate
~~~
constexpr const char* const uploadPath = "/tmp/upload/";
constexpr const char* const myObjectFileName = "myObject";
const std::string qualFile1Name =
std::string{uploadPath} + myObjectFileName;
std::ofstream ofs{qualFile1Name};
ofs << "Line 11\n" << "Line 12\n" << "Line 13\n" << std::flush;
ofs.close();
// Access container previously created with cbe::Container::createContainer()
cbe::Container myContainer = ~~~;
std::shared_ptr<MyUploadDelegate> myUploadDelegate =
std::make_shared<MyUploadDelegate>();
// Create an object named after file name in variable qualFile1Name
myContainer.upload(qualFile1Name, myUploadDelegate);
// Continuously, use the Object instance passed into the delegate.
cbe::Object object = myUploadDelegate->waitForRsp();
// Check if upload was successful
if (!object) {
// Not, bail out
~~~
// }
~~~
A collection of Item, can also represent a table or folder.
Definition: Container.h:63
cbe::Object upload(const std::string &filePath, UploadDelegatePtr delegate)
Upload object to container with file given by filePath.
Holder of a set of data, can represent a table row.
Definition: Object.h:64
Definition: TransferError.h:18
Definition: UploadDelegate.h:28
DefaultCtor
Default constructor marker.
Definition: Types.h:204
Definition: Context.h:11
Continues at: Async retrieving the Stream attached to a cbe::Object with the Object::getStreams()"

◆ upload() [2/3]

cbe::Object cbe::Container::upload ( const std::string &  name,
const std::string &  path,
UploadDelegatePtr  delegate 
)

Create an object in current container by uploading a file.

Object is named by name, residing at path.

The object being created is instantly returned with a temporary id. When the response is retrieved from from the server, via callback method onUploadSuccess() the object will be updated with its final unique id.

Parameters
nameName of local file name. The object, that is created, will be given the same name.
pathPath to local folder where the file is located. The can be relative or absolute and must end with a slash (/).
delegatePointer to a delegate::UploadDelegate instance that is implemented by the user.
Returns
The created Object, first with its temporary id, and after successful with is final id.

◆ upload() [3/3]

cbe::Object cbe::Container::upload ( const std::string &  name,
std::uint64_t  length,
const char *  byteData,
UploadDelegatePtr  delegate 
)

Upload from local memory to an object.

Parameters
namename that the uploaded object will get
lengthsize of file in Bytes
byteData(char pointer to an array containing the data).
delegatePointer to a delegate::UploadDelegate instance that is implemented by the user.

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