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

Holder of a set of data, can represent a table row. More...

#include <Object.h>

Inheritance diagram for cbe::Object:
Collaboration diagram for cbe::Object:

Public Types

using MoveDelegatePtr = delegate::object::MoveDelegatePtr
 
using RenameDelegatePtr = delegate::object::RenameDelegatePtr
 
using RemoveDelegatePtr = delegate::object::RemoveDelegatePtr
 
using DownloadDelegatePtr = delegate::DownloadDelegatePtr
 
using DownloadBinaryDelegatePtr = delegate::DownloadBinaryDelegatePtr
 
using UploadDelegatePtr = delegate::UploadDelegatePtr
 
using UpdateKeyValuesDelegatePtr = delegate::UpdateKeyValuesDelegatePtr
 
using GetStreamsDelegatePtr = delegate::GetStreamsDelegatePtr
 
using Streams = cbe::Streams
 Collection of Stream objects. More...
 
using GetAclDelegatePtr = delegate::AclDelegatePtr
 
using SetAclDelegatePtr = delegate::AclDelegatePtr
 
using ShareDelegatePtr = delegate::ShareDelegatePtr
 
using UnShareDelegatePtr = delegate::UnShareDelegatePtr
 
using PublishDelegatePtr = delegate::PublishDelegatePtr
 
using UnPublishDelegatePtr = delegate::UnPublishDelegatePtr
 
using UnSubscribeDelegatePtr = delegate::UnSubscribeDelegatePtr
 

Public Member Functions

void move (cbe::ContainerId dstId, MoveDelegatePtr delegate)
 Relocates an object to a different container. More...
 
void rename (const std::string &name, RenameDelegatePtr delegate)
 Rename object. More...
 
void remove (RemoveDelegatePtr delegate)
 Remove the object from cloud and locally. More...
 
void download (const std::string &path, DownloadDelegatePtr delegate)
 Download the data of current object to the the local file system. More...
 
void download (std::size_t &&sizeLimit, DownloadBinaryDelegatePtr delegate)
 Download the binary data associated with current object. More...
 
void downloadStream (const std::string &path, cbe::Stream stream, DownloadDelegatePtr delegate)
 
void uploadStream (const std::string &filePath, cbe::StreamId streamId, UploadDelegatePtr delegate)
 Upload a file for adding a new or replacing existing stream attached to this object. More...
 
void updateKeyValues (KeyValues keyValues, UpdateKeyValuesDelegatePtr delegate)
 Adds key/value pair data to the object. More...
 
void updateKeyValues (UpdateKeyValuesDelegatePtr delegate)
 Deletes all key/value pairs of data to the object. More...
 
void getStreams (GetStreamsDelegatePtr delegate)
 Downloads the streams meta data associated with current object to the SDK's cache. More...
 
std::string getMimeType () const
 Returns the mime type of the object. More...
 
uint64_t length () const
 Returns the binary length/size in bytes of current object.
 
cbe::object_t getObjectType () const
 Returns the Object type. More...
 
cbe::KeyValues keyValues ()
 Returns all the key/values for current object as a map.
 
void getAcl (GetAclDelegatePtr delegate)
 Returns the Access Control List for current Object. More...
 
void setAcl (cbe::AclMap aclMap, SetAclDelegatePtr delegate)
 Sets the Access Control List for current object. More...
 
void share (cbe::UserId toUserGroup, std::string description, ShareDelegatePtr delegate)
 Share current object to a user. More...
 
void unShare (cbe::ShareId shareId, UnShareDelegatePtr delegate)
 Unshare the object to a specific shareId created when sharing. More...
 
void publish (cbe::PublishAccess security, cbe::PublishVisibility privacy, std::string description, std::string password, PublishDelegatePtr delegate)
 Publishes current object to any user. More...
 
void unPublish (UnPublishDelegatePtr delegate)
 UnPublishes current object. More...
 
void unSubscribe (UnSubscribeDelegatePtr delegate)
 UnSubscribes from this object. More...
 
