OceanDirectLighthouseC++  3.1.1
OceanDirect Lighthouse C++/C API
oceandirect::api::OceanDirectAPI Class Reference

Public Member Functions

virtual int addNetworkDevice (const char *ipAddressStr, const char *deviceTypeStr, int *errorCode)
 
virtual void addRS232DeviceLocation (char *deviceTypeName, char *deviceBusPath, unsigned int baud, int *errorCode)
 
virtual AdvanceAdvancedControl ()
 
virtual void applyElectricDarkCorrection (long deviceID, int *errorCode, bool value)
 
virtual void applyNonLinearityCorrection (long deviceID, int *errorCode, bool value)
 
void boxcarCorrectSpectrum (long deviceID, int *errorCode, const double *illuminatedSpectrum, unsigned int illuminatedSpectrumLength, unsigned int boxcarWidth, double *boxcarCorrectedSpectrum, unsigned int boxcarCorrectedSpectrumLength)
 
virtual void closeDevice (long deviceID, int *errorCode)
 
virtual int darkCorrectSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength, double *illuminatedSpectrum, int illuminatedSpectrumLength, double *darkCorrectedSpectrum, int darkCorrectedSpectrumLength)
 
virtual int darkCorrectSpectrum (long deviceID, int *errorCode, double *illuminatedSpectrum, int illuminatedSpectrumLength, double *darkCorrectedSpectrum, int darkCorrectedSpectrumLength)
 
virtual int detectNetworkDevices ()
 
virtual bool electricDarkCorrectionUsage (long deviceID, int *errorCode)
 
virtual unsigned long getAcquisitionDelayIncrementMicroseconds (long deviceID, int *errorCode)
 
virtual unsigned long getAcquisitionDelayMaximumMicroseconds (long deviceID, int *errorCode)
 
virtual unsigned long getAcquisitionDelayMicroseconds (long deviceID, int *errorCode)
 
virtual unsigned long getAcquisitionDelayMinimumMicroseconds (long deviceID, int *errorCode)
 
virtual void getAPIRCNumber (unsigned int *candidate)
 
virtual void getAPIVersionNumber (unsigned int *major, unsigned int *minor, unsigned int *point)
 
virtual unsigned short int getBoxcarWidth (long deviceID, int *errorCode)
 
virtual int getDarkCorrectedSpectrum (long deviceID, int *errorCode, double *darkCorrectedSpectrum, int darkCorrectedSpectrumLength)
 
virtual int getDarkCorrectedSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength, double *darkCorrectedSpectrum, int darkCorrectedSpectrumLength)
 
virtual IDevice * getDeviceByID (long id)
 
virtual unsigned char getDeviceEndpoint (long deviceID, int *error_code, usbEndpointType endpointType)
 
virtual int getDeviceIDs (long *ids, unsigned long maxLength)
 
virtual int getDeviceModelText (long deviceID, int *errorCode, char *buffer, unsigned int bufferLength)
 
virtual int getDeviceType (long deviceID, int *errorCode, char *buffer, unsigned int length)
 
virtual int getElectricDarkPixelCount (long deviceID, int *errorCode)
 
virtual int getElectricDarkPixelIndices (long deviceID, int *errorCode, int *indices, int length)
 
virtual int getErrorMessage (int errorCode, char *returnMessage, int length)
 
virtual int getErrorStringLength (int errorCode)
 
virtual int getFormattedSpectrum (long deviceID, int *errorCode, double *buffer, int bufferLength)
 
virtual int getFormattedSpectrumLength (long deviceID, int *errorCode)
 
virtual int getIndexAtWavelength (long deviceID, int *errorCode, double &wavelength, double approxWavelength)
 
virtual int getIndicesAtAnyWavelength (long deviceID, int *errorCode, int *indices, int indicesLength, double *wavelength, int wavelengthLength)
 
virtual int getIndicesAtWavelengthRange (long deviceID, int *errorCode, int *indices, int indicesLength, double *wavelengthLength, int wavelengthSize, double lo, double hi)
 
virtual unsigned long getIntegrationTimeIncrementMicros (long deviceID, int *errorCode)
 
virtual unsigned long getIntegrationTimeMicros (long deviceID, int *errorCode)
 
virtual unsigned long getMaximumIntegrationTimeMicros (long deviceID, int *errorCode)
 
virtual double getMaximumIntensity (long deviceID, int *errorCode)
 
virtual unsigned long getMinimumAveragingIntegrationTimeMicros (long deviceID, int *errorCode)
 
virtual unsigned long getMinimumIntegrationTimeMicros (long deviceID, int *errorCode)
 
virtual int getNetworkDeviceIDs (long *ids, unsigned long maxLength)
 
virtual int getNonlinearityCorrectedSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength, double *nonlinearityCorrectedSpectrum, int nonlinearityCorrectedSpectrumLength)
 
virtual int getNonlinearityCorrectedSpectrum (long deviceID, int *errorCode, double *nonlinearityCorrectedSpectrum, int nonlinearityCorrectedSpectrumLength)
 
virtual int getNumberOfDeviceIDs ()
 
virtual int getRawSpectrumWithMetadata (long deviceID, int *errorCode, SpectrumWithMetadata *buffer, int bufferLength)
 
virtual unsigned int getScansToAverage (long deviceID, int *errorCode)
 
virtual int getSerialNumber (long deviceID, int *errorCode, char *buffer, int bufferLength)
 
virtual unsigned char getSerialNumberMaximumLength (long deviceID, int *errorCode)
 
virtual int getStoredDarkSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength)
 
virtual long long int getTime (long deviceID, int *errorCode)
 
virtual int getTriggerMode (long deviceID, int *errorCode)
 
virtual int getWavelengthCoefficients (long deviceID, int *errorCode, double *coeff, int length)
 
virtual int getWavelengths (long deviceID, int *errorCode, double *wavelengths, int length)
 
virtual bool isFeatureEnabled (long deviceId, int *errorCode, FeatureId featureId)
 
