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.
	operator bool () 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. Check the err output parameter, DeviceInfo::is_valid() or operator bool().

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 occurs, 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

operator bool()

operator bool ( ) const

inlineexplicitnoexcept

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