ZDCImageManager

@interface ZDCImageManager : NSObject

The ImageManager simplifies the process of fetching, downloading & resizing images. This includes both node thumbnails & user avatars.

  • Direct access to the underlying in-memory cache container.

    You can configure the cache directly (via either countLimit and/or totalCostLimit), or you can flush the cache (via removeAllObjects function).

    All items put into the cache are assigned a cost value based on the size of the data in bytes. So its generally recommended that you configure the cache using the totalCostLimit property.

    The default configuration is:

    • countLimit = 0
    • totalCostLimit = 5 MiB (i.e.: 1024 * 1024 * 5)

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSCache *_Nonnull nodeThumbnailsCache;

    Swift

    var nodeThumbnailsCache: NSCache<AnyObject, AnyObject> { get }
  • Direct access to the underlying in-memory cache container.

    You can configure the cache directly (via either countLimit and/or totalCostLimit), or you can flush the cache (via removeAllObjects function).

    All items put into the cache are assigned a cost value based on the size of the data in bytes. So its generally recommended that you configure the cache using the totalCostLimit property.

    The default configuration is:

    • countLimit = 0
    • totalCostLimit = 5 MiB (i.e.: 1024 * 1024 * 5)

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSCache *_Nonnull userAvatarsCache;

    Swift

    var userAvatarsCache: NSCache<AnyObject, AnyObject> { get }
  • Fetches the node’s thumbnail.

    Here’s how this works:

    • First, the in-memory cache is consulted to see if we have a ready image. That is, an image that’s already been loaded from an earlier request, and the result has been cached in memory.
    • If there’s a match in the cache, the preFetchBlock is invoked with it’s willFetch parameter set to FALSE. After which the method execution terminates - meaning the postFetchBlock is NOT invoked.
    • Otherwise the preFetchBlock is invoked with it’s willFetch parameter to to TRUE.
    • Then the node thumbnail is asynchronously loaded from disk (if available in the DiskManager), or downloaded from the cloud.
    • If the thumbnail is downloaded from the cloud, it will be cached in the DiskManager automatically.
    • After loading or downloading, the image is cached in memory, and forwarded to you via the postFetchBlock.

     

    Note

    You can contol the size of the in-memory cache via the nodeThumbnailsCache property.

    @important Empty results are also cached to prevent duplicate lookups. For example, if a node doesn’t have a thumbnail, the result of the lookup (the 404), will be cached. This results in the preFetchBlock being invoked with its willFetch parameter to to FALSE, and its image parameter set to nil.

    Declaration

    Objective-C

    - (nullable ZDCDownloadTicket *)
        fetchNodeThumbnail:(nonnull ZDCNode *)node
               withOptions:(nullable ZDCFetchOptions *)options
             preFetchBlock:(nonnull void (^)(UIImage *_Nullable, BOOL))preFetchBlock
            postFetchBlock:(nonnull void (^)(UIImage *_Nullable,
                                             NSError *_Nullable))postFetchBlock;

    Swift

    func fetchNodeThumbnail(_ node: ZDCNode, with options: ZDCFetchOptions?, preFetch preFetchBlock: (UIImage?, Bool) -> Void, postFetch postFetchBlock: @escaping (UIImage?, Error?) -> Void) -> ZDCDownloadTicket?

    Parameters

    node

    The node for which you wish to display the thumbnail.

    options

    If nil, the default options will be used.

    preFetchBlock

    This block is always invoked. And it’s invoked BEFORE this method returns. It only returns an image if there’s a match in the cache that can immediately be used. If the preFetchBlock parameter willFetch if FALSE, the postFetchBlock will NOT be invoked. Keep in mind that (image==nil && !willFetch) is a valid combination representing a previous fetch which resulted in no image for the request.

    postFetchBlock

    This method is invoked after the image has been read from disk or downloaded from the cloud. This block is only invoked if the preFetchBlock is invoked with its willFetch parameter set to true. This block is always invoked on the main thread.

  • Fetches the node’s thumbnail, and allows you to process the image.

    Here’s how this works:

    • A key is generated using a combination of the nodeID + processingID.
    • This key is used to check the in-memory cache to see if we have a ready image. That is, an image that’s already been loaded & processed from an earlier request, and the result (post-processing) has been cached in memory.
    • If there’s a match in the cache, the preFetchBlock is invoked with it’s willFetch parameter set to FALSE. After which the method execution terminates - meaning the postFetchBlock is NOT invoked.
    • Otherwise the preFetchBlock is invoked with it’s willFetch parameter to to TRUE.
    • Then the node thumbnail is asynchronously loaded from disk (if available in the DiskManager), or downloaded from the cloud.
    • If the thumbnail is downloaded from the cloud, it will be cached in the DiskManager automatically.
    • After loading or downloading, the processingBlock is invoked (on a background thread).
    • The image returned from the processingBlock will be cached in-memory, and forwarded to the user via the postFetchBlock.

     

    Note

    You can contol the size of the in-memory cache via the nodeThumbnailsCache property.

    @important Empty results are also cached to prevent duplicate lookups. For example, if a node doesn’t have a thumbnail, the result of the lookup (the 404), will be cached. This results in the preFetchBlock being invoked with its willFetch parameter to to FALSE, and its image parameter set to nil.

    Declaration

    Objective-C

    - (nullable ZDCDownloadTicket *)
        fetchNodeThumbnail:(nonnull ZDCNode *)node
               withOptions:(nullable ZDCFetchOptions *)options
              processingID:(nullable NSString *)processingID
           processingBlock:(nonnull ZDCImageProcessingBlock)imageProcessingBlock
             preFetchBlock:(nonnull void (^)(UIImage *_Nullable, BOOL))preFetchBlock
            postFetchBlock:(nonnull void (^)(UIImage *_Nullable,
                                             NSError *_Nullable))postFetchBlock;

    Swift

    func fetchNodeThumbnail(_ node: ZDCNode, with options: ZDCFetchOptions?, processingID: String?, processingBlock imageProcessingBlock: @escaping ZDCImageProcessingBlock, preFetch preFetchBlock: (UIImage?, Bool) -> Void, postFetch postFetchBlock: @escaping (UIImage?, Error?) -> Void) -> ZDCDownloadTicket?

    Parameters

    node

    The node for which you wish to display the thumbnail.

    options

    If nil, the default options will be used.

    processingID

    A unique identifier that distinguishes the results of this imageProcessingBlock from other imageProcessingBlocks that you may be using in other parts of your application. For example, if your block resizes the image to 64*64, then you might pass the string 64*64. If you pass a nil processingID, then the image won’t be cached in memory.

    imageProcessingBlock

    A block you can use to modify the image. For example you might scale the image to a certain size, round the corners, give it tint, etc. The block will be invoked on a background thread.

    preFetchBlock

    This block is always invoked. And it’s invoked BEFORE this method returns. It only returns an image if there’s a match in the cache that can immediately be used. If the preFetchBlock parameter willFetch if FALSE, the postFetchBlock will NOT be invoked. Keep in mind that (image==nil && !willFetch) is a valid combination representing a previous fetch which resulted in no image for the request.

    postFetchBlock

    This method is invoked after the image has been read from disk or downloaded from the cloud. And after the processingBlock has done its work. This block is only invoked if the preFetchBlock is invoked with its willFetch parameter set to true. This block is always invoked on the main thread.

  • Removes all cached thumbnail images for the given node.

    There’s usually little reason to use this method because the ImageManager automatically flushes its cache in response to changes in the DiskManager.

    Declaration

    Objective-C

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

    Swift

    func flushNodeThumbnailCache(_ nodeID: String)

    Parameters

    nodeID

    Which node’s thumbnail to flush from the cache (nodeID == ZDCNode.uuid)

  • Removes all cached thumbnail images for the given processingID.

    You might use this method if you have an infrequently used ViewController, and you’d prefer to flush the cache of all images it created since you don’t anticipate needing them again anytime soon.

    Declaration

    Objective-C

    - (void)flushNodeThumbnailCacheWithProcessingID:
        (nonnull NSString *)processingID;

    Swift

    func flushNodeThumbnailCache(withProcessingID processingID: String)

    Parameters

    processingID

    A processingID that was used in fetchNodeThumbnail:withProcessingID::::

  • Fetches the user’s avatar.

    Here’s how this works:

    • First, the in-memory cache is consulted to see if we have a ready image. That is, an image that’s already been loaded from an earlier request, and the result has been cached in memory.
    • If there’s a match in the cache, the preFetchBlock is invoked with it’s willFetch parameter set to FALSE. After which the method execution terminates - meaning the postFetchBlock is NOT invoked.
    • Otherwise the preFetchBlock is invoked with it’s willFetch parameter to to TRUE.
    • Then the user avatar is asynchronously loaded from disk (if available in the DiskManager), or downloaded from the cloud.
    • If the thumbnail is downloaded from the cloud, it will be cached in the DiskManager automatically.
    • After loading or downloading, the image is cached in memory, and forwarded to you via the postFetchBlock.

     

    Note

    You can contol the size of the in-memory cache via the userAvatarsCache property.

    @important Empty results are also cached to prevent duplicate lookups. For example, if a user doesn’t have an avatar, the result of the lookup (the 404), will be cached. This results in the preFetchBlock being invoked with its willFetch parameter to to FALSE, and its image parameter set to nil.

    Declaration

    Objective-C

    - (nullable ZDCDownloadTicket *)
        fetchUserAvatar:(nonnull ZDCUser *)user
            withOptions:(nullable ZDCFetchOptions *)options
          preFetchBlock:(nonnull void (^)(UIImage *_Nullable, BOOL))preFetchBlock
         postFetchBlock:(nonnull void (^)(UIImage *_Nullable,
                                          NSError *_Nullable))postFetchBlock;

    Swift

    func fetchUserAvatar(_ user: ZDCUser, with options: ZDCFetchOptions?, preFetch preFetchBlock: (UIImage?, Bool) -> Void, postFetch postFetchBlock: @escaping (UIImage?, Error?) -> Void) -> ZDCDownloadTicket?

    Parameters

    user

    The user for which you wish to display the avatar.

    options

    If nil, the default options will be used.

    preFetchBlock

    This block is always invoked. And it’s invoked BEFORE this method returns. It only returns an image if there’s a match in the cache that can immediately be used. If the preFetchBlock parameter willFetch if FALSE, the postFetchBlock will NOT be invoked. Keep in mind that (image==nil && !willFetch) is a valid combination representing a previous fetch which resulted in no image for the request.

    postFetchBlock

    This method is invoked after the image has been read from disk or downloaded from the cloud. This block is only invoked if the preFetchBlock is invoked with its willFetch parameter set to true. This block is always invoked on the main thread.

  • Fetches the node’s thumbnail, and allows you to process the image.

    Here’s how this works:

    • A key is generated using a combination of the nodeID + processingID.
    • This key is used to check the in-memory cache (userAvatarsCache) to see if we have a ready image. That is, an image that’s already been loaded & processed from an earlier request, and the result (post-processing) has been cached in memory.
    • If there’s a match in the cache), the preFetchBlock is invoked with it’s willFetch parameter set to FALSE. After which the method execution terminates - meaning neither the processingBlock nor the postFetchBlock are invoked.
    • Otherwise the preFetchBlock is invoked with it’s willFetch parameter to to TRUE.
    • Then the user avatar is asynchronously is loaded from disk (if available in the DiskManager), or downloaded from the cloud.
    • If the user avatar is downloaded from the cloud, it will be cached in the DiskManager automatically.
    • After loading or downloading, the processingBlock is invoked (on a background thread).
    • The image returned from the processingBlock will be cached in-memory, and forwarded to the user via the postFetchBlock.

     

    Note

    You can contol the size of the in-memory cache via the nodeThumbnailsCache property.

    @important Empty results are also cached to prevent duplicate lookups. For example, if a user doesn’t have an avatar, the result of the lookup (the 404), will be cached. This results in the preFetchBlock being invoked with its willFetch parameter to to FALSE, and its image parameter set to nil.

    Declaration

    Objective-C

    - (nullable ZDCDownloadTicket *)
        fetchUserAvatar:(nonnull ZDCUser *)user
            withOptions:(nullable ZDCFetchOptions *)options
           processingID:(nullable NSString *)processingID
        processingBlock:(nonnull ZDCImageProcessingBlock)imageProcessingBlock
          preFetchBlock:(nonnull void (^)(UIImage *_Nullable, BOOL))preFetchBlock
         postFetchBlock:(nonnull void (^)(UIImage *_Nullable,
                                          NSError *_Nullable))postFetchBlock;

    Swift

    func fetchUserAvatar(_ user: ZDCUser, with options: ZDCFetchOptions?, processingID: String?, processingBlock imageProcessingBlock: @escaping ZDCImageProcessingBlock, preFetch preFetchBlock: (UIImage?, Bool) -> Void, postFetch postFetchBlock: @escaping (UIImage?, Error?) -> Void) -> ZDCDownloadTicket?

    Parameters

    user

    The user for which you wish to fetch the avatar.

    options

    If nil, the default options will be used.

    processingID

    A unique identifier that distinguishes the results of this imageProcessingBlock from other imageProcessingBlocks that you may be using in other parts of your application. For example, if your block resizes the image to 64*64, then you might pass the string 64*64. If you pass a nil processingID, then the image won’t be cached in memory.

    imageProcessingBlock

    A block you can use to modify the image. For example you might scale the image to a certain size, round the corners, give it tint, etc. The block will be invoked on a background thread.

    preFetchBlock

    This block is always invoked. And it’s invoked BEFORE this method returns. It only returns an image if there’s a match in the cache that can immediately be used. If the preFetchBlock parameter willFetch if FALSE, the postFetchBlock will NOT be invoked. Keep in mind that (image==nil && !willFetch) is a valid combination representing a previous fetch which resulted in no image for the request.

    postFetchBlock

    This method is invoked after the image has been read from disk or downloaded from the cloud. And after the processingBlock has done its work. This block is only invoked if the preFetchBlock is invoked with its willFetch parameter set to true. This block is always invoked on the main thread.

  • Fetches the node’s thumbnail, and allows you to process the image.

     

    Note

    You can contol the size of the in-memory cache via the nodeThumbnailsCache property.

    @important Empty results are also cached to prevent duplicate lookups. For example, if a user doesn’t have an avatar, the result of the lookup (the 404), will be cached. This results in the preFetchBlock being invoked with its willFetch parameter to to FALSE, and its image parameter set to nil.

    Declaration

    Objective-C

    - (nullable ZDCDownloadTicket *)
        fetchUserAvatar:(nonnull ZDCSearchResult *)searchResult
             identityID:(nullable NSString *)identityID
           processingID:(nullable NSString *)processingID
        processingBlock:(nonnull ZDCImageProcessingBlock)imageProcessingBlock
          preFetchBlock:(nonnull void (^)(UIImage *_Nullable, BOOL))preFetchBlock
         postFetchBlock:(nonnull void (^)(UIImage *_Nullable,
                                          NSError *_Nullable))postFetchBlock;

    Swift

    func fetchUserAvatar(_ searchResult: ZDCSearchResult, identityID: String?, processingID: String?, processingBlock imageProcessingBlock: @escaping ZDCImageProcessingBlock, preFetch preFetchBlock: (UIImage?, Bool) -> Void, postFetch postFetchBlock: @escaping (UIImage?, Error?) -> Void) -> ZDCDownloadTicket?

    Parameters

    searchResult

    A search result from ZDCUserSearchManager.

    identityID

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

    processingID

    A unique identifier that distinguishes the results of this imageProcessingBlock from other imageProcessingBlocks that you may be using in other parts of your application. For example, if your block resizes the image to 64*64, then you might pass the string 64*64. If you pass a nil processingID, then the image won’t be cached in memory.

    imageProcessingBlock

    A block you can use to modify the image. For example you might scale the image to a certain size, round the corners, give it tint, etc. The block will be invoked on a background thread.

    preFetchBlock

    This block is always invoked. And it’s invoked BEFORE this method returns. It only returns an image if there’s a match in the cache that can immediately be used. If the preFetchBlock parameter willFetch if FALSE, the postFetchBlock will NOT be invoked. Keep in mind that (image==nil && !willFetch) is a valid combination representing a previous fetch which resulted in no image for the request.

    postFetchBlock

    This method is invoked after the image has been read from disk or downloaded from the cloud. And after the processingBlock has done its work. This block is only invoked if the preFetchBlock is invoked with its willFetch parameter set to true. This block is always invoked on the main thread.

  • Removes all cached avatar images for the given user.

    There’s usually little reason to use this method because the ImageManager automatically flushes its cache in response to changes in the DiskManager.

    Declaration

    Objective-C

    - (void)flushUserAvatarsCache:(nonnull NSString *)userID;

    Swift

    func flushUserAvatarsCache(_ userID: String)

    Parameters

    userID

    Which user’s thumbnail to flush from the cache (userID == ZDCUser.uuid)

  • Removes all cached avatar images for the given processingID.

    You might use this method if you have an infrequently used ViewController, and you’d prefer to flush the cache of all images it created since you don’t anticipate needing them again anytime soon.

    Declaration

    Objective-C

    - (void)flushUserAvatarsCacheWithProcessingID:(nonnull NSString *)processingID;

    Swift

    func flushUserAvatarsCache(withProcessingID processingID: String)

    Parameters

    processingID

    A processingID that was used in fetchUserAvatar:withProcessingID::::

  • Returns the default user avatar used by the framework.

    Declaration

    Objective-C

    - (nonnull UIImage *)defaultUserAvatar;

    Swift

    func defaultUserAvatar() -> UIImage
  • Returns the default multi-user avatar used by the framework.

    Declaration

    Objective-C

    - (nonnull UIImage *)defaultMultiUserAvatar;

    Swift

    func defaultMultiUserAvatar() -> UIImage