Device Enumeration

EnumerationResult

typedef struct fluxEngine_C_v1_EnumerationResult fluxEngine_C_v1_EnumerationResult

Device enumeration result.

This structure contains the result of a device enumeration. It will contain a list of devices that were found, a list of drivers that were found (even if the drivers didn’t find any devices), and a list of warnings and errors of the various drivers.

DriverType

enum fluxEngine_C_v1_DriverType

Driver type.

Values:

enumerator fluxEngine_C_v1_DriverType_Instrument

Instrument driver.

This driver accesses instrument devices, such as cameras, spectrometers, and other sensors.

enumerator fluxEngine_C_v1_DriverType_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.

DriverState

enum fluxEngine_C_v1_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 fluxEngine_C_v1_DriverState_Unknown

The state is unknown.

This likely indicates an internal error during enumeration.

enumerator fluxEngine_C_v1_DriverState_OK

OK.

The driver could successfully perform the enumeration. This is a valid state even if the driver didn’t find any device.

enumerator fluxEngine_C_v1_DriverState_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 fluxEngine_C_v1_DriverState_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 fluxEngine_C_v1_DriverState_EnumerationError

Enumeration error.

The driver generated an error message during the enumeration process. That error can be queried from the enumeration result.

enumerator fluxEngine_C_v1_DriverState_Crashed

Driver crashed.

The driver crashed during enumeration. This typically indicates that there is an issue with a missing dependency of the driver.

enumerate_devices

int fluxEngine_C_v1_enumerate_devices(fluxEngine_C_v1_Handle *handle, int type, fluxEngine_C_v1_EnumerationResult **out, int64_t timeoutMs, fluxEngine_C_v1_Error **error)

Enumerate devices.

This method enumerates all devices that are connected to the system for which drivers have been installed. Please note that fluxEngine_C_v1_set_driver_isolation_executable() and fluxEngine_C_v1_set_driver_base_directory() 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 must be freed via fluxEngine_C_v1_EnumerationResult_free(). Note that a call to fluxEngine_C_v1_EnumerationResult_free() will also free the associated structures (except the device parameter info structure of an enumerated device, which must be freed separately).

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

handle – The fluxEngine handle
type – The type of drivers to identify. This may either be a value of type fluxEngine_C_v1_DriverType, or -1 to indicate that all driver types should be searched for
out – [out] The enumeration result
timeoutMs – The time to wait for the enumeration to complete. Note that this method will always wait this amount of time before it returns.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumerationResult_num_devices

int fluxEngine_C_v1_EnumerationResult_num_devices(fluxEngine_C_v1_EnumerationResult *enumeration_result, fluxEngine_C_v1_Error **error)

Get the number of devices found.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumeration_result – The enumeration result
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

The number of devices on success, -1 on failure

EnumerationResult_get_device

int fluxEngine_C_v1_EnumerationResult_get_device(fluxEngine_C_v1_EnumerationResult *enumeration_result, int index, fluxEngine_C_v1_EnumeratedDevice **enumerated_device, fluxEngine_C_v1_Error **error)

Get a specific enumerated device.

Information about the enumerated device may be queried by the corresponding accessors. The pointer returned by this method may be used in comparisons with pointers returned from other methods, such as fluxEngine_C_v1_EnumeratedDriver_get_device(), that return enumerated devices of the same enumeration result.

Important: the device structure will be valid only as long as the enumeration result has not been freed.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceEnumerationInvalidIndex

Parameters:

enumeration_result – The enumeration result
index – The index of the enumerated device, starting at 0, ending at one less than the number of enumerated devices
enumerated_device – [out] The enumerated device
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumerationResult_num_drivers

int fluxEngine_C_v1_EnumerationResult_num_drivers(fluxEngine_C_v1_EnumerationResult *enumeration_result, fluxEngine_C_v1_Error **error)

Get the number of drivers.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumeration_result – The enumeration result
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

The number of drivers on success, -1 on failure

EnumerationResult_get_driver

int fluxEngine_C_v1_EnumerationResult_get_driver(fluxEngine_C_v1_EnumerationResult *enumeration_result, int index, fluxEngine_C_v1_EnumeratedDriver **enumerated_driver, fluxEngine_C_v1_Error **error)

Get a specific driver.

Information about the driver may be queried by the corresponding accessors. The pointer returned by this method may be used in comparisons with pointers returned from other methods, such as fluxEngine_C_v1_EnumeratedDevice_get_driver(), that return drivers of the same enumeration result.

