Error Handling

typedef struct fluxEngine_C_v1_Error fluxEngine_C_v1_Error

Error information structure.

This opaque structure contains information about an error that occurred. It is allocated when an error occurs (and returned to the user) and must be freed with the fluxEngine_C_v1_Error_free() function once the user is done with it.

The structure stores at least the following information:

  • A text message in English that contains a description of the error that occurred (encoded in UTF-8)

  • An error code that gives an indication about the type of error This could be something like “file could not be opened”.

  • An operating system error code that gives more information about the error if the error was caused by a call to an operating system function - for example, if a file could not be opened, this will contain the operating system error code for the reason the file could not be opened

Most fluxEngine functions will have a signature that follows the following pattern: 

int function_name(parameters..., fluxEngine_C_v1_Error** error);
The return value of this function will be 0 on success, or -1 on an error. In that case, if the error parameter of that function call is not NULL, a pointer to a newly allocated error structure will be stored there that the user can inspect to determine more information about the error. Hence there are two methods of calling a fluxEngine function with that type of signature:

  1. Call it by supplying NULL to the error parameter, then the user can detect that an error occurred, but cannot detect any more information about the error: 

    int ret = fluxEngine_C_v1_some_function(param1, param2,
                                        NULL);
if (ret == 0) {
    // SUCCESS
} else {
    // ERROR (but no possibility to determine the type)
}

  2. Call it by supplying a pointer to an error structure, then it is possible to determine the type of error: 

    fluxEngine_C_v1_Error* error = NULL;
int ret = fluxEngine_C_v1_some_function(param1, param2,
                                        &error);
if (ret == 0) {
    // SUCCESS
} else {
    // ERROR
    char* error_message = strdup(
        fluxEngine_C_v1_Error_get_message(error));
    int64_t error_code =
        fluxEngine_C_v1_Error_get_code(error);
    fluxEngine_C_v1_Error_free(error);
}
    A special condition exists: if an out-of-memory condition occurs, the error structure will be NULL. This is due to the fact that if not enough memory was available to allocate something, there is likely also not enough memory available to allocate the error object. The fluxEngine_C_v1_Error_get_message(), fluxEngine_C_v1_Error_get_code() and fluxEngine_C_v1_Error_get_os_code() functions will treat a NULL pointer passed to them as an allocation error.

enum fluxEngine_C_v1_ErrorCode

Error code.

This enumeration describes possible error codes that give an indication what went wrong when calling specific functions.

Values:

enumerator fluxEngine_C_v1_ErrorCode_Success

Success.

This error code will never be returned, but exists in this enumeration for the sake of completeness.

(Note that when a NULL error structure is returned when a function fails, it indicates an allocation failure, not the success of the operation.)

enumerator fluxEngine_C_v1_ErrorCode_Unknown

Unknown error.

If an error occurred that has not yet been categorized with a specific error code, this code will be returned.

enumerator fluxEngine_C_v1_ErrorCode_AllocationFailure

Allocation failure.

This code will never be stored in an actual error object, as allocation failures will be returned as NULL error structures. However, fluxEngine_C_v1_Error_get_code() will return this code when given a NULL pointer.

enumerator fluxEngine_C_v1_ErrorCode_InvalidArgument

Invalid argument.

If an argument passed to a function is invalid (for example if a NULL pointer is passed where it should not have been, but also other cases), then this method will be returned.

enumerator fluxEngine_C_v1_ErrorCode_HandleNoLongerValid

The handle is no longer valid.

If an operation is performed on a handle that has been destroyed, but where the metadata is still kept in memory because one or more models and/or processing contexts have not yet been freed, this error will be returned.

If this error occurs this indicates undefined behavior, as this essentially amounts to a use-after-free of the handle structure.

enumerator fluxEngine_C_v1_ErrorCode_ModelNoLongerValid

The model is no longer valid.

If an operation is performed on a model whose handle has already been destroyed, this error will be returned.

In contrast to fluxEngine_C_v1_ErrorCode_HandleNoLongerValid occurring, this is only undefined behavior if the model that is being operated on has already been freed once.

enumerator fluxEngine_C_v1_ErrorCode_ProcessingContextNoLongerValid

The processing context is no longer valid.

If an operation is performed on a model whose handle has already been destroyed, this error will be returned.

It is also possible that this error is returned if the number of processing threads of a given handle was changed after creating the processing context.

In contrast to fluxEngine_C_v1_ErrorCode_HandleNoLongerValid occurring, this is only undefined behavior if the model that is being operated on has already been freed once.

enumerator fluxEngine_C_v1_ErrorCode_IndexOutOfRange

An index that was supplied is out of range.

When using functions that return information about an object that is indexed, such as fluxEngine_C_v1_Model_get_group_info() to obtain the information about a specific group within a model, if the index is out of range, this error code will be returned.

For example, if a model has 3 groups and the group_id parameter given to fluxEngine_C_v1_Model_get_group_info() is not 0, 1 or 2, then this error will be returned.

enumerator fluxEngine_C_v1_ErrorCode_NotImplemented

Not implemented.

A specific functionality is not implemented in fluxEngine’s public API (yet).

enumerator fluxEngine_C_v1_ErrorCode_InvalidWrapper

Invalid wrapper.

This error code will never occur in the pure C API, but is reserved for languages that wrap the C API in an object oriented languages, such as C++. In that case wrapper objects may exist that don’t contain a valid pointer to an underlying C object — and accessing those should result in an error. This error code is for these circumstances.

enumerator fluxEngine_C_v1_ErrorCode_FileAccessError

Generic File I/O error.

If accessing a file fails, and the implementation cannot currently determine the precise type of error, this code will be returned to indciate any type of error related to accessing a given file.

enumerator fluxEngine_C_v1_ErrorCode_FileNotFoundError

File Not Found.

This error code is returned if a file was not found when trying to access it.

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

enumerator fluxEngine_C_v1_ErrorCode_FileAccessDeniedError

File Access Denied.

This error code is returned if a file could not be opened due to a lack of permissions for either the file itself, or a directory leading up to the file.

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

enumerator fluxEngine_C_v1_ErrorCode_FileTypeError

File Type Error.

This error code is returned if the specified file is not actually a file, but for example a directory (or some other filesystem object that is not considered a file).

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

enumerator fluxEngine_C_v1_ErrorCode_FileInUseError

File Is In Use.

This error code is returned if a file could not be opened because it is in use by another program.

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

enumerator fluxEngine_C_v1_ErrorCode_ReadOnlyFilesystem

Read-Only Filesystem.

This error code is reserved for future use.

(Currently there are no functions in fluxEngine that write files.)

enumerator fluxEngine_C_v1_ErrorCode_IOError

I/O Error.

This error code is returned if a file could not be opened or an I/O operation could not be perfomed due to an I/O error. This could be due to a hardware device malfunctioning, or a network drive suddenly becoming inaccessible.

Note that if the precise cause of failing to open a file could not be determined, the more generic fluxEngine_C_v1_ErrorCode_FileAccessError could also be returned.

enumerator fluxEngine_C_v1_ErrorCode_HandleAlreadyCreated

A handle has already been created.

Current limitations of the fluxEngine library allow only for the creation of a single handle. If the user attempts to create a second handle, this error code will be returned.

enumerator fluxEngine_C_v1_ErrorCode_InvalidLicense

Invalid license.

The supplied license is invalid, and could either not be parsed, or the parsed data did not make any sense. This is typically the case if something other than the correct license file is passed to fluxEngine_C_v1_init().

enumerator fluxEngine_C_v1_ErrorCode_LicenseWrongProduct

License is for wrong product.

The supplied license is for the wrong product (for example, fluxTrainer), but not for fluxEngine.

enumerator fluxEngine_C_v1_ErrorCode_LicenseExpired

License has expired.

If the license was issued only up to a certain date, and that date has passed, the license is expired and this error will be returned.

enumerator fluxEngine_C_v1_ErrorCode_LicenseUpdateExpired

License is for previous versions of the software.

The supplied license is only valid for versions of fluxEngine that were built before a specific date, and the current version of fluxEngine has passed that date.

enumerator fluxEngine_C_v1_ErrorCode_LicenseIdentifierMismatch

License identifier mismatch.

The supplied license does not match the current system. For example, when a license issued to the mainboard serial number of a given system is run on a system with a different mainboard serial number, this error will be returned.

enumerator fluxEngine_C_v1_ErrorCode_LicenseDongleRemoved

The license dongle has been removed.

The license was tied to a dongle and that dongle has since been removed from the computer.

enumerator fluxEngine_C_v1_ErrorCode_LicenseDeviceNotConnected

The device the license is tied to is not connected.

If the license is tied to the serial number of a device (such as a camera), it must be connected before certain operations can occur, such as the creation of a processing context or the processing of data. If the device is not currently connected this error will be returned. (Note that only the current connection state is checked.)

If the license is not tied to the serial number of a camera this type of error will not occur.

enumerator fluxEngine_C_v1_ErrorCode_LicenseFeatureNotPresent

A license feature required for this operation is not present in the license.

For example, if model processing is not enabled, attempting to load a model will fail with this error.

When creating a device processing context, if a specific device is of a type that is not supported by the license, this may also be returned.

enumerator fluxEngine_C_v1_ErrorCode_ThreadCreationError

Unable to create a background processing thread.

A background processing thread could not be created by fluxEngine, possibly due to resource exhaustion or an operating system limit.

enumerator fluxEngine_C_v1_ErrorCode_ThreadInitFunctionError

The user-supplied thread initialization function returned a non-zero return code.

The user-supplied thread initialization function returned a non-zero return code, causing the thread creation to be aborted. It is up to the user to store further information about the failure to perform the per-thread initialization in the user-defined context.

enumerator fluxEngine_C_v1_ErrorCode_InvalidModelData

Invalid Model Data.

When loading a model (either from memory or from a file) this error code is returned if the model could not be loaded, for example because the data of the model was corrupt, or the file that was passed was not a LuxFlux Runtime Model (.fluxmdl).

enumerator fluxEngine_C_v1_ErrorCode_ModelContainsUnsupportedFilter

Model Contains Unsupported Filter.

The supplied model contains a filter that is not supported by the current version of fluxEngine. It was likely created with a newer version of fluxTrainer.

enumerator fluxEngine_C_v1_ErrorCode_ModelContainsUnlicensedFilter

Model Contains Unlicensed Filter.

The supplied model contains a filter that is not allowed by the currently loaded license, and can hence not be loaded.

enumerator fluxEngine_C_v1_ErrorCode_ModelNotConsistent

The supplied model is not consistent.

The model that was loaded is not in a consistent state. This indicates a problem during the export of the model.

enumerator fluxEngine_C_v1_ErrorCode_ModelSourceTypeUnsupported

The supplied model is for unsupported data.

The model that was loaded is for processing data of a type that is currently not supported by fluxEngine. Currently only hyperspectral data (Cubes or PushBroom frames) are supported.

enumerator fluxEngine_C_v1_ErrorCode_ModelWrongSourceType

The loaded model is not a HSI model.

When creating a processing context for HSI data, if the loaded model is not a HSI model, this error code will be returned.

At the moment, this will never happen, as only HSI models can be loaded. Future versions might return this error code though.

enumerator fluxEngine_C_v1_ErrorCode_FilterCreationError

Could not create required filter.

When creating a processing context, several filters are automatically created and added to the model to ensure that they can properly transform the input data to the format the model expects. This error is returned if one of these filters could not be created for any reason.

enumerator fluxEngine_C_v1_ErrorCode_WavelengthRangeDeterminationError

Could not determine wavelength range of model.

The wavelength setting of the source node in a given model could not be read during the creation of a processing context.

enumerator fluxEngine_C_v1_ErrorCode_InputDimensionError

The supplied dimensions of the input do not make sense.

The dimensions of the input supplied while either creating a processing context or providing the next input data pointer do not make sense, for example because a negative number was provided.

enumerator fluxEngine_C_v1_ErrorCode_InputStrideError

The supplied stride of the input does not fit.

The stride of the input supplied while providing the next input data pointer does not fit the dimension structure of the input data.

For example, if an entire cube is being processed, and the dimension structure of the cube is (500, 300, 200), then a stride structure of (60000, 200, 1) would be acceptable, but a stride structure of (50000, 200, 1) would not be, as the first stride is smaller than the second stride times the second dimension.

enumerator fluxEngine_C_v1_ErrorCode_WhiteReferenceMissingError

No white reference provided.

When creating a processing context for a model that is given in reflectances or absorbances, but the data provided by the user will be in raw intensities, a white reference must exist for fluxEngine to be able to automatically reference the input data. If no white reference is provided during processing context creation in that circumstance, this error will be returned.

Note: this error will not occur if the data provided by the user is already reflectance data — or the model is set to process raw intensities and the user provides intensity data.

enumerator fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

The provided dimensions of the white reference are not acceptable.

When providing a white reference while setting up a processing context, the dimension of the provided reference must be supplied. If those dimensions are not congruent to the input dimensions, this error code will be returned.

Please note that references always have an additional dimension that allows fluxEngine to average over multiple reference measurements, so the reference for processing entire HSI cubes will be a tensor of order 4, for example.

enumerator fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

The provided dimensions of the dark reference are not acceptable.

When providing a dark reference while setting up a processing context, the dimension of the provided reference must be supplied. If those dimensions are not congruent to the input dimensions, this error code will be returned.

Please note that references always have an additional dimension that allows fluxEngine to average over multiple reference measurements, so the reference for processing entire HSI cubes will be a tensor of order 4, for example.

enumerator fluxEngine_C_v1_ErrorCode_PreprocessingSetupError

An error occurred while setting up preprocessing.

While performing the final actions required to initialize the preprocessing steps for the input data, an error occurred.

enumerator fluxEngine_C_v1_ErrorCode_ProcessingSetupError

An error occurred while setting up processing.

While performing the final actions required to initialize the processing sequence, an error occurred.

enumerator fluxEngine_C_v1_ErrorCode_InputWavelengthValueError

Input wavelength value error.

One of the wavelengths supplied as the input data did not have a finite value. This happens if the list of input wavelengths contain NaN or infinities.

enumerator fluxEngine_C_v1_ErrorCode_InputScalarTypeError

Input scalar type error.

The scalar type of the specified input does not match the scalar type of the processing context.

enumerator fluxEngine_C_v1_ErrorCode_OutputIdNotPresent

No output sink with the given output id is present.

This error will be returned by fluxengine_C_v1_ProcessingContext_find_output_sink() if there is no output sink in the loaded model with the requested output id.

enumerator fluxEngine_C_v1_ErrorCode_OutputIdNotUnique

Multiple outuput sinks with the given output id are present.

This error will be returned by fluxengine_C_v1_ProcessingContext_find_output_sink() if there is more than one output sink in the loaded model with the requested output id.

enumerator fluxEngine_C_v1_ErrorCode_StorageTypeMismatch

Storage type mismatch while introspecting an output sink.

When using either fluxEngine_C_v1_ProcessingContext_get_output_sink_tensor_structure() or fluxEngine_C_v1_ProcessingContext_get_output_sink_object_list_structure() to obtain more detailed information about an output sink, if the output sink has a different storage type, this error will be returned.

For example, calling fluxEngine_C_v1_ProcessingContext_get_output_sink_tensor_structure() for an output sink that will return a list of detected objects would result in this error.

enumerator fluxEngine_C_v1_ErrorCode_ProcessingContextTypeMismatch

The processing context is of the wrong type.

When setting the next input pointer by either fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() or fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() or their corresponding extended variants, if the context was created for a different type of data, this error will be returned.

For example, calling fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() on a context that was created to process PushBroom frames will result in this error.

enumerator fluxEngine_C_v1_ErrorCode_ProcessingUnknownError

An unknown error occurred during processing.

This happens when the actual processing step during a call to fluxEngine_C_v1_ProcessingContext_process_next() fails in an unknown manner.

enumerator fluxEngine_C_v1_ErrorCode_ProcessingInternalError

An internal error occurred during processing.

An internal error occurred during data processing.

enumerator fluxEngine_C_v1_ErrorCode_ProcessingAborted

Processing was aborted by the user.

enumerator fluxEngine_C_v1_ErrorCode_ProcessingSourceDataMissing

The source data for processing was not set by the user.

If the user has never called any of the fluxEngine_C_v1_ProcessingContext_set_source_data_hsi_cube() or fluxEngine_C_v1_ProcessingContext_set_source_data_pushbroom_frame() functions or their extended variants before a call to fluxEngine_C_v1_ProcessingContext_process_next() this error will occur.

This also occurs if the user has not set the source data again after a call to fluxEngine_C_v1_ProcessingContext_reset_state().

enumerator fluxEngine_C_v1_ErrorCode_ParameterInfoNoLongerValid

The parameter info is no longer valid.

If a given parameter info was obtained from a connected device the parameter information will only remain valid as long as the device is connected. If the device has since disconnected the parameter information will become invalid.

If that is the case this error will be returned by methods that return information about a parameter info.

enumerator fluxEngine_C_v1_ErrorCode_ParameterIndexOutOfRange

The parameter index is out of range.

If information about a parameter is queried by index and the given parameter index is out of range, this error will occur.

Note that a negativ index will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as a negativ index is never valid.

enumerator fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist

A parameter with that name does not exist.

If information about a parameter is queried by name and that name does not describe a valid parameter, this error will occur.

Note that a null pointer supplied for the name will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as that can never be valid.

An alias for this code exists under the name fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound.

enumerator fluxEngine_C_v1_ErrorCode_ParameterInternalQueryError

An internal error occurred while querying a parameter.

This indicates an internal error (and likely a bug) when querying information about a parameter.

enumerator fluxEngine_C_v1_ErrorCode_ParameterWrongType

When querying a parameter the wrong type was encountered.

When querying information about a parameter that requires the parameter to be of a specific type, and the parameter in question is of a different type, this error occurs.

An alias for this code exists under the name fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError.

enumerator fluxEngine_C_v1_ErrorCode_ParameterEnumerationIndexOutOfRange

The enumeration entry index is out of range.

If information about an enumeration entry is queried by index and the given enumeration entry index is out of range, this error will occur.

Note that a negativ index will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as a negativ index is never valid.

enumerator fluxEngine_C_v1_ErrorCode_ParameterEnumerationNameDoesNotExist

An enumeration entry with that name does not exist.

If information about an enumeration entry is queried by name and that name does not describe a valid enumeration entry, this error will occur.

Note that a null pointer supplied for the name will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as that can never be valid.

enumerator fluxEngine_C_v1_ErrorCode_ParameterAffectedIndexOutOfRange

The affected parameter index is out of range.

If information about an affected parameter is queried by index and the given affected parameter index is out of range, this error will occur.

Note that a negativ index will result in a fluxEngine_C_v1_ErrorCode_InvalidArgument instead of this error, as a negativ index is never valid.

enumerator fluxEngine_C_v1_ErrorCode_ParameterNoDefaults

No defaults are available for the given parameter info.

Parameter infos of connected devices do not contain information about default values. When querying default values of these parameter infos this error will occur.

enumerator fluxEngine_C_v1_ErrorCode_ParameterQueryError

Error querying parameter information.

An error occurred while querying parameter information. For example, when attempting to query the minimum value of a parameter that is currently not accessible, this error might occur.

enumerator fluxEngine_C_v1_ErrorCode_DeviceEnumerationInvalidIndex

An invalid index was supplied while querying an enumeration result.

While retrieving an enumeration result object (driver, device, warning, error) by its index, an invalid index was supplied by the user.

For example, if there were 2 devices found, but the user wants to query the device with index 15, this erorr will occur.

enumerator fluxEngine_C_v1_ErrorCode_DriverNotFound

The specified driver could not be found.

When attempting to connect to a device group the specified driver (identified by driver type and name) could not be found.

enumerator fluxEngine_C_v1_ErrorCode_DeviceConnectionEnumerationTimeout

Device connection: enumeration timeout.

When connecting to a device the device is searched for internally before connecting to it. If the device cannot be found again (assuming the device id stems from a previous enumeration attempt) this error will occur.

Typically this happens when the device disappears between initial enumeration and the connection attempt. This could be due to a loose connection, sudden power loss, or the device crashing after the initial enumeration attempt.

enumerator fluxEngine_C_v1_ErrorCode_DeviceConnectionDriverError

Device connection: driver error.

During device connection a driver error occurred, most likely indicating that the driver itself crashed for some reason.

enumerator fluxEngine_C_v1_ErrorCode_DeviceConnectionParametrizationError

Device connection: internal parametrization error.

The driver returned invalid connection parameter information during the connection attempt. This is likely a bug in the driver or fluxEngine.

enumerator fluxEngine_C_v1_ErrorCode_DeviceConnectionFailed

Device connection: connection failed.

Could not connect to the specified device. The error message will be the message generated by the driver and give a better indication about the actual issue when not being able to connect to the device.

The most common possible causes are:

  • For devices that must be probed: the device is not connected

  • The user doesn’t have permissions to access the device

  • For network devices: the device is in the wrong subnet and is hence not accessible

  • For network devices: the system firewall blocks fluxDriverIsolation.exe from receiving packets from the network

  • The device is not supported by the driver (and that could only be determined during a connection attempt)

  • An invalid connection setting (such as an invalid calibration file) was specified during the connection attempt

enumerator fluxEngine_C_v1_ErrorCode_DeviceNoLongerValid

The device is no longer valid.

This error occurs when the user attempts to access a device when the corresponding fluxEngine handle has been closed and the device has been force-disconnected and is no longer in a valid state. The user must unload the device group when this error occurs.

enumerator fluxEngine_C_v1_ErrorCode_DeviceParameterListNotFound

Parameter list not found.

The specified parameter list has not been exposed by the connected driver.

enumerator fluxEngine_C_v1_ErrorCode_DeviceParameterNotFound

Parameter not found (alias)

A parameter with the specific name does not exist.

This error may also occur during device connection and when writing unrelated parameters, as some parameters are re-read after connection and after each parameter change to keep meta data for the device up to date. If one of these internal parameters (that the driver uses to give fluxEngine additional information) is somehow missing, this error could occur in those cases (i.e. writing to a different parameter or connecting the device group).

This name is an alias for fluxEngine_C_v1_ErrorCode_ParameterNameDoesNotExist, as they have the same code.

enumerator fluxEngine_C_v1_ErrorCode_DeviceParameterAccessError

Parameter access error.

The parameter in question could not be accessed

This occurs when a parameter is not accessible (in the case of read or write operation) or read-only (in the case of a write operation).

For example, some camera devices have the ability to set a frame rate independent of the exposure time — and a boolean parameter must be enabled for this before the actual frame rate parameter may be written to (or even read from).

enumerator fluxEngine_C_v1_ErrorCode_DeviceParameterTypeError

Parameter type error (alias)

The parameter in question has the wrong type. For example, attempting to read an integer value from a string parameter will result in this error.

This error may also occur during device connection and when writing unrelated parameters, as some parameters are re-read after connection and after each parameter change to keep meta data for the device up to date. If one of these internal parameters (that the driver uses to give fluxEngine additional information) has the wrong type (due to a bug in the driver), this error could occur in those cases (i.e. writing to a different parameter or connecting the device group).

This name is an alias for fluxEngine_C_v1_ErrorCode_ParameterWrongType, as they have the same code.

enumerator fluxEngine_C_v1_ErrorCode_DeviceParameterReadError

Parameter read error.

The parameter in question could not be read, even though the access mode is OK.

This can have multiple reasons, for example if the device has been unplugged in the mean time.

This error may also occur during device connection and when writing unrelated parameters, as some parameters are re-read after connection and after each parameter change to keep meta data for the device up to date. If one of these internal parameters (that the driver uses to give fluxEngine additional information) cannot be read, this error could occur in those cases (i.e. writing to a different parameter or connecting the device group).

enumerator fluxEngine_C_v1_ErrorCode_DeviceParameterWriteError

Parameter write error.

The parameter in question could not be written to.

This may occur if an invalid value is given to a parameter. For example, if an integer parameter only accepts values between 2 and 5, and the value 17 is supplied, this error may occur.

enumerator fluxEngine_C_v1_ErrorCode_DeviceTypeError

Device type error.

When attempting to use a type-specific device function (such as functions for instrument devices or light control devices), if the type of the device does not match the function that is being called, this error will occur.

enumerator fluxEngine_C_v1_ErrorCode_DeviceStatusQueryError

Device status query error.

Typically it should always be possible to query the status of a connected device, even if the device is in an irrecoverable error state. But if that does fail for some unknown reason this error will occur.

enumerator fluxEngine_C_v1_ErrorCode_DeviceResetError

Device recoverable error reset failed.

While attempting to reset from a recoverable error the reset failed. This can typically occur in three situations:

  • The recoverable error has not yet been cleared — for example a temperature sensor might still indicate that a temperature is too far out of bounds for the device to function at all.

  • The original recoverable error has cleared, but in the mean time a different recoverable error has occurred.

  • The device has encountered an irrecoverable error in the mean time.

enumerator fluxEngine_C_v1_ErrorCode_InstrumentDeviceIncompatibleError

The instrument device is not compatible with fluxEngine.

The instrument device is currently not compatible with the public fluxEngine API. This may occur if a newer driver is used in conjunction with an older version of fluxEngine.

enumerator fluxEngine_C_v1_ErrorCode_InstrumentDeviceShmAlreadySetup

The shared memory buffers have already been set up.

fluxEngine_C_v1_InstrumentDevice_setup_internal_buffers() may only be called once for an instrument device; any call to that method afterwards will trigger this error.

enumerator fluxEngine_C_v1_ErrorCode_InstrumentDeviceShmSetupError

Error setting up shared memory buffers.

fluxEngine_C_v1_InstrumentDevice_setup_internal_buffers() could not set up the shared memory segment for receiving buffers from the instrument device.

If not enough memory is available for the amount (and size) of the buffers this could occur on a normal system, but otherwise is an indication of a more serious problem.

enumerator fluxEngine_C_v1_ErrorCode_InstrumentDeviceShmNotSetupError

Shared memory has not yet been set up.

This occurs when attempting to start acquisition while the shared memory has not yet been set up.

enumerator fluxEngine_C_v1_ErrorCode_InstrumentDeviceInvalidReferenceName

The specified reference name is invalid.

While starting acquisition, if the specified reference name is not supported by the device, this error will occur. (See the documentation of the fluxEngine_C_v1_InstrumentDeviceAcquisitionParameters structure for further details.)

enumerator fluxEngine_C_v1_ErrorCode_InstrumentDeviceAcquisitionStartError

Acquisition start error.

Device acquisition could not be started. This typically indicates a misconfiguration of the device, or a bug in the driver.

enumerator fluxEngine_C_v1_ErrorCode_InstrumentDeviceAcquisitionStopError

Acquisition stop error.

Device acquisition could not be stopped. This typically indicates a bug in the driver or fluxEngine, as stopping acquisition should always work.

enumerator fluxEngine_C_v1_ErrorCode_InstrumentDeviceInternalBufferError

Internal buffer error.

This is an indication of a bug in the driver or fluxEngine because the driver returned a buffer that fluxEngine doesn’t know about.

enumerator fluxEngine_C_v1_ErrorCode_BufferAlreadyReturned

Buffer already returned.

Cannot perform an operation on a buffer that has been returned back to the driver.

enumerator fluxEngine_C_v1_ErrorCode_BufferContainerFull

Buffer container full.

Cannot add a buffer to a container because the container is full.

enumerator fluxEngine_C_v1_ErrorCode_BufferStructureMismatch

Buffer structure mismatch.

When copying data into a persistent buffer, or copying data out of a buffer, there is a mismatch between the structure of the buffer and the source or target of the copy operation.

enumerator fluxEngine_C_v1_ErrorCode_BufferTargetMemoryTooSmallError

Buffer target memory too small.

When extracting raw data from a buffer container this indicates the memory area the user has provided is too small.

enumerator fluxEngine_C_v1_ErrorCode_BufferContainerPastRingBufferSize

Buffer container: the entry is no longer available.

When extracting data from a buffer container: the buffer container in question is a ring buffer, and the specific entry is not available anymore due to the ring buffer’s capacity.

enumerator fluxEngine_C_v1_ErrorCode_LightControlDeviceForceStateError

Cannot force state of light control device.

This is coupled with a driver-generated error message that explains the reason for the failure.

enumerator fluxEngine_C_v1_ErrorCode_LightControlDeviceRampError

Cannot wait for the ramp of the light control device.

This is coupled with a driver-generated error message that explains the reason for the failure.

enumerator fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

Device processing setup: invalid reference.

The user has specified a reference during the processing setup that the driver does not support in the current mode. For example, a device that provides pre-referenced data (for example a virtual camera) will not support white or dark references when setting up a processing context.

enumerator fluxEngine_C_v1_ErrorCode_DeviceProcessingInformationMissing

Device processing setup: internal inforamtion missing.

The driver has not provided the appropriate amount of information for fluxEngine to be able to set up a processing context for the device. This is likely a bug in the driver.

enumerator fluxEngine_C_v1_ErrorCode_DeviceProcessingPreprocessingSetupError

Device processing setup: preprocessing setup error.

Could not set up the preprocessing steps for a processing context. The following lists the situations that could lead to this error (though the list is not exhaustive):

  • A missing white reference in some cases

  • The user wants to record HSI data interpolated onto a wavelength grid that has no overlap with the actual wavelengths of the device

  • The user’s license for fluxEngine does not support the specific preprocessing steps required

enumerator fluxEngine_C_v1_ErrorCode_DeviceProcessingReferenceSetupError

Reference setup error.

An error occurred while setting up the supplied reference measurements that didn’t fall into one of the existing categories, such as:

  • fluxEngine_C_v1_ErrorCode_DeviceProcessingInvalidReferenceError

  • fluxEngine_C_v1_ErrorCode_WhiteReferenceDimensionError

  • fluxEngine_C_v1_ErrorCode_DarkReferenceDimensionError

enumerator fluxEngine_C_v1_ErrorCode_DeviceProcessingBufferIncompatible

The suppled processing buffer is incompatible.

When using a device buffer or persistent buffer as the input to a processing context (via either fluxEngine_C_v1_ProcessingContext_set_source_data_persistent_buffer() or fluxEngine_C_v1_ProcessingContext_set_source_data_buffer()), if the structure of the buffer is not compatible with the processing context, this error will occur.

For example, if the user creates a processing context for a camera device, changes the ROI of the camera, and then uses buffers obtained after the ROI change with the processing context before the ROI change, this error may occur.

enumerator fluxEngine_C_v1_ErrorCode_MeasurementProcessingTypeError

The measurement type is incompatible with the model.

When creating a processing context for a specific measurement, if the type of the measurement is incompatible with the given model, this error will occur.

enumerator fluxEngine_C_v1_ErrorCode_MeasurementProcessingMutuallyIncompatible

Multiple measurements are mutually incompatible.

When creating a processing context for a list of measurements, and the measurements in the list are mutually incompatible (for example due to a different scalar type, but could also be if they have different white/dark references), this error will occur.

enumerator fluxEngine_C_v1_ErrorCode_MeasurementProcessingIncompatibleWithFixedSize

Cannot create a processing context for fixed sizes.

When creating a processing context for a list of measurements, and the measurements in the list are compatible, but have varying spatial sizes, and the user has not specified the fluxEngine_C_v1_MeasurementProcessingContextFlag_VariableSpatialSize flag, this error will occur.

typedef int fluxEngine_C_v1_OsErrorCode

Operating system error code.

This typedef aliases the operating system’s type to report errors. On Windows systems this is DWORD, as that is returned by GetLastError(), on all other systems it is int, as that is the type of the errno variable.

char const *fluxEngine_C_v1_Error_get_message(fluxEngine_C_v1_Error *error)

Get a human-readable message associated with an error.

Returns a human-readable message associated with the given error. The human-readable message will be in English, encoded in UTF-8, and may be subject to change between versions. It must therefore not be parsed by the user, and only used for informational purposes - display the message for the user, log the message, or similar.

The pointer returned by this function must not be freed by the user directly. It is valid until the error object is freed, after that the user must not use it anymore. If the message is needed for a longer period of time, the string must be copied.

If a NULL pointer is passed to this function, it is assumed that an allocation error occurred, in which case this method will return the fixed string "Allocation failure".

Parameters

  • error – The error object to obtain the message from

Returns

The message associated with the error object

int64_t fluxEngine_C_v1_Error_get_code(fluxEngine_C_v1_Error *error)

Get the code associated with an error.

Returns a generic code associated with an error. This code will be one of the values defined in fluxEngine_C_v1_ErrorCode.

If a NULL pointer is passed to this function, it is assumed that an allocation error occurred, in which case this method will return the fixed value fluxEngine_C_v1_ErrorCode_AllocationFailure.

Parameters

  • error – The error object to obtain the code from

Returns

The error code stored in the object

fluxEngine_C_v1_OsErrorCode fluxEngine_C_v1_Error_get_os_code(fluxEngine_C_v1_Error *error)

Get the operating system code associated with an error.

If an error was caused by an operating system function, for example, while opening a file, this will contain the operating system error code underlying to the error.

On Windows systems this will correspond to the result of GetLastError() called immediately after the call to the operating system function that resulted in the error.

On other operating systems this will correspond to the value of the global errno variable read immediately after the call to the operating system function that resulted in the error.

Note that due to the usage of third-party libraries it is not always possible for fluxEngine to determine the underlying operating system error code of a failed operation, even if an operating system function is responsible for the error. In that case this may still be 0.

If a NULL pointer is passed to this function, it is assumed that an allocation error occurred, in which case this method will return ERROR_OUTOFMEMORY on Windows systems and ENOMEM on all other systems.

Parameters

  • error – The error object to obtain the code from

Returns

The error code stored in the object, or 0 if the error was not caused by a call to an operating system function, or if the operating system error could not be determined for some reason.

void fluxEngine_C_v1_Error_free(fluxEngine_C_v1_Error *error)

Free an error object.

Frees all of the memory associated with a given error object. Any pointer returned by fluxEngine_C_v1_Error_get_message() is invalid after a call to this method.

It is safe to pass a NULL pointer to this function, in which case nothing will happen.

Parameters

  • error – The error object to free