CBLCameraInitiatedTransferResult

Objective-C

@protocol CBLCameraInitiatedTransferResult <NSObject>

Swift

protocol CameraInitiatedTransferResult : NSObjectProtocol

The result of a camera-initiated transfer.

Result objects are stored entirely locally, and as such are not under the time pressure that the intial camera- initiated transfer object is. However, they can be fairly resource heavy (especially when the transfer is of a RAW image) so it’s recommended that they are dealt with reasonably quickly.

How this object manages its resources is an implementation detail, and any buffers of cache files it creates will be cleaned up when the object is deallocated. To take ownership of the transfer result, use the appropriate methods to extract representations into RAM or to disk.

  • The representations available in this transfer result.

    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)containsRepresentation:
    (CBLCameraInitiatedTransferRepresentation)representation;

    Swift

    func contains(_ representation: CameraInitiatedTransferRepresentation) -> Bool

  • Returns YES if not saving the contents of this result 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 }

  • A file name hint for the original representation of the image, if available.

    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 a suggested file name extension for the given representation or nil if the representation isn’t available.

    To match camera conventions, extensions will be uppercase (“JPG”, “CR3”, “ARW”, “HEIC”, etc).

    Warning

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

    Note

    This method is guaranteed to return a valid value as long as the representation is available. This can be useful if the fileNameHint property is nil and you need to write a representation to disk.

    Declaration

    Objective-C

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

    Swift

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

  • Returns the type UTI for the given representation, or nil if the representation isn’t available.

    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 representation is in a RAW image format not recognised by the operating system.

    Declaration

    Objective-C

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

    Swift

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

  • Returns the file size of a given representation, or 0 if the size is unknown or the representation isn’t available.

    Note

    The file size of the preview representation of a result generated with an original representation may be unknown, since the preview is generated on-demand in this situation.

    Warning

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

    Declaration

    Objective-C

    - (NSInteger)fileSizeForRepresentation:
    (CBLCameraInitiatedTransferRepresentation)representation;

    Swift

    func fileSize(for representation: CameraInitiatedTransferRepresentation) -> Int

  • Write the given representation to disk.

    Warning

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

    Declaration

    Objective-C

    - (void)writeRepresentation:
            (CBLCameraInitiatedTransferRepresentation)representation
                      toURL:(NSURL *_Nonnull)destinationUrl
          completionHandler:
              (nonnull CBLErrorableOperationCallback)completionHandler;

    Swift

    func write(_ representation: CameraInitiatedTransferRepresentation, to destinationUrl: URL) async throws

    Parameters

    representation

    The representation to write.
    destinationUrl

    The URL at which to write the representation. CascableCore will attempt to create the parent directory tree if it isn’t already present.
    completionHandler

    The completion handler, called on the main queue, when the operation succeeds or fails.

  • Write the given representation to disk.

    Warning

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

    Declaration

    Objective-C

    - (void)writeRepresentation:
            (CBLCameraInitiatedTransferRepresentation)representation
                      toURL:(NSURL *_Nonnull)destinationUrl
            completionQueue:(dispatch_queue_t _Nonnull)completionQueue
          completionHandler:
              (nonnull CBLErrorableOperationCallback)completionHandler;

    Swift

    func write(_ representation: CameraInitiatedTransferRepresentation, to destinationUrl: URL, completionQueue: dispatch_queue_t) async throws

    Parameters

    representation

    The representation to write.
    destinationUrl

    The URL at which to write the representation. CascableCore will attempt to create the parent directory tree if it isn’t already present.
    completionQueue

    The queue on which to call the completion handler.
    completionHandler

    The completion handler to be called when the operation succeeds or fails.

  • Retrieve the given representation as an in-memory data object.

    Warning

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

    Warning

    This operation may fail if the representation is large enough to risk crashes due to high memory usage. If this happens, the resulting error will have the code CBLErrorCodeObjectTooLarge.

    Declaration

    Objective-C

    - (void)generateDataForRepresentation:
            (CBLCameraInitiatedTransferRepresentation)representation
                    completionHandler:
                        (void (^_Nonnull)(NSData *_Nullable,
                                          NSError *_Nullable))completionHandler;

    Swift

    func generateData(for representation: CameraInitiatedTransferRepresentation) async throws -> Data

    Parameters

    representation

    The representation to retrieve.
    completionHandler

    The completion handler, called on the main queue, when the operation succeeds or fails.

  • Retrieve the given representation as an in-memory data object.

    Warning

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

    Warning

    This operation may fail if the representation is large enough to risk crashes due to high memory usage. If this happens, the resulting error will have the code CBLErrorCodeObjectTooLarge.

    Declaration

    Objective-C

    - (void)generateDataForRepresentation:
            (CBLCameraInitiatedTransferRepresentation)representation
                      completionQueue:(dispatch_queue_t _Nonnull)completionQueue
                    completionHandler:
                        (void (^_Nonnull)(NSData *_Nullable,
                                          NSError *_Nullable))completionHandler;

    Swift

    func generateData(for representation: CameraInitiatedTransferRepresentation, completionQueue: dispatch_queue_t) async throws -> Data

    Parameters

    representation

    The representation to retrieve.
    completionQueue

    The queue on which to call the completion handler.
    completionHandler

    The completion handler to be called when the operation succeeds or fails.

  • Generate an image from the preview representation.

    Note

    This method requires that the result contains the CBLCameraInitiatedTransferRepresentationPreview representation.

    Declaration

    Objective-C

    - (void)generatePreviewImage:
    (void (^_Nonnull)(UIImage *_Nullable, NSError *_Nullable))completionHandler;

    Swift

    func generatePreviewImage() async throws -> UIImage

    Parameters

    completionHandler

    The completion handler, called on the main queue, when the operation succeeds or fails.