Important: the driver structure will be valid only as long as the enumeration result has not been freed.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceEnumerationInvalidIndex

Parameters:

enumeration_result – The enumeration result
index – The index of the driver, starting at 0, ending at one less than the number of drivers
enumerated_driver – [out] The driver
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumerationResult_num_warnings

int fluxEngine_C_v1_EnumerationResult_num_warnings(fluxEngine_C_v1_EnumerationResult *enumeration_result, fluxEngine_C_v1_Error **error)

Get the number of warnings during enumeration.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumeration_result – The enumeration result
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

The number of warnings on success, -1 on failure

EnumerationResult_get_warning

int fluxEngine_C_v1_EnumerationResult_get_warning(fluxEngine_C_v1_EnumerationResult *enumeration_result, int index, fluxEngine_C_v1_EnumerationWarning **enumeration_warning, fluxEngine_C_v1_Error **error)

Get an enumeration warning.

Information about the warning may be queried by the corresponding accessors. Important: the warning structure will be valid only as long as the enumeration result has not been freed.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceEnumerationInvalidIndex

Parameters:

enumeration_result – The enumeration result
index – The index of the warning, starting at 0, ending at one less than the number of warnings
enumeration_warning – [out] The warning
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumerationResult_num_errors

int fluxEngine_C_v1_EnumerationResult_num_errors(fluxEngine_C_v1_EnumerationResult *enumeration_result, fluxEngine_C_v1_Error **error)

Get the number of errors during enumeration.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumeration_result – The enumeration result
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

The number of errors on success, -1 on failure

EnumerationResult_get_error

int fluxEngine_C_v1_EnumerationResult_get_error(fluxEngine_C_v1_EnumerationResult *enumeration_result, int index, fluxEngine_C_v1_EnumerationError **enumeration_error, fluxEngine_C_v1_Error **error)

Get an enumeration error.

Information about the error may be queried by the corresponding accessors. Important: the error structure will be valid only as long as the enumeration result has not been freed.

The error returned when this method is successful is an error that occurred during the enumeration process, while the error structure that is filled if this method fails is an indication that something went wrong while retrieving the error. The following codes may be returned by this function in that case:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceEnumerationInvalidIndex

Parameters:

enumeration_result – The enumeration result
index – The index of the error, starting at 0, ending at one less than the number of errors
enumeration_error – [out] The error
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumerationResult_free

void fluxEngine_C_v1_EnumerationResult_free(fluxEngine_C_v1_EnumerationResult *enumeration_result)

Free an enumeration result.

Important: all of the structures retrieved from the enumeration result are invalid after a call to this method.

Passing NULL to this method is safe. (In that case this method has no effect.)

Parameters:

enumeration_result – The enumeration result to free

EnumeratedDevice

typedef struct fluxEngine_C_v1_EnumeratedDevice fluxEngine_C_v1_EnumeratedDevice

Enumerated device.

This structure describes an enumerated device. The various accessors may be used to query the manufacturer, model, and serial number of the device, as well as information about the required connection parameters for it. Finally an id is provided that identifies the device to the connect method.

EnumeratedDevice_get_id

int fluxEngine_C_v1_EnumeratedDevice_get_id(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, void **buffer, size_t *size, fluxEngine_C_v1_Error **error)

Get the id of the device.

This device id may be used to identify the device for the purpose of the fluxEngine_C_v1_DeviceGroup_connect() method. The id should be considered non-permanent: unplugging the device and plugging it back in again, or rebooting the computer will likely cause the same device to have a different id. It is guaranteed to be valid for long enough that after an enumeration process the user may use it to connect to that device.

The id should be considered opaque by the user: newer versions of fluxEngine may return a completely different id for the same device; even just updating the driver may result in a different id.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_device – The enumerated device to query
buffer – [out] Where to store the pointer to the allocated id buffer. This must be freed via the fluxEngine_C_v1_id_free() function
size – [out] Where to store the number of bytes the id uses
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDevice_get_driver

int fluxEngine_C_v1_EnumeratedDevice_get_driver(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, fluxEngine_C_v1_EnumeratedDriver **enumerated_driver, fluxEngine_C_v1_Error **error)

Get the driver associated with the device.

The pointer returned by this method in the enumerated_driver parameter will be equal to the pointer of a driver that can be obtained via the fluxEngine_C_v1_EnumerationResult_get_driver() method.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_device – The enumerated device to query
enumerated_driver – [out] Where to store a pointer to the driver structure
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDevice_get_display_name