virtual bool nonLinearityCorrectionUsage (long deviceID, int *errorCode)
 
virtual int nonlinearityCorrectSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength, double *illuminatedSpectrum, int illuminatedSpectrumLength, double *nonlinearityCorrectedSpectrum, int nonlinearityCorrectedSpectrumLength)
 
virtual int nonlinearityCorrectSpectrum (long deviceID, int *errorCode, double *illuminatedSpectrum, int illuminatedSpectrumLength, double *nonlinearityCorrectedSpectrum, int nonlinearityCorrectedSpectrumLength)
 
virtual void openDevice (long deviceID, int *errorCode)
 
virtual int probeDevices ()
 
virtual void setAcquisitionDelayMicroseconds (long deviceID, int *errorCode, unsigned long delayMicroseconds)
 
virtual void setBoxcarWidth (long deviceID, int *errorCode, unsigned short int boxcarWidth)
 
virtual void setIntegrationTimeMicros (long deviceID, int *errorCode, unsigned long integrationTimeMicros)
 
void setMulticastMsgResponseReadDelay (size_t delayMs)
 
void setMulticastMsgResponseReadRetry (size_t retryCount)
 
void setMulticastMsgSendRetry (size_t retryCount)
 
virtual void setScansToAverage (long deviceID, int *errorCode, unsigned int scansToAverage)
 
virtual void setStoredDarkSpectrum (long deviceID, int *errorCode, double *darkSpectrum, int darkSpectrumLength)
 
virtual void setTime (long deviceID, int *errorCode, long long int timeInMicrosecond)
 
virtual void setTriggerMode (long deviceID, int *errorCode, int mode)
 

Static Public Member Functions

static OceanDirectAPIgetInstance ()
 
static void shutdown ()
 

Protected Member Functions

virtual long addTCPIPv4DeviceLocation (const char *deviceTypeName, std::string ipAddr, int port, int *errorCode)
 
virtual long addTCPIPv4OBP2DeviceLocation (const char *deviceTypeName, std::string ipAddr, int port, int *errorCode)
 
virtual std::string getDeviceModel (long deviceID, int *errorCode, int index)
 

Static Protected Attributes

static OceanDirectAPIinstance
 

Friends

class InstrumentedOceanDirectAPI
 
class NetOceanDirectAdmin
 
class OceanDirectAdminAPI
 

Member Function Documentation

◆ addNetworkDevice()

virtual int oceandirect::api::OceanDirectAPI::addNetworkDevice ( const char *  ipAddressStr,
const char *  deviceTypeStr,
int *  errorCode 
)
virtual

Manually create an instance of the network attached device and then open it using the openDevice() function. It is the responsiblitiy of the user to ensure that the device exists and is configured properly. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Parameters
ipAddressStrThe ip address as string (ex: "10.20.30.100" ) of the device to be opened.
deviceTypeStrThe device type could be OceanFX or OceanHDX. This is case sensitive.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist;
Returns
The device id or -1 if an error occured.

◆ addRS232DeviceLocation()

virtual void oceandirect::api::OceanDirectAPI::addRS232DeviceLocation ( char *  deviceTypeName,
char *  deviceBusPath,
unsigned int  baud,
int *  errorCode 
)
virtual

Use the addRS232DeviceLocation() method to specify that a device may be found on a particular serial bus with a given baud rate. Once specified, the typical openDevice() function can be used to access it.

Parameters
deviceTypeNamea valid Ocean spectrometer device type.
deviceBusPatha valid serial port path that the device is connected to.
baudthe baud rate for the specified serial port.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_CODE_INVALID_ARGUMENT if the device cannot be created.

◆ addTCPIPv4DeviceLocation()

virtual long oceandirect::api::OceanDirectAPI::addTCPIPv4DeviceLocation ( const char *  deviceTypeName,
std::string  ipAddr,
int  port,
int *  errorCode 
)
protectedvirtual

Use the addIPv4DeviceLocation() method to specify that a device may be found on a TCP/IPv4 network on a given port. Once specified, the typical openDevice() function can be used to access it.

Parameters
deviceTypeNamea valid Ocean spectrometer device type.
ipAddra valid IP address.
porta valid TCP/UDP port.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_CODE_INVALID_ARGUMENT if the device cannot be created.

◆ AdvancedControl()

virtual Advance* oceandirect::api::OceanDirectAPI::AdvancedControl ( )
virtual

Advanced extension of the API. Access to the advanced APIs is throught the pointer returned by this function.

Returns
a pointer to access the advanced APIs.

◆ applyElectricDarkCorrection()

virtual void oceandirect::api::OceanDirectAPI::applyElectricDarkCorrection ( long  deviceID,
int *  errorCode,
bool  value 
)
virtual
Deprecated:
Use electric dark correction on the acquired spectra.
See also
setStoredDarkSpectrum
getStoredDarkSpectrum
getDarkCorrectedSpectrum
electricDarkCorrectionUsage()
Warning
if electric dark correction is enabled using this function then some of the newer dark correction functionality e.g. getDarkCorrectedSpectrum may not be used.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_COMMAND_NOT_SUPPORTED if the device does not support electric dark correction; ERROR_NO_DEVICE if the device does not exist.

◆ applyNonLinearityCorrection()

virtual void oceandirect::api::OceanDirectAPI::applyNonLinearityCorrection ( long  deviceID,
int *  errorCode,
bool  value 
)
virtual
Deprecated:
Set nonlinearity correction on or off on raw spectrum
See also
setStoredDarkSpectrum
getStoredDarkSpectrum
getNonlinearityCorrectedSpectrum
nonLinearityCorrectionUsage()
Warning
if nonlinearity correction is enabled using this function then some of the newer nonlinearity correction functionality e.g. getNonlinearityCorrectedSpectrum may not be used.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist.
valuetrue if nonlinearity correction is to be used, false otherwise.

◆ boxcarCorrectSpectrum()

