CBLCameraCore

Objective-C

@protocol CBLCameraCore <NSObject>

Swift

protocol CameraCore : NSObjectProtocol

Camera connection, disconnection and status methods.

  • Returns the camera’s “friendly” identifier, typically the serial number.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) NSString *friendlyIdentifier;

    Swift

    var friendlyIdentifier: String? { get }

  • Returns YES if the instance is connected to a physical camera, otherwise NO.

    The connectionState property returns more fine-grained detail about the camera’s state. The value of this property is equivalent to (connectionState == CBLCameraConnectionStateConnected).

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL connected;

    Swift

    var connected: Bool { get }

  • Returns an object representing information about the device. Will be nil if not connected.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nullable) id<CBLDeviceInfo> deviceInfo;

    Swift

    var deviceInfo: (any DeviceInfo)? { get }

  • Returns the CBLCameraDiscoveryService used to connect this camera.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly, nonnull) id<CBLCameraDiscoveryService> service;

    Swift

    var service: any CameraDiscoveryService { get }

  • Returns the CBLCameraFamily for this camera.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLCameraFamily cameraFamily;

    Swift

    var cameraFamily: CameraFamily { get }

  • Returns the CBLCameraTransport for this camera.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLCameraTransport cameraTransport;

    Swift

    var cameraTransport: CameraTransport { get }

  • Returns the friendly, user-set name of the camera, if available. May be nil until the camera is connected.

    Declaration

    Objective-C

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

    Swift

    var friendlyDisplayName: String? { get }

  • Returns the connection state of the camera.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLCameraConnectionState connectionState;

    Swift

    var connectionState: ConnectionState { get }

  • Returns YES if the disconnection that just happens was expected or not.

    This property is only valid inside a triggered observation of the connectionState property or within the callback block of disconnectFromDevice:callbackQueue:.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL disconnectionWasExpected;

    Swift

    var disconnectionWasExpected: Bool { get }

  • Returns any warnings that occurred during connection to the camera.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly, nullable) NSArray<id<CBLCameraConnectionWarning>> *connectionWarnings;

    Swift

    var connectionWarnings: [any ConnectionWarning]? { get }

  • Attempt to connect to the device with the given flags.

    The passed block is called when a session is established or if the connection or session setup failed. If the error parameter of the callback is nil, connection and session setup was successful.

    In some cases, the connection will complete successfully enough to be useable, but with some warnings. A notable example is when connecting to a very new model of camera, some advanced functionality may not be available yet. If there are warnings, these will contained in the warnings parameter of the callback block. These warnings should be presented to the user if they fall in a category your application uses.

    In some circumstances, the connection process is stalled by the camera requiring authentication. If this happens, the authenticationRequestCallback will be called with information on the request. You should display UI to the user on how to satisy the request, which will vary depending on the type of authentication request (see the documentation for id <CBLCameraAuthenticationContext> for more details.

    Once the authentication request has been satisfied, the authenticationResolvedCallback will be called, signalling that the request has been satisifed and you can close your UI.

    Note

    If you get a authenticationRequestCallback, you will always get a authenticationResolvedCallback before camera connection completes. Importantly, you may get more than one sequence of authentication requests/resolves during a connection - for example, if the camera rejects the given username and password, it may grant another try before failing.

    Note

    The callback blocks will be called on the main queue.

    Declaration

    Objective-C

    - (void)connectWithFlags:(nullable NSDictionary<NSString *, id> *)flags
     authenticationRequestCallback:(nonnull CBLCameraAuthenticationRequestBlock)
                                       authenticationRequestCallback
    authenticationResolvedCallback:
        (nonnull CBLCameraAuthenticationResolvedBlock)
            authenticationResolvedCallback
                completionCallback:
                    (nonnull CBLCameraConnectionCompleteBlock)callback;

    Swift

    func connect(flags: [String : Any]?, authenticationRequestCallback: @escaping CameraAuthenticationRequestBlock, authenticationResolvedCallback: @escaping CameraAuthenticationResolvedBlock, completionCallback callback: @escaping ConnectionCompleteCallback)

    Parameters

    flags

    The connection flags for this session. Can be nil.
    authenticationRequestCallback

    The callback to be invoked when a camera needs user authentication.
    authenticationResolvedCallback

    The callback to be invoked when a camera’s authentication request has been resolved.
    callback

    The callback to be called when the connection succeeds or fails.

  • Attempt to connect to the device with the given client name.

    Equivalent to calling -connectWithFlags:authenticationRequestCallback:authenticationResolvedCallback:completionCallback: with a nil flags parameter.

    See the documentation for -connectWithFlags:authenticationRequestCallback:authenticationResolvedCallback:completionCallback: for details.

    Declaration

    Objective-C

    - (void)connectWithAuthenticationRequestCallback:
            (nonnull CBLCameraAuthenticationRequestBlock)
                authenticationRequestCallback
                  authenticationResolvedCallback:
                      (nonnull CBLCameraAuthenticationResolvedBlock)
                          authenticationResolvedCallback
                              completionCallback:
                                  (nonnull CBLCameraConnectionCompleteBlock)
                                      callback;

    Swift

    func connect(authenticationRequestCallback: @escaping CameraAuthenticationRequestBlock, authenticationResolvedCallback: @escaping CameraAuthenticationResolvedBlock, completionCallback callback: @escaping ConnectionCompleteCallback)

    Parameters

    authenticationRequestCallback

    The callback to be invoked when a camera needs user authentication.
    authenticationResolvedCallback

    The callback to be invoked when a camera’s authentication request has been resolved.
    callback

    The callback to be called when the connection succeeds or fails.

  • Attempt to disconnect from the device.

    The passed block is called when the session is ended and connections have been terminated. If the error parameter of the callback is nil, disconnection was successful.

    Declaration

    Objective-C

    - (void)disconnectWithFlags:(nullable NSDictionary<NSString *, id> *)flags
         completionCallback:(nullable CBLErrorableOperationCallback)callback
              callbackQueue:(nullable dispatch_queue_t)queue;

    Swift

    func disconnect(withFlags flags: [String : Any]?, completionCallback callback: ErrorableOperationCallback?, callbackQueue queue: dispatch_queue_t?)

    Parameters

    flags

    The disconnection flags.
    callback

    The callback to be called when disconnection succeeds or fails.
    queue

    The queue on which to trigger the callback.

  • Attempt to disconnect from the device.

    The passed block is called when the session is ended and connections have been terminated. If the error parameter of the callback is nil, disconnection was successful.

    Equivalent to calling disconnectWithFlags:completionCallback:callbackQueue: with a nil flags parameter.

    Declaration

    Objective-C

    - (void)disconnect:(nullable CBLErrorableOperationCallback)callback
     callbackQueue:(nullable dispatch_queue_t)queue;

    Swift

    func disconnect(_ callback: ErrorableOperationCallback?, callbackQueue queue: dispatch_queue_t?)

    Parameters

    callback

    The callback to be called when disconnection succeeds or fails.
    queue

    The queue on which to trigger the callback.

Querying Available Functionality

  • Returns a bitmask of the supported advanced functionality of this camera.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLCameraSupportedFunctionality supportedFunctionality;

    Swift

    var supportedFunctionality: SupportedFunctionality { get }

  • Returns YES if the camera supports the given functionality, otherwise NO.

    Declaration

    Objective-C

    - (BOOL)supportsFunctionality:(CBLCameraSupportedFunctionality)functionality;

    Swift

    func supportsFunctionality(_ functionality: SupportedFunctionality) -> Bool

    Parameters

    functionality

    The functionality to test for.

  • Returns a bitmask of the current available command categories.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLCameraAvailableCommandCategory currentCommandCategories;

    Swift

    var currentCommandCategories: AvailableCommandCategory { get }

  • Returns YES if the camera currently supports the given category, otherwise NO.

    Declaration

    Objective-C

    - (BOOL)currentCommandCategoriesContainsCategory:
    (CBLCameraAvailableCommandCategory)category;

    Swift

    func currentCommandCategoriesContains(_ category: AvailableCommandCategory) -> Bool

    Parameters

    category

    The category to test for.

  • Returns YES if the camera is able to switch to the given category combination, otherwise NO.

    Declaration

    Objective-C

    - (BOOL)supportsCommandCategories:(CBLCameraAvailableCommandCategory)categories;

    Swift

    func supportsCommandCategories(_ categories: AvailableCommandCategory) -> Bool

    Parameters

    categories

    The command category combination to check if the camera supports.

  • Attempt to switch the camera into a mode that supports the given category combination.

    It is not guaranteed that the camera’s current command categories will end up exactly the same as what’s passed in, but if the method succeeds you can expect that they will contain the requested category/categories.

    For example, some cameras support both stills shooting and filesystem access at the same time. Requesting the command category .stillsShooting will succeed, but the camera will end up with current command categories of [.stillsShooting, .filesystemAccess].

    In general, it’s safe to call this method with a single category (for example, if you want to shoot video, .videoRecording) — CascableCore will put the camera into the closest sensible mode that supports that category.

    To check if the camera supports your desired command category/categories, use -supportsCommandCategories:.

    Declaration

    Objective-C

    - (void)
    setCurrentCommandCategories:(CBLCameraAvailableCommandCategory)categories
             completionCallback:(nonnull CBLErrorableOperationCallback)block;

    Swift

    func setCurrentCommandCategories(_ categories: AvailableCommandCategory, completionCallback block: @escaping ErrorableOperationCallback)

    Parameters

    categories

    The command categories the camera should accept.
    block

    The block to be called when the camera has switched modes and is able to accept commands in the given categories, or an error occurs.