Error Handling

ErrorCode

enum class fluxEngine::ErrorCode

Error Codes.

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

Any exception thrown by fluxEngine that is a subclass of the Error class will contain one of these codes.

This does not include a mapping of all C error codes, as some of them are mapped onto the exception classes of the standard library. See the Error class for details.

See also

Error

Values:

enumerator Unknown

Unknown error.

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

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

This error code will always be set in a subclass of Error, ObjectNoLongerValidError, to allow the user to polymorphically catch this kind of error.

enumerator 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 ErrorCode::HandleNoLongerValid occurring, this is not an indication of undefined behavior.

This error code will always be set in a subclass of Error, ObjectNoLongerValidError, to allow the user to polymorphically catch this kind of error.

enumerator 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 ErrorCode::HandleNoLongerValid occurring, this is not an indication of undefined behavior.

This error code will always be set in a subclass of Error, ObjectNoLongerValidError, to allow the user to polymorphically catch this kind of error.

enumerator NotImplemented

Not implemented.

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

This error code will always be set in a subclass of Error, NotImplementedError, to allow the user to polymorphically catch this kind of error.

enumerator InvalidWrapper

Invalid wrapper.

The user has attempted to access a default-constructed wrapper object that doesn’t wrap a valid underlying C pointer.

This error code will always be set in a subclass of Error, EmptyWrapperError, to allow the user to polymorphically catch this kind of error.

See also

Error

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

This error code will always be set in a subclass of Error, FileAccessError, to allow the user to polymorphically catch this kind of error.

See also

FileAccessError

enumerator FileNotFoundError

File Not Found.

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

This error code will always be set in an indirect subclass of Error, FileNotFoundError, which itself is a direct subclass of FileAccessError, to allow the user to polymorphically catch this kind of error.

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

See also

FileAccessError

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

This error code will always be set in an indirect subclass of Error, FileAccessDeniedError, which itself is a direct subclass of FileAccessError, to allow the user to polymorphically catch this kind of error.

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

See also

FileAccessError

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

This error code will always be set in an indirect subclass of Error, FileTypeError, which itself is a direct subclass of FileAccessError, to allow the user to polymorphically catch this kind of error.

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

See also

FileAccessError

See also

FileTypeError

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

This error code will always be set in an indirect subclass of Error, FileInUseError, which itself is a direct subclass of FileAccessError, to allow the user to polymorphically catch this kind of error.

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

See also

FileAccessError

See also

FileInUseError

enumerator ReadOnlyFilesystem

Read-Only Filesystem.

This error code is reserved for future use.

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

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

This error code will always be set in a subclass of Error, IOError, to allow the user to polymorphically catch this kind of error.

See also

IOError

enumerator 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 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().

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See also

LicenseError

enumerator LicenseWrongProduct

License is for wrong product.

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

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See also

LicenseError

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

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See also

LicenseError

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

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See also

LicenseError

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

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See also

LicenseError

enumerator LicenseDongleRemoved

The license dongle has been removed.

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

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See also

LicenseError

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

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See also

LicenseError

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

This error code will always be set in a subclass of Error, LicenseError, to allow the user to polymorphically catch this kind of error.

See also

LicenseError

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

This error code will always be set in a subclass of Error, InitializationError, to allow the user to polymorphically catch this kind of error.

enumerator ThreadInitFunctionError

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

This error code exists for completeness sake, as the C++ wrapper code will propagate exceptions from the thread initialization function directly to the user.

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

This could also be the result of an I/O error that could not be properly caught.

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See also

ModelLoadError

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

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See also

ModelLoadError

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

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See also

ModelLoadError

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

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See also

ModelLoadError

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

This error code will always be set in a subclass of Error, ModelLoadError, to allow the user to polymorphically catch this kind of error.

See also

ModelLoadError

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, InputDimensionError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, InputStrideError, to allow the user to polymorphically catch this kind of error.

See also

InputStrideError

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

enumerator IlluminationReferenceMissingError

No illumination reference provided.

When creating a processing context for a model that requires illumination corrected intensities, but the data provided by the user has not yet been illumination corrected, an illumination reference must exist for fluxEngine to be able to automatically reference the input data. If no illumination reference is provided during processing context creation in that circumstance, this error will be returned.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