void oceandirect::api::OceanDirectAPI::boxcarCorrectSpectrum ( long  deviceID,
int *  errorCode,
const double *  illuminatedSpectrum,
unsigned int  illuminatedSpectrumLength,
unsigned int  boxcarWidth,
double *  boxcarCorrectedSpectrum,
unsigned int  boxcarCorrectedSpectrumLength 
)

Apply a boxcar correction on the given illuminated spectrum.

Parameters
[in]deviceIDThe identifier of the device as returned by getDeviceIDs.
[out]errorCodeSet to 0 if successful, an OceanDirect error code (nonzero) otherwise ERROR_VALUE_NOT_FOUND no stored dark spectrum was found; ERROR_NO_DEVICE if deviceID is not a valid and open deviceID ERROR_TRANSFER_ERROR if a communication error occurred ERROR_FEATURE_NOT_FOUND if device does not support this feature ERROR_COMMAND_NOT_SUPPORTED if device does not support this command.
[in/out]illuminatedSpectrum The spectrum that will be boxcar corrected.
[in]boxcarWidthThe boxcar width.

◆ closeDevice()

virtual void oceandirect::api::OceanDirectAPI::closeDevice ( long  deviceID,
int *  errorCode 
)
virtual

This will attempt to close the bus connection to the device with the given ID. The id becomes invalid after closing the device. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

See also
openDevice()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist.

◆ darkCorrectSpectrum() [1/2]

virtual int oceandirect::api::OceanDirectAPI::darkCorrectSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength,
double *  illuminatedSpectrum,
int  illuminatedSpectrumLength,
double *  darkCorrectedSpectrum,
int  darkCorrectedSpectrumLength 
)
virtual

Dark correct a previously acquired illuminated spectrum using a previously acquired dark spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success;
darkSpectrumthe buffer that contains the dark spectrum to be used for the dark correction.
darkSpectrumLengththe actual size of the dark spectrum buffer.
illuminatedSpectrumthe buffer that contains the illuminated spectrum to be corrected.
illuminatedSpectrumLengththe actual size of the illuminated spectrum buffer.
darkCorrectedSpectrumthe buffer that will receive the dark corrected spectrum.
darkCorrectedSpectrumLengththe actual size of the dark corrected buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ darkCorrectSpectrum() [2/2]

virtual int oceandirect::api::OceanDirectAPI::darkCorrectSpectrum ( long  deviceID,
int *  errorCode,
double *  illuminatedSpectrum,
int  illuminatedSpectrumLength,
double *  darkCorrectedSpectrum,
int  darkCorrectedSpectrumLength 
)
virtual

Dark correct a previously acquired illuminated spectrum using a stored dark spectrum.

See also
setStoredDarkSpectrum
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found.
illuminatedSpectrumthe buffer that contains the illuminated spectrum to be corrected.
illuminatedSpectrumLengththe actual size of the illuminated spectrum buffer.
darkCorrectedSpectrumthe buffer that will receive the dark corrected spectrum.
darkCorrectedSpectrumLengththe actual size of the dark corrected buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ detectNetworkDevices()

virtual int oceandirect::api::OceanDirectAPI::detectNetworkDevices ( )
virtual

This provides a way to find all Ethernet discoverable devices on a network. Afterwards, a call to probeDevices is neccessary to grab the interface for opening and connecting to discovered device. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

See also
probeDevices()
Returns
the number of detected network devices.

◆ electricDarkCorrectionUsage()

virtual bool oceandirect::api::OceanDirectAPI::electricDarkCorrectionUsage ( long  deviceID,
int *  errorCode 
)
virtual
Deprecated:
Determine if electric dark correction to the acquired spectra is on or off.
See also
applyElectricDarkCorrection()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_COMMAND_NOT_SUPPORTED if the device does not support electric dark correction; ERROR_NO_DEVICE if the device does not exist.
Returns
true if electric dark correction is turned on, false if electric dark correction is either turned off or is not supported (see the returned error code).

◆ getAcquisitionDelayIncrementMicroseconds()

virtual unsigned long oceandirect::api::OceanDirectAPI::getAcquisitionDelayIncrementMicroseconds ( long  deviceID,
int *  errorCode 
)
virtual

Get the acquisition delay period increment in microseconds. The increment is the minimum difference (in microseconds) between two adjacent, valid acquisition delay periods.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the acquisition delay period increment in microseconds.

◆ getAcquisitionDelayMaximumMicroseconds()

virtual unsigned long oceandirect::api::OceanDirectAPI::getAcquisitionDelayMaximumMicroseconds ( long  deviceID,
int *  errorCode 
)
virtual

Get the maximum valid acquisition delay period in microseconds.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the maximum acquisition delay period in microseconds.

◆ getAcquisitionDelayMicroseconds()

virtual unsigned long oceandirect::api::OceanDirectAPI::getAcquisitionDelayMicroseconds ( long  deviceID,
int *  errorCode 
)
virtual

Get the acquisition delay period in microseconds.

See also
setAcquisitionDelayMicroseconds()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the acquisition delay period in microseconds.

◆ getAcquisitionDelayMinimumMicroseconds()

virtual unsigned long oceandirect::api::OceanDirectAPI::getAcquisitionDelayMinimumMicroseconds ( long  deviceID,
int *  errorCode 
)
virtual

Get the minimum valid acquisition delay period in microseconds.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the minimum acquisition delay period in microseconds.

◆ getAPIVersionNumber()

virtual void oceandirect::api::OceanDirectAPI::getAPIVersionNumber ( unsigned int *  major,
unsigned int *  minor,
unsigned int *  point 
)
virtual

Return the major, minor and point release version numbers.

Parameters
majorthe major software version number.
minorthe minor software version number.
pointthe point software version number.

◆ getBoxcarWidth()

virtual unsigned short int oceandirect::api::OceanDirectAPI::getBoxcarWidth ( long  deviceID,
int *  errorCode 
)
virtual

Get the width of the boxcar smoothing to be applied to the returned spectrum. When this value has been set greater than 0, boxcar smoothing (a moving average) is applied to the spectrum returned by getFormattedSpectrum (or getRawSpectrumWithMetadata). The width specified is the number of pixels either side of the central pixel of the average i.e. if the result of this function is n, the "full width" of the smoothing is 2*n+1.

