Connection

Connect

Overview

This API attempts to connect to the camera device specified by the user.

This function is an asynchronous connection request. If this function returns without error, the asynchronous connection request has been initiated successfully. Success or failure of the connection is communicated to the user through the IDeviceCallback interface. This interface must be implemented by the user to use the Camera Remote SDK.

The content transfer function has been added from version 1.05.00, and the openMode parameter has been added to this API. The openMode parameter is optional. This can be omitted when performing remote control as before.

From version 1.06.00, the function to specify the behavior of automatic reconnection and the information for SSH authenticate connection has been added. The automatic reconnection control parameters are optional. By default, automatic reconnection is enabled, but when in ContentsTransferMode, automatic reconnection is forcibly disabled. This is due to the limitations of the camera body.

From version 1.13.00, added new openMode parameter “RemoteTransfer”.

• See “Supporting physical layer” for content transfer support models

• See “Pull out content stored on media in ContentsTransferMode” for content transfer capabilities

• See “Pull out content stored on media in RemoteTransferMode” for content transfer with remote control capabilities.

When operating a camera that requires SSH authentication, it is necessary to set a User name and Password on the camera body. In addition, it is necessary to acquire fingerprint data in advance with GetFingerprint().

Definition

CrError Connect(ICrCameraObjectInfo* pCameraObjectInfo, IDeviceCallback* callback, CrDeviceHandle* deviceHandle, CrSdkControlMode openMode = CrSdkControlMode_Remote, CrReconnectingSet reconnect = CrReconnecting_ON , const char* userId = 0, const char* userPassword = 0, const char* fingerprint = 0, CrInt32u fingerprintSize = 0, const CrInt16u* pairingDisplayName = nullptr);

Input parameters

Type	Explanation
ICrCameraObjectInfo*	pCameraObjectInfo The camera which is going to be connected. This parameter is return by ICrEnumCameraObjectInfo::GetCameraObjectInfo().
IDeviceCallback*	callback The user-implemented device callback interface. App developers who use this SDK should implement the callback function interface to handle events from the camera such as connected or disconnected, property change, etc.
CrSdkControlMode	openMode This parameter is optional. If you want to pull out the contents of the media and save it on the host device, specify “CrSdkControlMode_ContentsTransfer”. Note : Switching between RemoteControlMode and ContentsTransferMode cannot be performed while connected. After disconnecting in each mode, reconnect in the desired mode.
CrReconnectingSet	reconnect This parameter is optional. With the default value, the SDK that detects an unexpected disconnection will try to reconnect for a period of time (= called the automatic reconnection function). Specify CrReconnecting_OFF when you want to disable the automatic reconnection function.
const char*	userId This parameter is optional. Specify the User name for the SSH authentication. Make it null terminated. For details on how to set the User name for SSH authentication, refer to the help guide for the target camera.
const char*	userPassword This parameter is optional. Specify the password for the SSH authentication. Make it null terminated. For details on how to set the password for SSH authentication, refer to the help guide for the target camera.
const char*	fingerprint This parameter is optional. Specify the fingerprint data obtained by GetFingerprint().
CrInt32u	fingerprintSize This parameter is optional. Specify the length of the fingerprint parameter.
const CrInt16u*	pairingDisplayName This parameter is optional. Specify the pairing display name for the SSH authentication. Make it null terminated. For details on how to set the pairing display name for SSH authentication, refer to the help guide for the target camera.

Input/Output parameters

Type	Explanation
CrDeviceHandle*	deviceHandle The handle of the connected camera is returned in the variable. This must be set 0 before calling Connect().

Return value

Type

Explanation

CrError

CrError_None on Success CrError_Init if the SDK is uninitialized CrError_Generic_Unknown If the pCameraObjectInfo is NULL, and no valid deviceNumber is supplied CrError_Connect_ContentsTransfer_NotSupported Connected to a model that does not support content transfer. Errors starting with CrError_Connect_SSH, such as CrError_Connect_SSH_ServerConnectFailed, indicate an SSH connection error. Other than errors above, see Status code & Error

Related API

• GetFingerprint

• Disconnect

• EnumCameraObjects

• CreateCameraObjectInfo

• IDeviceCallback::OnConnected

Special note (details)

This API can be used in two ways: to connect to a new device and to reconnect to an existing device.

To connect to a new device, supply a deviceHandle value of 0 and a pointer to a valid ICrCameraObjectInfo.

To reconnect to an existing device, supply the deviceHandle of that device to this API and NULL in pCameraObjectInfo. The SDK will then reuse the existing internal device handle and attempt to connect to the specified camera device. Reconnection will not work if the specific device was previously released with the ReleaseDevice API. In this case, CrError_Generic_Unknown will be returned.

A successful connection is reported to the user through the IDeviceCallback::OnConnected interface function. An implementation of this function must be supplied to Connect by the user though the callback parameter.

The deviceHandle out-parameter returns the SDK device identifier to the user. This identifier is required to use subsequent SDK API functions to interact with the connected device.

Repeatedly entering the wrong SSH parameters will lock the camera. In that case, turn off the power switch of the camera and restart it, or wait for a while and then try again.

Please never call Connect() again before receive IDeviceCallback::OnConnected or IDeviceCallback::OnError() because in processing connection task.

Disconnect

Overview

This API function disconnects the indicated device.

After calling this API, the deviceHandle remains valid and can be used to reconnect to the same device.

Definition

CrError Disconnect(CrDeviceHandle deviceHandle);

Input parameters

Type	Explanation
CrDeviceHandle	deviceHandle

Output parameters

None

Return value

Type	Explanation
CrError	CrError_None If the deviceHandle is a valid handle. In this case, the connection to the camera will be closed. CrError_Init if the SDK is uninitialized CrError_Generic_InvalidHandle If the deviceHandle is an invalid handle Other than errors above, see Status code & Error

Related API

• Connect

• ReleaseDevice

• Release

• IDeviceCallback::OnDisconnected

Special note (details)

Stops the internal processing threads on the indicated device and disconnects from the device.

The SDK signals successful disconnection by calling IDeviceCallback::OnDisconnected.

Calling this API will not invalidate the existing deviceHandle. This function simple disconnects the device. Unless ReleaseDevice is called, the device handle can be reused to connect to the same device. Do not call ReleaseDevice or Release before the IDeviceCallback::OnDisconnected notification.