CBLCameraInitiatedTransferRequest

Objective-C

@protocol CBLCameraInitiatedTransferRequest <NSObject>

Swift

protocol CameraInitiatedTransferRequest : NSObjectProtocol

A camera-initiated transfer is a request from a camera to transfer an image file (or at least, a representation of one such as a preview) to the connected host. This typically happens soon after a shot is taken, and can allow the previewing and transferring of images even if the camera currently doesn’t allow access to its storage.

Camera-initiated transfers can be time-sensitive as the camera moves on to newer images or flushes buffers — they should be dealt with expediently.

In some cases, the camera-initiated transfer to the host may be the only destination for an image. Commonly referred to as “tethered shooting” (or at least a variant of it), the camera might not attempt (or not be able to) save the image to its own storage. If this is the case, not correctly handling a camera-initiated transfer will case data loss. Check the -isOnlyDestinationForImage property — if that returns YES, not transferring and saving the original representation of the image will cause it to be lost.

  • Returns YES if the transfer request is still valid, otherwise NO. Transfers will time out after some amount of time.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isValid;

    Swift

    var isValid: Bool { get }

  • Returns YES if not executing this camera-initiated transfer may cause data loss. For example, a camera set to only save images to the connected host would set this to YES.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL isOnlyDestinationForImage;

    Swift

    var isOnlyDestinationForImage: Bool { get }

  • Returns YES if not executing this camera-initiated transfer will “clog up” the camera’s transfer buffer. This can return YES independently of the isOnlyDestinationForImage property. Not executing transfers that have this property set will stop delivery of further transfers.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL executionRequiredToClearBuffer;

    Swift

    var executionRequiredToClearBuffer: Bool { get }

  • Returns the source image’s file name, if available. Not guaranteed to exactly match the name on the camera’s storage. This value may not be available until the transfer completes (or at all) — see CBLCameraInitiatedTransferResult.

    Declaration

    Objective-C

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

    Swift

    var fileNameHint: String? { get }

  • Returns the date and time at which the request was produced. CascableCore will attempt to match this value to the underlying image’s EXIF timestamp, if available. Otherwise, this will be the date and time at which the request was received from the camera.

    Note

    Since EXIF doesn’t tend to have the concept of timezones, dates from this property will also adhere to that “standard” in that they’ll be expressed in the GMT+0 timezone. I.e., an image produced at 14:00 local time in California will actually be expressed at 14:00 GMT. When dealing with these values (or showing them to the user), make sure you account for this - when using date formatters, this as simple as explicitly setting the formatter’s timezone to GMT+0.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nonnull) NSDate *dateProduced;

    Swift

    var dateProduced: Date { get }

  • Returns an option set of the representations available for this transfer.

    Common combinations are preview-only, or preview and original.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLCameraInitiatedTransferRepresentation availableRepresentations;

    Swift

    var availableRepresentations: CameraInitiatedTransferRepresentation { get }

  • Returns YES if the receiver can provide the given representation, otherwise NO.

    Declaration

    Objective-C

    - (BOOL)canProvideRepresentation:
    (CBLCameraInitiatedTransferRepresentation)representation;

    Swift

    func canProvide(_ representation: CameraInitiatedTransferRepresentation) -> Bool

  • Returns a predicted file size for the given representation, or 0 if the representation isn’t available or its size is currently unknown.

    Note

    It’s very rare that a preview representation’s size will be known at this stage.

    Warning

    You must only pass a single representation to this method, otherwise 0 will be returned.

    Declaration

    Objective-C

    - (NSInteger)predictedFileSizeForRepresentation:
    (CBLCameraInitiatedTransferRepresentation)representation;

    Swift

    func predictedFileSize(for representation: CameraInitiatedTransferRepresentation) -> Int

  • Returns the file type UTI for the given representation, or nil if the representation isn’t available or if the format of the requested representation is unknown before loading.

    Warning

    You must only pass a single representation to this method, otherwise nil will be returned.

    Note

    This method may fall back to returning kUTTypeData if the original representation is in a RAW image format not recognised by the operating system.

    Declaration

    Objective-C

    - (NSString *_Nullable)predictedUTIForRepresentation:
    (CBLCameraInitiatedTransferRepresentation)representation;

    Swift

    func predictedUTI(for representation: CameraInitiatedTransferRepresentation) -> String?

  • Returns the state of the transfer. A camera-initiated transfer can only be performed once.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLCameraInitiatedTransferState transferState;

    Swift

    var transferState: CameraInitiatedTransferState { get }

  • Returns the progress of the transfer, if available. While this property is marked nonnull for binding purposes, the values in the returned progress object are only meaningful when the transfer is in progress.

    Not all cameras provide progress information — in these cases, the progress will remain indeterminate.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nonnull) NSProgress *transferProgress;

    Swift

    var transferProgress: Progress { get }

  • Execute the camera-initiated transfer if it’s still valid.

    If possible, CascableCore will optimise the transfer to reduce the amount of data transferred (and therefore time needed). For example, if a camera-initiated transfer request has both the preview and original representations available, CascableCore may perform a partial transfer if only the preview representation is requested. This is particularly useful if, for example, you want to show previews of RAW images.

    Warning

    A camera-initiated transfer can only be performed once.

    Declaration

    Objective-C

    - (void)
    executeTransferForRepresentations:
        (CBLCameraInitiatedTransferRepresentation)representations
                    completionHandler:
                        (CBLCameraInitiatedTransferCompletionHandler _Nonnull)
                            completionHandler;

    Swift

    func executeTransfer(for representations: CameraInitiatedTransferRepresentation) async throws -> any CameraInitiatedTransferResult

    Parameters

    representations

    The representations to transfer from the camera. Must be present in the availableRepresentations property.
    completionHandler

    The completion handler, to be called on the main queue, when the transfer succeeds or fails.

  • Execute the camera-initiated transfer if it’s still valid.

    If possible, CascableCore will optimise the transfer to reduce the amount of data transferred (and therefore time needed). For example, if a camera-initiated transfer request has both the preview and original representations available, CascableCore may perform a partial transfer if only the preview representation is requested. This is particularly useful if, for example, you want to show previews of RAW images.

    Warning

    A camera-initiated transfer can only be performed once.

    Declaration

    Objective-C

    - (void)
    executeTransferForRepresentations:
        (CBLCameraInitiatedTransferRepresentation)representations
                      completionQueue:(dispatch_queue_t _Nonnull)completionQueue
                    completionHandler:
                        (CBLCameraInitiatedTransferCompletionHandler _Nonnull)
                            completionHandler;

    Swift

    func executeTransfer(for representations: CameraInitiatedTransferRepresentation, completionQueue: dispatch_queue_t) async throws -> any CameraInitiatedTransferResult

    Parameters

    representations

    The representations to transfer from the camera. Must be present in the availableRepresentations property.
    completionQueue

    The queue on which to deliver the completion handler.
    completionHandler

    The completion handler to be calle when the transfer succeeds or fails.