See also
setBoxcarWidth()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the width of the smoothing to be applied per returned spectrum.

◆ getDarkCorrectedSpectrum() [1/2]

virtual int oceandirect::api::OceanDirectAPI::getDarkCorrectedSpectrum ( long  deviceID,
int *  errorCode,
double *  darkCorrectedSpectrum,
int  darkCorrectedSpectrumLength 
)
virtual

Acquire a spectrum and use the previously stored dark spectrum to perform a dark correction then return the dark corrected spectrum.

See also
setStoredDarkSpectrum.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_DARK_NONLINEARITY_CORRECTION_CONFLICT legacy correction functionality has been enabled using either applyElectricDarkCorrection or applyNonLinearityCorrection or both; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found. ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
darkCorrectedSpectrumthe buffer that will receive the dark corrected spectrum.
darkCorrectedSpectrumLengththe actual size of the dark correction buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ getDarkCorrectedSpectrum() [2/2]

virtual int oceandirect::api::OceanDirectAPI::getDarkCorrectedSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength,
double *  darkCorrectedSpectrum,
int  darkCorrectedSpectrumLength 
)
virtual

Acquire a spectrum and use the supplied dark spectrum to perform a dark correction then return the dark corrected spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_DARK_NONLINEARITY_CORRECTION_CONFLICT legacy correction functionality has been enabled using either applyElectricDarkCorrection or applyNonLinearityCorrection or both; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
darkSpectrumthe buffer that contains the dark spectrum to be used for the dark correction.
darkSpectrumLengththe actual size of the dark spectrum buffer.
darkCorrectedSpectrumthe buffer that will receive the dark corrected spectrum.
darkCorrectedSpectrumLengththe actual size of the dark correction buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ getDeviceEndpoint()

virtual unsigned char oceandirect::api::OceanDirectAPI::getDeviceEndpoint ( long  deviceID,
int *  error_code,
usbEndpointType  endpointType 
)
virtual

Get the usb endpoint address for a specified type of endpoint

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_INPUT_OUT_OF_BOUNDS if an invalid endpoint value is supplied; ERROR_NO_DEVICE if the device does not exist.
endpointTypethe USB endpoint type (see UsbEndpoint.h)
Returns
the endpoint address for the requested endpoint.

◆ getDeviceIDs()

virtual int oceandirect::api::OceanDirectAPI::getDeviceIDs ( long *  ids,
unsigned long  maxLength 
)
virtual

This provides a unique ID of each device that is detected or specified. The IDs are copied into the user-provided buffer. These IDs are weak references: attempting to access a device that no longer exists will cause an error value to be returned but should not cause any instability. The IDs may be entirely random, but a given ID will always refer to the same device for as long as the program is running. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Parameters
idsthe buffer to receive the device IDs.
maxLengththe actual size of the buffer ids.
Returns
the number of device IDs actually copied into the array or 0 on error.

◆ getDeviceModel()

virtual std::string oceandirect::api::OceanDirectAPI::getDeviceModel ( long  deviceID,
int *  errorCode,
int  index 
)
protectedvirtual

Get the device Model name

◆ getDeviceModelText()

virtual int oceandirect::api::OceanDirectAPI::getDeviceModelText ( long  deviceID,
int *  errorCode,
char *  buffer,
unsigned int  bufferLength 
)
virtual

Get the device model name by passing in a pre-allocated buffer

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the feature is not available; ERROR_NO_DEVICE if the device does not exist.
buffera character buffer to receive the device model string.
bufferLengththe length of the supplied buffer.
Returns
the actual length of the device model string on success.

◆ getDeviceType()

virtual int oceandirect::api::OceanDirectAPI::getDeviceType ( long  deviceID,
int *  errorCode,
char *  buffer,
unsigned int  length 
)
virtual

Get a string that describes the type of device

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_BAD_USER_BUFFER if the pointer to the buffer is null or the supplied buffer length is 0; ERROR_NO_DEVICE if the device does not exist.
buffera character buffer to receive the device type string.
lengththe length of the supplied buffer.
Returns
the actual length of the device type string on success.

◆ getElectricDarkPixelCount()

virtual int oceandirect::api::OceanDirectAPI::getElectricDarkPixelCount ( long  deviceID,
int *  errorCode 
)
virtual

Get electric dark pixel count

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_COMMAND_NOT_SUPPORTED if the device does not support electric dark correction; ERROR_NO_DEVICE if the device does not exist.
Returns
the number of electric dark pixels or zero if the electric dark correction is not supported (see the returned error code).

◆ getElectricDarkPixelIndices()

virtual int oceandirect::api::OceanDirectAPI::getElectricDarkPixelIndices ( long  deviceID,
int *  errorCode,
int *  indices,
int  length 
)
virtual

Get electric dark pixel indices.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_COMMAND_NOT_SUPPORTED if the device does not support electric dark correction; ERROR_NO_DEVICE if the device does not exist.
indicesthe buffer that will receive the indices of the electric dark pixels.
lengththe actual size of the buffer.
Returns
the number of electric dark pixels copied into the buffer or zero if the electric dark correction is not supported (see the returned error code).

◆ getErrorMessage()

virtual int oceandirect::api::OceanDirectAPI::getErrorMessage ( int  errorCode,
char *  returnMessage,
int  length 
)
virtual

Get error message associated with the given error code. If the error code is incorrect then the return message will be "Error. Undefined error".

Parameters
errorCodeThe error code.
returnMessageThe output buffer.
lengthOutput buffer length
Returns
The number of characters copied into the output buffer.

◆ getErrorStringLength()

virtual int oceandirect::api::OceanDirectAPI::getErrorStringLength ( int  errorCode)
virtual

Get error message length associated with the given error code. If the error code is incorrect then the return message length will be 0.

Parameters
errorCodeThe error code.
Returns
The number of characters copied into the output buffer.