int fluxEngine_C_v1_EnumeratedDevice_get_display_name(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, char **display_name, fluxEngine_C_v1_Error **error)

Get the display name of a device.

This will return a string that may be shown to the user that identifies the device. It will typically have the format Manufacturer Model (Serial Number), but if one or more of these quantities is empty or missing, they will be omitted.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_device – The enumerated device to query
display_name – [out] The display name of the device. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDevice_get_manufacturer

int fluxEngine_C_v1_EnumeratedDevice_get_manufacturer(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, char **manufacturer, fluxEngine_C_v1_Error **error)

Get the manufacturer of a device.

This will never return a NULL string.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_device – The enumerated device to query
manufacturer – [out] The manufacturer of the device. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDevice_get_model_name

int fluxEngine_C_v1_EnumeratedDevice_get_model_name(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, char **model_name, fluxEngine_C_v1_Error **error)

Get the device model.

This will never return a NULL string.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_device – The enumerated device to query
model_name – [out] The model name of the device. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDevice_get_serial_number

int fluxEngine_C_v1_EnumeratedDevice_get_serial_number(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, char **serial_number, fluxEngine_C_v1_Error **error)

Get the serial number of an enumerated device.

In some cases it is possible to obtain the serial number of a device just from enumerating it. This is often the case for devices that are plugged in via USB (as long as they provide their serial number in the USB descriptor) and for devices that can be found via an Ethernet protocol that supports discovery. This is typically not the case for devices that must be probed (such as devices that are controlled via a serial port).

In case it is possible to obtain a serial number of the device without first connecting to it, that serial number will be reported here. If that is not the case, or the device simply does not have a serial number, a NULL string will be returned. If the device does have a serial number, it will be reported once the device has been connected, even if NULL is returned here. The only guarantee is that if a non-NULL string is returned here, the serial number reported here will be identical to the serial number reported after the user has connected to that device.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_device – The enumerated device to query
serial_number – [out] The serial number of the device. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDevice_get_parameter_info

int fluxEngine_C_v1_EnumeratedDevice_get_parameter_info(fluxEngine_C_v1_EnumeratedDevice *enumerated_device, fluxEngine_C_v1_ParameterInfo **parameter_info, fluxEngine_C_v1_Error **error)

Get the connection parameter info of an enumerated device.

The resulting structure will describe all of the connection parameters that the device provides. For some devices the user must provide connection parameters (such as a calibration file), while they might be optional for other devices.

The resulting parameter information structure will remain valid even if the enumeration result is freed and must be freed explicitly via the fluxEngine_C_v1_ParameterInfo_free() method.

Multiple calls to this method will result in different parameter information structures that are equivalent to having called fluxEngine_C_v1_ParameterInfo_dup() on a single one, but must each be freed individually.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_device – The enumerated device to query
parameter_info – [out] The parameter information structure
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDriver

typedef struct fluxEngine_C_v1_EnumeratedDriver fluxEngine_C_v1_EnumeratedDriver

Enumerated driver.

This structure describes an enumerated driver. The accessors provide the (normalized) file name of the driver, the driver type, the driver description as well as the driver version.

EnumeratedDriver_get_name

int fluxEngine_C_v1_EnumeratedDriver_get_name(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, char **name, fluxEngine_C_v1_Error **error)

Get the normalized file name of the driver.

This must be passed to the fluxEngine_C_v1_DeviceGroup_connect() method to identify the driver that should be used.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_driver – The driver to query
name – [out] The normalized file name of the driver that is used to identify it in conjunction with the driver’s type
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDriver_get_type

int fluxEngine_C_v1_EnumeratedDriver_get_type(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, fluxEngine_C_v1_DriverType *type, fluxEngine_C_v1_Error **error)

Get the type of the driver.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_driver – The driver to query
type – [out] The type of the driver
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDriver_get_description

int fluxEngine_C_v1_EnumeratedDriver_get_description(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, char **description, fluxEngine_C_v1_Error **error)

Get a human-readable description of the driver.

If the driver could not be loaded at all, or the driver crashed before its description could be queried, this method will return NULL.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_driver – The driver to query
description – [out] The description of the driver. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDriver_get_version

int fluxEngine_C_v1_EnumeratedDriver_get_version(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, char **version, fluxEngine_C_v1_Error **error)

Get a human-readable version of the driver.

If the driver could not be loaded at all, or the driver crashed before its version could be queried, this method will return NULL.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_driver – The driver to query
version – [out] The version of the driver. It must be freed by the user via the fluxEngine_C_v1_string_free() method.
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDriver_get_state

