Ditto  1.0.19
Public Member Functions | List of all members
ditto::PendingCollectionsOperation Class Reference

These objects are returned when calling collections() on Store objects. More...

Public Member Functions

PendingCollectionsOperationlimit (uint32_t limit)
 Limit the number of collections that get returned. More...
 
PendingCollectionsOperationoffset (uint32_t offset)
 Offset the resulting set of collections. More...
 
PendingCollectionsOperationsort (std::string query, SortDirection direction)
 Sort the collections based on a property of the collection. More...
 
std::vector< Collectionexec ()
 Return the list of collections requested based on the preceding function chaining. More...
 
Subscription subscribe ()
 Subscribes the device to updates about collections that other devices know about. More...
 
std::shared_ptr< LiveQueryobserve (CollectionsEventHandler handler)
 Enables you to listen for changes that occur in relation to the collections that are known about. A block gets called when an update is received either locally or remotely. More...
 
std::shared_ptr< LiveQueryobserve_local (CollectionsEventHandler handler)
 Enables you to listen for changes that occur in relation to the collections that are known about locally. More...
 
std::shared_ptr< LiveQueryobserve_with_next_signal (CollectionsEventWithNextSignalHandler handler)
 Enables you to listen for changes that occur in relation to the collections that are known about. A block gets called when an update is received either locally or remotely. You can signal when you are ready for the next event to be delivered. More...
 
std::shared_ptr< LiveQueryobserve_local_with_next_signal (CollectionsEventWithNextSignalHandler handler)
 Enables you to listen for changes that occur in relation to the collections that are known about locally. You can signal when you are ready for the next event to be delivered. More...
 

Detailed Description

These objects are returned when calling collections() on Store objects.

They allow chaining of further collections-related functions. You can either call exec on the object to get an array of Collections as an immediate return value, or you can establish either a live query or a subscription, which both work over time.

A live query, established by calling observe, will notify you every time there's a change in the collections that the device knows about.

A subscription, established by calling subscribe, will act as a signal to other peers that the device connects to that you would like to receive updates from them about the collections that they know about.

Calling observe will generate both a subscription and a live query at the same time.

If you'd like to only observe local changes then you can call observe_local.

If you want to observe changes in such a way that you can signal when you're ready for the live query to deliver a new update then you can call observe_with_next_signal or observe_local_with_next_signal.

Member Function Documentation

◆ exec()

std::vector< Collection > ditto::PendingCollectionsOperation::exec ( )

Return the list of collections requested based on the preceding function chaining.

Returns
a list of Collections based on the preceding function chaining.

◆ limit()

PendingCollectionsOperation & ditto::PendingCollectionsOperation::limit ( uint32_t  limit)

Limit the number of collections that get returned.

Parameters
[in]limitthe maximum number of collections that will be returned.
Returns
a `PendingCollectionsOperation that you can chain further function calls to.

◆ observe()

std::shared_ptr< LiveQuery > ditto::PendingCollectionsOperation::observe ( CollectionsEventHandler  handler)

Enables you to listen for changes that occur in relation to the collections that are known about. A block gets called when an update is received either locally or remotely.

The returned LiveQuery object must be kept in scope for as long as you want the provided handler to be called when an update occurs.

Parameters
[in]handlera lambda that will be called every time there is an update about the list of known about collections.
Returns
a LiveQuery object that must be kept in scope for as long as you want to keep receiving updates.

◆ observe_local()

std::shared_ptr< LiveQuery > ditto::PendingCollectionsOperation::observe_local ( CollectionsEventHandler  handler)

Enables you to listen for changes that occur in relation to the collections that are known about locally.

The returned LiveQuery object must be kept in scope for as long as you want the provided handler to be called when an update occurs.

Parameters
[in]handlera lambda that will be called every time there is an update about the list of known about collections.
Returns
a LiveQuery object that must be kept in scope for as long as you want to keep receiving updates.

◆ observe_local_with_next_signal()

std::shared_ptr< LiveQuery > ditto::PendingCollectionsOperation::observe_local_with_next_signal ( CollectionsEventWithNextSignalHandler  handler)

Enables you to listen for changes that occur in relation to the collections that are known about locally. You can signal when you are ready for the next event to be delivered.

The returned LiveQuery object must be kept in scope for as long as you want the provided handler to be called when an update occurs.

Parameters
[in]handlera lambda that will be called every time there is an update about the list of known about collections.
Returns
a LiveQuery object that must be kept in scope for as long as you want to keep receiving updates.

◆ observe_with_next_signal()

std::shared_ptr< LiveQuery > ditto::PendingCollectionsOperation::observe_with_next_signal ( CollectionsEventWithNextSignalHandler  handler)

Enables you to listen for changes that occur in relation to the collections that are known about. A block gets called when an update is received either locally or remotely. You can signal when you are ready for the next event to be delivered.

The returned LiveQuery object must be kept in scope for as long as you want the provided handler to be called when an update occurs.

Parameters
[in]handlera lambda that will be called every time there is an update about the list of known about collections.
Returns
a LiveQuery object that must be kept in scope for as long as you want to keep receiving updates.

◆ offset()

PendingCollectionsOperation & ditto::PendingCollectionsOperation::offset ( uint32_t  offset)

Offset the resulting set of collections.

This is useful if you aren't interested in the first N collections for one reason or another. For example, you might already have obtained the first 20 collections and so you might want to get the next 20 collections, and that is when you would use offset.

Parameters
[in]offsetthe number of collections that you want the eventual resulting set of collections to be offset by (and thus not include).
Returns
a PendingCollectionsOperation that you can chain further function calls to.

◆ sort()

PendingCollectionsOperation & ditto::PendingCollectionsOperation::sort ( std::string  query,
SortDirection  direction 
)

Sort the collections based on a property of the collection.

Parameters
[in]querythe query specifies the logic to be used when sorting the collections.
[in]directionspecify whether you want the sorting order to be ascending or descending.
Returns
a PendingCollectionsOperation that you can chain further function calls to.

◆ subscribe()

Subscription ditto::PendingCollectionsOperation::subscribe ( )

Subscribes the device to updates about collections that other devices know about.

The returned Subscription object must be kept in scope for as long as you want to keep receiving updates.

Returns
a Subscription object that must be kept in scope for as long as you want to keep receiving updates from other devices about the collections that they know about.