◆ getFormattedSpectrum()

virtual int oceandirect::api::OceanDirectAPI::getFormattedSpectrum ( long  deviceID,
int *  errorCode,
double *  buffer,
int  bufferLength 
)
virtual

Get a formatted spectrum

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NOT_ENOUGH_BUFFER_SPACE if the size of the buffer is smaller than the formatted spectrum length; ERROR_NO_DEVICE if the device does not exist.
bufferthe buffer that will receive the formatted spectrum.
bufferLengththe actual size of the buffer.
Returns
the actual number of pixels copied into buffer.

◆ getFormattedSpectrumLength()

virtual int oceandirect::api::OceanDirectAPI::getFormattedSpectrumLength ( long  deviceID,
int *  errorCode 
)
virtual

Get formatted spectrum length i.e. the number of pixels in the spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the size of the formatted spectrum.

◆ getIndexAtWavelength()

virtual int oceandirect::api::OceanDirectAPI::getIndexAtWavelength ( long  deviceID,
int *  errorCode,
double &  wavelength,
double  approxWavelength 
)
virtual

Get wavelength closest to the specified approximate wavelength.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_CODE_ARRAY_INDEX_OUT_OF_BOUNDS the specified wavelengths is not within the device's wavelength range; ERROR_NO_DEVICE if the device does not exist.
wavelengththe wavelength of the pixel nearest to the approximate wavelength within the device's wavelength range.
approxWavelengththe approximate wavelength of the desired pixel to be found.
Returns
the index of the pixel closest to the approximate wavelength on success, -1 otherwise.

◆ getIndicesAtAnyWavelength()

virtual int oceandirect::api::OceanDirectAPI::getIndicesAtAnyWavelength ( long  deviceID,
int *  errorCode,
int *  indices,
int  indicesLength,
double *  wavelength,
int  wavelengthLength 
)
virtual

Get the indices and actual wavelengths of a specified set of wavelengths.

Note
if any of the specified wavelengths are out of bounds then the wavelengths array may be partially overwritten with the actual wavelengths found up to the point when the error occurred.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_CODE_ARRAY_INDEX_OUT_OF_BOUNDS one or more of the specified wavelengths is not within the device's wavelength range; ERROR_NO_DEVICE if the device does not exist.
indicesThe buffer that will receive the indices of the pixels associated with the specified wavelengths.
indicesLengthThe indices buffer size.
wavelengthThe wavelengths to be searched for, overwritten with the actual wavelengths found.
wavelengthLengthThe wavelength buffer size.
lengththe actual length of the array of wavelengths to be searched for.
Returns
the number of pixel indices copied into the buffer.

◆ getIndicesAtWavelengthRange()

virtual int oceandirect::api::OceanDirectAPI::getIndicesAtWavelengthRange ( long  deviceID,
int *  errorCode,
int *  indices,
int  indicesLength,
double *  wavelengthLength,
int  wavelengthSize,
double  lo,
double  hi 
)
virtual

Get wavelength indices within a specified wavelength range

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_CODE_ARRAY_INDEX_OUT_OF_BOUNDS the lower or upper bound specified is not within the device's wavelength range;
ERROR_NO_DEVICE if the device does not exist.
indicesThe output buffer that will receive the indices of the pixels in the specified range.
indicesLengthThe indices buffer size.
wavelengthThe output buffer that will receive the wavelengths associated with each pixel index.
wavelengthLengthThe wavelength buffer size.
lothe lower bound of the wavelength range.
hithe upper bound of the wavelength range.
Returns
the number of pixel indices copied into the buffer.

◆ getInstance()

static OceanDirectAPI* oceandirect::api::OceanDirectAPI::getInstance ( )
static

No public constructor. To use this class in C++, you must first call getInstance(). This provides a singleton: it is the same on every call.

Parameters
licenseStatusreturns 0 on success i.e. there is a valid software license, 1 otherwise in which case Ocean should be contacted.

◆ getIntegrationTimeIncrementMicros()

virtual unsigned long oceandirect::api::OceanDirectAPI::getIntegrationTimeIncrementMicros ( long  deviceID,
int *  errorCode 
)
virtual

Get integration time increment in microseconds

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_INPUT_OUT_OF_BOUNDS if an invalid integration time is supplied; ERROR_NO_DEVICE if the device does not exist.
Returns
the integration time increment in microseconds.

◆ getIntegrationTimeMicros()

virtual unsigned long oceandirect::api::OceanDirectAPI::getIntegrationTimeMicros ( long  deviceID,
int *  errorCode 
)
virtual

Get integration time in microseconds

See also
setIntegrationTimeMicros()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_INPUT_OUT_OF_BOUNDS if an invalid integration time is supplied; ERROR_NO_DEVICE if the device does not exist.
Returns
the integration time in microseconds.

◆ getMaximumIntegrationTimeMicros()

virtual unsigned long oceandirect::api::OceanDirectAPI::getMaximumIntegrationTimeMicros ( long  deviceID,
int *  errorCode 
)
virtual

Get maximum integration time in microseconds

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the maximum integration time in microseconds.

◆ getMaximumIntensity()

virtual double oceandirect::api::OceanDirectAPI::getMaximumIntensity ( long  deviceID,
int *  errorCode 
)
virtual

Get max intensity (in raw counts) that can be returned in any pixel.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the maximum pixel intensity.

◆ getMinimumAveragingIntegrationTimeMicros()

virtual unsigned long oceandirect::api::OceanDirectAPI::getMinimumAveragingIntegrationTimeMicros ( long  deviceID,
int *  errorCode 
)
virtual

Get minimum integration time in microseconds when averaging is enabled.

Note
some devices that make use of onboard functionality to perform averaging have a different, larger, minimum integration time for acquisition when averaging is enabled. Refer to the documentation for your spectrometer to see if this is the case. The minimum integration time when averaging is not enabled can be determined using getMinimumIntegrationTimeMicros.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the minimum integration time in microseconds with averaging enabled.

◆ getMinimumIntegrationTimeMicros()

