Imaging Control 4 C Library 1.2.0
|
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. | |
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 void(* ic4_devenum_device_list_change_deleter) (void *user_ptr) |
Function pointer for cleanup of the device-list-changed user data.
[in] | user_ptr | User data that was specified when calling ic4_devenum_event_add_device_list_changed() |
typedef void(* ic4_devenum_device_list_change_handler) (struct IC4_DEVICE_ENUM *pDevEnum, void *user_ptr) |
Function pointer for the device-list-changed handler.
[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() |
enum IC4_TL_TYPE |
bool ic4_devenum_create | ( | struct IC4_DEVICE_ENUM ** | ppEnumerator | ) |
Creates a new device enumerator.
[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(). |
true
on success, otherwise false
. Use ic4_get_last_error() to query error information.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.
[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. |
true
on success, otherwise false
.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().
[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 |
true
on success, otherwise false
.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().
[in] | pEnumerator | A pointer to a device enumerator |
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.
[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(). |
true
on success, otherwise false
.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.
[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(). |
true
on success, otherwise false
.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().
[in] | pEnumerator | A pointer to a device enumerator |
struct IC4_DEVICE_ENUM * ic4_devenum_ref | ( | struct IC4_DEVICE_ENUM * | pEnumerator | ) |
Increases the device enumerator's internal reference count by one.
[in] | pEnumerator | A pointer to a device enumerator |
NULL
, the function returns NULL
. An error value is not set.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.
[in] | pEnumerator | A pointer to a device enumerator |
NULL
, the function does nothing. An error value is not set.bool ic4_devenum_update_device_list | ( | struct IC4_DEVICE_ENUM * | pEnumerator | ) |
Searches for video capture devices and populates the enumerator's internal device list.
[in] | pEnumerator | A pointer to a device enumerator |
true
on success, otherwise false
. Use ic4_get_last_error() to query error information.bool ic4_devenum_update_interface_list | ( | struct IC4_DEVICE_ENUM * | pEnumerator | ) |
Searches for interfaces and populates the enumerator's internal interface list.
[in] | pEnumerator | A pointer to a device enumerator |
true
on success, otherwise false
. Use ic4_get_last_error() to query error information.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.
[in] | pInfo1 | First device info |
[in] | pInfo2 | Second device info |
true
if the device information objects refer to the same video capture device, otherwise false
.true
. 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.
[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(). |
true
on success, otherwise false
. Use ic4_get_last_error() to query error information. const char * ic4_devinfo_get_model_name | ( | const struct IC4_DEVICE_INFO * | pInfo | ) |
Get the model name from a device information object.
[in] | pInfo | A pointer to a device information object |
NULL
if an error occured.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.
[in] | pInfo | A pointer to a device information object |
NULL
if an error occured.const char * ic4_devinfo_get_unique_name | ( | const struct IC4_DEVICE_INFO * | pInfo | ) |
Get the device's unique name from a device information object.
[in] | pInfo | A pointer to a device information object |
NULL
if an error occured.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.
[in] | pInfo | A pointer to a device information object |
NULL
if an error occured.DeviceUserID
feature in the device's property map. const char * ic4_devinfo_get_version | ( | const struct IC4_DEVICE_INFO * | pInfo | ) |
Get the device version from a device information object.
[in] | pInfo | A pointer to a device information object |
NULL
if an error occured.struct IC4_DEVICE_INFO * ic4_devinfo_ref | ( | struct IC4_DEVICE_INFO * | pInfo | ) |
Increases the device information's internal reference count by one.
[in] | pInfo | A pointer to a device information object |
NULL
, the function returns NULL
. An error value is not set.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.
[in] | pInfo | A pointer to a device information object |
NULL
, the function does nothing. An error value is not set.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.
[in] | pInterface1 | First interface object |
[in] | pInterface2 | Second interface object |
true
if the device interface objects refer to the same interface, otherwise false
.true
. 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().
[in] | pInterface | A pointer to a device interface |
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.
[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(). |
true
on success, otherwise false
.const char * ic4_devitf_get_display_name | ( | const struct IC4_INTERFACE * | pInterface | ) |
Returns the name of the device interface.
[in] | pInterface | A pointer to a device interface |
NULL
. Use ic4_get_last_error() to query error information. 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.
[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(). |
true
on success, otherwise false
. Use ic4_get_last_error() to query error information. 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.
[in] | pInterface | A pointer to a device interface |
NULL
. Use ic4_get_last_error() to query error information. 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.
[in] | pInterface | A pointer to a device interface |
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.
[in] | pInterface | A pointer to a device interface |
NULL
. Use ic4_get_last_error() to query error information. struct IC4_INTERFACE * ic4_devitf_ref | ( | struct IC4_INTERFACE * | pInterface | ) |
Increases the device interface's internal reference count by one.
[in] | pInterface | A pointer to a device interface |
NULL
, the function returns NULL
. An error value is not set.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.
[in] | pInterface | A pointer to a device interface |
NULL
, the function does nothing. An error value is not set.bool ic4_devitf_update_device_list | ( | struct IC4_INTERFACE * | pInterface | ) |
Searches for video capture devices and populates the device interfaces's internal device list.
[in] | pInterface | A pointer to a device interface |
true
on success, otherwise false
. Use ic4_get_last_error() to query error information.