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_ENUMic4_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_INTERFACEic4_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_ptrUser 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]pDevEnumPointer to the device enumerator on which the callback was registered
[in]user_ptrUser data that was specified when calling ic4_devenum_event_add_device_list_changed()

Enumeration Type Documentation

◆ 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]ppEnumeratorA 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]pEnumeratorThe device enumerator for which the callback is registered
[in]handlerThe function to be called when the list of available video capture devices has changed
[in]user_ptrUser data to be passed in calls to handler.
[in]deleterA 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]pEnumeratorThe device enumerator for which the callback is currently registered
[in]handlerPointer to the function to be unregistered
[in]user_ptrUser 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]pEnumeratorA 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]pEnumeratorA pointer to a device enumerator
[in]indexList position of the device whose information is to be retrieved
[out]ppInfoA 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]pEnumeratorA pointer to a device enumerator
[in]indexList position of the interface to be opened
[out]ppInterfaceA 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]pEnumeratorA 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]pEnumeratorA 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]pEnumeratorA 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]pEnumeratorA 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]pEnumeratorA 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]pInfo1First device info
[in]pInfo2Second 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]pInfoA device information object
[out]ppInterfaceA 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]pInfoA 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]pInfoA 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]pInfoA 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]pInfoA 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]pInfoA 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]pInfoA 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]pInfoA 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]pInterface1First interface object
[in]pInterface2Second 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]pInterfaceA 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]pInterfaceA pointer to a device interface
[in]indexList position of the device whose information is to be retrieved
[out]ppInfoA 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]pInterfaceA 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]pInterfaceA pointer to a device interface
[out]ppMapA 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]pInterfaceA 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]pInterfaceA 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]pInterfaceA 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]pInterfaceA 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]pInterfaceA 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]pInterfaceA 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