virtual unsigned long oceandirect::api::OceanDirectAPI::getMinimumIntegrationTimeMicros ( long  deviceID,
int *  errorCode 
)
virtual

Get minimum integration time in microseconds.

Note
some devices that make use of onboard functionality to perform averaging have a different, larger, minimum integration time for acquisition when averaging is enabled. Refer to the documentation for your spectrometer to see if this is the case. The minimum integration time when averaging is enabled can be determined using getMinimumAveragingIntegrationTimeMicros.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the minimum integration time in microseconds for acquisition with no averaging.

◆ getNetworkDeviceIDs()

virtual int oceandirect::api::OceanDirectAPI::getNetworkDeviceIDs ( long *  ids,
unsigned long  maxLength 
)
virtual

This provides a unique ID of each network attached device that is detected or manually specified. The IDs are copied into the user-provided buffer. These IDs are weak references: attempting to access a device that no longer exists will cause an error value to be returned but should not cause any instability. The IDs may be entirely random, but a given ID will always refer to the same device for as long as the program is running. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

Parameters
idsthe buffer to receive the device IDs.
maxLengththe actual size of the buffer ids.
Returns
the number of device IDs actually copied into the array or 0 on error.

◆ getNonlinearityCorrectedSpectrum() [1/2]

virtual int oceandirect::api::OceanDirectAPI::getNonlinearityCorrectedSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength,
double *  nonlinearityCorrectedSpectrum,
int  nonlinearityCorrectedSpectrumLength 
)
virtual

Acquire a spectrum and use the supplied dark spectrum to perform a dark correction followed by the nonlinearity correction then return the nonlinearity corrected spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_DARK_NONLINEARITY_CORRECTION_CONFLICT legacy correction functionality has been enabled using either applyElectricDarkCorrection or applyNonLinearityCorrection or both; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
darkSpectrumthe buffer that contains the dark spectrum to be used for the dark correction.
darkSpectrumLengththe actual size of the dark spectrum buffer.
nonlinearityCorrectedSpectrumthe buffer that will receive the nonlinearity corrected spectrum.
nonlinearityCorrectedSpectrumLengththe actual size of the nonlinearity correction buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ getNonlinearityCorrectedSpectrum() [2/2]

virtual int oceandirect::api::OceanDirectAPI::getNonlinearityCorrectedSpectrum ( long  deviceID,
int *  errorCode,
double *  nonlinearityCorrectedSpectrum,
int  nonlinearityCorrectedSpectrumLength 
)
virtual

Acquire a spectrum and use the previously stored dark spectrum to perform a dark correction followed by a nonlinearity correction then return the nonlinearity corrected spectrum.

See also
setStoredDarkSpectrum.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_DARK_NONLINEARITY_CORRECTION_CONFLICT legacy correction functionality has been enabled using either applyElectricDarkCorrection or applyNonLinearityCorrection or both; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
nonlinearityCorrectedSpectrumthe buffer that will receive the nonlinearity corrected spectrum.
nonlinearityCorrectedSpectrumLengththe actual size of the nonlinearity correction buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ getNumberOfDeviceIDs()

virtual int oceandirect::api::OceanDirectAPI::getNumberOfDeviceIDs ( )
virtual

This provides the number of devices that have either been probed or manually specified. Devices are not opened automatically, but this can provide a bound for getDeviceIDs(). Note that this should only be done by one thread at a time.

Returns
the total number of devices, both specified and probed.

◆ getRawSpectrumWithMetadata()

virtual int oceandirect::api::OceanDirectAPI::getRawSpectrumWithMetadata ( long  deviceID,
int *  errorCode,
SpectrumWithMetadata *  buffer,
int  bufferLength 
)
virtual

Get raw spectrum with meta-data. Only OBP enabled devices supported this command. The number of returned spectra depends on the following condition: 1) Device supports data buffering: A) If buffering is enabled then the number of spectra returned depends on how many spectra are in the buffer. It can be 0. B) If buffering is disabled then command will block until the requested number of spectra is received. 2) Device don't support data buffering: A) Only 1 spectra will be returned per call.

See also
SpectrumWithMetadata.h
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_CODE_INVALID_ARGUMENT if the size of the buffer is less than 1 or greater than 15; ERROR_NO_DEVICE if the device does not exist.
bufferthe buffer that will receive the formatted spectrum.
bufferLengththe actual size of the buffer.
Returns
the actual number of spectra copied into buffer.

◆ getScansToAverage()

virtual unsigned int oceandirect::api::OceanDirectAPI::getScansToAverage ( long  deviceID,
int *  errorCode 
)
virtual

Get the number of spectra to be averaged per returned spectrum. When this value has been set greater than 1 the specified number of spectra are averaged and the resulting average is returned by getFormattedSpectrum (or getRawSpectrumWithMetadata).

See also
setScansToAverage()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the number of spectra to be averaged per returned spectrum.

◆ getSerialNumber()

virtual int oceandirect::api::OceanDirectAPI::getSerialNumber ( long  deviceID,
int *  errorCode,
char *  buffer,
int  bufferLength 
)
virtual

Get the serial number of the device.

See also
getSerialNumberMaximumLength
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the serial number feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
bufferthe buffer to receive the returned serial number.
bufferLengththe size of the supplied buffer.
Returns
the actual number of characters in the returned serial number.

◆ getSerialNumberMaximumLength()

virtual unsigned char oceandirect::api::OceanDirectAPI::getSerialNumberMaximumLength ( long  deviceID,
int *  errorCode 
)
virtual

Return maximum length of the device serial number.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the serial number feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
Returns
the maximum length of the serial number.

◆ getStoredDarkSpectrum()

virtual int oceandirect::api::OceanDirectAPI::getStoredDarkSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength 
)
virtual

Retrieve a previously stored dark spectrum for use in subsequent corrections i.e. dark correction and nonlinearity correction.

