DittoPendingCollectionsOperation

public class DittoPendingCollectionsOperation

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

They allow chaining of further collections-related functions. You can either call exec on the object to get an array of DittoCollections 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 observeLocal, 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.

Typically, an app would set up a subscribe in some part of the application which is long-lived to ensure the device receives updates from the mesh. These updates will be automatically received and written into the local store. Elsewhere, where you need to use this data, an observeLocal can be used to notify you of the data, and all subsequent changes to the data.

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

  • Limit the number of collections that get returned.

    Declaration

    Swift

    public func limit(_ limit: Int32) -> Self

    Parameters

    limit

    The maximum number of collections that will be returned.

    Return Value

    A DittoPendingCollectionsOperation that you can chain further function calls to.

  • Sort the collections based on a property of the collection.

    Declaration

    Swift

    public func sort(_ query: String, direction: DittoSortDirection) -> Self

    Parameters

    query

    The query specifies the logic to be used when sorting the collections.
    direction

    Specify whether you want the sorting order to be ascending or descending.

    Return Value

    A DittoPendingCollectionsOperation that you can chain further function calls to.

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

    Declaration

    Swift

    public func offset(_ offset: UInt32) -> Self

    Parameters

    offset

    The number of collections that you want the eventual resulting set of collections to be offset by (and thus not include).

    Return Value

    A DittoPendingCollectionsOperation that you can chain further function calls to.

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

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

    Declaration

    Swift

    public func subscribe() -> DittoSubscription

    Return Value

    A DittoSubscription 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.

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

    Declaration

    Swift

    public func exec() -> [DittoCollection]

    Return Value

    A list of DittoCollectionss based on the preceding function chaining.

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

    This won’t subscribe to receive updates from other devices and so it will only fires when a local change to the known about collections occurs. If you want to receive remote updates as well then also call subscribe.

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

    Declaration

    Swift

    public func observeLocal(
    deliverOn queue: DispatchQueue = .main,
    eventHandler: @escaping (DittoCollectionsEvent) -> Void
) -> DittoLiveQuery

    Parameters

    queue

    The DispatchQueue that will be used to deliver live query updates. Defaults to DispatchQueue.main.
    eventHandler

    A closure that will be called every time there is an update about the list of known about collections.

    Return Value

    A DittoLiveQuery object that must be kept in scope for as long as you want to keep receiving updates.

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

    This won’t subscribe to receive updates from other devices and so it will only fires when a local change to the known about collections occurs. If you want to receive remote updates as well then also call subscribe.

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

    Declaration

    Swift

    public func observeLocalWithNextSignal(
    deliverOn queue: DispatchQueue = .main,
    eventHandler: @escaping (DittoCollectionsEvent, @escaping DittoSignalNext) -> Void
) -> DittoLiveQuery

    Parameters

    queue

    The DispatchQueue that will be used to deliver live query updates. Defaults to DispatchQueue.main.
    eventHandler

    A closure that will be called every time there is an update about the list of known about collections.

    Return Value

    A DittoLiveQuery object that must be kept in scope for as long as you want to keep receiving updates.