Device Property

GetDeviceProperties

Overview

This API gets device properties from the device specified by the deviceHandle. This retrieves all of the available properties of device. This list contains information about each property’s current value, list of valid values and whether or not the property value can currently be updated by the user.

Definition

CrError GetDeviceProperties(CrDeviceHandle deviceHandle, CrDeviceProperty** properties, CrInt32* numOfProperties);

Input parameters

Type	Explanation
CrDeviceHandle	deviceHandle

Output parameters

Type	Explanation
CrDeviceProperty**	properties The property list pointer. Developers should pass the address of a modifiable CrDeviceProperty pointer. The value of this pointer should be initialized to nullptr. The function will make a copy of the SDK-internal CrDeviceProperty list for the indicated deviceHandle. When function returns successfully, this parameter will point to the copy of CrDeviceProperty list.
CrInt32*	numOfProperties A pointer to an integer which indicates the number of CrDeviceProperty objects in the property list. App developers should pass the address of a modifiable CrInt32 variable. This function will write the size of the returned list to the variable.

Return value

Type	Explanation
CrError	CrError_None If the properties are returned successfully 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

• GetSelectDeviceProperties

• ReleaseDeviceProperties

• SetDeviceProperty

• IDeviceCallback::OnPropertyChanged

• IDeviceCallback::OnPropertyChangedCodes

Special note (details)

This is a factory function. The SDK will allocate memory. Call the ReleaseDeviceProperties API to correctly release the generated list.

This API function retrieves a list of all the properties supported by the indicated device. Each returned property also provides its current value, a list of values it supports and whether or not the property is currently modifiable.

It is important to initialize the out-parameter pointer to nullptr before passing it to this function. This is required to detect whether or not a list has been created. The out-parameter properties will remain unmodified if the property list cannot be retrieved.

If the list is successfully retrieved, properties points to the list and out-parameter numOfProperties indicates the number of items in the list.

GetSelectDeviceProperties

Overview

This API gets specified device properties from the device specified by the deviceHandle.

This list contains information about each property’s current value, list of valid values and whether or not the property value can currently be updated by the user.

Definition

CrError GetSelectDeviceProperties(CrDeviceHandle deviceHandle, CrInt32u numOfCodes, CrInt32u* codes, CrDeviceProperty** properties, CrInt32* numOfProperties);

Input parameters

Type	Explanation
CrDeviceHandle	deviceHandle
CrInt32u	numOfCodes Number of device properties to get.
CrInt32u*	codes List of device property codes to get.

Output parameters

Type	Explanation
CrDeviceProperty**	properties The property list pointer. Developers should pass the address of a modifiable CrDeviceProperty pointer. The value of this pointer should be initialized to nullptr. The function will make a copy of the SDK-internal CrDeviceProperty list for the indicated deviceHandle. When function returns successfully, this parameter will point to the copy of CrDeviceProperty list.
CrInt32*	numOfProperties A pointer to an integer which indicates the number of CrDeviceProperty objects in the property list. App developers should pass the address of a modifiable CrInt32 variable. This function will write the size of the returned list to the variable.

Return value

Type	Explanation
CrError	CrError_None If the properties are returned successfully 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

• GetDeviceProperties

• ReleaseDeviceProperties

• SetDeviceProperty

• IDeviceCallback::OnPropertyChangedCodes

Special note (details)

This is a factory function. The SDK will allocate memory. Call the ReleaseDeviceProperties API to correctly release the generated list.

This API function retrieves a list of specified properties supported by the indicated device. Each returned property also provides its current value, a list of values it supports and whether or not the property is currently modifiable.

It is important to initialize the out-parameter pointer to nullptr before passing it to this function. This is required to detect whether or not a list has been created. The out-parameter properties will remain unmodified if the property list cannot be retrieved.

If the list is successfully retrieved, properties points to the list and out-parameter numOfProperties indicates the number of items in the list.

ReleaseDeviceProperties

Overview

This API function releases the CrDeviceProperty list allocated by GetDeviceProperties.

Definition

CrError ReleaseDeviceProperties(CrDeviceHandle deviceHandle, CrDeviceProperty* properties);

Input parameters

Type	Explanation
CrDeviceHandle	deviceHandle
CrDeviceProperty*	properties The property list pointer pointing to the list to be released.

Output parameters

None

Return value

Type	Explanation
CrError	CrError_None If the property list is released successfully 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

• GetDeviceProperties

• GetSelectDeviceProperties

Special note (details)

This function releases the CrDeviceProperty list that is associated with the specified device handle.

SetDeviceProperty

Overview

Request the SDK set a new value to the selected property for the corresponding device.

The function is asynchronous and returns to the user as soon as the SDK enqueues the requested action. After the property of the camera changed, OnPropertyChanged() and other callback functions are called and GetDeviceProperties() will return the new property value.

Definition

CrError SetDeviceProperty(CrDeviceHandle deviceHandle, CrDeviceProperty* pProperty);

Input parameters

Type	Explanation
CrDeviceHandle	deviceHandle
CrDeviceProperty*	pProperty This parameter points to the CrDeviceProperty object which contains the property that will be set to the device.

Output parameters

None

Return value

Type	Explanation
CrError	CrError_None If the command is sent out. 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

• GetDeviceProperties

• GetSelectDeviceProperties

• IDeviceCallback::OnPropertyChanged

• IDeviceCallback::OnPropertyChangedCodes

Special note (details)

Requests the SDK set the indicated pProperty on the corresponding device indicated by deviceHandle.

pProperty contains the desired property code and desired property value.

The desired value should be one of the valid values retrieved from GetDeviceProperties. The SDK will not set an unsupported value.

The return value from this function will not indicate whether or not the property was set successfully. If the property is updated successfully the SDK will call IDeviceCallback:: OnPropertyChanged() and other callback functions. The warning code will indicate that a property has changed.