See also
setStoredDarkSpectrum.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_NO_DEVICE if the device does not exist.
darkSpectrumthe buffer that contains the dark spectrum to be retrieved.
darkSpectrumLengththe actual size of the dark buffer.
Returns
the size of the stored dark spectrum on success, zero otherwise.

◆ getTime()

virtual long long int oceandirect::api::OceanDirectAPI::getTime ( long  deviceID,
int *  errorCode 
)
virtual

Return the system time of the device. The time is returned as an integer representing the number of microseconds since January 1 1970 based on the current device system clock.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.

◆ getTriggerMode()

virtual int oceandirect::api::OceanDirectAPI::getTriggerMode ( long  deviceID,
int *  errorCode 
)
virtual

Get the spectrometer trigger mode. Please see your spectrometer documentation for valid values of the trigger mode.

See also
setTriggerMode()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_CODE_INVALID_ARGUMENT if the mode supplied is not valid; ERROR_NO_DEVICE if the device does not exist ERROR_COMMAND_NOT_SUPPORTED device don't support this command.
Returns
the current trigger mode being used by the device.

◆ getWavelengthCoefficients()

virtual int oceandirect::api::OceanDirectAPI::getWavelengthCoefficients ( long  deviceID,
int *  errorCode,
double *  coeff,
int  length 
)
virtual

Get the coefficients of the polynomial used to calculate the wavelengths.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the wavelengths feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
coeffan array to receive the coefficient values.
lengththe actual length of the supplied coefficients array.
Returns
the actual number of coefficients copied into the coefficients array.

◆ getWavelengths()

virtual int oceandirect::api::OceanDirectAPI::getWavelengths ( long  deviceID,
int *  errorCode,
double *  wavelengths,
int  length 
)
virtual

Get the wavelengths for each pixel of the specified device.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the wavelengths feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
wavelengthsan array to receive the wavelength values.
lengththe actual length of the supplied wavelengths array.
Returns
the actual number of wavelengths copied into the wavelengths array.

◆ isFeatureEnabled()

virtual bool oceandirect::api::OceanDirectAPI::isFeatureEnabled ( long  deviceId,
int *  errorCode,
FeatureId  featureId 
)
virtual

Check if a specified feature is enabled for a device, return true if yes, false if not

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist.
featureIdthe feature ID of interest (declared elsewhere in OceanDirectAPI.h).
Returns
true if the specified feature is enabled, false otherwise.

◆ nonLinearityCorrectionUsage()

virtual bool oceandirect::api::OceanDirectAPI::nonLinearityCorrectionUsage ( long  deviceID,
int *  errorCode 
)
virtual
Deprecated:
Determine if nonlinearity correction is on or off on raw spectrum
See also
applyNonLinearityCorrection()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist.
Returns
true if nonlinearity correction is turned on, false otherwise.

◆ nonlinearityCorrectSpectrum() [1/2]

virtual int oceandirect::api::OceanDirectAPI::nonlinearityCorrectSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength,
double *  illuminatedSpectrum,
int  illuminatedSpectrumLength,
double *  nonlinearityCorrectedSpectrum,
int  nonlinearityCorrectedSpectrumLength 
)
virtual

Nonlinearity correct a previously acquired illuminated spectrum after dark correction using a previously acquired dark spectrum.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success;
darkSpectrumthe buffer that contains the dark spectrum to be used prior to the nonlinearity correction.
darkSpectrumLengththe actual size of the dark spectrum buffer.
illuminatedSpectrumthe buffer that contains the illuminated spectrum to be corrected.
illuminatedSpectrumLengththe actual size of the illuminated spectrum buffer.
nonlinearityCorrectedSpectrumthe buffer that will receive the nonlinearity corrected spectrum.
nonlinearityCorrectedSpectrumLengththe actual size of the nonlinearity corrected buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ nonlinearityCorrectSpectrum() [2/2]

virtual int oceandirect::api::OceanDirectAPI::nonlinearityCorrectSpectrum ( long  deviceID,
int *  errorCode,
double *  illuminatedSpectrum,
int  illuminatedSpectrumLength,
double *  nonlinearityCorrectedSpectrum,
int  nonlinearityCorrectedSpectrumLength 
)
virtual

Nonlinearity correct a previously acquired illuminated spectrum using a stored dark spectrum. This function performs a dark correction using a previously stored dark spectrum prior to performing the nonlinearity correction.

See also
setStoredDarkSpectrum
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_VALUE_NOT_FOUND no stored dark spectrum was found.
illuminatedSpectrumthe buffer that contains the illuminated spectrum to be corrected.
illuminatedSpectrumLengththe actual size of the illuminated spectrum buffer.
nonlinearityCorrectedSpectrumthe buffer that will receive the nonlinearity corrected spectrum.
nonlinearityCorrectedSpectrumLengththe actual size of the nonlinearity corrected buffer.
Returns
the size of the returned corrected spectrum on success, zero otherwise.

◆ openDevice()

virtual void oceandirect::api::OceanDirectAPI::openDevice ( long  deviceID,
int *  errorCode 
)
virtual

This will attempt to open the bus connection to the device with the given ID. After the device is closed the id becomes invalid. You need to call either probeDevices()/addNetworkDevice()/detectNetworkDevices() and getDeviceIDs() in order to have a valid id before reopening the device again. For a network connected device this function may return an error code if the device is not yet ready to accept incoming connection or the device is unreachable. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

See also
closeDevice()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_NO_DEVICE if the device does not exist;

◆ probeDevices()

virtual int oceandirect::api::OceanDirectAPI::probeDevices ( )
virtual

Use the probeDevices() method to force the driver to look for any device that can be found automatically. If this is not called then such devices will not be available for use. This should be used when attempting to find USB devices. Note that this should only be done by one thread at a time. For multithreaded application this function must be synchronized.

See also
detectNetworkDevices()
Returns
the number of detected USB devices.

◆ setAcquisitionDelayMicroseconds()

virtual void oceandirect::api::OceanDirectAPI::setAcquisitionDelayMicroseconds ( long  deviceID,
int *  errorCode,
unsigned long  delayMicroseconds 
)
virtual

Set the acquisition delay to the specified number of microseconds.

See also
getAcquisitionDelayMicroseconds()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_CODE_INVALID_ARGUMENT if the period supplied is not valid; ERROR_NO_DEVICE if the device does not exist
delayMicrosecondsthe acquisition delay period in microseconds.

◆ setBoxcarWidth()

virtual void oceandirect::api::OceanDirectAPI::setBoxcarWidth ( long  deviceID,
int *  errorCode,
unsigned short int  boxcarWidth 
)
virtual

Set the width of the boxcar smoothing to be applied to the returned spectrum. When this value is set greater than 0, boxcar smoothing (a moving average) is applied to the spectrum returned by getFormattedSpectrum (or getRawSpectrumWithMetadata). The width specified is the number of pixels either side of the central pixel of the average i.e. if the result of this function is n, the "full width" of the smoothing is 2*n+1.

Setting this value to 0 turns off the boxcar smoothing.

See also
getBoxcarWidth()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
boxcarWidththe width of the smoothing to be applied, or zero if smoothing is to be turned off.

◆ setIntegrationTimeMicros()

virtual void oceandirect::api::OceanDirectAPI::setIntegrationTimeMicros ( long  deviceID,
int *  errorCode,
unsigned long  integrationTimeMicros 
)
virtual

Set integration time in microseconds.

Note
some devices that make use of onboard functionality to perform averaging have a different, larger, minimum integration time for acquisition when averaging is enabled. Refer to the documentation for your spectrometer to see if this is the case. The minimum integration time when averaging is enabled can be determined using getMinimumAveragingIntegrationTimeMicros.
See also
getIntegrationTimeMicros()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_INPUT_OUT_OF_BOUNDS if an invalid integration time is supplied; ERROR_INTEGRATION_TIME_BELOW_AVERAGING_MIN if averaging is enabled and the specified integration time is below the minimum required for averaging (see getMinimumAveragingIntegrationTimeMicros); ERROR_NO_DEVICE if the device does not exist.
integrationTimeMicrosthe desired integration time in microseconds.

◆ setMulticastMsgResponseReadDelay()

void oceandirect::api::OceanDirectAPI::setMulticastMsgResponseReadDelay ( size_t  delayMs)

Set the delay between reading multicast response. This must be called before probing network devices.

See also
detectNetworkDevices()
Parameters
delayMsThe delay in milliseconds before next read.

◆ setMulticastMsgResponseReadRetry()

void oceandirect::api::OceanDirectAPI::setMulticastMsgResponseReadRetry ( size_t  retryCount)

Set the number of times to read multicast message response. This must be called before probing network devices.

See also
detectNetworkDevices()
Parameters
retryCountThe number of times to try reading multicast response messages.

◆ setMulticastMsgSendRetry()

void oceandirect::api::OceanDirectAPI::setMulticastMsgSendRetry ( size_t  retryCount)

Set the number of times to send multicast message for dynamic probing. This must be called before probing network devices.

See also
detectNetworkDevices()
Parameters
retryCountThe number of times to send messages.

◆ setScansToAverage()

virtual void oceandirect::api::OceanDirectAPI::setScansToAverage ( long  deviceID,
int *  errorCode,
unsigned int  scansToAverage 
)
virtual

Set the number of spectra to be averaged per returned spectrum. When this value is set greater than 1 the specified number of spectra are averaged and the resulting average is returned by getFormattedSpectrum (or getRawSpectrumWithMetadata). NOTE: Some devices have a minimum integration time for averaging that is different to the minimum integration time for unaveraged acquisition (see your spectrometer documentation to determine if this is a requirement).

See also
getScansToAverage()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_INTEGRATION_TIME_BELOW_AVERAGING_MIN if the current integration time is below the minimum required for averaging it will not be possible to enable averaging (see getMinimumAveragingIntegrationTimeMicros); ERROR_NO_DEVICE if the device does not exist.
scansToAveragethe number of scans to be averaged

◆ setStoredDarkSpectrum()

virtual void oceandirect::api::OceanDirectAPI::setStoredDarkSpectrum ( long  deviceID,
int *  errorCode,
double *  darkSpectrum,
int  darkSpectrumLength 
)
virtual

Store a dark spectrum for use in subsequent corrections i.e. dark correction and nonlinearity correction.

See also
getStoredDarkSpectrum.
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_NO_DEVICE if the device does not exist.
darkSpectrumthe buffer that contains the dark spectrum to be stored.
darkSpectrumLengththe actual size of the dark spectrum buffer.

◆ setTime()

virtual void oceandirect::api::OceanDirectAPI::setTime ( long  deviceID,
int *  errorCode,
long long int  timeInMicrosecond 
)
virtual

Sets the system time of the device. The time must be sepcified as the integer number of microseconds since 1 January 1970.

Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the feature is not available; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_NO_DEVICE if the device does not exist.
timeInMicrosecondthe time to set the device system clock as the number of microseconds since 1 January 1970.

◆ setTriggerMode()

virtual void oceandirect::api::OceanDirectAPI::setTriggerMode ( long  deviceID,
int *  errorCode,
int  mode 
)
virtual

Set the spectrometer trigger mode. Please see your spectrometer documentation for valid values of the trigger mode.

See also
getTriggerMode()
Parameters
deviceIDthe identifier of the device as returned by getDeviceIDs.
errorCodea code indicating the result of the operation: ERROR_SUCCESS on success; ERROR_FEATURE_NOT_FOUND if the spectrometer feature is not available; ERROR_COMMAND_NOT_SUPPORTED this command is not supported by the device; ERROR_TRANSFER_ERROR if a communication error occurred; ERROR_CODE_INVALID_ARGUMENT if the mode supplied is not valid; ERROR_NO_DEVICE if the device does not exist.
modethe trigger mode to apply.

◆ shutdown()

static void oceandirect::api::OceanDirectAPI::shutdown ( )
static

No public destructor. Call this to force memory cleanup.


The documentation for this class was generated from the following file: