![]() |
Imaging Control 4 C Library 1.4.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 occurred.| 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 occurred.| 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 occurred.| 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 occurred.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 occurred.| 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.