Device Enumeration
DriverType
-
enum class fluxEngine::DriverType
Driver type.
Values:
-
enumerator Instrument
Instrument driver.
This driver accesses instrument devices, such as cameras, spectrometers, and other sensors.
-
enumerator LightControl
Light control device.
This driver accesses light control devices that can be used to switch a light on and off, and possibly set the light intensity.
-
enumerator Instrument
DriverState
-
enum class fluxEngine::DriverState
Driver state.
Describes the state of the driver at the end of the enumeration process. This can be used to detect issues with the driver.
Values:
-
enumerator Unknown
The state is unknown.
This likely indicates an internal error during enumeration.
-
enumerator OK
OK.
The driver could successfully perform the enumeration. This is a valid state even if the driver didn’t find any device.
-
enumerator LoadTimeout
Driver load timeout.
The driver didn’t respond at all within the specified enumeration timeout, indicating that it didn’t load in time. If a sufficiently long timeout has been provided (e.g. more than 3 seconds) this is typically an indication that there is an issue with the driver.
-
enumerator LoadError
Driver load error.
The driver could not be loaded, for example because the driver file is not valid, or the isolation executable could not be found (in which case all drivers will suffer from this error).
-
enumerator EnumerationError
Enumeration error.
The driver generated an error message during the enumeration process. That error can be queried from the enumeration result.
-
enumerator Crashed
Driver crashed.
The driver crashed during enumeration. This typically indicates that there is an issue with a missing dependency of the driver.
-
enumerator Unknown
enumerateDevices
-
inline EnumerationResult fluxEngine::enumerateDevices(Handle &h, int driverType, std::chrono::milliseconds timeout)
Enumerate devices.
This method enumerates all devices that are connected to the system for which drivers have been installed. Please note that Handle::setDriverIsolationExecutable() and Handle::setDriverBaseDirectory() should be called before this method if the driver directory or the directory of the isolation executable are in non-standard paths.
The result of this function contains interconnected pointers, and all pointers within the result will become invalid once the result has been destroyed.
If an error occurs, an exception will be thrown. The following exceptions may occur:
std::bad_alloc
std::invalid_argument
- Parameters:
h – The fluxEngine handle
driverType – The type of driver to enumerate. Specify
-1to indicate all driver types should be enumerated, or the driver type static-cast to integer for a specific driver type.timeout – How long to enumerate. This method will always wait this long for the enumeration process to complete and will then return all devices that were found within that given timespan. It is recommended to set this to at least 3.5 seconds.
- Returns:
The enumerated devices
EnumerationResult
-
struct EnumerationResult
The result of an enumeration process.
This structure contains the result of an enumeration process. The individual members are interconnected via pointers, so once the result object is destroyed, all pointers to internal members also become invalid.
Public Members
-
std::vector<std::unique_ptr<EnumeratedDevice>> devices
The devices that were found.
-
std::vector<std::unique_ptr<EnumeratedDriver>> drivers
The drivers that were used during enumeration.
-
std::vector<EnumerationWarning> warnings
Warnings that occurred during enumeration.
-
std::vector<EnumerationError> errors
Errors that occurred during enumeration.
-
std::vector<std::unique_ptr<EnumeratedDevice>> devices
EnumeratedDevice
-
struct EnumeratedDevice
Enumerated device.
Describes a device that was found during enumeration.
Note that some drivers can’t actually enumerate the available devices in the system, and rely on probing to actually connect to a device. In that case a device entry will appear regardless of whether the device is actually present, and connection failure is the only way of ascertaining that the device is not actually present.
This structure is allocated as part of the EnumerationResult structure, and will automatically be freed when that structure is freed by the user. The individual sub-structures are inter-linked by pointers that reference each other — for this reason their lifetime is coupled to the entire EnumerationResult structure.
Public Members
-
std::vector<std::uint8_t> id
A driver-specific id of the device.
This id must be provided in combination with the type and name of the driver for a connection attempt.
The id is guaranteed to be stable for a short period of time after enumeration so that it may be used for connection purposes.
It is not guaranteed to be stable across reboots, software updates, etc. The user should never rely on the specific content of this id, even if it appars to be stable at the moment.
-
EnumeratedDriver *driver = {}
The driver that enumerated the device.
-
std::string displayName
The display name of the device.
This is a human-readable text that is of the format
Vendor Model (Serial Number), but in such a manner that if one or more of these strings is empty a sensible text will still be generated — for example, if a device has no serial number, the format will beVendor Modelinstead.
-
std::string manufacturer
The manufacturer of the device.
-
std::string model
The model of the device.
-
std::string serialNumber
The serial number of the device.
This may be empty, which can mean two things: either the device has no serial number, or the serial number could not be obtained during device enumeration and requires the user to connect to the device to actually read it.
-
ParameterInfo parameterInfo
The parameter info for the connection parameters.
Contains information about all connection parameters of the device. For some devices it is necessary to set the some parameters (such as the path to a calibration file) when connecting to the device. This contains the available parameters.
-
std::vector<std::uint8_t> id
EnumeratedDriver
-
struct EnumeratedDriver
Enumerated driver.
Describes a driver that was used during enumeration. Failed drivers will also have such a structure, even though they will not have any associated devices.
This structure is allocated as part of the EnumerationResult structure, and will automatically be freed when that structure is freed by the user. The individual sub-structures are inter-linked by pointers that reference each other — for this reason their lifetime is coupled to the entire EnumerationResult structure.
Public Members
-
std::string name
The name of the driver.
This is the filename component of the driver and may be used to identify the driver for connection purposes.
-
DriverType type = {}
The type of the driver.
This is required for identifying the driver for connection purposes.
-
std::string description
A human-readable name of the driver.
-
std::string version
A human-readable version of the driver.
-
DriverState state = {}
The state of the driver.
-
std::vector<EnumeratedDevice*> devices
The devices the driver has found.
This list may be empty if a specific driver has found no devices.
-
std::string name
EnumerationWarning
-
struct EnumerationWarning
Enumeration Warning.
Describes a warning that was encountered during enumeration. This could be a USB device that could not be accessed because the correct kernel driver is not installed, or a network device that was found but was on the wrong subnet for a given network interface.
This structure is allocated as part of the EnumerationResult structure, and will automatically be freed when that structure is freed by the user. The individual sub-structures are inter-linked by pointers that reference each other — for this reason their lifetime is coupled to the entire EnumerationResult structure.
Public Members
-
EnumeratedDriver *driver = {}
The driver for which the warning occurred.
-
std::string message
The warning message.
-
EnumeratedDriver *driver = {}
EnumerationError
-
struct EnumerationError
Enumeration Error.
Describes an error that occurred during enumeration, for example a driver that crashed.
This structure is allocated as part of the EnumerationResult structure, and will automatically be freed when that structure is freed by the user. The individual sub-structures are inter-linked by pointers that reference each other — for this reason their lifetime is coupled to the entire EnumerationResult structure.
Public Members
-
EnumeratedDriver *driver = {}
the driver for which the error occurred
This may be
nullptrif an error occurred that was not specific to an individual driver.
-
std::string message
The error message.
-
EnumeratedDriver *driver = {}