DeviceEnum Class Reference

Device enumerator. More...

Public Types

using	DeviceListChangedHandler = std::function< void(DeviceEnum &device_enum)> Function prototype for device-list-changed event handlers.
using	NotificationToken = void * Represents a registered callback.

Public Member Functions

	DeviceEnum (Error &err=Error::Default()) Creates a new device enumerator.
bool	is_valid () const noexcept Checks whether this device enumerator is a valid object.
NotificationToken	eventAddDeviceListChanged (DeviceListChangedHandler cb, Error &err=Error::Default()) Registers a new device-list-changed event handler.
bool	eventRemoveDeviceListChanged (NotificationToken token, Error &err=Error::Default()) Unregisters a device-list-changed event handler.

Static Public Member Functions

static std::vector< DeviceInfo >	enumDevices (Error &err=Error::Default()) Get a list of the devices currently attached to the system.
static std::vector< Interface >	enumInterfaces (Error &err=Error::Default()) Get a list of the interfaces present in the system.

Detailed Description

Device enumerator.

To query the devices attached to or the interfaces of the system, use the static functions DeviceEnum::enumDevices and DeviceEnum::enumInterfaces.

Device enumerator instances are only useful to register an event handler listening for changes to the detected device list.

Member Typedef Documentation

◆ DeviceListChangedHandler

using DeviceListChangedHandler = std::function<void(DeviceEnum& device_enum)>

Function prototype for device-list-changed event handlers.

Parameters

[in] device_enum The device enumerator on which the event handler was registered.

◆ NotificationToken

using NotificationToken = void*

Represents a registered callback.

When a callback function is registered using DeviceEnum::eventAddDeviceListChanged, a token is returned.

The token can then be used to remove the callback using DeviceEnum::eventRemoveDeviceListChanged at a later time.

Constructor & Destructor Documentation

◆ DeviceEnum()

DeviceEnum ( Error & err = Error::Default() )

inline

Creates a new device enumerator.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Note: If the constructor fails, the device enumerator object is in an invalid state. All member function calls will fail.

See also: DeviceEnum::is_valid

Member Function Documentation

◆ enumDevices()

static std::vector< DeviceInfo > enumDevices ( Error & err = Error::Default() )

inlinestatic

Get a list of the devices currently attached to the system.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: A std::vector containing ic4::DeviceInfo objects providing information about the detected video capture devices.
If an error occurs, the vector is empty.

◆ enumInterfaces()

static std::vector< Interface > enumInterfaces ( Error & err = Error::Default() )

inlinestatic

Get a list of the interfaces present in the system.

Interfaces represent physical connections for cameras to the computer, e.g. network adapters or USB controllers.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: A std::vector containing ic4::Interface objects providing information about the detected interfaces.
If an error occurs, the vector is empty.

◆ eventAddDeviceListChanged()

NotificationToken eventAddDeviceListChanged	(	DeviceListChangedHandler	cb,
		Error &	err = `Error::Default()`
	)

inline

Registers a new device-list-changed event handler.

Parameters

[in]	cb	Callback function to be called when a new device has been detected, or a device was detached.
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: A token that can be used to unregister the callback using .\n If an error occurrs, the function returns nullptr.

See also: DeviceEnum::eventRemoveDeviceListChanged

◆ eventRemoveDeviceListChanged()

bool eventRemoveDeviceListChanged	(	NotificationToken	token,
		Error &	err = `Error::Default()`
	)

inline

Unregisters a device-list-changed event handler.

Parameters

[in]	token	A token that was returned when registering an event handler using DeviceEnum::eventAddDeviceListChanged().
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: true on success, otherwise false.

See also: DeviceEnum::eventAddDeviceListChanged

◆ is_valid()

bool is_valid ( ) const

inlinenoexcept

Checks whether this device enumerator is a valid object.

If there is an error in the constructor, and function was not configured to throw on error, an invalid object is created. All member function calls will fail.

Returns: true, if this device enumerator was constructed successfully, otherwise false.
In case of an error, check the constructor's error parameter for details.

See also: Error Handling