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_enumThe 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]errReference 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]errReference 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]errReference 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]cbCallback function to be called when a new device has been detected, or a device was detached.
[out]errReference 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]tokenA token that was returned when registering an event handler using DeviceEnum::eventAddDeviceListChanged().
[out]errReference 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