ZDCNodeManager

@interface ZDCNodeManager : NSObject

Provides various methods for inspecting the node treesystem.

  • Returns the singleton instance.

    Declaration

    Objective-C

    + (nonnull instancetype)sharedInstance;

    Swift

    class func sharedInstance() -> Self
  • Returns a specific trunk (top-level root node).

    This method only returns nil if you pass an invalid parameter.

    Declaration

    Objective-C

    - (nullable ZDCTrunkNode *)trunkNodeForLocalUserID:
                                   (nonnull NSString *)localUserID
                                                treeID:(nonnull NSString *)treeID
                                                 trunk:(ZDCTreesystemTrunk)trunk
                                           transaction:(id)transaction;

    Swift

    func trunkNode(forLocalUserID localUserID: String, treeID: String, trunk: ZDCTreesystemTrunk, transaction: Any!) -> ZDCTrunkNode?

    Parameters

    localUserID

    The localUser for which you’re interested (localUserID == ZDCLocalUser.uuid)

    treeID

    The treeID you registered in the ZeroDark.cloud dashboard. This is the same treeID you passed when you created a ZeroDarkCloud instance.

    trunk

    The trunk you’re looking for.

    transaction

    A database transaction - allows the method to read from the database.

  • A trunk node is a top-level root node. This method walks up the tree until it finds the corresponding trunk.

    This method only returns nil if you pass a node that isn’t part of the treesystem.

    Declaration

    Objective-C

    - (nullable ZDCTrunkNode *)trunkNodeForNode:(nonnull ZDCNode *)node
                                    transaction:(id)transaction;

    Swift

    func trunkNode(for node: ZDCNode, transaction: Any!) -> ZDCTrunkNode?

    Parameters

    node

    Find the trunk for this node. (The node doesn’t need to be stored in the database for this method to work. But it will need to have a proper -[ZDCNode parentID] property set.)

    transaction

    A database transaction - allows the method to read from the database.

  • An anchor node is the nearest node in the hierarchy that provides a location anchor (e.g. an AWS region & bucket).

    This could be the trunkNode (a ZDCTrunkNode instance), meaning the user’s own region & bucket. Or it could be another node with a non-nil anchor property, meaning some other user’s region & bucket.

    The anchorNode is found by traversing up the node hierarchy towards the trunkNode, and searching for a node with anchor information. If not found, the trunkNode is returned.

    This method only returns nil if you pass a node that isn’t part of the treesystem.

    Declaration

    Objective-C

    - (nullable ZDCNode *)anchorNodeForNode:(nonnull ZDCNode *)node
                                transaction:(id)transaction;

    Swift

    func anchorNode(for node: ZDCNode, transaction: Any!) -> ZDCNode?

    Parameters

    node

    Find the anchorNode for this node. (The node doesn’t need to be stored in the database for this method to work. But it will need to have a proper -[ZDCNode parentID] property set.)

    transaction

    A database transaction - allows the method to read from the database.

  • Returns the owner of a given node.

    This is done by traversing the node hierarchy up (towards the trunk/root). The search completes when either:

    • the trunk node is encountered
    • an anchor node (with an explicit ownerID) is encountered

    If all else fails (e.g. because the node.parentID is invalid), then node.localUserID is returned.

    Declaration

    Objective-C

    - (nonnull NSString *)ownerIDForNode:(nonnull ZDCNode *)node
                             transaction:(id)transaction;

    Swift

    func ownerID(for node: ZDCNode, transaction: Any!) -> String

    Parameters

    node

    Find the ownerID for this node. (The node doesn’t need to be stored in the database for this method to work. But it should have a proper -[ZDCNode parentID] set.)

    transaction

    A database transaction - allows the method to read from the database.

  • Invokes ownerIDForNode:transaction:, and then uses the result to fetch the corresponding ZDCUser.

    The ZDCUser instance may be nil if the the owner is a non-local-user and the system hasn’t downloaded the remote user yet. You can always use the ZDCUserManager to download the user.

    Declaration

    Objective-C

    - (nullable ZDCUser *)ownerForNode:(nonnull ZDCNode *)node
                           transaction:(id)transaction;

    Swift

    func owner(for node: ZDCNode, transaction: Any!) -> ZDCUser?
  • 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

    Declaration

    Objective-C

    - (nullable ZDCNode *)targetNodeForNode:(nonnull ZDCNode *)node
                                transaction:(id)transaction;

    Swift

    func targetNode(for node: ZDCNode, transaction: Any!) -> ZDCNode?
  • Returns the path to the given node.

    Declaration

    Objective-C

    - (nullable ZDCTreesystemPath *)pathForNode:(nonnull ZDCNode *)node
                                    transaction:(id)transaction;

    Swift

    func path(for node: ZDCNode, transaction: Any!) -> ZDCTreesystemPath?

    Parameters

    node

    The node you’re interested in.

    transaction

    A database transaction - allows the method to read from the database.

  • Returns an array of all parent nodeID’s of the given node, up to the containerNode.

    The containerNode will be at index 0, and the immediate parentNodeID will be the last item in the array.

    Note

    The term nodeID is short for ZDCNode.uuid.

    Declaration

    Objective-C

    - (nonnull NSArray<NSString *> *)parentNodeIDsForNode:(nonnull ZDCNode *)node
                                              transaction:(id)transaction;

    Swift

    func parentNodeIDs(for node: ZDCNode, transaction: Any!) -> [String]

    Parameters

    node

    The node you’re interested in.

    transaction

    A database transaction - allows the method to read from the database.

  • Walks the tree from nodeID up to the root, and checks to see if potentialParentID is indeed in its hierarchy.

    Note

    The term nodeID is short for ZDCNode.uuid.

    Declaration

    Objective-C

    - (BOOL)isNode:(nonnull NSString *)nodeID
        aDescendantOf:(nonnull NSString *)potentialParentID
          transaction:(id)transaction;

    Swift

    func isNode(_ nodeID: String, aDescendantOf potentialParentID: String, transaction: Any!) -> Bool
  • Enumerates all ZDCNode.uuid’s whose parentID property matches the given parentID.

    This method is slightly faster than enumerating the ZDCNode objects, as it can skip fetching the objects from the database.

    This only includes the direct children of the given parent. Further ancestors (grandchildren, etc) are NOT enumerated. If you want a deep recursion (including grandchildren, etc), then use recursiveEnumerateNodeIDsWithParentID:transaction:usingBlock:.

    Declaration

    Objective-C

    - (void)enumerateNodeIDsWithParentID:(nonnull NSString *)parentID
                             transaction:(id)transaction
                              usingBlock:
                                  (nonnull void (^)(NSString *_Nonnull,
                                                    BOOL *_Nonnull))enumBlock;

    Swift

    func enumerateNodeIDs(withParentID parentID: String, transaction: Any!, using enumBlock: (String, UnsafeMutablePointer<ObjCBool>) -> Void)
  • Enumerates all ZDCNode.uuid’s who are ancestors of the given parentID. This includes direct children, as well as further ancestors (grandchildren, etc).

    The recursion process is performed using a depth first algorithm, and the path to each nodeID is provided via the enumBlock.

    The pathFromParent array does not contain the parentID, nor the nodeID parameter. It only contains all nodeIDs between the parentID & the nodeID. Thus, direct children of the parentID will have an empty pathFromParent array. The array is ordered such that the node closest to the parent is at index zero.

    Warning

    The pathFromParent array is mutable, and gets changed between each invocation of the block. So if you need to store it outside the block context, you’ll need to make a copy.

    The recurseInto parameter can be set to NO for any node’s for which you aren’t interested in the children/descendents.

    Note

    This method is slightly faster than enumerating the ZDCNode objects, as it can skip fetching the objects from the database.

    Declaration

    Objective-C

    - (void)recursiveEnumerateNodeIDsWithParentID:(nonnull NSString *)parentID
                                      transaction:(id)transaction
                                       usingBlock:(nonnull void (^)(
                                                      NSString *_Nonnull,
                                                      NSArray<NSString *> *_Nonnull,
                                                      BOOL *_Nonnull,
                                                      BOOL *_Nonnull))enumBlock;

    Swift

    func recursiveEnumerateNodeIDs(withParentID parentID: String, transaction: Any!, using enumBlock: (String, [String], UnsafeMutablePointer<ObjCBool>, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    parentID

    The node for which you wish to enumerate the children & ancestors. (parentID == nodeID_of_parent == ZDCNode.uuid)

    transaction

    A database transaction - allows the method to read from the database.

    enumBlock

    The block to invoke for each encountered nodeID during the recursive process.

  • Enumerates all ZDCNode’s whose parentID property matches the given parentID.

    This only includes the direct children of the given parent. Further ancestors (grandchildren, etc) are NOT enumerated. If you want a deep recursion (including grandchildren, etc), then use recursiveEnumerateNodesWithParentID:transaction:usingBlock:.

    Declaration

    Objective-C

    - (void)enumerateNodesWithParentID:(nonnull NSString *)parentID
                           transaction:(id)transaction
                            usingBlock:(nonnull void (^)(ZDCNode *_Nonnull,
                                                         BOOL *_Nonnull))enumBlock;

    Swift

    func enumerateNodes(withParentID parentID: String, transaction: Any!, using enumBlock: (ZDCNode, UnsafeMutablePointer<ObjCBool>) -> Void)
  • Enumerates all ZDCNodes’s who are ancestors of the given parentID. This includes direct children, as well as further ancestors (grandchildren, etc).

    The recursion process is performed using a depth first algorithm, and the path to each nodeID is provided via the enumBlock.

    The pathFromParent array is does not contain the parent, nor the node parameter. It only contains all nodes between the parent & the node. Thus, direct children of the parent will have an empty pathFromParent array. The array is ordered such that the node closest to the parent is at index zero.

    Warning

    The pathFromParent array is mutable, and gets changed between each invocation of the block. So if you need to store it outside the block context, you’ll need to make a copy.

    The recurseInto parameter can be set to NO for any node’s for which you aren’t interested in the children/descendents.

    Declaration

    Objective-C

    - (void)recursiveEnumerateNodesWithParentID:(nonnull NSString *)parentID
                                    transaction:(id)transaction
                                     usingBlock:(nonnull void (^)(
                                                    ZDCNode *_Nonnull,
                                                    NSArray<ZDCNode *> *_Nonnull,
                                                    BOOL *_Nonnull,
                                                    BOOL *_Nonnull))enumBlock;

    Swift

    func recursiveEnumerateNodes(withParentID parentID: String, transaction: Any!, using enumBlock: (ZDCNode, [ZDCNode], UnsafeMutablePointer<ObjCBool>, UnsafeMutablePointer<ObjCBool>) -> Void)

    Parameters

    parentID

    The node for which you wish to enumerate the children & ancestors. (parentID == nodeID_of_parent == ZDCNode.uuid)

    transaction

    A database transaction - allows the method to read from the database.

    enumBlock

    The block to invoke for each encountered node during the recursive process.

  • Returns whether or not the node has any children.

    Declaration

    Objective-C

    - (BOOL)hasChildren:(nonnull ZDCNode *)node transaction:(id)transaction;

    Swift

    func hasChildren(_ node: ZDCNode, transaction: Any!) -> Bool
  • Finds the node with the given name, if it exists, and returns it.

    In most cases this lookup is performed in O(log n), where n is number of ZDCNode’s where node.parentID == parentID.

    Declaration

    Objective-C

    - (nullable ZDCNode *)findNodeWithName:(nonnull NSString *)name
                                  parentID:(nonnull NSString *)parentID
                               transaction:(id)transaction;

    Swift

    func findNode(withName name: String, parentID: String, transaction: Any!) -> ZDCNode?

    Parameters

    name

    The ZDCNode.name to find. (i.e. the cleartext name, such as Inventory.numbers) The name comparison is both case-insensitive & localized. (So in German: daß == dass)

    parentID

    A reference to the parent node. (parentID == nodeID == ZDCNode.uuid)

    transaction

    A database transaction - allows the method to read from the database.

    Return Value

    The matching ZDCNode, or nil if it doesn’t exist.

  • Finds the node with the given path components.

    Declaration

    Objective-C

    - (nullable ZDCNode *)findNodeWithPath:(nonnull ZDCTreesystemPath *)path
                               localUserID:(nonnull NSString *)localUserID
                                    treeID:(nonnull NSString *)treeID
                               transaction:(id)transaction;

    Swift

    func findNode(withPath path: ZDCTreesystemPath, localUserID: String, treeID: String, transaction: Any!) -> ZDCNode?

    Parameters

    path

    The path of the node, such as /Documents/Inventory.numbers.

    localUserID

    This is the associated user account identifier. (localUserID == ZDCLocalUser.uuid)

    treeID

    The treesystem identifier. All nodes are segregated by treeID.

    transaction

    A database transaction - allows the method to read from the database.

    Return Value

    The matching ZDCNode, or nil if it doesn’t exist.

  • Finds the node with the given cloudName. This method is primarily for use by the PullManager.

    @note A cloudName is a hash of the cleartext name, combined with the parent diretory’s salt. That is, a cloudName prevents the cleartext name from being revealed to the server. You can get the cloudName for any node via the various methods in ZDCCloudPathManager.

    Declaration

    Objective-C

    - (nullable ZDCNode *)findNodeWithCloudName:(nonnull NSString *)cloudName
                                       parentID:(nonnull NSString *)parentID
                                    transaction:(id)transaction;

    Swift

    func findNode(withCloudName cloudName: String, parentID: String, transaction: Any!) -> ZDCNode?

    Parameters

    cloudName

    The cloudName of the node to find. (e.g. 58fidhxeyyfzgp73hgefpr956jaxa6xs)

    parentID

    The parentID of the node. (parentID == ZDCNode.parentID == parentNode.uuid)

    transaction

    A database transaction - allows the method to read from the database.

    Return Value

    The matching ZDCNode, or nil if it doesn’t exist.

  • Finds the node with the given cloudID & localUserID. This method is primarily for use by the PullManager.

    A SecondaryIndex in the database is utilized to make this a very fast lookup.

    @note Since nodes may be moved around (e.g. renamed or moved to different directories), the current location of the node in the cloud may not match the local path. However, the cloudID is immutable (set by the server, and cannot be changed), and is thus the most reliable way to lookup a matching node given the cloud version.

    Declaration

    Objective-C

    - (nullable ZDCNode *)findNodeWithCloudID:(nonnull NSString *)cloudID
                                  localUserID:(nonnull NSString *)localUserID
                                       treeID:(nonnull NSString *)treeID
                                  transaction:(id)transaction;

    Swift

    func findNode(withCloudID cloudID: String, localUserID: String, treeID: String, transaction: Any!) -> ZDCNode?

    Parameters

    cloudID

    The server-assigned identifier for the node. This value is immutable - the server doesn’t allow it to be changed.

    localUserID

    This is the associated user account identifier. (localUserID == ZDCLocalUser.uuid)

    treeID

    The treesystem identifier, as registered in the dashboard. All nodes are segregated by treeID.

    transaction

    A database transaction - allows the method to read from the database.

    Return Value

    The matching ZDCNode, or nil if it doesn’t exist.

  • Locates the node using only the cloud path information. This method is primarily for use by the PullManager.

    Declaration

    Objective-C

    - (nullable ZDCNode *)findNodeWithCloudPath:(nonnull ZDCCloudPath *)cloudPath
                                         bucket:(nonnull NSString *)bucket
                                         region:(AWSRegion)region
                                    localUserID:(nonnull NSString *)localUserID
                                         treeID:(nonnull NSString *)treeID
                                    transaction:(id)transaction;

    Swift

    func findNode(withCloudPath cloudPath: ZDCCloudPath, bucket: String, region: AWSRegion, localUserID: String, treeID: String, transaction: Any!) -> ZDCNode?

    Return Value

    The matching ZDCNode, or nil if it doesn’t exist.

  • Finds the node with a matching dirPrefix.

    A SecondaryIndex is utilized to make this a very fast lookup.

    Declaration

    Objective-C

    - (nullable ZDCNode *)findNodeWithDirPrefix:(nonnull NSString *)prefix
                                         bucket:(nonnull NSString *)bucket
                                         region:(AWSRegion)region
                                    localUserID:(nonnull NSString *)localUserID
                                         treeID:(nonnull NSString *)treeID
                                    transaction:(id)transaction;

    Swift

    func findNode(withDirPrefix prefix: String, bucket: String, region: AWSRegion, localUserID: String, treeID: String, transaction: Any!) -> ZDCNode?
  • Finds the pointer node with the given pointeeID.

    Declaration

    Objective-C

    - (nullable ZDCNode *)findNodeWithPointeeID:(nonnull NSString *)pointeeID
                                    localUserID:(nonnull NSString *)localUserID
                                         treeID:(nonnull NSString *)treeID
                                    transaction:(id)transaction;

    Swift

    func findNode(withPointeeID pointeeID: String, localUserID: String, treeID: String, transaction: Any!) -> ZDCNode?
  • Returns a list of all nodeID’s belonging to the given user (regardless of treeID).

    Note

    This list doesn’t include trunk nodes.

    Declaration

    Objective-C

    - (nonnull NSArray<NSString *> *)allNodeIDsWithLocalUserID:
                                         (nonnull NSString *)localUserID
                                                   transaction:(id)transaction;

    Swift

    func allNodeIDs(withLocalUserID localUserID: String, transaction: Any!) -> [String]
  • Returns a list of all nodeID’s belonging to the given user.

    Note

    This list doesn’t include trunk nodes.

    Declaration

    Objective-C

    - (nonnull NSArray<NSString *> *)
        allNodeIDsWithLocalUserID:(nonnull NSString *)localUserID
                           treeID:(nonnull NSString *)treeID
                      transaction:(id)transaction;

    Swift

    func allNodeIDs(withLocalUserID localUserID: String, treeID: String, transaction: Any!) -> [String]
  • Returns all ZDCNode.uuid’s where ZDCNode.cloudID is non-nil. That is, the node has been uploaded at least once.

    Important: uploaded once != fully synced right at this moment. Rather it means that we expect it to be on the server.

    Note: This method has been optimized for performance, and is the recommended approach.

    Declaration

    Objective-C

    - (nonnull NSArray<NSString *> *)
        allUploadedNodeIDsWithLocalUserID:(nonnull NSString *)localUserID
                                   treeID:(nonnull NSString *)treeID
                              transaction:(id)transaction;

    Swift

    func allUploadedNodeIDs(withLocalUserID localUserID: String, treeID: String, transaction: Any!) -> [String]
  • Updates the permissons for the node to match those of its parent.

    Declaration

    Objective-C

    - (BOOL)resetPermissionsForNode:(nonnull ZDCNode *)node
                        transaction:(id)transaction;

    Swift

    func resetPermissions(for node: ZDCNode, transaction: Any!) -> Bool

    Parameters

    node

    The node to modify. The passed instance must not be immutable, as this method intends to modify node.shareList.

    Return Value

    YES on success. NO on failure (node is immutable, doesn’t have parentID, etc)

  • This method may be used to resolve a conflict that can occur when two nodes are attempting to use the same name.

    This method appends a number to the end of the name until it’s unique. For example, if the given node.name is Foobar.ext, this method may return Foobar 2.ext.

    Declaration

    Objective-C

    - (nonnull NSString *)resolveNamingConflict:(nonnull ZDCNode *)node
                                    transaction:(id)transaction;

    Swift

    func resolveNamingConflict(_ node: ZDCNode, transaction: Any!) -> String

    Parameters

    node

    The node that’s in conflict with another node.

    transaction

    A database transaction - allows the method to read from the database.

    Return Value

    A node.name that’s safe to use (i.e. without it being in conflict with another known node)