int fluxEngine_C_v1_EnumeratedDriver_get_state(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, fluxEngine_C_v1_DriverState *state, fluxEngine_C_v1_Error **error)

Get the driver state.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_driver – The driver to query
state – [out] The state of the driver at the end of the enumeration process
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumeratedDriver_get_num_devices

int fluxEngine_C_v1_EnumeratedDriver_get_num_devices(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, fluxEngine_C_v1_Error **error)

Get the number of devices the driver found.

Note that the result will be returned as the (non-negative) return value of this function and not as an output parameter. Please check for success of this function via the rc < 0 condition and not the rc != 0 check that may be used for other functions.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumerated_driver – The driver to query
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

The number of devices on success, -1 on failure

EnumeratedDriver_get_device

int fluxEngine_C_v1_EnumeratedDriver_get_device(fluxEngine_C_v1_EnumeratedDriver *enumerated_driver, int index, fluxEngine_C_v1_EnumeratedDevice **enumerated_device, fluxEngine_C_v1_Error **error)

Get a device found by the driver.

If a driver found devices during enumeration, this method can be used to obtain the device structure associated with them. The index parameter will only count devices found by this specific driver, regardless of how many devices were found during the entirety of the enumeration process.

The pointer returned by this method in the enumerated_device parameter will be equal to the pointer of a device that can be obtained via the fluxEngine_C_v1_EnumerationResult_get_device() method.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument
fluxEngine_C_v1_ErrorCode_DeviceEnumerationInvalidIndex

Parameters:

enumerated_driver – The driver to query
index – The index of the device, starting at 0, ending at one less than the number of devices this specific driver has found
enumerated_device – [out] Where to store a pointer to the device structure
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumerationWarning

typedef struct fluxEngine_C_v1_EnumerationWarning fluxEngine_C_v1_EnumerationWarning

Enumeration warning.

This structure contains a warning message that a driver produced during the enumeration process.

EnumerationWarning_get_driver

int fluxEngine_C_v1_EnumerationWarning_get_driver(fluxEngine_C_v1_EnumerationWarning *enumeration_warning, fluxEngine_C_v1_EnumeratedDriver **enumerated_driver, fluxEngine_C_v1_Error **error)

Get the driver associated with the warning.

The pointer returned by this method in the enumerated_driver parameter will be equal to the pointer of a driver that can be obtained via the fluxEngine_C_v1_EnumerationResult_get_driver() method.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumeration_warning – The enumeration warning to query
enumerated_driver – [out] Where to store a pointer to the driver structure
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumerationWarning_get_message

int fluxEngine_C_v1_EnumerationWarning_get_message(fluxEngine_C_v1_EnumerationWarning *enumeration_warning, char **message, fluxEngine_C_v1_Error **error)

Get the warning message.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumeration_warning – The enumeration warning to query
message – [out] The enumeration warning. It must be freed by the user via fluxEngine_C_v1_string_free().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumerationError

typedef struct fluxEngine_C_v1_EnumerationError fluxEngine_C_v1_EnumerationError

Enumeration error.

This structure contains an error message that a driver produced during the enumeration process.

EnumerationError_get_driver

int fluxEngine_C_v1_EnumerationError_get_driver(fluxEngine_C_v1_EnumerationError *enumeration_error, fluxEngine_C_v1_EnumeratedDriver **enumerated_driver, fluxEngine_C_v1_Error **error)

Get the driver associated with the error.

The pointer returned by this method in the enumerated_driver parameter will be equal to the pointer of a driver that can be obtained via the fluxEngine_C_v1_EnumerationResult_get_driver() method.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumeration_error – The enumeration error to query
enumerated_driver – [out] Where to store a pointer to the driver structure
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure

EnumerationError_get_message

int fluxEngine_C_v1_EnumerationError_get_message(fluxEngine_C_v1_EnumerationError *enumeration_error, char **message, fluxEngine_C_v1_Error **error)

Get the error message.

The following specific error codes may be returned by this function:

fluxEngine_C_v1_ErrorCode_Unknown
fluxEngine_C_v1_ErrorCode_AllocationFailure
fluxEngine_C_v1_ErrorCode_InvalidArgument

Parameters:

enumeration_error – The enumeration error to query
message – [out] The enumeration error. It must be freed by the user via fluxEngine_C_v1_string_free().
error – [out] The resulting error object, if an error occurs. See the documentation of the fluxEngine_C_v1_Error structure for details on error handling.

Returns:

0 on success, -1 on failure