enumerator IlluminationReferenceDimensionError

The provided dimensions of the illumination reference are not acceptable.

When providing an illumination 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.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

enumerator ValueTypeMismatchError

Input value type mismatch error.

This error occurs when a model for intensity data (raw intensities, radiances, etc.) is used in conjunction with data that has already been white referenced (e.g. reflectances). In that case it is not possible to create a processing context and this error will occur.

This can also occur if a source explicitly requires relative or absolute radiances, but the input data is only provided in raw intensities.

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

enumerator ProcessingSetupError

An error occurred while setting up processing.

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

enumerator InputScalarTypeError

The supplied scalar type of the input does not match.

The scalar type of the input supplied while providing the next input data pointer does not match the scalar type with which the context was created.

This error code will always be set in a subclass of Error, InputScalarTypeError, to allow the user to polymorphically catch this kind of error.

See also

InputScalarTypeError

enumerator OutputIdNotPresent

No output sink with the given output id is present.

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

This error code will always be set in a subclass of Error, OutputIntrospectionError, to allow the user to polymorphically catch this kind of error.

enumerator OutputIdNotUnique

Multiple outuput sinks with the given output id are present.

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

This error code will always be set in a subclass of Error, OutputIntrospectionError, to allow the user to polymorphically catch this kind of error.

enumerator StorageTypeMismatch

Storage type mismatch while introspecting an output sink.

When using either ProcessingContext::outputSinkTensorStructure() or ProcessingContext::outputSinkObjectListStructure() 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 ProcessingContext::outputSinkTensorStructure() for an output sink that will return a list of detected objects would result in this error.

This error code will always be set in a subclass of Error, OutputIntrospectionError, to allow the user to polymorphically catch this kind of error.

enumerator ProcessingContextTypeMismatch

The processing context is of the wrong type.

When setting the next input pointer by calling ProcessingContext::setSourceData() in the wrong variant, because the context was created for a different type of data, this error will be returned.

For example, calling ProcessingContext::setSourceData() in the ProcessingContext::HSICube variant on a context that was created to process PushBroom frames will result in this error.

This error code will always be set in a subclass of Error, ProcessingContextTypeMismatchError, to allow the user to polymorphically catch this kind of error.

enumerator ProcessingUnknownError

An unknown error occurred during processing.

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

This error code will always be set in a subclass of Error, ProcessingError, to allow the user to polymorphically catch this kind of error.

See also

ProcessingError

enumerator ProcessingInternalError

An internal error occurred during processing.

An internal error occurred during data processing.

This error code will always be set in a subclass of Error, ProcessingError, to allow the user to polymorphically catch this kind of error.

See also

ProcessingError

enumerator ProcessingAborted

Processing was aborted by the user.

This error code will always be set in a subclass of Error, ProcessingError, to allow the user to polymorphically catch this kind of error.

See also

ProcessingError

enumerator ProcessingSourceDataMissing

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

If the user has never called ProcessingContext::setSourceData() before a call to ProcessingContext::processNext() this error will occur.

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

This error code will always be set in a subclass of Error, ProcessingError, to allow the user to polymorphically catch this kind of error.

See also

ProcessingError

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

In contrast to ErrorCode::HandleNoLongerValid occurring, this is not an indication of undefined behavior.

This error code will always be set in a subclass of Error, ObjectNoLongerValidError, to allow the user to polymorphically catch this kind of error.

enumerator 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 ErrorCode::InvalidArgument instead of this error, as a negative index is never valid.

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

enumerator 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 ErrorCode::InvalidArgument instead of this error, as that can never be valid.

An alias for this code exists under the name ErrorCode::DeviceParameterNotFound.

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

enumerator ParameterInternalQueryError

An internal error occurred while querying a parameter.

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

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

enumerator 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 ErrorCode::DeviceParameterTypeError.

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

enumerator 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 negative index will result in a ErrorCode::InvalidArgument instead of this error, as a negativ index is never valid.

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

enumerator 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 ErrorCode::InvalidArgument instead of this error, as that can never be valid.

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

