ZDCDownloadManager

@interface ZDCDownloadManager : NSObject

The DownloadManager is your one-stop-shop for downloading data from the cloud.

Recall that the ZeroDark.cloud framework will automatically fetch the treesystem outline for you. That is, it will tell you about the nodes that exist in the cloud, what their names are, and what the tree/heirarchy looks like. But you’re in complete control when it comes to downloading the actual data (node content). This allows you to optimize for your app. For example:

  • speed up new app logins by not downloading old content
  • save disk space by deleting local copies of node data that are no longer being used
  • optimize per-device by downloading certain content on demand

When you’re ready to download the node content, the DownloadManager simplifies the process for you. It will automatically coalesce multiple requests to download the same item. And it supports optional background downloads, so that downloads can continue while the app is backgrounded (or even quit).

For downloads of very large items, the DownloadManager will automatically download the item in parts. If the download is interrupted, it can automatically pick up where it left off.

It also provides an NSProgress instance for all downloads, allowing you to display progress items in your UI. And it works in concert with the ProgressManager to simplify UI development.

  • Downloads a small portion of the node’s content.

    Recall that the ZeroDark.cloud framework allows you to include 3 sections for every node:

    • metadata (optional)
    • thumbnail (optional)
    • data (required - actual content)

    By including additional sections, such as a thumbnail, you allow other devices to quickly fetch small amounts of data from the cloud. Just enough to drive your UI, but without forcing a full download of a potentially large item. This method provides the ability to dowload just these components - the meta components.

    Declaration

    Objective-C

    - (nonnull ZDCDownloadTicket *)
        downloadNodeMeta:(nonnull ZDCNode *)node
              components:(ZDCNodeMetaComponents)components
                 options:(nullable ZDCDownloadOptions *)options
         completionQueue:(nullable dispatch_queue_t)completionQueue
         completionBlock:(nonnull NodeMetaDownloadCompletionBlock)completionBlock;

    Swift

    func downloadNodeMeta(_ node: ZDCNode, components: ZDCNodeMetaComponents, options: ZDCDownloadOptions?, completionQueue: DispatchQueue?, completionBlock: @escaping NodeMetaDownloadCompletionBlock) -> ZDCDownloadTicket

    Parameters

    node

    The node you want to download.

    components

    Allows you to specify which components you’re interested in downloading.

    options

    Various options regarding how to download the file, and whether it should be cached via the DiskManager. If nil, the default options are used: {cacheToDiskManager: YES, canDownloadWhileInBackground: NO}

    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

    A ticket that can be used to track the download. The ticket includes a NSProgress item that can be used for tracking. The progress item is also registered with the ZDCProgressManager, and can be fetched from there as well. (Meaning you also get throughput & estimated time remaining for this progress item.)

  • Downloads the full DATA file from the cloud.

    Declaration

    Objective-C

    - (nonnull ZDCDownloadTicket *)
        downloadNodeData:(nonnull ZDCNode *)node
                 options:(nullable ZDCDownloadOptions *)options
         completionQueue:(nullable dispatch_queue_t)completionQueue
         completionBlock:(nonnull NodeDataDownloadCompletionBlock)completionBlock;

    Swift

    func downloadNodeData(_ node: ZDCNode, options: ZDCDownloadOptions?, completionQueue: DispatchQueue?, completionBlock: @escaping NodeDataDownloadCompletionBlock) -> ZDCDownloadTicket

    Parameters

    node

    The node you want to download.

    options

    Various options regarding how to download the file, and whether it should be cached via the DiskManager. If nil, the default options are used: {cacheToDiskManager: NO, canDownloadWhileInBackground: NO}

    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

    A ticket that can be used to track the download. The ticket includes a NSProgress item that can be used for tracking. The progress item is also registered with the ZDCProgressManager, and can be fetched from there as well. (Meaning you also get throughput & estimated time remaining for this progress item.)

  • Downloads the avatar for a user.

    Note

    This method doesn’t support background downloads (on iOS).

    Declaration

    Objective-C

    - (nonnull ZDCDownloadTicket *)
        downloadUserAvatar:(nonnull ZDCUser *)user
                   options:(nullable ZDCDownloadOptions *)options
           completionQueue:(nullable dispatch_queue_t)completionQueue
           completionBlock:
               (nonnull UserAvatarDownloadCompletionBlock)completionBlock;

    Swift

    func downloadUserAvatar(_ user: ZDCUser, options: ZDCDownloadOptions?, completionQueue: DispatchQueue?, completionBlock: @escaping UserAvatarDownloadCompletionBlock) -> ZDCDownloadTicket

    Parameters

    user

    The associated user. (userID == ZDCUser.uuid)

    options

    Various options regarding how to download the file, and whether it should be cached via the DiskManager. If nil, the default options are used: {cacheToDiskManager: YES, canDownloadWhileInBackground: NO} This method doesn’t support background downloads (on iOS).

    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

    A ticket that can be used to track the download. The ticket includes a NSProgress item that can be used for tracking.

  • Downloads the avatar for a user.

    Note

    This method doesn’t support background downloads (on iOS).

    Declaration

    Objective-C

    - (nonnull ZDCDownloadTicket *)
        downloadUserAvatar:(nonnull ZDCSearchResult *)searchResult
                identityID:(nullable NSString *)identityID
           completionQueue:(nullable dispatch_queue_t)completionQueue
           completionBlock:
               (nonnull UserAvatarDownloadCompletionBlock)completionBlock;

    Swift

    func downloadUserAvatar(_ searchResult: ZDCSearchResult, identityID: String?, completionQueue: DispatchQueue?, completionBlock: @escaping UserAvatarDownloadCompletionBlock) -> ZDCDownloadTicket

    Parameters

    searchResult

    A search result from ZDCUserSearchManager.

    identityID

    Allows you to specifiy which identityID to download. If nil, automatically uses the displayIdentity.

    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

    A ticket that can be used to track the download. The ticket includes a NSProgress item that can be used for tracking.