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 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 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 -> 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 -> 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.