std::string url ()
 URL to current object.
 
 Object (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 CloudBackend
 
class Container
 

Additional Inherited Members

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

Detailed Description

Holder of a set of data, can represent a table row.

Note
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.

Member Typedef Documentation

◆ DownloadBinaryDelegatePtr

Pointer to cbe::delegate::DownloadBinaryDelegate that is passed into asynchronous version of method download()

◆ DownloadDelegatePtr

◆ GetAclDelegatePtr

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

◆ GetStreamsDelegatePtr

Pointer to cbe::delegate::GetStreamsDelegate that is passed into asynchronous version of method getStream()

◆ MoveDelegatePtr

Pointer to cbe::delegate::object::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()

◆ RemoveDelegatePtr

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

◆ RenameDelegatePtr

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

◆ SetAclDelegatePtr

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

◆ Streams

Collection of Stream objects.

See cbe::Streams

◆ UnPublishDelegatePtr

Pointer to cbe::delegate::UnPublishDelegate 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

◆ UpdateKeyValuesDelegatePtr

Pointer to cbe::delegate::UpdateKeyValuesDelegate that is passed into asynchronous version of method updateKeyValues()

◆ UploadDelegatePtr

Pointer to cbe::delegate::UploadDelegate that is passed into asynchronous version of method uploadStream()

Member Function Documentation

◆ download() [1/2]

void cbe::Object::download ( const std::string &  path,
DownloadDelegatePtr  delegate 
)

Download the data of current object to the the local file system.

Asynchronous version of this service function.

The data will be contained in file, named after the name of current object (method name()), to the location given by parameter path.

Parameters
pathFolder location, on the local file system, of the file to be downloaded. This string must end with a slash ("/").
delegatePointer to a delegate::DownloadDelegate instance that is implemented by the user.

◆ download() [2/2]

void cbe::Object::download ( std::size_t &&  sizeLimit,
DownloadBinaryDelegatePtr  delegate 
)

Download the binary data associated with current object.

Asynchronous version of this service function.

The data, delivered as a BLOB (Binary Large OBject), via parameter data in the the callback method cbe::delegate::DownloadBinaryDelegate::onDownloadBinarySuccess().

Parameters
delegatePointer to a delegate::DownloadBinaryDelegate instance that is implemented by the user.
sizeLimitBlocks anything larger than the size limit the user inputs. Prevents accidental downloads of too large objects on to the device.

◆ downloadStream()

void cbe::Object::downloadStream ( const std::string &  path,
cbe::Stream  stream,
DownloadDelegatePtr  delegate 
)

Download a stream of an Object to local filesystem.

Asynchronous version of this service function.

Parameters
pathFolder location, on the local file system, of the file to be downloaded. This string must end with a slash ("/").
streamGet which stream you want by first calling getStream() and then choose which one to download.
delegatePointer to a delegate::DownloadDelegate instance that is implemented by the user.

Example
Async downloading the data attached to a cbe::Object via a Stream with Object::downloadStream()
Continuation of: Async uploading data to a cbe::Object via a Stream with Object::uploadStream()
~~~
#include "cbe/delegate/DownloadDelegate.h"
~~~
struct MyDownloadDelegate : cbe::delegate::DownloadDelegate {
std::mutex mutex{};
std::condition_variable conditionVariable{};
bool called{};
Success success{};
void onDownloadSuccess(cbe::Object&& object,
std::string path) final {
{
std::lock_guard<std::mutex> lock{mutex};
success = Success{std::move(object), std::move(path)};
called = true;
}
conditionVariable.notify_one();
}
void onDownloadError(cbe::delegate::TransferError&& transferError,
cbe::util::Context&& context) final {
{
std::lock_guard<std::mutex> lock{mutex};
success = Success{};
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 default constructed, this implies a failed
// cbe::Object::downloadStream() operation
return success.object;
}
}; // struct MyDownloadDelegate
~~~
std::shared_ptr<MyDownloadDelegate> myDownloadDelegate =
std::make_shared<MyDownloadDelegate>();
constexpr const char* const downloadPath = "/tmp/download/";
for (const auto& stream : streams2) {
const auto path = std::string{downloadPath} +
std::to_string(stream.streamId);
object.downloadStream(path, stream, myDownloadDelegate);
if (!myDownloadDelegate->waitForRsp()) {
// Failure, bail out
~~~
}
}
std::string path() const
Holder of a set of data, can represent a table row.
Definition: Object.h:64
Definition: DownloadDelegate.h:25
Definition: TransferError.h:18
Definition: Context.h:11

◆ getAcl()

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

Returns the Access Control List for current Object.

Asynchronous version of this service function.

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

◆ getMimeType()

std::string cbe::Object::getMimeType ( ) const

Returns the mime type of the object.

E.g., application/pdf, audio/wav, image/jpg, text/xml, video/mp4 etc.

◆ getObjectType()

cbe::object_t cbe::Object::getObjectType ( ) const

Returns the Object type.

See cbe::ObjectType.

◆ getStreams()

void cbe::Object::getStreams ( GetStreamsDelegatePtr  delegate)

Downloads the streams meta data associated with current object to the SDK's cache.

Asynchronous version of this service function.

The meta data i delivered as cbe::Streams via the delegate callback method cbe::delegate::GetStreamsDelegate::onGetStreamsSuccess()
Further, the actual stream data are retrieved through method downloadStream(const std::string&,cbe::Stream,DownloadDelegatePtr).

Note
This method must be re-called if you upload more streams, see uploadStream()
Parameters
delegatePointer to a delegate::GetStreamsDelegate instance that is implemented by the user.

Example
Async retrieving the Streams attached to a cbe::Object with the Object::getStreams()
Continuation of: Async creation of a cbe::Object by using Container::upload()
~~~
#include "cbe/delegate/GetStreamsDelegate.h"
#include "cbe/util/Optional.h"
~~~
struct MyGetStreamsDelegate : cbe::delegate::GetStreamsDelegate {
std::mutex mutex{};
std::condition_variable conditionVariable{};
bool called{};
// Represents the result stream meta data as a cbe::Optional. Where an empty
// Optional implies an error
void onGetStreamsSuccess(cbe::Streams&& streams) final {
{
std::lock_guard<std::mutex> lock{mutex};
this->streams = std::move(streams);
called = true;
}
conditionVariable.notify_one();
}
void onGetStreamsError(cbe::delegate::Error&& error,
cbe::util::Context&& context) final {
{
std::lock_guard<std::mutex> lock{mutex};
called = true;
}
conditionVariable.notify_one();
}
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 streams is still default constructed, this implies a failed
// cbe::Object::getStreams() operation
return std::move(streams);
}
}; // struct MyGetStreamsDelegate
~~~
std::shared_ptr<MyGetStreamsDelegate> getStreamsDelegate =
std::make_shared<MyGetStreamsDelegate>();
object.getStreams(getStreamsDelegate);
// Simply make use of the Optional bool type conversion operator on the return
// value from the waitForRsp() method to determine the outcome of the
// getStreams() invocation above
getStreamsDelegate->waitForRsp();
if (!streamsOpt1) {
// Failure, bail out
~~~
}
// Now, streamsOpt1 contains the streams meta data, so move it to variable
// streams1
const cbe::Object::Streams streams1 = std::move(*streamsOpt1);
~~~
cbe::Streams Streams
Collection of Stream objects.
Definition: Object.h:878
Definition: Error.h:14
Definition: GetStreamsDelegate.h:26
Class template Optional manages an optional contained value - i.e., a value that is either present or...
Definition: Optional.h:20
std::vector< cbe::Stream > Streams
Collection of Stream objects.
Definition: Stream.h:49
DefaultCtor
Default constructor marker.
Definition: Types.h:204
Continues at: Async uploading data to a cbe::Object via a Stream with Object::uploadStream()

◆ move()

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

Relocates an object to a different container.

Asynchronous version of this service function.

Parameters
dstIdId of the destination container.
delegatePointer to a delegate::object::MoveDelegate instance that is implemented by the user.

◆ publish()

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

Publishes current object to any user.

Asynchronous version of this service function.

Can be revoked with unPublish()

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

◆ remove()

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

Remove the object from cloud and locally.

Asynchronous version of this service function.

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

◆ rename()

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

Rename object.

Asynchronous version of this service function.

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

◆ setAcl()

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

Sets the Access Control List for current object.

Asynchronous version of this service function.

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

◆ share()

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

Share current object to a user.

Asynchronous version of this service function.

Notifies the user that a share has ocurred so that the user can check what permissions the have been given. Sharing gives read permissions as of right now but might change in the future.

Parameters
toUserGroupTakes a user id or group id (lastly named is for the future) and share to.
descriptionNames the specific share between you and the user/group.
delegatePointer to a delegate::ShareDelegatePtr instance that is implemented by the user.

◆ unPublish()

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

UnPublishes current object.

Asynchronous version of this service function.

Revokes previous publish().

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

◆ unShare()

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

Unshare the object to a specific shareId created when sharing.

Asynchronous version of this service function.

Each share is unique between user/group and the one sharing. This is represented with a unique share id.

Parameters
shareIdThe 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::Object::unSubscribe ( UnSubscribeDelegatePtr  delegate)

UnSubscribes from this object.

Asynchronous version of this service function.

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

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

◆ updateKeyValues() [1/2]

void cbe::Object::updateKeyValues ( KeyValues  keyValues,
UpdateKeyValuesDelegatePtr  delegate 
)

Adds key/value pair data to the object.

Asynchronous version of this service function.

Note
All existing key will be overwritten, new created.
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.
Parameters
keyValuesMap of key/value pairs (metadata).
delegatePointer to a delegate::UpdateKeyValuesDelegate instance that is implemented by the user.

◆ updateKeyValues() [2/2]

void cbe::Object::updateKeyValues ( UpdateKeyValuesDelegatePtr  delegate)

Deletes all key/value pairs of data to the object.

Same as updateKeyValues(KeyValues,UpdateKeyValuesDelegatePtr), but without the keyValues parameter.

Note
Any and all existing key/values will be erased.

◆ uploadStream()

void cbe::Object::uploadStream ( const std::string &  filePath,
cbe::StreamId  streamId,
UploadDelegatePtr  delegate 
)

Upload a file for adding a new or replacing existing stream attached to this object.

Asynchronous version of this service function.

Requires that method getStreams(GetStreamsDelegatePtr) is called to identify all streams associated with current object.

Parameters
filePathFully qualified file name. I.e., the path, relative or absolute, including file name.
streamIdIf the stream id already exists, it will be overwritten.
delegatePointer to a delegate::UploadDelegate instance that is implemented by the user.

Example
Async uploading data to a cbe::Object via a Stream with Object::uploadStream()
Continuation of: Async retrieving the Streams attached to a cbe::Object with the Object::getStreams()
~~~
#include "cbe/delegate/UploadDelegate.h"
~~~
#include <algorithm> // std::max_element
#include <vector> // std::cbegin, std::cend
~~~
struct MyUploadDelegate : cbe::delegate::UploadDelegate {
std::mutex mutex{};
std::condition_variable conditionVariable{};
bool called{};
// Default construct, further see comment for object member in
// MyUploadDelegate above
void onUploadSuccess(cbe::Object&& object) final {
{
std::lock_guard<std::mutex> lock{mutex};
this->object = std::move(object);
called = true;
}
conditionVariable.notify_one();
}
void onUploadError(cbe::delegate::TransferError&& transferError,
cbe::util::Context&& context) final {
{
std::lock_guard<std::mutex> lock{mutex};
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 default constructed, this implies a failed
// cbe::Object::uploadStream() operation
return object;
}
}; // struct MyUploadDelegate
~~~
constexpr const char* const myFile2Name = "myStream2";
const std::string qualFile2Name = std::string{uploadPath} + myFile2Name;
std::ofstream ofs2{qualFile2Name};
ofs2 << "Line 21\n" << "Line 22\n" << "Line 23\n" << "Line 24\n"
<< std::flush;
ofs2.close();
const auto nextStreamId =
std::max_element(std::cbegin(streams1), std::cend(streams1),
[](const cbe::Stream& stream1,
const cbe::Stream& stream2) {
return stream1.streamId < stream2.streamId;
})->streamId + 1;
std::shared_ptr<MyUploadDelegate> myUploadDelegate =
std::make_shared<MyUploadDelegate>();
object.uploadStream(qualFile2Name, nextStreamId, myUploadDelegate);
// Use of the bool type conversion operator to detect success or failure
// as above
if (!myUploadDelegate->waitForRsp()) {
// Failure, bail out
~~~
}
object.getStreams(getStreamsDelegate);
auto streamsOpt2 = getStreamsDelegate->waitForRsp();
if (!streamsOpt2) {
// Failure, bail out
~~~
}
const auto streams2 = std::move(*streamsOpt2);
~~~
A data file attached to Object.
Definition: Stream.h:24
cbe::StreamId streamId
Definition: Stream.h:30
Definition: UploadDelegate.h:28
Continues at: Async downloading the data attached to a cbe::Object via a Stream with Object::downloadStream()

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