Device Enumeration

This section describes how to enumerate and query information from connected video capture devices. More...

Data Structures

struct	IC4_DEVICE_ENUM Device enumerator type. More...
struct	IC4_DEVICE_INFO Device information type. More...
struct	IC4_INTERFACE Device interface type. More...

Typedefs

typedef void(*	ic4_devenum_device_list_change_handler) (struct IC4_DEVICE_ENUM pDevEnum, void user_ptr) Function pointer for the device-list-changed handler.
typedef void(*	ic4_devenum_device_list_change_deleter) (void *user_ptr) Function pointer for cleanup of the device-list-changed user data.

Enumerations

enum	IC4_TL_TYPE { IC4_TLTYPE_UNKNOWN , IC4_TLTYPE_GIGEVISION , IC4_TLTYPE_USB3VISION } Contains the possible transport layer types. More...

Functions

bool	ic4_devenum_create (struct IC4_DEVICE_ENUM **ppEnumerator) Creates a new device enumerator.
struct IC4_DEVICE_ENUM *	ic4_devenum_ref (struct IC4_DEVICE_ENUM *pEnumerator) Increases the device enumerator's internal reference count by one.
void	ic4_devenum_unref (struct IC4_DEVICE_ENUM *pEnumerator Decreases the device enumerator's internal reference count by one.
bool	ic4_devenum_update_device_list (struct IC4_DEVICE_ENUM *pEnumerator) Searches for video capture devices and populates the enumerator's internal device list.
int	ic4_devenum_get_device_count (const struct IC4_DEVICE_ENUM *pEnumerator) Returns the number of devices discovered by the previous call to ic4_devenum_update_device_list().
bool	ic4_devenum_get_devinfo (const struct IC4_DEVICE_ENUM pEnumerator, int index, struct IC4_DEVICE_INFO *ppInfo) Returns a IC4_DEVICE_INFO object describing one of the discovered video capture devices.
bool	ic4_devenum_update_interface_list (struct IC4_DEVICE_ENUM *pEnumerator) Searches for interfaces and populates the enumerator's internal interface list.
int	ic4_devenum_get_interface_count (const struct IC4_DEVICE_ENUM *pEnumerator) Returns the number of interfaces discovered by the previous call to ic4_devenum_update_interface_list().
bool	ic4_devenum_get_devitf (const struct IC4_DEVICE_ENUM pEnumerator, int index, struct IC4_INTERFACE *ppInterface) Returns a IC4_INTERFACE object describing one of the discovered interfaces.
bool	ic4_devenum_event_add_device_list_changed (struct IC4_DEVICE_ENUM pEnumerator, ic4_devenum_device_list_change_handler handler, void user_ptr, ic4_devenum_device_list_change_deleter deleter) Registers a function to be called when the list of available video capture devices has (potentially) changed.
bool	ic4_devenum_event_remove_device_list_changed (struct IC4_DEVICE_ENUM pEnumerator, ic4_devenum_device_list_change_handler handler, void user_ptr) Unregisters a device-list-changed handler that was previously registered using ic4_devenum_event_add_device_list_changed().
struct IC4_INTERFACE *	ic4_devitf_ref (struct IC4_INTERFACE *pInterface) Increases the device interface's internal reference count by one.
void	ic4_devitf_unref (struct IC4_INTERFACE *pInterface) Decreases the device interface's internal reference count by one.
const char *	ic4_devitf_get_display_name (const struct IC4_INTERFACE *pInterface) Returns the name of the device interface.
const char *	ic4_devitf_get_tl_name (const struct IC4_INTERFACE *pInterface) Returns the name of the transport layer that provides this interface object.
const char *	ic4_devitf_get_tl_version (const struct IC4_INTERFACE *pInterface) Returns the version of the transport layer that provides this interface object.
enum IC4_TL_TYPE	ic4_devitf_get_tl_type (const struct IC4_INTERFACE *pInterface) Returns the type of the transport layer used by this interface.
bool	ic4_devitf_get_property_map (const struct IC4_INTERFACE pInterface, struct IC4_PROPERTY_MAP *ppMap) Opens the property map for the specified device interface.
bool	ic4_devitf_update_device_list (struct IC4_INTERFACE *pInterface) Searches for video capture devices and populates the device interfaces's internal device list.
int	ic4_devitf_get_device_count (const struct IC4_INTERFACE *pInterface) Returns the number of devices discovered by the previous call to ic4_devitf_update_device_list().
bool	ic4_devitf_get_devinfo (const struct IC4_INTERFACE pInterface, int index, struct IC4_DEVICE_INFO *ppInfo) Returns a IC4_DEVICE_INFO object describing one of the discovered video capture devices.
bool	ic4_devitf_equals (const struct IC4_INTERFACE pInterface1, const struct IC4_INTERFACE pInterface2) Checks whether two device interface objects refer to the same interface.
struct IC4_DEVICE_INFO *	ic4_devinfo_ref (struct IC4_DEVICE_INFO *pInfo) Increases the device information's internal reference count by one.
void	ic4_devinfo_unref (struct IC4_DEVICE_INFO *pInfo) Decreases the device information's internal reference count by one.
const char *	ic4_devinfo_get_model_name (const struct IC4_DEVICE_INFO *pInfo) Get the model name from a device information object.
const char *	ic4_devinfo_get_serial (const struct IC4_DEVICE_INFO *pInfo) Get the textual representation of the serial number from a device information object.
const char *	ic4_devinfo_get_version (const struct IC4_DEVICE_INFO *pInfo) Get the device version from a device information object.
const char *	ic4_devinfo_get_user_id (const struct IC4_DEVICE_INFO *pInfo) Get the device's user-defined identifier from a device information object.
const char *	ic4_devinfo_get_unique_name (const struct IC4_DEVICE_INFO *pInfo) Get the device's unique name from a device information object.
bool	ic4_devinfo_equals (const struct IC4_DEVICE_INFO pInfo1, const struct IC4_DEVICE_INFO pInfo2) Checks whether two device information objects refer to the same video capture device.
bool	ic4_devinfo_get_devitf (const struct IC4_DEVICE_INFO pInfo, struct IC4_INTERFACE *ppInterface) Returns the interface the device represented by the device information object is attached to.

Detailed Description

This section describes how to enumerate and query information from connected video capture devices.

Call ic4_devenum_create() to create a device enumerator object (IC4_DEVICE_ENUM).

The enumerator provides access to a list of IC4_DEVICE_INFO objects representing the video capture devices which are present in the system.

IC4_DEVICE_INFO object allow querying device information such as the device's model name and serial number.

Typedef Documentation

◆ ic4_devenum_device_list_change_deleter

typedef void(* ic4_devenum_device_list_change_deleter) (void *user_ptr)

Function pointer for cleanup of the device-list-changed user data.

Parameters

[in] user_ptr User data that was specified when calling ic4_devenum_event_add_device_list_changed()

◆ ic4_devenum_device_list_change_handler

typedef void(* ic4_devenum_device_list_change_handler) (struct IC4_DEVICE_ENUM *pDevEnum, void *user_ptr)

Function pointer for the device-list-changed handler.

Parameters

[in]	pDevEnum	Pointer to the device enumerator on which the callback was registered
[in]	user_ptr	User data that was specified when calling ic4_devenum_event_add_device_list_changed()

Enumeration Type Documentation

◆ IC4_TL_TYPE

enum IC4_TL_TYPE

Contains the possible transport layer types.

Enumerator
IC4_TLTYPE_UNKNOWN	Other or unknown transport layer type.
IC4_TLTYPE_GIGEVISION	The transport layer uses the GigE Vision standard.
IC4_TLTYPE_USB3VISION	The transport layer uses the USB3 Vision standard.

Function Documentation

◆ ic4_devenum_create()

bool ic4_devenum_create ( struct IC4_DEVICE_ENUM ** ppEnumerator )

Creates a new device enumerator.

Parameters

[out] ppEnumerator A pointer to receive a pointer to the new device enumerator.
When the enumerator is no longer required, release the object reference using ic4_devenum_unref().

Returns: true on success, otherwise false. Use ic4_get_last_error() to query error information.

See also: ic4_devenum_unref

◆ ic4_devenum_event_add_device_list_changed()

bool ic4_devenum_event_add_device_list_changed	(	struct IC4_DEVICE_ENUM *	pEnumerator,
		ic4_devenum_device_list_change_handler	handler,
		void *	user_ptr,
		ic4_devenum_device_list_change_deleter	deleter
	)

Registers a function to be called when the list of available video capture devices has (potentially) changed.

Parameters

[in]	pEnumerator	The device enumerator for which the callback is registered
[in]	handler	The function to be called when the list of available video capture devices has changed
[in]	user_ptr	User data to be passed in calls to handler.
[in]	deleter	A function to be called when the handler was unregistered and the user_ptr will no longer be required. The deleter function can be used to release data associated with user_ptr. The deleter function will be called when the device-list-changed handler is unregistered, or the device enumerator object itself is destroyed.

Note: To unregister a device-list-changed handler, call ic4_devenum_event_remove_device_list_changed().
It is not guaranteed that every call to handler correlates to an actual change in the device list.

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_devenum_event_remove_device_list_changed()

bool ic4_devenum_event_remove_device_list_changed	(	struct IC4_DEVICE_ENUM *	pEnumerator,
		ic4_devenum_device_list_change_handler	handler,
		void *	user_ptr
	)

Unregisters a device-list-changed handler that was previously registered using ic4_devenum_event_add_device_list_changed().

Parameters

[in]	pEnumerator	The device enumerator for which the callback is currently registered
[in]	handler	Pointer to the function to be unregistered
[in]	user_ptr	User data that the function was previously registered with

Note: The pair of handler and user_ptr has to be an exact match to the parameters used in the call to ic4_devenum_event_add_device_list_changed().

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_devenum_get_device_count()

int ic4_devenum_get_device_count ( const struct IC4_DEVICE_ENUM * pEnumerator )

Returns the number of devices discovered by the previous call to ic4_devenum_update_device_list().

Parameters

[in] pEnumerator A pointer to a device enumerator

Returns: The number of devices in the enumerator's internal device list
If an error occurs, the function returns 0. ic4_get_last_error() can query error information.

See also: ic4_devenum_get_devinfo

◆ ic4_devenum_get_devinfo()

bool ic4_devenum_get_devinfo	(	const struct IC4_DEVICE_ENUM *	pEnumerator,
		int	index,
		struct IC4_DEVICE_INFO **	ppInfo
	)

Returns a IC4_DEVICE_INFO object describing one of the discovered video capture devices.

Parameters

[in]	pEnumerator	A pointer to a device enumerator
[in]	index	List position of the device whose information is to be retrieved
[out]	ppInfo	A pointer to receive a pointer to the a IC4_DEVICE_INFO object. When the device information object is no longer required, release the reference using ic4_devenum_unref().

Returns: true on success, otherwise false.

Remarks: ic4_devenum_update_device_list() has to be called before this function can return anything useful. Use ic4_devenum_get_device_count() to determine the maximum valid value for index.

See also: ic4_devinfo_unref

◆ ic4_devenum_get_devitf()

bool ic4_devenum_get_devitf	(	const struct IC4_DEVICE_ENUM *	pEnumerator,
		int	index,
		struct IC4_INTERFACE **	ppInterface
	)

Returns a IC4_INTERFACE object describing one of the discovered interfaces.

Parameters

[in]	pEnumerator	A pointer to a device enumerator
[in]	index	List position of the interface to be opened
[out]	ppInterface	A pointer to receive a pointer to the a IC4_INTERFACE object. When the interface object is no longer required, release the reference using ic4_devitf_unref().

Returns: true on success, otherwise false.

Remarks: ic4_devenum_update_interface_list() has to be called before this function can return anything useful. Use ic4_devenum_get_interface_count() to determine the maximum valid value for index.

See also: ic4_devinfo_unref

◆ ic4_devenum_get_interface_count()

int ic4_devenum_get_interface_count ( const struct IC4_DEVICE_ENUM * pEnumerator )

Returns the number of interfaces discovered by the previous call to ic4_devenum_update_interface_list().

Parameters

[in] pEnumerator A pointer to a device enumerator

Returns: The number of interfaces in the enumerator's internal interface list
If an error occurs, the function returns 0. ic4_get_last_error() can query error information.

See also: ic4_devenum_get_devitf

◆ ic4_devenum_ref()

struct IC4_DEVICE_ENUM * ic4_devenum_ref ( struct IC4_DEVICE_ENUM * pEnumerator )

Increases the device enumerator's internal reference count by one.

Parameters

[in] pEnumerator A pointer to a device enumerator

Returns: The pointer passed via pEnumerator

Remarks: If pEnumerator is NULL, the function returns NULL. An error value is not set.

See also: ic4_devenum_unref

◆ ic4_devenum_unref()

void ic4_devenum_unref ( struct IC4_DEVICE_ENUM * pEnumerator )

Decreases the device enumerator's internal reference count by one.

If the reference count reaches zero, the object is destroyed.

Parameters

[in] pEnumerator A pointer to a device enumerator

Remarks: If pEnumerator is NULL, the function does nothing. An error value is not set.

See also: ic4_devenum_ref

◆ ic4_devenum_update_device_list()

bool ic4_devenum_update_device_list ( struct IC4_DEVICE_ENUM * pEnumerator )

Searches for video capture devices and populates the enumerator's internal device list.

Parameters

[in] pEnumerator A pointer to a device enumerator

Returns: true on success, otherwise false. Use ic4_get_last_error() to query error information.

See also: ic4_devenum_get_device_count; ic4_devenum_get_devinfo

◆ ic4_devenum_update_interface_list()

bool ic4_devenum_update_interface_list ( struct IC4_DEVICE_ENUM * pEnumerator )

Searches for interfaces and populates the enumerator's internal interface list.

Parameters

[in] pEnumerator A pointer to a device enumerator

Returns: true on success, otherwise false. Use ic4_get_last_error() to query error information.

Remarks: Using the interface enumeration is entirely optional; for many use cases searching for devices via ic4_devenum_update_device_list() is sufficient.

See also: ic4_devenum_get_interface_count; ic4_devenum_get_devitf

◆ ic4_devinfo_equals()

bool ic4_devinfo_equals	(	const struct IC4_DEVICE_INFO *	pInfo1,
		const struct IC4_DEVICE_INFO *	pInfo2
	)

Checks whether two device information objects refer to the same video capture device.

Parameters

[in]	pInfo1	First device info
[in]	pInfo2	Second device info

Returns: true if the device information objects refer to the same video capture device, otherwise false.
If both pointers are NULL, the function returns true.

◆ ic4_devinfo_get_devitf()

bool ic4_devinfo_get_devitf	(	const struct IC4_DEVICE_INFO *	pInfo,
		struct IC4_INTERFACE **	ppInterface
	)

Returns the interface the device represented by the device information object is attached to.

Parameters

[in]	pInfo	A device information object
[out]	ppInterface	A pointer to receive a pointer to the a IC4_INTERFACE object. When the interface object is no longer required, release the reference using ic4_devitf_unref().

Returns: true on success, otherwise false. Use ic4_get_last_error() to query error information.

◆ ic4_devinfo_get_model_name()

const char * ic4_devinfo_get_model_name ( const struct IC4_DEVICE_INFO * pInfo )

Get the model name from a device information object.

Parameters

[in] pInfo A pointer to a device information object

Returns: A pointer to a null-terminated string containing the device's model name, or NULL if an error occured.
Use ic4_get_last_error() to query error information.
The memory pointed to by the return value is valid as long as the device information object exists.

◆ ic4_devinfo_get_serial()

const char * ic4_devinfo_get_serial ( const struct IC4_DEVICE_INFO * pInfo )

Get the textual representation of the serial number from a device information object.

Parameters

[in] pInfo A pointer to a device information object

Returns: A pointer to a null-terminated string containing the device's serial number, or NULL if an error occured.
Use ic4_get_last_error() to query error information.
The memory pointed to by the return value is valid as long as the device information object exists.
The format of the serial number string is device-specific.

◆ ic4_devinfo_get_unique_name()

const char * ic4_devinfo_get_unique_name ( const struct IC4_DEVICE_INFO * pInfo )

Get the device's unique name from a device information object.

Parameters

[in] pInfo A pointer to a device information object

Returns: A pointer to a null-terminated string containing the device's unique name, or NULL if an error occured.
Use ic4_get_last_error() to query error information.
The memory pointed to by the return value is valid as long as the device information object exists.
The unique name consists of an identifier for the device driver and the device's serial number, allowing devices to be uniquely identified by a single string.

◆ ic4_devinfo_get_user_id()

const char * ic4_devinfo_get_user_id ( const struct IC4_DEVICE_INFO * pInfo )

Get the device's user-defined identifier from a device information object.

Parameters

[in] pInfo A pointer to a device information object

Returns: A pointer to a null-terminated string containing the device's user-defined identifier, or NULL if an error occured.
Use ic4_get_last_error() to query error information.
The memory pointed to by the return value is valid as long as the device information object exists.

Remarks: If supported by the device, the device's user-defined identifier can be configured through the DeviceUserID feature in the device's property map.

◆ ic4_devinfo_get_version()

const char * ic4_devinfo_get_version ( const struct IC4_DEVICE_INFO * pInfo )

Get the device version from a device information object.

Parameters

[in] pInfo A pointer to a device information object

Returns: A pointer to a null-terminated string containing the device's version information, or NULL if an error occured.
Use ic4_get_last_error() to query error information.
The memory pointed to by the return value is valid as long as the device information object exists.
The format of the device version is device-specific.

◆ ic4_devinfo_ref()

struct IC4_DEVICE_INFO * ic4_devinfo_ref ( struct IC4_DEVICE_INFO * pInfo )

Increases the device information's internal reference count by one.

Parameters

[in] pInfo A pointer to a device information object

Returns: The pointer passed via pInfo

Remarks: If pInfo is NULL, the function returns NULL. An error value is not set.

See also: ic4_devinfo_unref

◆ ic4_devinfo_unref()

void ic4_devinfo_unref ( struct IC4_DEVICE_INFO * pInfo )

Decreases the device information's internal reference count by one.

If the reference count reaches zero, the object is destroyed.

Parameters

[in] pInfo A pointer to a device information object

Remarks: If pInfo is NULL, the function does nothing. An error value is not set.

See also: ic4_devenum_ref

◆ ic4_devitf_equals()

bool ic4_devitf_equals	(	const struct IC4_INTERFACE *	pInterface1,
		const struct IC4_INTERFACE *	pInterface2
	)

Checks whether two device interface objects refer to the same interface.

Parameters

[in]	pInterface1	First interface object
[in]	pInterface2	Second interface object

Returns: true if the device interface objects refer to the same interface, otherwise false.
If both pointers are NULL, the function returns true.

◆ ic4_devitf_get_device_count()

int ic4_devitf_get_device_count ( const struct IC4_INTERFACE * pInterface)

Returns the number of devices discovered by the previous call to ic4_devitf_update_device_list().

Parameters

[in] pInterface A pointer to a device interface

Returns: The number of devices in the inferface's internal device list
If an error occurs, the function returns 0. ic4_get_last_error() can query error information.

See also: ic4_devitf_get_devinfo

◆ ic4_devitf_get_devinfo()

bool ic4_devitf_get_devinfo	(	const struct IC4_INTERFACE *	pInterface,
		int	index,
		struct IC4_DEVICE_INFO **	ppInfo
	)

Returns a IC4_DEVICE_INFO object describing one of the discovered video capture devices.

Parameters

[in]	pInterface	A pointer to a device interface
[in]	index	List position of the device whose information is to be retrieved
[out]	ppInfo	A pointer to receive a pointer to the a IC4_DEVICE_INFO object. When the device information object is no longer required, release the reference using ic4_devenum_unref().

Returns: true on success, otherwise false.

Remarks: ic4_devitf_update_device_list() has to be called before this function can return anything useful. Use ic4_devitf_get_device_count() to determine the maximum valid value for index.

See also: ic4_devinfo_unref

◆ ic4_devitf_get_display_name()

const char * ic4_devitf_get_display_name ( const struct IC4_INTERFACE * pInterface )

Returns the name of the device interface.

Parameters

[in] pInterface A pointer to a device interface

Returns: A null-terminated string containing the device interface's name.
The memory pointed to by the returned pointer is valid as long as the interface object exists.
If an error occurs, the function returns NULL. Use ic4_get_last_error() to query error information.

◆ ic4_devitf_get_property_map()

bool ic4_devitf_get_property_map	(	const struct IC4_INTERFACE *	pInterface,
		struct IC4_PROPERTY_MAP **	ppMap
	)

Opens the property map for the specified device interface.

The property map can be used to query advanced interface information or configure the interface and its attached devices.

Parameters

[in]	pInterface	A pointer to a device interface
[out]	ppMap	A pointer to a pointer to a IC4_PROPERTY_MAP object. When the property map is no longer required, release the reference using ic4_propmap_unref().

Returns: true on success, otherwise false. Use ic4_get_last_error() to query error information.

◆ ic4_devitf_get_tl_name()

const char * ic4_devitf_get_tl_name ( const struct IC4_INTERFACE * pInterface )

Returns the name of the transport layer that provides this interface object.

This string can be interpreted as a name for the driver providing access to devices on the interface.

Parameters

[in] pInterface A pointer to a device interface

Returns: A null-terminated string containing the transport layer name.
The memory pointed to by the returned pointer is valid as long as the interface object exists.
If an error occurs, the function returns NULL. Use ic4_get_last_error() to query error information.

◆ ic4_devitf_get_tl_type()

enum IC4_TL_TYPE ic4_devitf_get_tl_type ( const struct IC4_INTERFACE * pInterface )

Returns the type of the transport layer used by this interface.

Parameters

[in] pInterface A pointer to a device interface

Returns: A IC4_TL_TYPE value describing the type of the transport layer.

◆ ic4_devitf_get_tl_version()

const char * ic4_devitf_get_tl_version ( const struct IC4_INTERFACE * pInterface )

Returns the version of the transport layer that provides this interface object.

This string can be interpreted as driver version for the driver providing access devices on the interface.

Parameters

[in] pInterface A pointer to a device interface

Returns: A null-terminated string containing the transport layer verision.
The memory pointed to by the returned pointer is valid as long as the interface object exists.
If an error occurs, the function returns NULL. Use ic4_get_last_error() to query error information.

◆ ic4_devitf_ref()

struct IC4_INTERFACE * ic4_devitf_ref ( struct IC4_INTERFACE * pInterface )

Increases the device interface's internal reference count by one.

Parameters

[in] pInterface A pointer to a device interface

Returns: The pointer passed via pInterface

Remarks: If pInterface is NULL, the function returns NULL. An error value is not set.

See also: ic4_devitf_unref

◆ ic4_devitf_unref()

void ic4_devitf_unref ( struct IC4_INTERFACE * pInterface )

Decreases the device interface's internal reference count by one.

If the reference count reaches zero, the object is destroyed.

Parameters

[in] pInterface A pointer to a device interface

Remarks: If pInterface is NULL, the function does nothing. An error value is not set.

See also: ic4_devitf_ref

◆ ic4_devitf_update_device_list()

bool ic4_devitf_update_device_list ( struct IC4_INTERFACE * pInterface )

Searches for video capture devices and populates the device interfaces's internal device list.

Parameters

[in] pInterface A pointer to a device interface

Returns: true on success, otherwise false. Use ic4_get_last_error() to query error information.

See also: ic4_devitf_get_device_count; ic4_devitf_get_devinfo