ZDCCloudTransaction

@interface ZDCCloudTransaction

ZDCCloud is a YapDatabase extension.

It manages the storage of the upload queue. This allows your application to work offline. Any changes that need to be pushed to the cloud will get stored in the database using a lightweight operation object that encodes the minimum information necessary to execute the operation at a later time.

It extends YapDatabaseCloudCore, which we also developed, and contributed to the open source community.

  • Returns the node with the given nodeID.

    Note

    You can find many other utility functions for inspecting the node treesystem in the ZDCNodeManager.

    Declaration

    Objective-C

    - (nullable ZDCNode *)nodeWithID:(nonnull NSString *)nodeID;

    Swift

    func node(id nodeID: String) -> ZDCNode?

    Parameters

    nodeID

    The identifier of the node. (nodeID == ZDCNode.uuid)

    Return Value

    Returns the matching node, if it exists. Nil otherwise.

  • Returns the existing node with the given path.

    Note

    You can find many other utility functions for inspecting the node treesystem in the ZDCNodeManager.

    Declaration

    Objective-C

    - (nullable ZDCNode *)nodeWithPath:(nonnull ZDCTreesystemPath *)path;

    Swift

    func node(path: ZDCTreesystemPath) -> ZDCNode?

    Parameters

    path

    The treesystem path of the node.

    Return Value

    Returns the matching node, if it exists. Nil otherwise.

  • Returns the parentNode for the given node.

    Declaration

    Objective-C

    - (nullable ZDCNode *)parentNode:(nonnull ZDCNode *)node;

    Swift

    func parentNode(_ node: ZDCNode) -> ZDCNode?
  • If the given node is a pointer (node.isPointer == true), then this method follows the pointer (recursively, if needed) until the target node is found.

    If the given node is not a pointer (node.isPointer == false), it simply returns the given node.

    Only returns nil if:

    • node is a pointer
    • node’s target doesn’t currently exist

    This method is short-hand for [ZDCNodeManager targetNodeForNode:transaction:]

    Declaration

    Objective-C

    - (nullable ZDCNode *)targetNode:(nonnull ZDCNode *)node;

    Swift

    func targetNode(_ node: ZDCNode) -> ZDCNode?
  • Returns the corresponding trunk node (top-level root node).

    This method is short-hand for [ZDCNodeManager trunkNodeForLocalUserID:treeID:trunk:transaction:]

    Declaration

    Objective-C

    - (nullable ZDCTrunkNode *)trunkNode:(ZDCTreesystemTrunk)trunk;

    Swift

    func trunkNode(_ trunk: ZDCTreesystemTrunk) -> ZDCTrunkNode?
  • Checks to see if there’s already a node occupying the given path. If so, this method will resolve the conflict by appending a number to the end of the nodeName until it’s unique. For example, if the given nodeNode is Foobar.ext, this method may return Foobar 2.ext.

    Declaration

    Objective-C

    - (nonnull ZDCTreesystemPath *)conflictFreePath:
        (nonnull ZDCTreesystemPath *)path;

    Swift

    func conflictFreePath(_ path: ZDCTreesystemPath) -> ZDCTreesystemPath
  • Creates a new node with the given path, and queues upload operation(s) to push the node to the cloud.

    Declaration

    Objective-C

    - (nullable ZDCNode *)createNodeWithPath:(nonnull ZDCTreesystemPath *)path
                                       error:
                                           (NSError *_Nullable *_Nullable)outError;

    Swift

    func createNode(withPath path: ZDCTreesystemPath) throws -> ZDCNode

    Parameters

    path

    The treesystem path of the node.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    The newly created node.

  • Creates a new node with the given path, and queues upload operation(s) to push the node to the cloud.

    Declaration

    Objective-C

    - (nullable ZDCNode *)
        createNodeWithPath:(nonnull ZDCTreesystemPath *)path
              dependencies:(nullable NSArray<ZDCCloudOperation *> *)dependencies
                     error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func createNode(withPath path: ZDCTreesystemPath, dependencies: [ZDCCloudOperation]?) throws -> ZDCNode

    Parameters

    path

    The treesystem path of the node.

    dependencies

    If the upload operation should be dependent upon other operations, you may pass those dependencies here.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    The newly created node.

  • Inserts the given node into the treesystem (as configured), and queues upload operation(s) to push the node to the cloud.

    Declaration

    Objective-C

    - (BOOL)insertNode:(nonnull ZDCNode *)node
                 error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func insertNode(_ node: ZDCNode) throws

    Parameters

    node

    The node to insert into the treesystem.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    True on succeess. False otherwise.

  • Use this method to modify an existing node. For example, you can use it to:

    • rename a node (i.e. you change node.name value)
    • move a node (i.e. you change node.parentID value)
    • change permissions (i.e. you modify node.shareList entries)

    If you didn’t change the node metadata, but rather the node data (i.e. the data generated by your app), then you should instead use the queueDataUploadForNodeID:: method.

    Declaration

    Objective-C

    - (nullable ZDCCloudOperation *)modifyNode:(nonnull ZDCNode *)node
                                         error:(NSError *_Nullable *_Nullable)
                                                   outError;

    Swift

    func modifyNode(_ node: ZDCNode) throws -> ZDCCloudOperation

    Parameters

    node

    The node you want to modify.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    If the request was successful, returns the queued operation. Otherwise returns nil, in which case, outError will be set.

  • Moves the given node to a new location, and queues an operation to push the change to the cloud.

    On success, this method will change the following properties of the node:

    • parentID
    • name
    • shareList (to match new parent)

    Declaration

    Objective-C

    - (nullable ZDCNode *)moveNode:(nonnull ZDCNode *)node
                            toPath:(nonnull ZDCTreesystemPath *)path
                             error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func move(_ node: ZDCNode, to path: ZDCTreesystemPath) throws -> ZDCNode

    Parameters

    node

    The node you want to modify.

    path

    The treesystem path of the new location.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    If the request was successful, returns the modified node. Otherwise returns nil, in which case, outError will be set.

  • Use this method to queue a data upload operation for the given node.

    That is, you’ve modified the underlying data for a node. Now you want the changed data (generated by your app) to be pushed to the cloud. However, the node metadata hasn’t changed (name, permissions, etc), so there’s no need to use the modifyNode:: method.

    Invoking this method will create an return an operation to push the changes to the cloud.

    Declaration

    Objective-C

    - (nullable ZDCCloudOperation *)
        queueDataUploadForNodeID:(nonnull NSString *)nodeID
                   withChangeset:(nullable NSDictionary *)changeset;

    Swift

    func queueDataUpload(forNodeID nodeID: String, withChangeset changeset: [AnyHashable : Any]?) -> ZDCCloudOperation?

    Parameters

    nodeID

    The node for which the data has changed. (nodeID == ZDCNode.uuid)

    changeset

    An optional changeset to store within the operation.

    Return Value

    If the request was successful, returns the queued operation. Otherwise returns nil, in which case, outError will be set.

  • Removes the given node from the treesystem, and enqueues a delete operation to delete it from the cloud.

    Declaration

    Objective-C

    - (nullable ZDCCloudOperation *)deleteNode:(nonnull ZDCNode *)node
                                         error:(NSError *_Nullable *_Nullable)
                                                   outError;

    Swift

    func delete(_ node: ZDCNode) throws -> ZDCCloudOperation

    Parameters

    node

    The node you want to delete.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    If the request was successful, returns the queued operation. Otherwise returns nil, in which case, outError will be set.

  • Removes the given node from the treesystem, and enqueues a delete operation to delete it from the cloud.

    Declaration

    Objective-C

    - (nullable ZDCCloudOperation *)deleteNode:(nonnull ZDCNode *)node
                                   withOptions:(ZDCDeleteNodeOptions)options
                                         error:(NSError *_Nullable *_Nullable)
                                                   outError;

    Swift

    func delete(_ node: ZDCNode, with options: ZDCDeleteNodeOptions = []) throws -> ZDCCloudOperation

    Parameters

    node

    The node which you wish to delete.

    options

    A bitmask that specifies the options to use when deleting the node.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    If the request was successful, returns the queued operation. Otherwise returns nil, in which case, outError will be set.

  • Enqueues a message to be sent to the specified recipients.

    Messages are first uploaded into the sender’s outbox, and then copied server-side into the recipient’s inbox.

    You supply the data for the message via [ZeroDarkCloudDelegate dataForMessage:transaction:]. And you’ll be informed of the message deliveries via [ZeroDarkCloudDelegate didSendMessage:transaction:]

    For more information about messaging, see the docs: https://zerodarkcloud.readthedocs.io/en/latest/client/messaging/

    Declaration

    Objective-C

    - (nullable ZDCNode *)
        sendMessageToRecipients:(nonnull NSArray<ZDCUser *> *)recipients
                          error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func sendMessage(toRecipients recipients: [ZDCUser]) throws -> ZDCNode

    Parameters

    recipients

    A list of recipients that should receive the message.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    Returns the message node on success, nil otherwise.

  • Enqueues a message to be sent to the specified recipients.

    Messages are first uploaded into the sender’s outbox, and then copied server-side into the recipient’s inbox.

    You supply the data for the message via [ZeroDarkCloudDelegate dataForMessage:transaction:]. And you’ll be informed of the message deliveries via [ZeroDarkCloudDelegate didSendMessage:transaction:]

    For more information about messaging, see the docs: https://zerodarkcloud.readthedocs.io/en/latest/client/messaging/

    In a collaboration scenario, your message may be dependent upon permissions changes. For example, if Alice wants to share a branch of her treesystem with Bob, this is typically a 2-step process. First Alice must give Bob read-write permission to the branch. And then Alice can send Bob an invitation to collaborate on that branch. This is typically achieved by first using the method recursiveAddShareItem:forUserID:nodeID. This method returns an array of ZDCCloudOperations. So then you’d just pass that array of operations to this method as dependencies. This ensures that the treesystem permissions are modified before the message is sent.

    Declaration

    Objective-C

    - (nullable ZDCNode *)
        sendMessageToRecipients:(nonnull NSArray<ZDCUser *> *)recipients
               withDependencies:
                   (nullable NSArray<ZDCCloudOperation *> *)dependencies
                          error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func sendMessage(toRecipients recipients: [ZDCUser], withDependencies dependencies: [ZDCCloudOperation]?) throws -> ZDCNode

    Parameters

    recipients

    A list of recipients that should receive the message.

    dependencies

    If the message operation should be dependent upon other operations, you may pass those dependencies here.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    Returns the message node on success, nil otherwise.

  • Enqueues a signal to be sent to the specified recipient.

    A signal is a lightweight outgoing message. (They’re different from normal messaages.)

    Signals are delivered into the inbox of the recipient ONLY. There is NOT a copy of the message within the outbox of the sender. In other words, signals are designed to be minimal, and don’t cause additional overhead for the sender.

    You supply the data for the message via [ZeroDarkCloudDelegate dataForMessage:transaction:]. And you’ll be informed of the message deliveries via [ZeroDarkCloudDelegate didSendMessage:transaction:]

    For more information about messaging, see the docs: https://zerodarkcloud.readthedocs.io/en/latest/client/messaging/

    Declaration

    Objective-C

    - (nullable ZDCNode *)sendSignalToRecipient:(nonnull ZDCUser *)recipient
                                          error:(NSError *_Nullable *_Nullable)
                                                    outError;

    Swift

    func sendSignal(toRecipient recipient: ZDCUser) throws -> ZDCNode

    Parameters

    recipient

    The user to send the message to.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    Returns a signal node on success, nil otherwise.

  • Enqueues a signal to be sent to the specified recipient.

    A signal is a lightweight outgoing message. (They’re different from normal messaages.)

    Signals are delivered into the inbox of the recipient ONLY. There is NOT a copy of the message within the outbox of the sender. In other words, signals are designed to be minimal, and don’t cause additional overhead for the sender.

    You supply the data for the message via [ZeroDarkCloudDelegate dataForMessage:transaction:]. And you’ll be informed of the message deliveries via [ZeroDarkCloudDelegate didSendMessage:transaction:]

    For more information about messaging, see the docs: https://zerodarkcloud.readthedocs.io/en/latest/client/messaging/

    Declaration

    Objective-C

    - (nullable ZDCNode *)
        sendSignalToRecipient:(nonnull ZDCUser *)recipient
             withDependencies:(nullable NSArray<ZDCCloudOperation *> *)dependencies
                        error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func sendSignal(toRecipient recipient: ZDCUser, withDependencies dependencies: [ZDCCloudOperation]?) throws -> ZDCNode

    Parameters

    recipient

    The user to send the message to.

    dependencies

    If the signal operation should be dependent upon other operations, you may pass those dependencies here.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    Returns a signal node on success, nil otherwise.

  • Queues an operation to perform a server-side-copy, from the given node, to the recipient’s inbox.

    The given node must be part of the localUser’s treesystem.

    On success, a temporary node is returned. The temporary node isn’t part of the treesystem, but it is stored in the database. This node will be automatically deleted after the operation has been completed.

    Declaration

    Objective-C

    - (nullable ZDCNode *)copyNode:(nonnull ZDCNode *)node
                  toRecipientInbox:(nonnull ZDCUser *)recipient
                             error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func copy(_ node: ZDCNode, toRecipientInbox recipient: ZDCUser) throws -> ZDCNode

    Parameters

    node

    The node to copy.

    recipient

    The user to send the message to.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    Returns a temporary node on success, nil otherwise.

  • Queues an operation to perform a server-side-copy, from the given node, to the recipient’s inbox.

    The given node must be part of the localUser’s treesystem.

    On success, a temporary node is returned. The temporary node isn’t part of the treesystem, but it is stored in the database. This node will be automatically deleted after the operation has been completed.

    Note

    You can also add dependencies via the -modifyOperation: method, available via the superclass (YapDatabaseCloudCoreTransaction).

    Declaration

    Objective-C

    - (nullable ZDCNode *)copyNode:(nonnull ZDCNode *)node
                  toRecipientInbox:(nonnull ZDCUser *)recipient
                  withDependencies:
                      (nullable NSArray<ZDCCloudOperation *> *)dependencies
                             error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func copy(_ node: ZDCNode, toRecipientInbox recipient: ZDCUser, withDependencies dependencies: [ZDCCloudOperation]?) throws -> ZDCNode

    Parameters

    node

    The node to copy.

    recipient

    The user to send the message to.

    dependencies

    If the message operation should be dependent upon other operations, you may pass those dependencies here.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    Returns a temporary node on success, nil otherwise.

  • Queues an operation to perform a server-side-copy, from the given node, to the recipient’s treesystem.

    The given node must be part of the localUser’s treesystem.

    On success, a temporary node is returned. The temporary node isn’t part of the treesystem, but it is stored in the database. This node will be automatically deleted after the operation has been completed.

    Declaration

    Objective-C

    - (nullable ZDCNode *)copyNode:(nonnull ZDCNode *)node
                       toRecipient:(nonnull ZDCUser *)recipient
                          withName:(nonnull NSString *)nodeName
                        parentNode:(nonnull ZDCNode *)parentNode
                             error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func copy(_ node: ZDCNode, toRecipient recipient: ZDCUser, withName nodeName: String, parentNode: ZDCNode) throws -> ZDCNode

    Parameters

    node

    The node to copy.

    recipient

    The user to send the message to.

    nodeName

    The name of the destination node.

    parentNode

    The parent of the destination node.

    Return Value

    Returns a temporary node on success, nil otherwise.

  • Queues an operation to perform a server-side-copy, from the given node, to the recipient’s treesystem.

    The given node must be part of the localUser’s treesystem.

    On success, a temporary node is returned. The temporary node isn’t part of the treesystem, but it is stored in the database. This node will be automatically deleted after the operation has been completed.

    Declaration

    Objective-C

    - (nullable ZDCNode *)copyNode:(nonnull ZDCNode *)node
                       toRecipient:(nonnull ZDCUser *)recipient
                   remoteCloudPath:(nonnull ZDCCloudPath *)remoteCloudPath
                             error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func copy(_ node: ZDCNode, toRecipient recipient: ZDCUser, remoteCloudPath: ZDCCloudPath) throws -> ZDCNode

    Parameters

    node

    The node to copy.

    recipient

    The user to send the message to.

    remoteCloudPath

    The destination location to copy the node to. Typically this information is derived from a dropbox invite.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    Returns a temporary node on success, nil otherwise.

  • A dropbox invite encompasses the information required for another user to write into your treesystem.

    Imagine that Alice has a node in her treesystem at: /foo/bar/filesFromFriends

    She wants to setup the node as a dropbox for Bob: That is:

    • Bob should be allowed to write files into this directory
    • But Bob doesn’t have permission to read the files in this directory
    • And Bob doesn’t have permission to delete files from this directory

    Alice can accomplish this by:

    • giving Bob write permission on the node
    • sending Bob a dropbox invite for the node

    What’s nice about this system is that Bob doesn’t see the parentNode. That is, Bob cannot discover the location of /foo/bar/filesFromFriends. So he wouldn’t be able to determine, for example, who else Alice has given Dropbox permission to.

    Further, since Bob doesn’t have read permission, he won’t be able to see the other children of the node. So he also won’t be able to determine which other friends have sent Alice files.

    Declaration

    Objective-C

    - (nullable ZDCDropboxInvite *)dropboxInviteForNode:(nonnull ZDCNode *)node;

    Swift

    func dropboxInvite(for node: ZDCNode) -> ZDCDropboxInvite?
  • Grafting allows you to add another user’s branch into your own treesystem. It’s used for collaboration, as the branch is now shared between multiple users.

    More information about grafting can be found in the docs: https://zerodarkcloud.readthedocs.io/en/latest/client/collaboration/

    Declaration

    Objective-C

    - (nullable ZDCGraftInvite *)graftInviteForNode:(nonnull ZDCNode *)node;

    Swift

    func graftInvite(for node: ZDCNode) -> ZDCGraftInvite?
  • Grafting allows you to add another user’s branch into your own treesystem. It’s used for collaboration, as the branch is now shared between multiple users.

    See

    graftInviteForNode:

    Declaration

    Objective-C

    - (nullable ZDCNode *)
        graftNodeWithLocalPath:(nonnull ZDCTreesystemPath *)path
               remoteCloudPath:(nonnull ZDCCloudPath *)remoteCloudPath
                 remoteCloudID:(nonnull NSString *)remoteCloudID
                    remoteUser:(nonnull ZDCUser *)remoteUser
                         error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func graftNode(withLocalPath path: ZDCTreesystemPath, remoteCloudPath: ZDCCloudPath, remoteCloudID: String, remoteUser: ZDCUser) throws -> ZDCNode

    Parameters

    path

    The local path for the pointer node. It will point to the node in the other user’s treesystem.

    remoteCloudPath

    The location of the node in the other user’s treesystem. Typically this information is delivered to you via a message/signal. And the remote user typically gets this information via the graftInviteForNode: method.

    remoteCloudID

    The cloudID of the node in the other user’s treesystem. This parameter allows the system to find the corresponding node, even if the node gets moved/renamed.

    remoteUser

    The owner of the foreign treesystem.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    If the request was successful, returns the newly created node. Otherwise returns nil, in which case, outError will be set.

  • Modifies the permissons for a treesystem branch rooted at the specified node.

    This method adds the given shareItem to the specified node, and all of the node’s children, grand-children, etc (recursively).

    This is a convenience method for modifying a branch of the treesystem. You can accomplish the same thing manually by:

    • using the NodeManager to recursively enumerate the node
    • modifying each node.shareList
    • invoking cloudTransaction.modifyNode to save the changes, and queue the upload

    Declaration

    Objective-C

    - (nonnull NSArray<ZDCCloudOperation *> *)
        recursiveAddShareItem:(nonnull ZDCShareItem *)shareItem
                    forUserID:(nonnull NSString *)userID
                       nodeID:(nonnull NSString *)nodeID;

    Swift

    func recursiveAddShareItem(_ shareItem: ZDCShareItem, forUserID userID: String, nodeID: String) -> [ZDCCloudOperation]
  • Modifies the permissons for a treesystem branch rooted at the specified node.

    This method removes the permissions for the user from the specified node, and all of the node’s children, grand-children, etc (recursively).

    This is a convenience method for modifying a branch of the treesystem. You can accomplish the same thing manually by:

    • using the NodeManager to recursively enumerate the node
    • modifying each node.shareList
    • invoking cloudTransaction.modifyNode to save the changes, and queue the upload

    Declaration

    Objective-C

    - (nonnull NSArray<ZDCCloudOperation *> *)
        recursiveRemoveShareItemForUserID:(nonnull NSString *)userID
                                   nodeID:(nonnull NSString *)nodeID;

    Swift

    func recursiveRemoveShareItem(forUserID userID: String, nodeID: String) -> [ZDCCloudOperation]
  • Call this method to link an object in the database to an existing node.

    Linking allows you to create a one-to-one mapping between a node, and one of your own database objects.

    Note

    If you need one-to-many mappings, you can instead use the tagging feature. See setTag:forNodeID:withIdentifier: for more information.

    The node must already exist in the database. (If you just created the node, use createNode:error: to add it to the database first.)

    You can link a {collection, key} tuple that doesn’t yet exist in the database. However, you must add the corresponding object to the database before the transaction completes, or the linkage will be dropped.

    Declaration

    Objective-C

    - (BOOL)linkNodeID:(nonnull NSString *)nodeID
                 toKey:(nonnull NSString *)key
          inCollection:(nullable NSString *)collection
                 error:(NSError *_Nullable *_Nullable)outError;

    Swift

    func linkNodeID(_ nodeID: String, toKey key: String, inCollection collection: String?) throws

    Parameters

    nodeID

    The node that you’d like to link. (nodeID == ZDCNode.uuid)

    key

    The key component of the {collection, key} tuple of your own object that you wish to link to the node.

    collection

    The collection component of the {collection, key} tuple of your own object that you wish to link to the node.

    outError

    Set to nil on success. Otherwise returns an error that explains what went wrong.

    Return Value

    Returns YES if successful, NO otherwise (and sets outError parameter if given).

  • If an object in the database has been linked to a node, then deleting that object from the database implicitly creates an operation to delete the node from the cloud.

    However, this may not always be the desired outcome. Sometimes a device wishes to delete an object simply because it’s no longer needed locally. For example, if the object was cached, and the system is clearing unneeded items from the cache. In this case, simply unlink the node manually, and pass shouldUpload as NO. This effectively removes the link without modifying the cloud.

    Alternatively, you may wish to delete a node from the cloud, but keep the local copy. In this case, just use deleteNode:shouldUpload:operations:,

    Declaration

    Objective-C

    - (nullable NSString *)unlinkKey:(nonnull NSString *)key
                        inCollection:(nullable NSString *)collection;

    Swift

    func unlinkKey(_ key: String, inCollection collection: String?) -> String?

    Parameters

    key

    The key component of the {collection, key} tuple of your own object that you wish to link to the node.

    collection

    The collection component of the {collection, key} tuple of your own object that you wish to link to the node.

    Return Value

    If the collection/key tuple was linked to a node, returns the nodeID (after unlinking).

  • If the given collection/key tuple is linked to a node, this method returns the linked nodeID. (nodeID == ZDCNode.uuid)

    Declaration

    Objective-C

    - (nullable NSString *)linkedNodeIDForKey:(nonnull NSString *)key
                                 inCollection:(nullable NSString *)collection;

    Swift

    func linkedNodeID(forKey key: String, inCollection collection: String?) -> String?
  • If the given collection/key tuple is linked to a node, this method returns the linked node.

    This is the same as linkedNodeIDForKey:inCollection:, but it also fetches the corresponding ZDCNode from the database for you.

    Declaration

    Objective-C

    - (nullable ZDCNode *)linkedNodeForKey:(nonnull NSString *)key
                              inCollection:(nullable NSString *)collection;

    Swift

    func linkedNode(forKey key: String, inCollection collection: String?) -> ZDCNode?
  • Returns whether or not the node is currently linked to a {collection, key} tuple.

    Declaration

    Objective-C

    - (BOOL)isNodeLinked:(nonnull NSString *)nodeID;

    Swift

    func isNodeLinked(_ nodeID: String) -> Bool

    Parameters

    nodeID

    The node for which to look for a link. (nodeID == ZDCNode.uuid)

  • If the given node is linked to a collection/key tuple, this method returns the linked tuple information.

    Declaration

    Objective-C

    - (BOOL)getLinkedKey:(NSString *_Nullable *_Nullable)key
              collection:(NSString *_Nullable *_Nullable)collection
               forNodeID:(nonnull NSString *)nodeID;

    Swift

    func __getLinkedKey(_ key: AutoreleasingUnsafeMutablePointer<NSString?>?, collection: AutoreleasingUnsafeMutablePointer<NSString?>?, forNodeID nodeID: String) -> Bool

    Parameters

    key

    Returns the key component of the collection/key tuple (if found).

    collection

    Returns the collection component of the collection/key tuple (if found).

    nodeID

    The node for which to look for a link. (nodeID == ZDCNode.uuid)

    Return Value

    YES if the node is linked to an item in the database. No otherwise.

  • Combines several API’s to return the linked object for a given nodeID.

    In particular, this method invokes getLinkedKey:collection:forNodeID: first. And if that method returns a {collection, key} tuple, then the corresponding object is fetched from the database.

    Declaration

    Objective-C

    - (nullable id)linkedObjectForNodeID:(nonnull NSString *)nodeID;

    Swift

    func linkedObject(forNodeID nodeID: String) -> Any?

    Parameters

    nodeID

    The node for which to look for a link. (nodeID == ZDCNode.uuid)

    Return Value

    If the node is linked to a {collection, key} tuple, then returns the result of querying the database for the object with the matching tuple. Otherwise returns nil.

  • Combines several methods to return the linked object for a given treesystem path.

    In particular, this method invokes -[ZDCNodeManager findNodeWithPath:localUserID:treeID:transaction:] first. And if that method returns a node, then the linkedObjectForNodeID: method is utilized.

    Declaration

    Objective-C

    - (nullable id)linkedObjectForPath:(nonnull ZDCTreesystemPath *)path;

    Swift

    func linkedObject(for path: ZDCTreesystemPath) -> Any?

    Parameters

    path

    The treesystem path of the node.

    Return Value

    If the corresponding node is linked to a {collection, key} tuple, then returns the result of querying the database for the object with the matching tuple. Otherwise returns nil.

  • Returns the currently set tag for the given {nodeID, identifier} tuple.

    @return The most recently assigned tag.

    Declaration

    Objective-C

    - (nullable id)tagForNodeID:(nonnull NSString *)nodeID
                 withIdentifier:(nonnull NSString *)identifier;

    Swift

    func tag(forNodeID nodeID: String, withIdentifier identifier: String) -> Any?

    Parameters

    nodeID

    The associated node. (nodeID == ZDCNode.uuid)

    identifier

    A unique identifier for the type of tag being stored.

  • Allows you to set or update the current tag value for the given {nodeID, identifier} tuple.

    If the given tag is nil, the effect is the same as invoking removeTagForKey:withIdentifier:. If the given tag is an unsupported class, throws an exception.

    Declaration

    Objective-C

    - (void)setTag:(nullable id)tag
             forNodeID:(nonnull NSString *)nodeID
        withIdentifier:(nonnull NSString *)identifier;

    Swift

    func setTag(_ tag: Any?, forNodeID nodeID: String, withIdentifier identifier: String)

    Parameters

    tag

    The tag to store. The following classes are supported:

    • NSString
    • NSNumber
    • NSData
    nodeID

    The associated node. (nodeID == ZDCNode.uuid)

    identifier

    A unique identifier for the type of tag being stored.

  • Allows you to enumerate the current set of tuples associated with the given node.

    Declaration

    Objective-C

    - (void)enumerateTagsForNodeID:(nonnull NSString *)nodeID
                         withBlock:(nonnull void (^)(NSString *_Nonnull,
                                                     id _Nonnull,
                                                     BOOL *_Nonnull))block;

    Swift

    func enumerateTags(forNodeID nodeID: String, with block: (String, Any, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    nodeID

    The associated node. (nodeID == ZDCNode.uuid)

  • Removes the tag for the given {nodeID, key} tuple.

    Note that this method only removes the specific nodeID+key value. If there are other tags for the same node, but different keys, then those values will remain set. To remove all such values, use removeAllTagsForNode.

    See

    removeAllTagsForNodeID:

    Declaration

    Objective-C

    - (void)removeTagForNodeID:(nonnull NSString *)nodeID
                withIdentifier:(nonnull NSString *)identifier;

    Swift

    func removeTag(forNodeID nodeID: String, withIdentifier identifier: String)

    Parameters

    nodeID

    The associated node. (nodeID == ZDCNode.uuid)

    identifier

    A unique identifier for the type of tag being stored.

  • Removes all tags with the given nodeID (matching any identifier).

    Declaration

    Objective-C

    - (void)removeAllTagsForNodeID:(nonnull NSString *)nodeID;

    Swift

    func removeAllTags(forNodeID nodeID: String)
  • When the ZeroDarkCloudDelegate is informed of a new/modified node, it may need to download the node’s data. However, the download may or may not succeed. And if the download fails, then the delegate will likely want to retry the download later (i.e. when Internet connectivity is restored).

    This means the delegate will need to keep track of which nodes need to be downloaded. This method is designed to assist in keeping track of that list.

    Declaration

    Objective-C

    - (void)markNodeAsNeedsDownload:(nonnull NSString *)nodeID
                         components:(ZDCNodeComponents)components;

    Swift

    func markNodeAsNeedsDownload(_ nodeID: String, components: ZDCNodeComponents)

    Parameters

    nodeID

    The node needing to be downloaded. (nodeID == ZDCNode.uuid)

    components

    Typically you pass ZDCNodeComponents_All to specify that all components of a node are out-of-date. However, you can customize this in advanced situations.

  • After a download succeeds, invoke this method to remove the flag.

    Declaration

    Objective-C

    - (void)unmarkNodeAsNeedsDownload:(nonnull NSString *)nodeID
                           components:(ZDCNodeComponents)components
                        ifETagMatches:(nullable NSString *)eTag;

    Swift

    func unmarkNodeAsNeedsDownload(_ nodeID: String, components: ZDCNodeComponents, ifETagMatches eTag: String?)

    Parameters

    nodeID

    The node you successfully downloaded. (nodeID == ZDCNode.uuid)

    components

    Pass ZDCNodeComponents_All to specify that all components are now up-to-date. However, if you only downloaded one component, such as the thumbnail, then just specify that component.

    eTag

    If you pass a non-nil eTag, then the flag will only be removed if ZDCNode.eTag_data matches the given eTag. You can get the eTag from the DownloadManager’s completion block parameter, via [ZDCCloudDataInfo eTag].

  • Returns YES/true if you’ve marked the node as needing to be downloaded.

    A bitwise comparison is performed between the currently marked components, and the passed components parameter. YES is returned if ANY of the components (flags, bits) are currented marked as needing download.

    Declaration

    Objective-C

    - (BOOL)nodeIsMarkedAsNeedsDownload:(nonnull NSString *)nodeID
                             components:(ZDCNodeComponents)components;

    Swift

    func nodeIsMarkedAsNeedsDownload(_ nodeID: String, components: ZDCNodeComponents) -> Bool

    Parameters

    nodeID

    The node in question. (nodeID == ZDCNode.uuid)

    components

    The component(s) in question.

  • Returns the operations that were added to the push queue in THIS transaction.

    When you create, modify or delete a node, the system creates and queues operations to push these changes to the cloud. The operations are stored safely in the database, and are executed by the PushManager.

    Occassionally you may want to tweak an operation’s dependencies or priority. You can do that at any time using the underlying functions exposed by YapDatabaseCloudCore.

    Note

    ZDCCloudTransaction extends YapDatabaseCloudCoreTransaction. So you have full access to the public API of YapDatabaseCloudCoreTransaction too.

    Declaration

    Objective-C

    - (nonnull NSArray<ZDCCloudOperation *> *)addedOperations;

    Swift

    func addedOperations() -> [ZDCCloudOperation]
  • Returns the operations that were added to the push queue in THIS transaction (for the given nodeID).

    When you create, modify or delete a node, the system creates and queues operations to push these changes to the cloud. The operations are stored safely in the database, and are executed by the PushManager.

    Occassionally you may want to tweak an operation’s dependencies or priority. You can do that at any time using the underlying functions exposed by YapDatabaseCloudCore.

    Note

    ZDCCloudTransaction extends YapDatabaseCloudCoreTransaction. So you have full access to the public API of YapDatabaseCloudCoreTransaction too.

    Declaration

    Objective-C

    - (nonnull NSArray<ZDCCloudOperation *> *)addedOperationsForNodeID:
        (nonnull NSString *)nodeID;

    Swift

    func addedOperations(forNodeID nodeID: String) -> [ZDCCloudOperation]

    Parameters

    nodeID

    The node whose operations you’re looking for. (nodeID == ZDCNode.uuid)

  • Returns YES if there pending uploads for the given nodeID. This information may be useful in determining why your data is out-of-sync with the cloud.

    Declaration

    Objective-C

    - (BOOL)hasPendingDataUploadsForNodeID:(nonnull NSString *)nodeID;

    Swift

    func hasPendingDataUploads(forNodeID nodeID: String) -> Bool
  • Returns a list of pending ZDCCloudOperations for which:

    • op.type == ZDCCloudOperationType_Put
    • op.nodeID matches the list of childNodeIDs for the given parent node.

    Occassionally you may want to tweak an operation’s dependencies or priority. You can do that at any time using the underlying functions exposed by YapDatabaseCloudCore.

    Note

    ZDCCloudTransaction extends YapDatabaseCloudCoreTransaction. So you have full access to the public API of YapDatabaseCloudCoreTransaction too.

    If this method doesn’t do exactly what you want, you can easily create your own version of it. Since ZDCCloudTransaction extends YapDatabaseCloudCoreTransaction, you can use methods such as [YapDatabaseCloudCoreTransaction enumerateOperationsUsingBlock:] to perform your own enumeration with your own filters.

    Declaration

    Objective-C

    - (nonnull NSArray<ZDCCloudOperation *> *)pendingPutOperationsWithParentID:
        (nonnull NSString *)parentNodeID;

    Swift

    func pendingPutOperations(withParentID parentNodeID: String) -> [ZDCCloudOperation]
  • Returns a list of pending ZDCCloudOperations for which:

    • op.type == ZDCCloudOperationType_CopyLeaf
    • op.dstCloudLocator matches the given recipients inbox

    Occassionally you may want to tweak an operation’s dependencies or priority. You can do that at any time using the underlying functions exposed by YapDatabaseCloudCore.

    Note

    ZDCCloudTransaction extends YapDatabaseCloudCoreTransaction. So you have full access to the public API of YapDatabaseCloudCoreTransaction too.

    If this method doesn’t do exactly what you want, you can easily create your own version of it. Since ZDCCloudTransaction extends YapDatabaseCloudCoreTransaction, you can use methods such as [YapDatabaseCloudCoreTransaction enumerateOperationsUsingBlock:] to perform your own enumeration with your own filters.

    Declaration

    Objective-C

    - (nonnull NSArray<ZDCCloudOperation *> *)
        pendingCopyOperationsWithRecipientInbox:(nonnull ZDCUser *)recipient;

    Swift

    func pendingCopyOperations(withRecipientInbox recipient: ZDCUser) -> [ZDCCloudOperation]
  • Enumerates all the operations in the queue, and returns an array of values extracted from ZDCCloudOperation.changeset.

    If you’re using the ZDCSyncable protocol, this is what you’ll need to perform a merge.

    Declaration

    Objective-C

    - (nonnull NSArray<NSDictionary *> *)pendingChangesetsForNodeID:
        (nonnull NSString *)nodeID;

    Swift

    func pendingChangesets(forNodeID nodeID: String) -> [[AnyHashable : Any]]

    Parameters

    nodeID

    The node whose operations you’re looking for. (nodeID == ZDCNode.uuid)

  • Invoke this method after you’ve downloaded and processed the latest version of a node’s data.

    This informs the system that your data is now up-to-date with the given version/eTag. In particular, this tells the system to update all queued ZDCCloudOperation.eTag values.

    This method is one of the ways in which you can resolve a conflict.

    See

    [ZeroDarkCloudDelegate didDiscoverConflict:forNode:atPath:transaction:]

    Declaration

    Objective-C

    - (void)didMergeDataWithETag:(nonnull NSString *)eTag
                       forNodeID:(nonnull NSString *)nodeID;

    Swift

    func didMergeData(withETag eTag: String, forNodeID nodeID: String)
  • Invoke this method if you’ve been notified of a conflict, and you’ve decided to let the cloud version win. In other words, you’ve decided not to overwrite the cloud version with the local version.

    This method is one of the ways in which you can resolve a conflict.

    See

    [ZeroDarkCloudDelegate didDiscoverConflict:forNode:atPath:transaction:]

    Declaration

    Objective-C

    - (void)skipDataUploadsForNodeID:(nonnull NSString *)nodeID;

    Swift

    func skipDataUploads(forNodeID nodeID: String)