ZDCProgressManager

@interface ZDCProgressManager : NSObject

The ProgressManager provides real-time progress information for active operations.

This includes:

  • downloads : as in the downloads of node data that you request through the DownloadManager
  • uploads : which get queued for the push manager, and then get uploaded when possible

The ProgressManager automatically monitors its progress items, and provides you with the following useful information:

  • Bandwidth calculations:

    • Estimated bytes-per-second.
    • Available via progress.userInfo[NSProgressThroughputKey]
  • Time remaining calculations:

    • Estimated time remaining based on averaged throughput & remaining bytes.
    • Available via progress.userInfo[NSProgressEstimatedTimeRemainingKey]
  • Returns the list of nodeIDs that currently have associated downloads. The downloads can be of any type - either meta or data.

    Declaration

    Objective-C

    - (nonnull NSSet<NSString *> *)allDownloadingNodeIDs;

    Swift

    func allDownloadingNodeIDs() -> Set<String>
  • Returns the list of nodeIDs (for the given user) that currently have associated downloads. The downloads can be of any type - either ‘meta’ or ‘data’.

    Declaration

    Objective-C

    - (nonnull NSSet<NSString *> *)allDownloadingNodeIDs:
        (nonnull NSString *)localUserID;

    Swift

    func allDownloadingNodeIDs(_ localUserID: String) -> Set<String>

    Parameters

    localUserID

    The user you’re interested in. (localUserID == ZDCLocalUser.uuid)

  • If available, returns the download progress of the node.

    If there are currently multiple downloads for the node, the selection priority is (from highest to lowest): ‘data’, ‘all-meta’, ‘thumbnail’, ‘metadata’, ‘header’. You can extract the ZDCProgressType value via progress.userInfo[ZDCProgressTypeKey]. You can extract the ZDCNodeMetaComponents value via progress.userInfo[ZDCNodeMetaComponentsKey].

    Declaration

    Objective-C

    - (nullable NSProgress *)downloadProgressForNodeID:(nonnull NSString *)nodeID;

    Swift

    func downloadProgress(forNodeID nodeID: String) -> Progress?

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    Return Value

    The download progress, if available.

  • Returns the list of nodeIDs that currently have associated ‘meta’ downloads.

    Note

    Downloads are started via the ZDCDownloadManager.

    Declaration

    Objective-C

    - (nonnull NSSet<NSString *> *)allMetaDownloadingNodeIDs;

    Swift

    func allMetaDownloadingNodeIDs() -> Set<String>
  • Returns the list of nodeIDs (for the given user) that currently have associated ‘meta’ downloads.

    Note

    Downloads are started via the ZDCDownloadManager.

    Declaration

    Objective-C

    - (nonnull NSSet<NSString *> *)allMetaDownloadingNodeIDs:
        (nonnull NSString *)localUserID;

    Swift

    func allMetaDownloadingNodeIDs(_ localUserID: String) -> Set<String>

    Parameters

    localUserID

    The user you’re interested in. (localUserID == ZDCLocalUser.uuid)

  • If available, returns the ‘meta’ download progress of the node.

    If multiple ‘meta’ downloads exist for the given node, the selection priority is (from highest to lowest): ‘all-meta’, ‘thumbnail’, ‘metadata’, ‘header’. You can extract the ZDCNodeMetaComponents value via progress.userInfo[ZDCNodeMetaComponentsKey].

    Declaration

    Objective-C

    - (nullable NSProgress *)metaDownloadProgressForNodeID:
        (nonnull NSString *)nodeID;

    Swift

    func metaDownloadProgress(forNodeID nodeID: String) -> Progress?

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

  • If available, returns the ‘meta’ download progress of the node.

    If you pass nil for the components parameter, and multiple downloads exist, the selection priority is (from highest to lowest): ‘all-meta’, ‘thumbnail’, ‘metadata’, ‘header’. You can extract the ZDCNodeMetaComponents value via progress.userInfo[ZDCNodeMetaComponentsKey].

    Declaration

    Objective-C

    - (nullable NSProgress *)
        metaDownloadProgressForNodeID:(nonnull NSString *)nodeID
                           components:(nullable NSNumber *)components;

    Swift

    func metaDownloadProgress(forNodeID nodeID: String, components: NSNumber?) -> Progress?

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    components

    Pass non-nil wrapped ZDCNodeMetaComponents if you’re interested in a particular meta download. Otherwise pass nil to receive based on the standard priority.

  • If available, returns the ‘meta’ download progress of the node. If the completionBlock is non-nil, then it will be invoked upon download completion.

    If multiple ‘meta’ downloads exist for the given node, the selection priority is (from highest to lowest): ‘all-meta’, ‘thumbnail’, ‘metadata’, ‘header’. You can extract the ZDCNodeMetaComponents value via progress.userInfo[ZDCNodeMetaComponentsKey].

    Note

    The progress manager supports multiple {completionBlock, completionQueue} tuples. All of them will be invoked upon download completion.

    Declaration

    Objective-C

    - (nullable NSProgress *)
        metaDownloadProgressForNodeID:(nonnull NSString *)nodeID
                      completionQueue:(nullable dispatch_queue_t)completionQueue
                      completionBlock:
                          (nullable NodeMetaDownloadCompletionBlock)completionBlock;

    Swift

    func metaDownloadProgress(forNodeID nodeID: String, completionQueue: DispatchQueue?, completionBlock: NodeMetaDownloadCompletionBlock? = nil) -> Progress?

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    completionQueue

    The GCD dispatch queue in which you’d like the completionBlock to be invoked. If not specified (nil), the main thread will automatically be used.

    completionBlock

    The block to invoke upon download completion. This block will be invoked asynchronously on the completionQueue.

  • If available, returns the ‘meta’ download progress of the node. If the completionBlock is non-nil, then it will be invoked upon download completion.

    If you pass nil for the components parameter, and multiple ‘meta’ downloads exist for the given node, the selection priority is (from highest to lowest): ‘all-meta’, ‘thumbnail’, ‘metadata’, ‘header’. You can extract the ZDCNodeMetaComponents value via progress.userInfo[ZDCNodeMetaComponentsKey].

    Note

    The progress manager supports multiple {completionBlock, completionQueue} tuples. All of them will be invoked upon download completion.

    Declaration

    Objective-C

    - (nullable NSProgress *)
        metaDownloadProgressForNodeID:(nonnull NSString *)nodeID
                           components:(nullable NSNumber *)components
                      completionQueue:(nullable dispatch_queue_t)completionQueue
                      completionBlock:
                          (nullable NodeMetaDownloadCompletionBlock)completionBlock;

    Swift

    func metaDownloadProgress(forNodeID nodeID: String, components: NSNumber?, completionQueue: DispatchQueue?, completionBlock: NodeMetaDownloadCompletionBlock? = nil) -> Progress?

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    components

    Pass non-nil wrapped ZDCNodeMetaComponents if you’re interested in a particular meta download. Otherwise pass nil to receive based on the standard priority.

    completionQueue

    The GCD dispatch queue in which you’d like the completionBlock to be invoked. If not specified (nil), the main thread will automatically be used.

    completionBlock

    The block to invoke upon download completion. This block will be invoked asynchronously on the completionQueue.

  • Adds the given listener. That is, a {completionQueue, completionBlock} for the download.

    If multiple ‘meta’ downloads exist for the given node, the selection priority is (from highest to lowest): ‘all-meta’, ‘thumbnail’, ‘metadata’, ‘header’. You can extract the ZDCNodeMetaComponents value via progress.userInfo[ZDCNodeMetaComponentsKey].

    This method is the same as calling metaDownloadProgressForNodeID:completionQueue:completionBlock:, and then ignoring the return value. It’s just named better. And you won’t have to worry about the compiler whining that you ignored the return value.

    Note

    The progress manager supports multiple {completionBlock, completionQueue} tuples. All of them will be invoked upon download completion.

    Declaration

    Objective-C

    - (BOOL)
        addMetaDownloadListenerForNodeID:(nonnull NSString *)nodeID
                         completionQueue:(nullable dispatch_queue_t)completionQueue
                         completionBlock:(nonnull NodeMetaDownloadCompletionBlock)
                                             completionBlock;

    Swift

    func addMetaDownloadListener(forNodeID nodeID: String, completionQueue: DispatchQueue?, completionBlock: @escaping NodeMetaDownloadCompletionBlock) -> Bool

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    completionQueue

    The GCD dispatch queue in which you’d like the completionBlock to be invoked. If not specified (nil), the main thread will automatically be used.

    completionBlock

    The block to invoke upon download completion. This block will be invoked asynchronously on the completionQueue.

    Return Value

    YES if there’s an existing ‘data’ download for the given nodeID, and the {completionQueue, completionBlock} was added to the list. NO otherwise.

  • Adds the given listener. That is, a {completionQueue, completionBlock} for the download.

    If you pass nil for the components parameter, and multiple ‘meta’ downloads exist for the given node, the selection priority is (from highest to lowest): ‘all-meta’, ‘thumbnail’, ‘metadata’, ‘header’. You can extract the ZDCNodeMetaComponents value via progress.userInfo[ZDCNodeMetaComponentsKey].

    This method is the same as calling metaDownloadProgressForNodeID:components:completionQueue:completionBlock:, and then ignoring the return value. It’s just named better. And you won’t have to worry about the compiler whining that you ignored the return value.

    Note

    The progress manager supports multiple {completionBlock, completionQueue} tuples. All of them will be invoked upon download completion.

    Declaration

    Objective-C

    - (BOOL)
        addMetaDownloadListenerForNodeID:(nonnull NSString *)nodeID
                              components:(nullable NSNumber *)components
                         completionQueue:(nullable dispatch_queue_t)completionQueue
                         completionBlock:(nonnull NodeMetaDownloadCompletionBlock)
                                             completionBlock;

    Swift

    func addMetaDownloadListener(forNodeID nodeID: String, components: NSNumber?, completionQueue: DispatchQueue?, completionBlock: @escaping NodeMetaDownloadCompletionBlock) -> Bool

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    completionQueue

    The GCD dispatch queue in which you’d like the completionBlock to be invoked. If not specified (nil), the main thread will automatically be used.

    completionBlock

    The block to invoke upon download completion. This block will be invoked asynchronously on the completionQueue.

    Return Value

    YES if there’s an existing ‘data’ download for the given nodeID, and the {completionQueue, completionBlock} was added to the list. NO otherwise.

  • Associates the given progress with a download of the node. If there is already a download for this {localUserID, nodeID} tuple, then the request is ignored.

    Declaration

    Objective-C

    - (BOOL)setMetaDownloadProgress:(nonnull NSProgress *)progress
                          forNodeID:(nonnull NSString *)nodeID
                         components:(ZDCNodeMetaComponents)components
                        localUserID:(nonnull NSString *)localUserID;

    Swift

    func setMetaDownloadProgress(_ progress: Progress, forNodeID nodeID: String, components: ZDCNodeMetaComponents, localUserID: String) -> Bool

    Parameters

    progress

    An NSProgress associated with the download.

    nodeID

    Every node has a unique ID. (nodeID == ZDCNode.uuid)

    components

    The specific components being downloaded (with extraneous flags removed).

    localUserID

    The download is going through this account. (localUserID == ZDCLocalUser.uuid)

    Return Value

    YES if the download was added to the list. NO if there was already a download in the list for the {localUserID, nodeID} tuple.

  • Removes the associated download listener. This doesn’t stop the download, it just removes the listener.

    Note

    The completionBlock may still be invoked if it’s already be dispatched.

    If you have an existing progress instance, but you don’t know what components parameter to use: You can extract the ZDCNodeMetaComponents value via progress.userInfo[ZDCNodeMetaComponentsKey].

    Declaration

    Objective-C

    - (void)removeMetaDownloadListenerForNodeID:(nonnull NSString *)nodeID
                                     components:(ZDCNodeMetaComponents)components
                                completionBlock:
                                    (nonnull NodeMetaDownloadCompletionBlock)
                                        completionBlock;

    Swift

    func removeMetaDownloadListener(forNodeID nodeID: String, components: ZDCNodeMetaComponents, completionBlock: @escaping NodeMetaDownloadCompletionBlock)
  • The party responsible for executing the download invokes this method once the download has terminated.

    This method removes the associated download progress, and then invokes all the queued completionBlocks with the given parameters.

    Declaration

    Objective-C

    - (void)removeMetaDownloadProgressForNodeID:(nonnull NSString *)nodeID
                                     components:(ZDCNodeMetaComponents)components
                                     withHeader:(nullable ZDCCloudDataInfo *)header
                                       metadata:(nullable NSData *)metadata
                                      thumbnail:(nullable NSData *)thumbnail
                                          error:(nullable NSError *)error;

    Swift

    func removeMetaDownloadProgress(forNodeID nodeID: String, components: ZDCNodeMetaComponents, withHeader header: ZDCCloudDataInfo?, metadata: Data?, thumbnail: Data?, error: Error?)
  • Returns the list of nodeIDs that currently have associated ‘data’ downloads.

    Note

    Downloads are started via the ZDCDownloadManager.

    Declaration

    Objective-C

    - (nonnull NSSet<NSString *> *)allDataDownloadingNodeIDs;

    Swift

    func allDataDownloadingNodeIDs() -> Set<String>
  • Returns the list of nodeIDs (for the given user) that currently have associated ‘data’ downloads.

    Note

    Downloads are started via the ZDCDownloadManager.

    Declaration

    Objective-C

    - (nonnull NSSet<NSString *> *)allDataDownloadingNodeIDs:
        (nonnull NSString *)localUserID;

    Swift

    func allDataDownloadingNodeIDs(_ localUserID: String) -> Set<String>

    Parameters

    localUserID

    The user you’re interested in. (localUserID == ZDCLocalUser.uuid)

  • If available, returns the ‘data’ download progress of the node.

    Declaration

    Objective-C

    - (nullable NSProgress *)dataDownloadProgressForNodeID:
        (nonnull NSString *)nodeID;

    Swift

    func dataDownloadProgress(forNodeID nodeID: String) -> Progress?

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

  • If available, returns the ‘data’ download progress of the node. If the completionBlock is non-nil, then it will be invoked upon download completion.

    Note

    The progress manager supports multiple {completionBlock, completionQueue} tuples. All of them will be invoked upon download completion.

    Declaration

    Objective-C

    - (nullable NSProgress *)
        dataDownloadProgressForNodeID:(nonnull NSString *)nodeID
                      completionQueue:(nullable dispatch_queue_t)completionQueue
                      completionBlock:
                          (nullable NodeDataDownloadCompletionBlock)completionBlock;

    Swift

    func dataDownloadProgress(forNodeID nodeID: String, completionQueue: DispatchQueue?, completionBlock: NodeDataDownloadCompletionBlock? = nil) -> Progress?

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    completionQueue

    The GCD dispatch queue in which you’d like the completionBlock to be invoked. If not specified (nil), the main thread will automatically be used.

    completionBlock

    The block to invoke upon download completion. This block will be invoked asynchronously on the completionQueue.

  • Adds the given listener. That is, a {completionQueue, completionBlock} for the download.

    This method is the same as calling dataDownloadProgressForNodeID:completionQueue:completionBlock:, and then ignoring the return value. It’s just named better. And you won’t have to worry about the compiler whining that you ignored the return value.

    Note

    The progress manager supports multiple {completionBlock, completionQueue} tuples. All of them will be invoked upon download completion.

    Declaration

    Objective-C

    - (BOOL)
        addDataDownloadListenerForNodeID:(nonnull NSString *)nodeID
                         completionQueue:(nullable dispatch_queue_t)completionQueue
                         completionBlock:(nonnull NodeDataDownloadCompletionBlock)
                                             completionBlock;

    Swift

    func addDataDownloadListener(forNodeID nodeID: String, completionQueue: DispatchQueue?, completionBlock: @escaping NodeDataDownloadCompletionBlock) -> Bool

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    completionQueue

    The GCD dispatch queue in which you’d like the completionBlock to be invoked. If not specified (nil), the main thread will automatically be used.

    completionBlock

    The block to invoke upon download completion. This block will be invoked asynchronously on the completionQueue.

    Return Value

    YES if there’s an existing ‘data’ download for the given nodeID, and the {completionQueue, completionBlock} was added to the list. NO otherwise.

  • Associates the given progress with a download of the node. If there is already a download for this {localUserID, nodeID} tuple, then the request is ignored.

    Declaration

    Objective-C

    - (BOOL)setDataDownloadProgress:(nonnull NSProgress *)progress
                          forNodeID:(nonnull NSString *)nodeID
                        localUserID:(nonnull NSString *)localUserID;

    Swift

    func setDataDownloadProgress(_ progress: Progress, forNodeID nodeID: String, localUserID: String) -> Bool

    Parameters

    progress

    An NSProgress associated with the download.

    nodeID

    Every node has a unique ID. (nodeID == ZDCNode.uuid)

    localUserID

    The download is going through this account. (localUserID == ZDCLocalUser.uuid)

    Return Value

    YES if the download was added to the list. NO if there was already a download in the list for the {localUserID, nodeID} tuple.

  • Removes the associated download listener. This doesn’t stop the download, it just removes the listener.

    Note

    The completionBlock may still be invoked if it’s already be dispatched.

    Declaration

    Objective-C

    - (void)removeDataDownloadListenerForNodeID:(nonnull NSString *)nodeID
                                completionBlock:
                                    (nonnull NodeDataDownloadCompletionBlock)
                                        completionBlock;

    Swift

    func removeDataDownloadListener(forNodeID nodeID: String, completionBlock: @escaping NodeDataDownloadCompletionBlock)
  • The party responsible for executing the download invokes this method once the download has terminated.

    This method removes the associated download progress, and then invokes all the queued completionBlocks with the given parameters.

    Declaration

    Objective-C

    - (void)removeDataDownloadProgressForNodeID:(nonnull NSString *)nodeID
                                     withHeader:(nullable ZDCCloudDataInfo *)header
                                     cryptoFile:(nullable ZDCCryptoFile *)cryptoFile
                                          error:(nullable NSError *)error;

    Swift

    func removeDataDownloadProgress(forNodeID nodeID: String, withHeader header: ZDCCloudDataInfo?, cryptoFile: ZDCCryptoFile?, error: Error?)
  • Returns the list of operationUUIDs that currently have an associated upload progress.

    Declaration

    Objective-C

    - (nonnull NSSet<NSUUID *> *)allUploadingOperationUUIDs;

    Swift

    func allUploadingOperationUUIDs() -> Set<UUID>
  • Returns the list of operationUUIDs (for the given user) that currently have associated upload progress.

    Declaration

    Objective-C

    - (nonnull NSSet<NSUUID *> *)allUploadingOperationUUIDs:
        (nonnull NSString *)localUserID;

    Swift

    func allUploadingOperationUUIDs(_ localUserID: String) -> Set<UUID>
  • Returns the list of nodeIDs that currently have associated downloads.

    Declaration

    Objective-C

    - (nonnull NSSet<NSString *> *)allUploadingNodeIDs;

    Swift

    func allUploadingNodeIDs() -> Set<String>
  • Returns the list of nodeIDs (for the given user) that currently have associated upload progress.

    Declaration

    Objective-C

    - (nonnull NSSet<NSString *> *)allUploadingNodeIDs:
        (nonnull NSString *)localUserID;

    Swift

    func allUploadingNodeIDs(_ localUserID: String) -> Set<String>
  • If available, returns the upload progress for the given operation.

    Declaration

    Objective-C

    - (nullable NSProgress *)uploadProgressForOperationUUID:
        (nonnull NSUUID *)operationID;

    Swift

    func uploadProgress(forOperationUUID operationID: UUID) -> Progress?

    Parameters

    operationID

    The operation you’re interested in (operationID == ZDCCloudOperation.uuid)

    Return Value

    The progress for the upload in-flight, if it exists. Nil otherwise.

  • If available, returns the upload progress for the given operation.

    Declaration

    Objective-C

    - (nullable NSProgress *)
        uploadProgressForOperationUUID:(nonnull NSUUID *)operationID
                       completionQueue:(nullable dispatch_queue_t)completionQueue
                       completionBlock:
                           (nullable UploadCompletionBlock)completionBlock;

    Swift

    func uploadProgress(forOperationUUID operationID: UUID, completionQueue: DispatchQueue?, completionBlock: UploadCompletionBlock? = nil) -> Progress?

    Parameters

    operationID

    The operation you’re interested in (operationID == ZDCCloudOperation.uuid)

    completionQueue

    The GCD dispatch queue in which you’d like the completionBlock to be invoked. If not specified (nil), the main thread will automatically be used.

    completionBlock

    The block to invoke upon upload completion. This block will be invoked asynchronously on the completionQueue.

    Return Value

    The progress for the upload in-flight, if it exists. Nil otherwise.

  • If available, returns the upload progress for the node.

    A data upload is a ZDCCloudOperation whose putType is ZDCCloudOperationPutType_Node_Data. That is, an upload of the node’s data => the actual content. As opposed to the RCRD => treesystem bookkeeping stuff.

    Declaration

    Objective-C

    - (nullable NSProgress *)dataUploadProgressForNodeID:(nonnull NSString *)nodeID;

    Swift

    func dataUploadProgress(forNodeID nodeID: String) -> Progress?

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    Return Value

    The progress for the upload in-flight, if it exists. Nil otherwise.

  • If available, returns the upload progress for the node.

    A data upload is a ZDCCloudOperation whose putType is ZDCCloudOperationPutType_Node_Data. That is, an upload of the node’s data => the actual content. As opposed to the RCRD => treesystem bookkeeping stuff.

    Declaration

    Objective-C

    - (nullable NSProgress *)
        dataUploadProgressForNodeID:(nonnull NSString *)nodeID
                    completionQueue:(nullable dispatch_queue_t)completionQueue
                    completionBlock:(nullable UploadCompletionBlock)completionBlock;

    Swift

    func dataUploadProgress(forNodeID nodeID: String, completionQueue: DispatchQueue?, completionBlock: UploadCompletionBlock? = nil) -> Progress?

    Parameters

    nodeID

    The node you’re interested in. (nodeID == ZDCNode.uuid)

    completionQueue

    The GCD dispatch queue in which you’d like the completionBlock to be invoked. If not specified (nil), the main thread will automatically be used.

    completionBlock

    The block to invoke upon upload completion. This block will be invoked asynchronously on the completionQueue.

    Return Value

    The progress for the upload in-flight, if it exists. Nil otherwise.

  • Associates the given progress with the upload for the operation.

    Declaration

    Objective-C

    - (BOOL)setUploadProgress:(nonnull NSProgress *)progress
                 forOperation:(nonnull ZDCCloudOperation *)operation;

    Swift

    func setUploadProgress(_ progress: Progress, for operation: ZDCCloudOperation) -> Bool

    Parameters

    progress

    An NSProgress associated with the upload.

    operation

    The associated operation.

    Return Value

    YES if the upload was added to the list. NO if there was already an upload in the list for the operation.

  • The party responsible for executing the upload invokes this method once the upload has terminated.

    This method removes the associated upload progress, and then invokes all the queued completionBlocks with the given parameter.

    Declaration

    Objective-C

    - (void)removeUploadProgressForOperationUUID:(nonnull NSUUID *)operationID
                                     withSuccess:(BOOL)success;

    Swift

    func removeUploadProgress(forOperationUUID operationID: UUID, withSuccess success: Bool)