CBLFileSystemItem

Objective-C

@protocol CBLFileSystemItem <NSObject>

Swift

protocol FileSystemItem : NSObjectProtocol

A filesystem item represents a file or folder on the camera’s storage.

  • Returns YES if the item’s metadata has been loaded, otherwise NO.

    If metadata hasn’t been loaded, many properties will return nil or zero values.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL metadataLoaded;

    Swift

    var metadataLoaded: Bool { get }

  • Returns the name of the file.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSString *name;

    Swift

    var name: String? { get }

  • Returns the size of the file, or zero for directories or items whose metadata hasn’t been loaded.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger size;

    Swift

    var size: UInt { get }

  • Returns the internal handle to the file.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) id handle;

    Swift

    var handle: Any? { get }

  • Returns YES if the file is protected (i.e., cannot be deleted), otherwise NO.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isProtected;

    Swift

    var isProtected: Bool { get }

  • Returns the creation date of the file, or nil for items whose metadata hasn’t been loaded.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSDate *dateCreated;

    Swift

    var dateCreated: Date? { get }

  • The item’s rating. Follows the IPTC StarRating spec (0 = no rating, otherwise 1-5 stars).

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSInteger rating;

    Swift

    var rating: Int { get }

  • The item’s rating mutation type. Folders and unsupported files will return CBLFileSystemItemMutableRatingTypeNone, as will items without loaded metadata (i.e., -metadataLoaded returns NO), and items on a camera that doesn’t support mutating an item’s rating via remote control at all.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLFileSystemItemMutableRatingType ratingMutationType;

    Swift

    var ratingMutationType: FileSystemItemMutableRatingType { get }

  • Attempt to update the item’s rating to the given value. See the -ratingMutationType property for valid values. Values will be clamped to the allowable range.

    Due to the caveats mentioned below, it’s highly recommended that you observe the -rating property for changes to an item’s rating rather than rely on the completion handler of this method.

    @note: Updating the rating of an image may change the rating of other, releated images (such as the other side of a RAW+JPEG pair).

    @note: The completion handler of this method indicates whether the command was accepted by the camera and didn’t immediately fail. Some cameras will accept the command but still not update the rating in some instances - we’ve observed this happening on Canon cameras when trying to apply a rating to images shot with a different camera model, for example.

    Declaration

    Objective-C

    - (void)updateRatingTo:(NSInteger)newRating
     completionHandler:(nonnull CBLErrorableOperationCallback)completionHandler;

    Swift

    func updateRating(to newRating: Int) async throws

  • Returns the parent item of this file, or nil if the receiver represents the root directory.

    Declaration

    Objective-C

    @property (nonatomic, weak, readonly, nullable) id<CBLFileSystemFolderItem> parent;

    Swift

    weak var parent: (any FileSystemFolderItem)? { get }

  • Returns the storage device on which this file is placed.

    Declaration

    Objective-C

    @property (nonatomic, weak, readonly, nullable) id<CBLFileStorage> storage;

    Swift

    weak var storage: (any FileStorage)? { get }

  • Returns YES if the file is a known image type, else NO.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isKnownImageType;

    Swift

    var isKnownImageType: Bool { get }

  • Returns YES if the file is a known video type, else NO.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isKnownVideoType;

    Swift

    var isKnownVideoType: Bool { get }

  • Permanently removes the file from the device.

    Declaration

    Objective-C

    - (void)removeFromDevice:(nonnull CBLErrorableOperationCallback)block;

    Swift

    func removeFromDevice(_ block: @escaping ErrorableOperationCallback)

  • Returns YES if removing this item could have side effects — for example, removing one image from a RAW+JPEG pair will also remove the other.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL removalRemovesPairedItems;

    Swift

    var removalRemovesPairedItems: Bool { get }

  • Loads the metadata for the receiver if it hasn’t already been loaded.

    If metadata has already been loaded, the callback block will be immediately called with no error.

    Declaration

    Objective-C

    - (void)loadMetadata:(nonnull CBLErrorableOperationCallback)block;

    Swift

    func loadMetadata(_ block: @escaping ErrorableOperationCallback)

    Parameters

    block

    The block to trigger after loading completes or fails. Will be called on the main queue.

  • Fetch the thumbnail of the given file system item.

    Declaration

    Objective-C

    - (void)
    fetchThumbnailWithPreflightBlock:(nonnull CBLPreviewImagePreflight)preflight
              thumbnailDeliveryBlock:(nonnull CBLPreviewImageDelivery)delivery;

    Swift

    func fetchThumbnail(preflightBlock preflight: @escaping PreviewImagePreflight, thumbnailDeliveryBlock delivery: @escaping PreviewImageDelivery)

    Parameters

    preflight

    A block that will be called when the thumbnail is about to be fetched. Return YES to allow the operation to continue, or NO to cancel.
    delivery

    The block that will be called when the thumbnail has successfully been fetched, or an error occurred.

  • Fetch the thumbnail of the given file system item.

    Declaration

    Objective-C

    - (void)
    fetchThumbnailWithPreflightBlock:(nonnull CBLPreviewImagePreflight)preflight
              thumbnailDeliveryBlock:(nonnull CBLPreviewImageDelivery)delivery
                       deliveryQueue:(nonnull dispatch_queue_t)deliveryQueue;

    Swift

    func fetchThumbnail(preflightBlock preflight: @escaping PreviewImagePreflight, thumbnailDeliveryBlock delivery: @escaping PreviewImageDelivery, deliveryQueue: dispatch_queue_t)

    Parameters

    preflight

    A block that will be called when the thumbnail is about to be fetched. Return YES to allow the operation to continue, or NO to cancel.
    delivery

    The block that will be called when the thumbnail has successfully been fetched, or an error occurred.
    deliveryQueue

    The queue on which the delivery block will be called.

  • Fetch image metadata (EXIF, IPTC, etc) for the given file system item. Only works with known image types.

    The returned metadata is in the form of an ImageIO-compatible dictionary. See CGImageProperties.h for details.

    Declaration

    Objective-C

    - (void)fetchEXIFMetadataWithPreflightBlock:(nonnull CBLEXIFPreflight)preflight
                      metadataDeliveryBlock:(nonnull CBLEXIFDelivery)delivery;

    Swift

    func fetchEXIFMetadata(preflightBlock preflight: @escaping EXIFPreflight, metadataDeliveryBlock delivery: @escaping EXIFDelivery)

    Parameters

    preflight

    A block that will be called when the metadata is about to be fetched. Return YES to allow the operation to continue, or NO to cancel.
    delivery

    The block that will be called when the metadata has successfully been fetched, or an error occurred.

  • Fetch image metadata (EXIF, IPTC, etc) for the given file system item. Only works with known image types.

    The returned metadata is in the form of an ImageIO-compatible dictionary. See CGImageProperties.h for details.

    Declaration

    Objective-C

    - (void)fetchEXIFMetadataWithPreflightBlock:(nonnull CBLEXIFPreflight)preflight
                      metadataDeliveryBlock:(nonnull CBLEXIFDelivery)delivery
                              deliveryQueue:
                                  (nonnull dispatch_queue_t)deliveryQueue;

    Swift

    func fetchEXIFMetadata(preflightBlock preflight: @escaping EXIFPreflight, metadataDeliveryBlock delivery: @escaping EXIFDelivery, deliveryQueue: dispatch_queue_t)

    Parameters

    preflight

    A block that will be called when the metadata is about to be fetched. Return YES to allow the operation to continue, or NO to cancel.
    delivery

    The block that will be called when the metadata has successfully been fetched, or an error occurred.
    deliveryQueue

    The queue on which the delivery block will be called.

  • Fetch video metadata for the given file system item. Only works with known video types.

    Declaration

    Objective-C

    - (void)fetchVideoMetadataWithPreflightBlock:
            (nonnull CBLVideoMetadataPreflight)preflight
                       metadataDeliveryBlock:
                           (nonnull CBLVideoMetadataDelivery)delivery;

    Swift

    func fetchVideoMetadata(preflightBlock preflight: @escaping VideoMetadataPreflight, metadataDeliveryBlock delivery: @escaping VideoMetadataDelivery)

    Parameters

    preflight

    A block that will be called when the metadata is about to be fetched. Return YES to allow the operation to continue, or NO to cancel.
    delivery

    The block that will be called when the metadata has successfully been fetched, or an error occurred.

  • Fetch video metadata for the given file system item. Only works with known video types.

    Declaration

    Objective-C

    - (void)fetchVideoMetadataWithPreflightBlock:
            (nonnull CBLVideoMetadataPreflight)preflight
                       metadataDeliveryBlock:
                           (nonnull CBLVideoMetadataDelivery)delivery
                               deliveryQueue:
                                   (nonnull dispatch_queue_t)deliveryQueue;

    Swift

    func fetchVideoMetadata(preflightBlock preflight: @escaping VideoMetadataPreflight, metadataDeliveryBlock delivery: @escaping VideoMetadataDelivery, deliveryQueue: dispatch_queue_t)

    Parameters

    preflight

    A block that will be called when the metadata is about to be fetched. Return YES to allow the operation to continue, or NO to cancel.
    delivery

    The block that will be called when the metadata has successfully been fetched, or an error occurred.
    deliveryQueue

    The queue on which the delivery block will be called.

  • Fetch a preview of the given file system item.

    Declaration

    Objective-C

    - (void)
    fetchPreviewWithPreflightBlock:(nonnull CBLPreviewImagePreflight)preflight
              previewDeliveryBlock:(nonnull CBLPreviewImageDelivery)delivery;

    Swift

    func fetchPreview(preflightBlock preflight: @escaping PreviewImagePreflight, previewDeliveryBlock delivery: @escaping PreviewImageDelivery)

    Parameters

    preflight

    A block that will be called when the preview is about to be fetched. Return YES to allow the operation to continue, or NO to cancel.
    delivery

    The block that will be called when the preview has successfully been fetched, or an error occurred.

  • Fetch a preview of the given file system item.

    Declaration

    Objective-C

    - (void)fetchPreviewWithPreflightBlock:
            (nonnull CBLPreviewImagePreflight)preflight
                  previewDeliveryBlock:(nonnull CBLPreviewImageDelivery)delivery
                         deliveryQueue:(nonnull dispatch_queue_t)deliveryQueue;

    Swift

    func fetchPreview(preflightBlock preflight: @escaping PreviewImagePreflight, previewDeliveryBlock delivery: @escaping PreviewImageDelivery, deliveryQueue: dispatch_queue_t)

    Parameters

    preflight

    A block that will be called when the preview is about to be fetched. Return YES to allow the operation to continue, or NO to cancel.
    delivery

    The block that will be called when the preview has successfully been fetched, or an error occurred.
    deliveryQueue

    The queue on which the delivery block will be called.

  • Stream a file from the device.

    File streaming takes place in a series of block callbacks — one to allow you to set up any state required to receive the file data, then a series of delivery callbacks containing chunks of the file, then a completion callback to allow post-stream cleanup.

    Warning

    The callback blocks will be executed on the main queue.

    @returns Returns a progress object that can be use to track the progress of the transfer.

    Declaration

    Objective-C

    - (NSProgress *_Nonnull)
    streamItemWithPreflightBlock:(nonnull CBLFileStreamPreflight)preflight
              chunkDeliveryBlock:
                  (nonnull CBLFileStreamChunkDelivery)chunkDelivery
                   completeBlock:(nonnull CBLFileStreamCompletion)complete;

    Swift

    func streamItem(preflightBlock preflight: @escaping FileStreamPreflight, chunkDeliveryBlock chunkDelivery: @escaping FileStreamChunkDelivery, complete: @escaping FileStreamCompletion) -> Progress

    Parameters

    preflight

    Block to be called exactly once before the stream is started. The value returned here will be passed as the context parameter of the chunkDelivery and complete blocks.
    chunkDelivery

    This block will be called zero or more times in succession to deliver the file’s data. The context parameter of this block will contain the value returned in the preflight block. In some circumstances, this block may be invoked with an empty/zero-length chunk of data. Make sure your code handles this case properly. Such a delivery should not be treated as an error, and you should return the desired instruction as normal.
    complete

    Block to be called exactly once after the last data chunk has been delivered (if any). If the stream failed or was cancelled, the error parameter will be non-nil and you should delete anything written to disk as the file won’t be complete. The context parameter of this block will contain the value returned in the preflight block.

  • Stream a file from the device.

    File streaming takes place in a series of block callbacks — one to allow you to set up any state required to receive the file data, then a series of delivery callbacks containing chunks of the file, then a completion callback to allow post-stream cleanup.

    @returns Returns a progress object that can be use to track the progress of the transfer.

    Declaration

    Objective-C

    - (NSProgress *_Nonnull)
    streamItemWithPreflightBlock:(nonnull CBLFileStreamPreflight)preflight
                  preflightQueue:(nonnull dispatch_queue_t)preflightQueue
              chunkDeliveryBlock:
                  (nonnull CBLFileStreamChunkDelivery)chunkDelivery
                   deliveryQueue:(nonnull dispatch_queue_t)deliveryQueue
                   completeBlock:(nonnull CBLFileStreamCompletion)complete
                   completeQueue:(nonnull dispatch_queue_t)completeQueue;

    Swift

    func streamItem(preflightBlock preflight: @escaping FileStreamPreflight, preflightQueue: dispatch_queue_t, chunkDeliveryBlock chunkDelivery: @escaping FileStreamChunkDelivery, deliveryQueue: dispatch_queue_t, complete: @escaping FileStreamCompletion, complete completeQueue: dispatch_queue_t) -> Progress

    Parameters

    preflight

    Block to be called exactly once before the stream is started. The value returned here will be passed as the context parameter of the chunkDelivery and complete blocks.
    preflightQueue

    The queue on which to execute the preflight block.
    chunkDelivery

    This block will be called zero or more times in succession to deliver the file’s data. The context parameter of this block will contain the value returned in the preflight block. In some circumstances, this block may be invoked with an empty/zero-length chunk of data. Make sure your code handles this case properly. Such a delivery should not be treated as an error, and you should return the desired instruction as normal.
    deliveryQueue

    The queue on which to execute the delivery block.
    complete

    Block to be called exactly once after the last data chunk has been delivered (if any). If the stream failed or was cancelled, the error parameter will be non-nil and you should delete anything written to disk as the file won’t be complete. The context parameter of this block will contain the value returned in the preflight block.
    completeQueue

    The queue on which to execute the completion block.