enumerator 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 negative index will result in a ErrorCode::InvalidArgument instead of this error, as a negativ index is never valid.

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

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

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

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

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

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

This error code will always be set in a subclass of Error, DeviceEnumerationError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, DeviceConnectionError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, DeviceConnectionError, to allow the user to polymorphically catch this kind of error.

enumerator DeviceConnectionDriverError

Device connection: driver error.

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

This error code will always be set in a subclass of Error, DeviceConnectionError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, DeviceConnectionError, to allow the user to polymorphically catch this kind of error.

enumerator 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

This error code will always be set in a subclass of Error, DeviceConnectionError, to allow the user to polymorphically catch this kind of error.

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

In contrast to ErrorCode::HandleNoLongerValid occurring, this is not an indication of undefined behavior.

This error code will always be set in a subclass of Error, ObjectNoLongerValidError, to allow the user to polymorphically catch this kind of error.

enumerator DeviceParameterListNotFound

Parameter list not found.

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

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

enumerator 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 ErrorCode::ParameterNameDoesNotExist, as they have the same code.

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

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

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

enumerator 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 ErrorCode::ParameterWrongType, as they have the same code.

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

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

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

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

This error code will always be set in a subclass of Error, ParameterError, to allow the user to polymorphically catch this kind of error.

See also

ParameterError

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

This error code will always be set in a subclass of Error, DeviceError, to allow the user to polymorphically catch this kind of error.

See also

DeviceError

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

This error code will always be set in a subclass of Error, DeviceError, to allow the user to polymorphically catch this kind of error.

See also

DeviceError

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

This error code will always be set in a subclass of Error, DeviceError, to allow the user to polymorphically catch this kind of error.

See also

DeviceError

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

enumerator InstrumentDeviceShmAlreadySetup

The shared memory buffers have already been set up.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

enumerator InstrumentDeviceShmSetupError

Error setting up shared memory buffers.

InstrumentDevice::setupInternalBuffers() 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.

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

enumerator 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 InstrumentDevice::AcquisitionParameters structure for further details.)

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

enumerator InstrumentDeviceAcquisitionStartError

Acquisition start error.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

enumerator BufferAlreadyReturned

Buffer already returned.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

enumerator BufferContainerFull

Buffer container full.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, InstrumentDeviceError, to allow the user to polymorphically catch this kind of error.

enumerator LightControlDeviceForceStateError

Cannot force state of light control device.

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

This error code will always be set in a subclass of Error, LightControlDeviceError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, LightControlDeviceError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

enumerator 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

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

enumerator 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:

  • ErrorCode::DeviceProcessingInvalidReferenceError

  • ErrorCode::WhiteReferenceDimensionError

  • ErrorCode::DarkReferenceDimensionError

  • ErrorCode::IlluminationReferenceDimensionError

This error code will always be set in a subclass of Error, ProcessingContextCreationError, to allow the user to polymorphically catch this kind of error.

enumerator DeviceProcessingBufferIncompatible

The suppled processing buffer is incompatible.

When using a device buffer or persistent buffer as the input to a processing context (via ther overload of ProcessingContext::setSourceData() that accepts a BufferInfo or a PersistentBufferInfo), 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.

This error code will always be set in a subclass of Error, InputBufferIncompatibleError, to allow the user to polymorphically catch this kind of error.

enumerator 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 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 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 MeasurementProcessingContextFlag_VariableSpatialSize flag, this error will occur.

OSErrorCode

using fluxEngine::OSErrorCode = 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.

Error

class Error : public std::runtime_error

Base exception class for fluxEngine errors.

When fluxEngine throws an exception, it will always throw one of the following exceptions:

  • This class or a subclass of it to describe an error that is specific to fluxEngine

  • std::bad_alloc to describe allocation failures

  • std::invalid_argument if an invalid argument was passed to any fluxEngine method

  • std::out_of_range to indicate an index was out of range (for example, when introspecting groups of a model, if the group id is invalid, this will be thrown)

  • During thread creation any exception in the thread initialization callback the user supplies will be forwarded to the user

Subclassed by fluxEngine::DeviceError, fluxEngine::EmptyWrapperError, fluxEngine::FileAccessError, fluxEngine::IOError, fluxEngine::InitializationError, fluxEngine::InputBufferIncompatibleError, fluxEngine::InputDimensionError, fluxEngine::InputScalarTypeError, fluxEngine::InputStrideError, fluxEngine::LicenseError, fluxEngine::ModelLoadError, fluxEngine::NotImplementedError, fluxEngine::ObjectNoLongerValidError, fluxEngine::OutputIntrospectionError, fluxEngine::ParameterError, fluxEngine::ProcessingContextCreationError, fluxEngine::ProcessingContextTypeMismatchError, fluxEngine::ProcessingError

Public Functions

inline Error(std::string message, ErrorCode errorCode, OSErrorCode osErrorCode = {})

Constructor.

The error message may be retrieved by the standard what() method of all std::exception subclasses.

Parameters:
  • message – The error message

  • errorCode – The error code, see ErrorCode for details

  • osErrorCode – The operating system error code if an OS function was responsibly for the specific error

inline Error(Error const&) = default

Copy constructor.

inline Error(Error&&) = default

Move constructor.

inline Error &operator=(Error const&) = default

Copy assignment operator.

inline Error &operator=(Error&&) = default

Move assignment operator.

inline ErrorCode errorCode() const noexcept

Get the error code of this exception.

Returns:

The error code of this exception

inline OSErrorCode osErrorCode() const noexcept

Get the underlying operating system error code.

Not all methods invoke operating system functions, in which case this will be 0. It may also be 0 if it was not possible to obtain the operating system’s internal error code for a given operation.

Returns:

The underlying operating system error code

Public Static Functions

static inline void throwFromErrorStruct(fluxEngine_C_v1_Error *error)

Throw an error from a C struct.

Given an error structure returned by the wrapped C API, create the correct subclass of Error and throw it. Also free the C struct to avoid memory leaks.

Parameters:

error – The C error struct

static inline void throwFromArguments(std::string message, ErrorCode errorCode, OSErrorCode osErrorCode = {})

Throw an error from a set of arguments.

This will automatically throw the correct subclass of the error class depending on the specified error code. The arguments will be passed to the constructor of that class.

Note that this will only throw subclasses of the Error class, std::invalid_argument or std::bad_alloc must still be thrown by the user directly.

Parameters:
  • message – The error message

  • errorCode – The error code, see ErrorCode for details

  • osErrorCode – The operating system error code if an OS function was responsibly for the specific error

ObjectNoLongerValidError

class ObjectNoLongerValidError : public fluxEngine::Error

Object No Longer Valid Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to fluxEngine objects no longer being valid. This includes the following error codes:

NotImplementedError

class NotImplementedError : public fluxEngine::Error

Not Implemented Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to functionality not being implemented in fluxEngine. This includes the following error codes:

EmptyWrapperError

class EmptyWrapperError : public fluxEngine::Error

Empty Wrapper Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to the C++ wrapper object in question being default-constructed and hence not wrapping a valid underlying object of fluxEngine’s C API. Think of this as somewhat similar to a null pointer dereferencing exception.

This will only wrap the error code ErrorCode::InvalidWrapper.

FileAccessError

class FileAccessError : public fluxEngine::Error

File Access Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to errors in accessing files. There are also further subclasses of this error. The following error codes will be assigned this class or a subclass thereof:

Subclassed by fluxEngine::FileAccessDeniedError, fluxEngine::FileInUseError, fluxEngine::FileNotFoundError, fluxEngine::FileTypeError, fluxEngine::ReadOnlyFilesystemError

FileNotFoundError

class FileNotFoundError : public fluxEngine::FileAccessError

File Not Found Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to a file not existing. This will always correspond to the error code ErrorCode::FileNotFoundError.

FileAccessDeniedError

class FileAccessDeniedError : public fluxEngine::FileAccessError

File Access Denied Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to not being able to access a file due to the file’s permissions. This will always correspond to the error code ErrorCode::FileAccessDeniedError.

FileTypeError

class FileTypeError : public fluxEngine::FileAccessError

File Type Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to not being able to access a file because it is not a file, but a directory, or some other filesystem object. This will always correspond to the error code ErrorCode::FileTypeError.

FileInUseError

class FileInUseError : public fluxEngine::FileAccessError

File In Use Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to a file being in use by another program. This will always correspond to the error code ErrorCode::FileInUseError.

ReadOnlyFilesystemError

class ReadOnlyFilesystemError : public fluxEngine::FileAccessError

Read-Only Filesystem.

This error class exists to allow the user to polymorphically catch all exceptions that relate to a file not being writable due to the underlying filesystem being read-only. This will always correspond to the error code ErrorCode::ReadOnlyFilesystemError.

This class will currently never be thrown, as there is no part of fluxEngine that opens files for writing.

IOError

class IOError : public fluxEngine::Error

I/O Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to an underlying I/O error while performing an I/O operation. This will always correspond to the error code ErrorCode::IOError.

LicenseError

class LicenseError : public fluxEngine::Error

License Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to the license being rejected by fluxEngine. This includes the following error codes:

InitializationError

class InitializationError : public fluxEngine::Error

Initialization Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to initialization issues in fluxEngine. This includes the following error codes:

ModelLoadError

class ModelLoadError : public fluxEngine::Error

Model Load Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to loading and parsing models in fluxEngine. This includes the following error codes:

ProcessingContextCreationError

class ProcessingContextCreationError : public fluxEngine::Error

Processing Context Creation Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to the creation of processing contexts in fluxEngine. This includes the following error codes:

InputDimensionError

class InputDimensionError : public fluxEngine::Error

Input Dimension Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to the input dimensions not being specified correctly, either while creating a processing context, or while setting the source data before execution. This always corresponds to the error code ErrorCode::InputDimensionError.

InputStrideError

class InputStrideError : public fluxEngine::Error

Input Stride Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to the input strides not being specified correctly while setting the source data before execution. This always corresponds to the error code ErrorCode::InputStrideError.

InputBufferIncompatibleError

class InputBufferIncompatibleError : public fluxEngine::Error

Input Buffer Incompatible Error.

This error class exists to allow the user to polymorphically catch all exceptions that relate to the input buffer not being compatible with the processing context while setting the source data before execution. This always corresponds to the error code ErrorCode::DeviceProcessingBufferIncompatible.

OutputIntrospectionError

class OutputIntrospectionError : public fluxEngine::Error

Output Introspection Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to the introspection of output sinks in a given processing context. This includes the following error codes:

ProcessingContextTypeMismatchError

class ProcessingContextTypeMismatchError : public fluxEngine::Error

Processing Context Type Error.

This error class exists to allow the user to polymorphically catch if they accidentally try to set the wrong type of input data for a given processing context, or attempt to create a processing context for measurements that are of the wrong type for a specific model. This includes the following error codes:

ProcessingError

class ProcessingError : public fluxEngine::Error

Processing Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to the actual processing of data. This includes the following error codes:

ParameterError

class ParameterError : public fluxEngine::Error

ParameterError.

This error class exists to allow the user to polymorphically catch most exceptions that relate to parametrization of devices. This includes the following error codes:

DeviceError

class DeviceError : public fluxEngine::Error

DeviceError.

This error class exists to allow the user to polymorphically catch most exceptions that relate to devices themselves. This includes the following error codes:

Additionally there are the following subclasses:

Subclassed by fluxEngine::DeviceConnectionError, fluxEngine::DeviceEnumerationError, fluxEngine::InstrumentDeviceError, fluxEngine::LightControlDeviceError

DeviceEnumerationError

class DeviceEnumerationError : public fluxEngine::DeviceError

Device Enumeration Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to the enumeration of devices. This includes the following error codes:

DeviceConnectionError

class DeviceConnectionError : public fluxEngine::DeviceError

Device Connection Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to the connection of device groups. This includes the following error codes:

InstrumentDeviceError

class InstrumentDeviceError : public fluxEngine::DeviceError

Instrument Device Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to operations specific to instrument devices. This includes the following error codes:

LightControlDeviceError

class LightControlDeviceError : public fluxEngine::DeviceError

Light Control Device Error.

This error class exists to allow the user to polymorphically catch most exceptions that relate to operations specific to light control devices. This includes the following error codes: