SeaBreeze
Data Structures | Functions
SeaBreezeAPI.h File Reference
#include "api/DllDecl.h"
#include "api/seabreezeapi/DeviceAdapter.h"

Go to the source code of this file.

Data Structures

class  SeaBreezeAPI
 This is an interface to SeaBreeze that allows the user to connect to devices over USB and other buses. This is intended as a usable and extensible API. More...
 

Functions

DLL_DECL void sbapi_initialize ()
 
DLL_DECL void sbapi_shutdown ()
 
DLL_DECL int sbapi_add_TCPIPv4_device_location (char *deviceTypeName, char *ipAddress, unsigned int port)
 
DLL_DECL int sbapi_add_RS232_device_location (char *deviceTypeName, char *deviceBusPath, unsigned int baud)
 
DLL_DECL int sbapi_probe_devices ()
 
DLL_DECL int sbapi_get_number_of_device_ids ()
 
DLL_DECL int sbapi_get_device_ids (long *ids, unsigned int max_ids)
 
DLL_DECL int sbapi_open_device (long id, int *error_code)
 
DLL_DECL void sbapi_close_device (long id, int *error_code)
 
DLL_DECL const char * sbapi_get_error_string (int error_code)
 
DLL_DECL int sbapi_get_device_type (long id, int *error_code, char *buffer, unsigned int length)
 
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_primary_out (long id, int *error_code)
 
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_primary_in (long id, int *error_code)
 
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_secondary_out (long id, int *error_code)
 
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_secondary_in (long id, int *error_code)
 
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_secondary_in2 (long id, int *error_code)
 
DLL_DECL int sbapi_get_number_of_raw_usb_bus_access_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_raw_usb_bus_access_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL int sbapi_raw_usb_bus_access_read (long deviceID, long featureID, int *error_code, unsigned char *buffer, int buffer_length, unsigned char endpoint)
 
DLL_DECL int sbapi_raw_usb_bus_access_write (long deviceID, long featureID, int *error_code, unsigned char *buffer, int buffer_length, unsigned char endpoint)
 
DLL_DECL int sbapi_get_number_of_serial_number_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_serial_number_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL int sbapi_get_serial_number (long deviceID, long featureID, int *error_code, char *buffer, int buffer_length)
 
DLL_DECL unsigned char sbapi_get_serial_number_maximum_length (long deviceID, long featureID, int *error_code)
 
DLL_DECL int sbapi_get_number_of_spectrometer_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_spectrometer_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL void sbapi_spectrometer_set_trigger_mode (long deviceID, long featureID, int *error_code, int mode)
 
DLL_DECL void sbapi_spectrometer_set_integration_time_micros (long deviceID, long featureID, int *error_code, unsigned long integration_time_micros)
 
DLL_DECL long sbapi_spectrometer_get_minimum_integration_time_micros (long deviceID, long featureID, int *error_code)
 
DLL_DECL double sbapi_spectrometer_get_maximum_intensity (long deviceID, long featureID, int *error_code)
 
DLL_DECL int sbapi_spectrometer_get_formatted_spectrum_length (long deviceID, long featureID, int *error_code)
 
DLL_DECL int sbapi_spectrometer_get_formatted_spectrum (long deviceID, long featureID, int *error_code, double *buffer, int buffer_length)
 
DLL_DECL int sbapi_spectrometer_get_unformatted_spectrum_length (long deviceID, long featureID, int *error_code)
 
DLL_DECL int sbapi_spectrometer_get_unformatted_spectrum (long deviceID, long featureID, int *error_code, unsigned char *buffer, int buffer_length)
 
DLL_DECL int sbapi_spectrometer_get_wavelengths (long deviceID, long featureID, int *error_code, double *wavelengths, int length)
 
DLL_DECL int sbapi_spectrometer_get_electric_dark_pixel_count (long deviceID, long featureID, int *error_code)
 
DLL_DECL int sbapi_spectrometer_get_electric_dark_pixel_indices (long deviceID, long featureID, int *error_code, int *indices, int length)
 
DLL_DECL int sbapi_get_number_of_pixel_binning_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_pixel_binning_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL void sbapi_binning_set_pixel_binning_factor (long deviceID, long featureID, int *error_code, unsigned char factor)
 
DLL_DECL unsigned char sbapi_binning_get_pixel_binning_factor (long deviceID, long featureID, int *error_code)
 
DLL_DECL void sbapi_binning_set_default_pixel_binning_factor (long deviceID, long featureID, int *error_code, unsigned char factor)
 
DLL_DECL void sbapi_binning_reset_default_pixel_binning_factor (long deviceID, long featureID, int *error_code)
 
DLL_DECL unsigned char sbapi_binning_get_default_pixel_binning_factor (long deviceID, long featureID, int *error_code)
 
DLL_DECL unsigned char sbapi_binning_get_max_pixel_binning_factor (long deviceID, long featureID, int *error_code)
 
DLL_DECL int sbapi_get_number_of_shutter_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_shutter_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL void sbapi_shutter_set_shutter_open (long deviceID, long featureID, int *error_code, unsigned char opened)
 
DLL_DECL int sbapi_get_number_of_light_source_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_light_source_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL int sbapi_light_source_get_count (long deviceID, long featureID, int *error_code)
 
DLL_DECL unsigned char sbapi_light_source_has_enable (long deviceID, long featureID, int *error_code, int light_source_index)
 
DLL_DECL unsigned char sbapi_light_source_is_enabled (long deviceID, long featureID, int *error_code, int light_source_index)
 
DLL_DECL void sbapi_light_source_set_enable (long deviceID, long featureID, int *error_code, int light_source_index, unsigned char enable)
 
DLL_DECL unsigned char sbapi_light_source_has_variable_intensity (long deviceID, long featureID, int *error_code, int light_source_index)
 
DLL_DECL double sbapi_light_source_get_intensity (long deviceID, long featureID, int *error_code, int light_source_index)
 
DLL_DECL void sbapi_light_source_set_intensity (long deviceID, long featureID, int *error_code, int light_source_index, double intensity)
 
DLL_DECL int sbapi_get_number_of_lamp_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_lamp_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL void sbapi_lamp_set_lamp_enable (long deviceID, long featureID, int *error_code, unsigned char lamp_enable)
 
DLL_DECL int sbapi_get_number_of_continuous_strobe_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_continuous_strobe_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL void sbapi_continuous_strobe_set_continuous_strobe_enable (long deviceID, long featureID, int *error_code, unsigned char enable)
 
DLL_DECL void sbapi_continuous_strobe_set_continuous_strobe_period_micros (long deviceID, long featureID, int *error_code, unsigned long period_micros)
 
DLL_DECL int sbapi_get_number_of_eeprom_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_eeprom_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL int sbapi_eeprom_read_slot (long deviceID, long featureID, int *error_code, int slot_number, unsigned char *buffer, int buffer_length)
 
DLL_DECL int sbapi_get_number_of_irrad_cal_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_irrad_cal_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL int sbapi_irrad_calibration_read (long deviceID, long featureID, int *error_code, float *buffer, int buffer_length)
 
DLL_DECL int sbapi_irrad_calibration_write (long deviceID, long featureID, int *error_code, float *buffer, int buffer_length)
 
DLL_DECL int sbapi_irrad_calibration_has_collection_area (long deviceID, long featureID, int *error_code)
 
DLL_DECL float sbapi_irrad_calibration_read_collection_area (long deviceID, long featureID, int *error_code)
 
DLL_DECL void sbapi_irrad_calibration_write_collection_area (long deviceID, long featureID, int *error_code, float area)
 
DLL_DECL int sbapi_get_number_of_thermo_electric_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_thermo_electric_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL double sbapi_tec_read_temperature_degrees_C (long deviceID, long featureID, int *error_code)
 
DLL_DECL void sbapi_tec_set_temperature_setpoint_degrees_C (long deviceID, long featureID, int *error_code, double temperature_degrees_celsius)
 
DLL_DECL void sbapi_tec_set_enable (long deviceID, long featureID, int *error_code, unsigned char tec_enable)
 
DLL_DECL int sbapi_get_number_of_nonlinearity_coeffs_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_nonlinearity_coeffs_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL int sbapi_nonlinearity_coeffs_get (long deviceID, long featureID, int *error_code, double *buffer, int max_length)
 
DLL_DECL int sbapi_get_number_of_temperature_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_temperature_features (long deviceID, int *error_code, long *temperatureFeatures, int max_features)
 
DLL_DECL unsigned char sbapi_temperature_count_get (long deviceID, long temperatureFeatureID, int *error_code)
 
DLL_DECL double sbapi_temperature_get (long deviceID, long temperatureFeatureID, int *error_code, int index)
 
DLL_DECL int sbapi_temperature_get_all (long deviceID, long temperatureFeatureID, int *error_code, double *buffer, int max_length)
 
DLL_DECL int sbapi_get_number_of_spectrum_processing_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_spectrum_processing_features (long deviceID, int *error_code, long *spectrumProcessingFeatures, int max_features)
 
DLL_DECL unsigned short int sbapi_spectrum_processing_scans_to_average_get (long deviceID, long spectrumProcessingFeatureID, int *error_code)
 
DLL_DECL void sbapi_spectrum_processing_scans_to_average_set (long deviceID, long spectrumProcessingFeatureID, int *error_code, unsigned short int scansToAverage)
 
DLL_DECL unsigned char sbapi_spectrum_processing_boxcar_width_get (long deviceID, long spectrumProcessingFeatureID, int *error_code)
 
DLL_DECL void sbapi_spectrum_processing_boxcar_width_set (long deviceID, long spectrumProcessingFeatureID, int *error_code, unsigned char boxcarWidth)
 
DLL_DECL int sbapi_get_number_of_revision_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_revision_features (long deviceID, int *error_code, long *revisionFeatures, int max_features)
 
DLL_DECL unsigned char sbapi_revision_hardware_get (long deviceID, long revisionFeatureID, int *error_code)
 
DLL_DECL unsigned short int sbapi_revision_firmware_get (long deviceID, long revisionFeatureID, int *error_code)
 
DLL_DECL int sbapi_get_number_of_optical_bench_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_optical_bench_features (long deviceID, int *error_code, long *opticalBenchFeatures, int max_features)
 
DLL_DECL unsigned short int sbapi_optical_bench_get_fiber_diameter_microns (long deviceID, long opticalBenchFeatureID, int *error_code)
 
DLL_DECL unsigned short int sbapi_optical_bench_get_slit_width_microns (long deviceID, long opticalBenchFeatureID, int *error_code)
 
DLL_DECL int sbapi_optical_bench_get_id (long deviceID, long featureID, int *error_code, char *buffer, int buffer_length)
 
DLL_DECL int sbapi_optical_bench_get_serial_number (long deviceID, long featureID, int *error_code, char *buffer, int buffer_length)
 
DLL_DECL int sbapi_optical_bench_get_coating (long deviceID, long featureID, int *error_code, char *buffer, int buffer_length)
 
DLL_DECL int sbapi_optical_bench_get_filter (long deviceID, long featureID, int *error_code, char *buffer, int buffer_length)
 
DLL_DECL int sbapi_optical_bench_get_grating (long deviceID, long featureID, int *error_code, char *buffer, int buffer_length)
 
DLL_DECL int sbapi_get_number_of_stray_light_coeffs_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_stray_light_coeffs_features (long deviceID, int *error_code, long *features, int max_features)
 
DLL_DECL int sbapi_stray_light_coeffs_get (long deviceID, long featureID, int *error_code, double *buffer, int max_length)
 
DLL_DECL int sbapi_get_number_of_data_buffer_features (long deviceID, int *error_code)
 
DLL_DECL int sbapi_get_data_buffer_features (long deviceID, int *error_code, long *buffer, unsigned int maxLength)
 
DLL_DECL void sbapi_data_buffer_clear (long deviceID, long featureID, int *error_code)
 Clear the data buffer. More...
 
DLL_DECL unsigned long sbapi_data_buffer_get_number_of_elements (long deviceID, long featureID, int *error_code)
 Get the number of data elements currently in the buffer. More...
 
DLL_DECL unsigned long sbapi_data_buffer_get_buffer_capacity (long deviceID, long featureID, int *error_code)
 Get the present limit of how many data elements will be retained by the buffer. This value can be changed with sbapi_data_buffer_set_buffer_capacity(). More...
 
DLL_DECL unsigned long sbapi_data_buffer_get_buffer_capacity_maximum (long deviceID, long featureID, int *error_code)
 Get the maximum possible configurable size for the data buffer. More...
 
DLL_DECL unsigned long sbapi_data_buffer_get_buffer_capacity_minimum (long deviceID, long featureID, int *error_code)
 Get the minimum possible configurable size for the data buffer. More...
 
DLL_DECL void sbapi_data_buffer_set_buffer_capacity (long deviceID, long featureID, int *error_code, unsigned long capacity)
 Set the number of data elements that the buffer should retain. More...
 
DLL_DECL int sbapi_get_number_of_acquisition_delay_features (long deviceID, int *errorCode)
 
DLL_DECL int sbapi_get_acquisition_delay_features (long deviceID, int *errorCode, long *buffer, unsigned int maxLength)
 
DLL_DECL void sbapi_acquisition_delay_set_delay_microseconds (long deviceID, long featureID, int *errorCode, unsigned long delay_usec)
 
DLL_DECL unsigned long sbapi_acquisition_delay_get_delay_microseconds (long deviceID, long featureID, int *errorCode)
 
DLL_DECL unsigned long sbapi_acquisition_delay_get_delay_increment_microseconds (long deviceID, long featureID, int *errorCode)
 
DLL_DECL unsigned long sbapi_acquisition_delay_get_delay_maximum_microseconds (long deviceID, long featureID, int *errorCode)
 
DLL_DECL unsigned long sbapi_acquisition_delay_get_delay_minimum_microseconds (long deviceID, long featureID, int *errorCode)
 

Detailed Description

Date
February 2015
Author
Ocean Optics, Inc., Kirk Clendinning, Heliospectra

This is an interface to SeaBreeze that allows the user to connect to devices over USB and other buses. This is intended as a usable and extensible API.

This provides a C interface to help with linkage.

LICENSE:

SeaBreeze Copyright (C) 2014, Ocean Optics Inc

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Function Documentation

DLL_DECL void sbapi_initialize ( )

This should be called prior to any other sbapi_call. The API may recover gracefully if this is not called, but future releases may assume this is called first. This should be called synchronously – a single thread should call this.

DLL_DECL void sbapi_shutdown ( )

This may be called to free up any allocated memory being held by the driver interface. After this is called by any thread, sbapi_initialize should be called again before any other sbapi_ functions are used.

DLL_DECL int sbapi_add_TCPIPv4_device_location ( char *  deviceTypeName,
char *  ipAddress,
unsigned int  port 
)

This specifies to the driver that a device of the given type might be found on the network at a given address and port. The driver will add the device type and location to the set of those that can be opened.

Parameters
deviceTypeName(Input) The name of a type of device. This can be one of the following: Jaz
ipAddress(Input) The IPv4 address of the device. This should be in "dotted quads" notation, such as "192.168.1.100".
port(Input) The network port to open on the device. This will depend on the device type; consult its datasheet.
Returns
zero on success, non-zero on error
DLL_DECL int sbapi_add_RS232_device_location ( char *  deviceTypeName,
char *  deviceBusPath,
unsigned int  baud 
)

This specifies to the driver that a device of the given type might be found on a particular RS232 bus (e.g. a COM port). The driver will add the device type and location to the set of those that can be opened.

Parameters
deviceTypeName(Input) The name of a type of device. This can be one of the following: QE-PRO, STS.
deviceBusPath(Input) The location of the device on the RS232 bus. This will be a platform-specific location. Under Windows, this may be COM1, COM2, etc. Under Linux, this might be /dev/ttyS0, /dev/ttyS1, etc.
baud(Input) Baud rate at which to open the device. This should be specified as the rate itself, e.g. 9600, 57600, or 115200.
Returns
zero on success, non-zero on error
DLL_DECL int sbapi_probe_devices ( )

This causes a search for known devices on all buses that support autodetection. This does NOT automatically open any device – that must still be done with the sbapi_open_device() function. Note that this should only be done by one thread at a time, and it is recommended that other threads avoid calling sbapi_get_number_of_device_ids() or sbapi_get_device_ids() while this is executing. Ideally, a single thread should be designated for all device discovery/get actions, and separate worker threads can be used for each device discovered.

Returns
the total number of devices that have been found automatically. If called repeatedly, this will always return the number of devices most recently found, even if they have been found or opened previously.
DLL_DECL int sbapi_get_number_of_device_ids ( )

This returns the total number of devices that are known either because they have been specified with sbapi_add_RS232_device_location or because they were probed on some bus. This can be used to bound the number of device references that can be gotten with sbapi_get_device_ids().

Returns
the total number of devices references that are available through sbapi_get_device_ids().
DLL_DECL int sbapi_get_device_ids ( long *  ids,
unsigned int  max_ids 
)

This will populate the provided buffer with up to max_ids of device references. These references must be used as the first parameter to most of the other sbapi_ calls. Each uniquely identifies a single device instance.

Parameters
ids(Output) an array of long integers that will be overwritten with the unique IDs of each known device. Note that these devices will not be open by default.
max_ids(Input) the maximum number of IDs that may be written to the array
Returns
The total number of device IDs that were written to the array. This may be zero on error.
DLL_DECL int sbapi_open_device ( long  id,
int *  error_code 
)

This function opens a device attached to the system. The device must be provided as a location ID from the sbapi_get_device_ids() function. Such locations can either be specified or probed using the other methods in this interface.

Parameters
id(Input) The location ID of a device to try to open. Only IDs that have been returned by a previous call to seabreeze_get_device_ids() are valid.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
0 if it opened a device successfully, or 1 if no device was opened (in which case the error_code variable will be set).
DLL_DECL void sbapi_close_device ( long  id,
int *  error_code 
)

This function closes the spectrometer attached to the system.

Parameters
id(Input) The location ID of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
DLL_DECL const char* sbapi_get_error_string ( int  error_code)

This function returns a description of the error denoted by error_code.

Parameters
error_code(Input) The integer error code to look up. Error codes may not be zero, but can be any non-zero integer (positive or negative).
Returns
char *: A description in the form of a string that describes what the error was.
DLL_DECL int sbapi_get_device_type ( long  id,
int *  error_code,
char *  buffer,
unsigned int  length 
)

This function copies a string denoting the type of the device into the provided buffer.

Parameters
id(Input) The location ID of a device previously opened with sbapi_get_device_locations().
error_code(Output) pointer to an integer that can be used for storing error codes. This may be NULL.
buffer(Output) Pointer to a user buffer that the name will be stored into. This may be one of the following:
  • NONE: Used if no spectrometer is found (error_code will also be set)
  • HR2000: Represents an HR2000 spectrometer
  • HR2000PLUS: Represents an HR2000+ spectrometer
  • HR4000: Represents an HR4000 spectrometer
  • JAZ: Represents a Jaz spectrometer
  • MAYA2000: Represents a MAYA2000 spectrometer
  • MAYA2000PRO: Represents a MAYA2000PRO spectrometer
  • MAYALSL: Represents a Maya-LSL spectrometer
  • NIRQUEST256: Represents an NIRQUEST256 spectrometer
  • NIRQUEST512: Represents an NIRQUEST512 spectrometer
  • QE65000: Represents a QE65000 spectrometer
  • STS: Represents an STS spectrometer
  • Torus: Represents a Torus spectrometer
  • USB2000: Represents a USB2000 spectrometer
  • USB2000PLUS: Represents a USB2000+ spectrometer
  • USB4000: Represents a USB4000 spectrometer
length(Input) Maximum number of bytes that may be written to the buffer
Returns
integral number of bytes actually written to the user buffer
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_primary_out ( long  id,
int *  error_code 
)

This function returns the usb endpoint for the type specified. If the type is not supported by the device, a zero is returned. 0 is normally the control endpoint. That value is not valid in this context.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the usb endpoint address.
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_primary_in ( long  id,
int *  error_code 
)

This function returns the usb endpoint for the type specified. If the type is not supported by the device, a zero is returned. 0 is normally the control endpoint. That value is not valid in this context.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the usb endpoint address.
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_secondary_out ( long  id,
int *  error_code 
)

This function returns the usb endpoint for the type specified. If the type is not supported by the device, a zero is returned. 0 is normally the control endpoint. That value is not valid in this context.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the usb endpoint address.
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_secondary_in ( long  id,
int *  error_code 
)

This function returns the usb endpoint for the type specified. If the type is not supported by the device, a zero is returned. 0 is normally the control endpoint. That value is not valid in this context.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the usb endpoint address.
DLL_DECL unsigned char sbapi_get_device_usb_endpoint_secondary_in2 ( long  id,
int *  error_code 
)

This function returns the usb endpoint for the type specified. If the type is not supported by the device, a zero is returned. 0 is normally the control endpoint. That value is not valid in this context.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the usb endpoint address.
DLL_DECL int sbapi_get_number_of_raw_usb_bus_access_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of raw usb bus access feature instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of raw usb bus access features that will be returned by a call to sbapi_get_raw_usb_bus_access_features().
DLL_DECL int sbapi_get_raw_usb_bus_access_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each raw usb bus access feature instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) a preallocated array to hold returned feature handles
max_features(Input) length of the preallocated buffer
Returns
the number of raw usb bus access feature IDs that were copied.
DLL_DECL int sbapi_raw_usb_bus_access_read ( long  deviceID,
long  featureID,
int *  error_code,
unsigned char *  buffer,
int  buffer_length,
unsigned char  endpoint 
)

This function reads out a raw usb access from the spectrometer's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an irradiance calibration feature. Valid IDs can be found with the sbapi_get_raw_usb_access_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
buffer(Output) preallocated array to hold an unsigned char buffer
buffer_length(Input) size of the preallocated buffer (should equal pixel count)
endpoint(Input) a USB endpoint gotten from one of the sbapi_get_device_usb_endpoint_xxx_xxx() type calls.
Returns
the number of floats read from the device into the buffer
DLL_DECL int sbapi_raw_usb_bus_access_write ( long  deviceID,
long  featureID,
int *  error_code,
unsigned char *  buffer,
int  buffer_length,
unsigned char  endpoint 
)

This function writes a buffer of unsigned chars to the specified USB endpoint if the feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an raw usb bus access feature. Valid IDs can be found with the sbapi_get_raw_usb_bus_access_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
buffer(Output) a pointer to unsigned char values to send to the usb endpoint
buffer_length(Input) number of calibration factors to write
endpoint(Input) a USB endpoint gotten from one of the sbapi_get_device_usb_endpoint_xxx_xxx() type calls.
Returns
the number of floats written from the buffer to the device
DLL_DECL int sbapi_get_number_of_serial_number_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of serial number instances available in the indicated device. Each instance may refer to a different module.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the number of serial_number features that will be returned by a call to sbapi_get_serial_number_features().
DLL_DECL int sbapi_get_serial_number_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each serial number instance for this device. Each instance refers to a single serial number feature.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) a pre-allocated array to hold the list of supported serial number features
max_features(Input) size of the preallocated output array
Returns
the number of serial number feature IDs that were copied.
DLL_DECL int sbapi_get_serial_number ( long  deviceID,
long  featureID,
int *  error_code,
char *  buffer,
int  buffer_length 
)

This reads the device's serial number and fills the provided array (up to the given length) with it.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a serial number feature. Valid IDs can be found with the sbapi_get_serial_number_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
buffer(Output) A pre-allocated array of characters that the serial number will be copied into
buffer_length(Input) The number of values to copy into the buffer (this should be no larger than the number of chars allocated in the buffer)
Returns
the number of bytes written into the buffer
DLL_DECL unsigned char sbapi_get_serial_number_maximum_length ( long  deviceID,
long  featureID,
int *  error_code 
)

This reads the possible maximum length of the device's serial number

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a serial number feature. Valid IDs can be found with the sbapi_get_serial_number_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the length of the serial number in an unsigned character byte
DLL_DECL int sbapi_get_number_of_spectrometer_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of spectrometer instances available in the indicated device. Each instance refers to a single optical bench.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the number of spectrometer features that will be returned by a call to sbapi_get_spectrometer_features().
DLL_DECL int sbapi_get_spectrometer_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each spectrometer instance for this device. Each instance refers to a single optical bench. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) a preallocated output array to hold the features
max_features(Input) size of the preallocated output array
Returns
Returns the number of spectrometer feature IDs that were copied.
DLL_DECL void sbapi_spectrometer_set_trigger_mode ( long  deviceID,
long  featureID,
int *  error_code,
int  mode 
)

This function sets the trigger mode for the specified device. Note that requesting an unsupported mode will result in an error.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
mode(Input) a trigger mode (0 = normal, 1 = software, 2 = synchronization, 3 = external hardware, etc - check your particular spectrometer's Data Sheet)
DLL_DECL void sbapi_spectrometer_set_integration_time_micros ( long  deviceID,
long  featureID,
int *  error_code,
unsigned long  integration_time_micros 
)

This function sets the integration time for the specified device. This function should not be responsible for performing stability scans.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
integration_time_micros(Input) The new integration time in units of microseconds
DLL_DECL long sbapi_spectrometer_get_minimum_integration_time_micros ( long  deviceID,
long  featureID,
int *  error_code 
)

This function returns the smallest integration time setting, in microseconds, that is valid for the spectrometer.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
Returns minimum legal integration time in microseconds if > 0. On error, returns -1 and error_code will be set accordingly.
DLL_DECL double sbapi_spectrometer_get_maximum_intensity ( long  deviceID,
long  featureID,
int *  error_code 
)

This function returns the maximum pixel intensity for the spectrometer.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
Returns maximum pixel intensity if > 0. On error, returns -1 and error_code will be set accordingly.
DLL_DECL int sbapi_spectrometer_get_formatted_spectrum_length ( long  deviceID,
long  featureID,
int *  error_code 
)

This returns an integer denoting the number of pixels in a formatted spectrum (as returned by get_formatted_spectrum(...)).

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the length of a formatted spectrum.
DLL_DECL int sbapi_spectrometer_get_formatted_spectrum ( long  deviceID,
long  featureID,
int *  error_code,
double *  buffer,
int  buffer_length 
)

This acquires a spectrum and returns the answer in formatted floats. In this mode, auto-nulling should be automatically performed for devices that support it.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
buffer(Output) A buffer (with memory already allocated) to hold the spectral data
buffer_length(Input) The length of the buffer
Returns
the number of floats read into the buffer
DLL_DECL int sbapi_spectrometer_get_unformatted_spectrum_length ( long  deviceID,
long  featureID,
int *  error_code 
)

This returns an integer denoting the length of a raw spectrum (as returned by get_unformatted_spectrum(...)).

Parameters
deviceID(Input) The index of a device previously opened with open_spectrometer().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the length of an unformatted spectrum.
DLL_DECL int sbapi_spectrometer_get_unformatted_spectrum ( long  deviceID,
long  featureID,
int *  error_code,
unsigned char *  buffer,
int  buffer_length 
)

This acquires a spectrum and returns the answer in raw, unformatted bytes.

Parameters
deviceID(Input) The index of a device previously opened with open_spectrometer().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
buffer(Output) A buffer (with memory already allocated) to hold the spectral data
buffer_length(Input) The length of the buffer
Returns
the number of bytes read into the buffer
DLL_DECL int sbapi_spectrometer_get_wavelengths ( long  deviceID,
long  featureID,
int *  error_code,
double *  wavelengths,
int  length 
)

This computes the wavelengths for the spectrometer and fills in the provided array (up to the given length) with those values.

Parameters
deviceID(Input) The index of a device previously opened with open_spectrometer().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Ouput) pointer to an integer that can be used for storing error codes.
wavelengths(Output) A pre-allocated array of doubles that the wavelengths will be copied into
length(Input) The number of values to copy into the wavelength array (this should be no larger than the number of doubles allocated in the wavelengths array)
Returns
the number of bytes written into the wavelength buffer
DLL_DECL int sbapi_spectrometer_get_electric_dark_pixel_count ( long  deviceID,
long  featureID,
int *  error_code 
)

This returns the number of pixels that are electrically active but optically masked (a.k.a. electric dark pixels). Note that not all detectors have optically masked pixels; in that case, this function will return zero.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of pixels that can be retrieved by the sbapi_spectrometer_get_electric_dark_pixel_indices() function.
DLL_DECL int sbapi_spectrometer_get_electric_dark_pixel_indices ( long  deviceID,
long  featureID,
int *  error_code,
int *  indices,
int  length 
)

This fills in the provided array (up to the given length) with the indices of the pixels that are electrically active but optically masked (a.k.a. electric dark pixels). Note that not all detectors have optically masked pixels; in that case, this function will return zero.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrometer feature. Valid IDs can be found with the sbapi_get_spectrometer_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
indices(Output) A pre-allocated array of ints that the pixel indices will be copied into
length(Input) The number of values to copy into the indices array (this should be no larger than the number of ints allocated in the indices array)
Returns
the number of bytes written into the indices buffer
DLL_DECL int sbapi_get_number_of_pixel_binning_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of pixel binning instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the number of pixel binning features that will be returned by a call to sbapi_get_pixel_binning_features().
DLL_DECL int sbapi_get_pixel_binning_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each pixel binning feature for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) a pre-populated array to hold the returned feature handles
max_features(Input) size of the pre-allocated array
Returns
the number of pixel binning feature IDs that were copied.
DLL_DECL void sbapi_binning_set_pixel_binning_factor ( long  deviceID,
long  featureID,
int *  error_code,
unsigned char  factor 
)

This function sets the pixel binning factor on the device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a pixel binning feature. Valid IDs can be found with the sbapi_get_pixel_binning_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
factor(Input) The desired pixel binning factor.
DLL_DECL unsigned char sbapi_binning_get_pixel_binning_factor ( long  deviceID,
long  featureID,
int *  error_code 
)

This function gets the pixel binning factor on the device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a pixel binning feature. Valid IDs can be found with the sbapi_get_pixel_binning_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the pixel binning factor for the specified feature.
DLL_DECL void sbapi_binning_set_default_pixel_binning_factor ( long  deviceID,
long  featureID,
int *  error_code,
unsigned char  factor 
)

This function sets the default pixel binning factor on the device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a pixel binning feature. Valid IDs can be found with the sbapi_get_pixel_binning_features() function.
error_code(Output)A pointer to an integer that can be used for storing error codes.
factor(Input) The desired default pixel binning factor.
DLL_DECL void sbapi_binning_reset_default_pixel_binning_factor ( long  deviceID,
long  featureID,
int *  error_code 
)

This function resets the default pixel binning factor on the device back to the factory default.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a pixel binning feature. Valid IDs can be found with the sbapi_get_pixel_binning_features() function.
error_code(Output)A pointer to an integer that can be used for storing error codes.
DLL_DECL unsigned char sbapi_binning_get_default_pixel_binning_factor ( long  deviceID,
long  featureID,
int *  error_code 
)

This function gets the default pixel binning factor on the device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a pixel binning feature. Valid IDs can be found with the sbapi_get_pixel_binning_features() function.
error_code(Output)A pointer to an integer that can be used for storing error codes.
Returns
the default pixel binning factor for the specified feature.
DLL_DECL unsigned char sbapi_binning_get_max_pixel_binning_factor ( long  deviceID,
long  featureID,
int *  error_code 
)

This function gets the maximum pixel binning factor on the device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a pixel binning feature. Valid IDs can be found with the sbapi_get_pixel_binning_features() function.
error_code(Output)A pointer to an integer that can be used for storing error codes.
Returns
the maximum pixel binning factor for the specified feature.
DLL_DECL int sbapi_get_number_of_shutter_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of shutter instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the number of shutter features that will be returned by a call to sbapi_get_shutter_features().
DLL_DECL int sbapi_get_shutter_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each shutter instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) a pre-populated array to hold the returned feature handles
max_features(Input) size of the pre-allocated array
Returns
the number of shutter feature IDs that were copied.
DLL_DECL void sbapi_shutter_set_shutter_open ( long  deviceID,
long  featureID,
int *  error_code,
unsigned char  opened 
)

This function sets the shutter state on the device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a shutter feature. Valid IDs can be found with the sbapi_get_shutter_features() function.
error_code(Output)A pointer to an integer that can be used for storing error codes.
opened(Input) A boolean used for denoting the desired state (opened/closed) of the shutter. If the value of opened is non-zero, then the shutter will open. If the value of opened is zero, then the shutter will close.
DLL_DECL int sbapi_get_number_of_light_source_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of light source instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the number of light source features that will be returned by a call to sbapi_get_light_source_features().
DLL_DECL int sbapi_get_light_source_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each light source instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) pointer to an integer that can be used for storing error codes.
features(Output) pre-allocated buffer that will receive the IDs of the feature instances
max_features(Input) the maximum number of elements that can be copied into the provided features array
Returns
the number of light source feature IDs that were copied.
DLL_DECL int sbapi_light_source_get_count ( long  deviceID,
long  featureID,
int *  error_code 
)

This function gets the number of light sources that are represented by the given featureID. Such light sources could be individual LEDs, light bulbs, lasers, etc. Each of these light sources may have different capabilities, such as programmable intensities and enables, which should be queried before they are used.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a light source feature. Valid IDs can be found with sbapi_get_light_source_features().
error_code(Output) pointer to an integer that can be used for storing error codes.
Returns
the number of light sources (e.g. bulbs) in the indicated feature
DLL_DECL unsigned char sbapi_light_source_has_enable ( long  deviceID,
long  featureID,
int *  error_code,
int  light_source_index 
)

Queries whether the indicated light source within the given feature instance has a usable enable/disable control. If this returns 0 (meaning no enable available) then calling sbapi_light_source_set_enable() or sbapi_light_source_is_enabled() is likely to result in an error.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a light source feature. Valid IDs can be found with the sbapi_get_light_source_features() function.
error_code(Ouput) A pointer to an integer that can be used for storing error codes.
light_source_index(Input) Which of potentially many light sources (LEDs, lasers, light bulbs) within the indicated feature instance to query
Returns
0 to indicate specified light source cannot be enabled/disabled, 1 to indicate specified light source can be enabled/disabled with sbapi_light_source_set_enable()
DLL_DECL unsigned char sbapi_light_source_is_enabled ( long  deviceID,
long  featureID,
int *  error_code,
int  light_source_index 
)

Queries whether the indicated light source within the given feature instance is enabled (energized).

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a light source feature. Valid IDs can be found with the sbapi_get_light_source_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
light_source_index(Input) Which of potentially many light sources (LEDs, lasers, light bulbs) within the indicated feature instance to query
Returns
0 to indicate specified light source is disabled (should emit no light), 1 to indicate specified light source is enabled (should emit light depending on configured intensity setting)
DLL_DECL void sbapi_light_source_set_enable ( long  deviceID,
long  featureID,
int *  error_code,
int  light_source_index,
unsigned char  enable 
)

Attempts to enable or disable the indicated light source within the given feature instance. Not all light sources have an enable/disable control, and this capability can be queried with sbapi_light_source_has_enable(). Note that an enabled light source should emit light according to its last (or default) intensity setting which might be the minimum; in this case, the light source might appear to remain off.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a light source feature. Valid IDs can be found with the sbapi_get_light_source_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
light_source_index(Input) Which of potentially many light sources (LEDs, lasers, light bulbs) within the indicated feature instance to query
enable(Input) Whether to enable the light source. A value of zero will attempt to disable the light source, and any other value will enable it.
DLL_DECL unsigned char sbapi_light_source_has_variable_intensity ( long  deviceID,
long  featureID,
int *  error_code,
int  light_source_index 
)

Queries whether the indicated light source within the given feature instance has a usable intensity control. If this returns 0 (meaning no control available) then calling sbapi_light_source_set_intensity() or sbapi_light_source_get_intensity() is likely to result in an error.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a light source feature. Valid IDs can be found with the sbapi_get_light_source_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
light_source_index(Input) Which of potentially many light sources (LEDs, lasers, light bulbs) within the indicated feature instance to query
Returns
0 to indicate specified light source cannot have its intensity changed, 1 to indicate the specified light source can have its intensity controlled with sbapi_light_source_set_intensity()
DLL_DECL double sbapi_light_source_get_intensity ( long  deviceID,
long  featureID,
int *  error_code,
int  light_source_index 
)

Queries the intensity level of the indicated light source within the given feature instance. The intensity is normalized over the range [0, 1], with 0 as the minimum and 1 as the maximum.

SAFETY WARNING: a light source at its minimum intensity (0) might still emit light, and in some cases, this may be harmful radiation. A value of 0 indicates the minimum of the programmable range for the light source, and does not necessarily turn the light source off. To disable a light source completely, use sbapi_light_source_set_enable() if the device supports this feature, or provide some other mechanism to allow the light to be disabled or blocked by the operator.

In some cases, the intensity may refer to the duty cycle of a pulsed light source instead of a continuous power rating. The actual power output of the light source might not vary linearly with the reported intensity, so independent measurement or calibration of the light source may be necessary.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a light source feature. Valid IDs can be found with the sbapi_get_light_source_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
light_source_index(Input) Which of potentially many light sources (LEDs, lasers, light bulbs) within the indicated feature instance to query
Returns
Real-valued result (as a double-precision floating point number) over the range [0, 1] where 0 represents the minimum programmable intensity level and 1 indicates the maximum. Note that the minimum intensity level might still allow the light source to produce light.
DLL_DECL void sbapi_light_source_set_intensity ( long  deviceID,
long  featureID,
int *  error_code,
int  light_source_index,
double  intensity 
)

Sets the intensity level of the indicated light source within the given feature instance. The intensity is normalized over the range [0, 1], with 0 as the minimum and 1 as the maximum.

SAFETY WARNING: a light source at its minimum intensity (0) might still emit light, and in some cases, this may be harmful radiation. A value of 0 indicates the minimum of the programmable range for the light source, and does not necessarily turn the light source off. To disable a light source completely, use sbapi_light_source_set_enable() if the device supports this feature, or provide some other mechanism to allow the light to be disabled or blocked by the operator.

In some cases, the intensity may refer to the duty cycle of a pulsed light source instead of a continuous power rating. The actual power output of the light source might not vary linearly with the reported intensity, so independent measurement or calibration of the light source may be necessary.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a light source feature. Valid IDs can be found with the sbapi_get_light_source_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
light_source_index(Input) Which of potentially many light sources (LEDs, lasers, light bulbs) within the indicated feature instance to query
intensity(Input) The target intensity of the light source in the range [0, 1]
DLL_DECL int sbapi_get_number_of_lamp_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of lamp instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of lamp features that will be returned by a call to sbapi_get_lamp_features().
DLL_DECL int sbapi_get_lamp_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each lamp instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) a preallocated array to hold returned feature handles
max_features(Input) length of the preallocated buffer
Returns
the number of lamp feature IDs that were copied.
DLL_DECL void sbapi_lamp_set_lamp_enable ( long  deviceID,
long  featureID,
int *  error_code,
unsigned char  lamp_enable 
)

This function sets the strobe enable on the spectrometer.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a lamp feature. Valid IDs can be found with the sbapi_get_lamp_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
lamp_enable(Input) A character used for denoting the desired value (high/low) of the strobe-enable pin. If the value of strobe_enable is zero, then the pin should be set low. If the value of strobe_enable is non-zero, then the pin should be set high.
DLL_DECL int sbapi_get_number_of_continuous_strobe_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of continuous strobe instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of continuous strobe features that will be returned by a call to sbapi_get_continuous_strobe_features().
DLL_DECL int sbapi_get_continuous_strobe_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each continuous strobe instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) a preallocated array to hold returned feature handles
max_features(Input) length of the preallocated buffer
Returns
the number of continuous strobe feature IDs that were copied.
DLL_DECL void sbapi_continuous_strobe_set_continuous_strobe_enable ( long  deviceID,
long  featureID,
int *  error_code,
unsigned char  enable 
)

This function sets the continuous strobe enable state on the device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a continuous strobe feature. Valid IDs can be found with the sbapi_get_continuous_strobe_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
enable(Input) A boolean used for denoting the desired state (on/off) of the continuous strobe generator. If the value of enable is nonzero, then the continuous strobe will operate. If the value of enable is zero, then the continuous strobe will stop. Note that on some devices the continuous strobe enable is tied to other enables (such as lamp enable or single strobe enable) which may cause side effects.
DLL_DECL void sbapi_continuous_strobe_set_continuous_strobe_period_micros ( long  deviceID,
long  featureID,
int *  error_code,
unsigned long  period_micros 
)

This function sets the continuous strobe period on the device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a continuous strobe feature. Valid IDs can be found with the sbapi_get_continuous_strobe_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
period_micros(Input) The new period of the continous strobe measured in microseconds
DLL_DECL int sbapi_get_number_of_eeprom_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of EEPROM instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of EEPROM features that will be returned by a call to sbapi_get_eeprom_features().
DLL_DECL int sbapi_get_eeprom_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each EEPROM instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) a preallocated array to hold returned feature handles
max_features(Input) length of the preallocated buffer
Returns
the number of EEPROM feature IDs that were copied.
DLL_DECL int sbapi_eeprom_read_slot ( long  deviceID,
long  featureID,
int *  error_code,
int  slot_number,
unsigned char *  buffer,
int  buffer_length 
)

This function reads a string out of the device's EEPROM slot and returns the result.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an EEPROM feature. Valid IDs can be found with the sbapi_get_eeprom_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
slot_number(Input) The number of the slot to read out. Possible values are 0 through 17.
buffer(Output) A buffer (with memory already allocated) to hold the value read out of the EEPROM slot
buffer_length(Input) The length of the buffer
Returns
the number of bytes read from the EEPROM slot into the buffer
DLL_DECL int sbapi_get_number_of_irrad_cal_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of irradiance calibration instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of irradiance calibration features that will be returned by a call to sbapi_get_irrad_cal_features().
DLL_DECL int sbapi_get_irrad_cal_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each irradiance calibration instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) a preallocated array to hold returned feature handles
max_features(Input) length of the preallocated buffer
Returns
the number of irradiance calibration feature IDs that were copied.
DLL_DECL int sbapi_irrad_calibration_read ( long  deviceID,
long  featureID,
int *  error_code,
float *  buffer,
int  buffer_length 
)

This function reads out an irradiance calibration from the spectrometer's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an irradiance calibration feature. Valid IDs can be found with the sbapi_get_irrad_cal_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
buffer(Output) preallocated array to hold irradiance calibration scalars (one per pixel)
buffer_length(Input) size of the preallocated buffer (should equal pixel count)
Returns
the number of floats read from the device into the buffer
DLL_DECL int sbapi_irrad_calibration_write ( long  deviceID,
long  featureID,
int *  error_code,
float *  buffer,
int  buffer_length 
)

This function writes an irradiance calibration to the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an irradiance calibration feature. Valid IDs can be found with the sbapi_get_irrad_cal_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
buffer(Output) array of floating point values to store into the device
buffer_length(Input) number of calibration factors to write
Returns
the number of floats written from the buffer to the device
DLL_DECL int sbapi_irrad_calibration_has_collection_area ( long  deviceID,
long  featureID,
int *  error_code 
)

This function checks for an irradiance collection area in the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an irradiance calibration feature. Valid IDs can be found with the sbapi_get_irrad_cal_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
0 if no collection area available, 1 if available.
DLL_DECL float sbapi_irrad_calibration_read_collection_area ( long  deviceID,
long  featureID,
int *  error_code 
)

This function reads an irradiance collection area from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an irradiance calibration feature. Valid IDs can be found with the sbapi_get_irrad_cal_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
float: collection area (usually in units of cm^2) read from device
DLL_DECL void sbapi_irrad_calibration_write_collection_area ( long  deviceID,
long  featureID,
int *  error_code,
float  area 
)

This function writes an irradiance collection area to the spectrometer's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an irradiance calibration feature. Valid IDs can be found with the sbapi_get_irrad_cal_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
area(Input) collection area to save to spectrometer, presumably in cm^2
DLL_DECL int sbapi_get_number_of_thermo_electric_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of thermoelectric cooler (TEC) instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of TEC features that will be returned by a call to sbapi_get_thermoelectric_features().
DLL_DECL int sbapi_get_thermo_electric_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each thermoelectric cooler (TEC) instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) preallocated array to hold feature handles
max_features(Input) size of the preallocated array
Returns
the number of TEC feature IDs that were copied.
DLL_DECL double sbapi_tec_read_temperature_degrees_C ( long  deviceID,
long  featureID,
int *  error_code 
)

This function reads the actual temperature of the TEC and returns the value in degrees celsius.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an thermoelectric cooler feature. Valid IDs can be found with the sbapi_get_thermo_electric_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
double: The TEC temperature in degrees celsius.
DLL_DECL void sbapi_tec_set_temperature_setpoint_degrees_C ( long  deviceID,
long  featureID,
int *  error_code,
double  temperature_degrees_celsius 
)

This function sets the target (setpoint) TEC temperature.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an thermoelectric cooler feature. Valid IDs can be found with the sbapi_get_thermo_electric_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
temperature_degrees_celsius(Input) desired temperature, in degrees celsius.
DLL_DECL void sbapi_tec_set_enable ( long  deviceID,
long  featureID,
int *  error_code,
unsigned char  tec_enable 
)

This function enables the TEC feature on the device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of an thermoelectric cooler feature. Valid IDs can be found with the sbapi_get_thermo_electric_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
tec_enable(Input) A character that denotes the desired TEC enable state. If the value of tec_enable is zero, the TEC should be disabled. If the value of tec_enable is non-zero, the TEC should be enabled.
DLL_DECL int sbapi_get_number_of_nonlinearity_coeffs_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of nonlinearity coefficient feature instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of features that will be returned by a call to sbapi_get_nonlinearity_coeffs_features().
DLL_DECL int sbapi_get_nonlinearity_coeffs_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each nonlinearity coefficient feature instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) preallocated array to hold returned feature handles
max_features(Input) size of preallocated array
Returns
the number of nonlinearity coefficient feature IDs that were copied.
DLL_DECL int sbapi_nonlinearity_coeffs_get ( long  deviceID,
long  featureID,
int *  error_code,
double *  buffer,
int  max_length 
)

This function reads out nonlinearity coefficients from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a nonlinearity coefficient feature. Valid IDs can be found with the sbapi_get_nonlinearity_coeffs_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
buffer(Output) preallocated buffer to store NLC coefficients
max_length(Input) size of preallocated buffer
Returns
the number of doubles read from the device into the buffer
DLL_DECL int sbapi_get_number_of_temperature_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of temperature feature instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of features that will be returned by a call to sbapi_get_temperature_features().
DLL_DECL int sbapi_get_temperature_features ( long  deviceID,
int *  error_code,
long *  temperatureFeatures,
int  max_features 
)

This function returns IDs for accessing each temperature feature instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) preallocated array to hold returned feature handles
max_features(Input) size of preallocated array
Returns
the number of temperature feature IDs that were copied.
DLL_DECL unsigned char sbapi_temperature_count_get ( long  deviceID,
long  temperatureFeatureID,
int *  error_code 
)

This function reads out an the number of indexed temperatures available from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a temperature feature. Valid IDs can be found with the sbapi_get_temperature_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of temperatures available as an unsigned char
DLL_DECL double sbapi_temperature_get ( long  deviceID,
long  temperatureFeatureID,
int *  error_code,
int  index 
)

This function reads out an indexed temperature from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a temperature feature. Valid IDs can be found with the sbapi_get_temperature_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
index(Input) An index for the device's temperature sensors
Returns
the temperature as a double
DLL_DECL int sbapi_temperature_get_all ( long  deviceID,
long  temperatureFeatureID,
int *  error_code,
double *  buffer,
int  max_length 
)

This function reads out all temperatures from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a temperature feature. Valid IDs can be found with the sbapi_get_temperature_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
buffer(Output) preallocated buffer to store temperatures
max_length(Input) size of preallocated buffer
Returns
the number of doubles read from the device into the buffer
DLL_DECL int sbapi_get_number_of_spectrum_processing_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of spectrum processing feature instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of features that will be returned by a call to sbapi_get_spectrum_processing_features().
DLL_DECL int sbapi_get_spectrum_processing_features ( long  deviceID,
int *  error_code,
long *  spectrumProcessingFeatures,
int  max_features 
)

This function returns IDs for accessing each spectrum processing feature instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) preallocated array to hold returned feature handles
max_features(Input) size of preallocated array
Returns
the number of spectrum processing feature IDs that were copied.
DLL_DECL unsigned short int sbapi_spectrum_processing_scans_to_average_get ( long  deviceID,
long  spectrumProcessingFeatureID,
int *  error_code 
)

This function reads out an the number of scans to average from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrum processing feature. Valid IDs can be found with the sbapi_get_spectrum_processing_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of scans to average as an unsigned short integer
DLL_DECL void sbapi_spectrum_processing_scans_to_average_set ( long  deviceID,
long  spectrumProcessingFeatureID,
int *  error_code,
unsigned short int  scansToAverage 
)

This function sets the number of scans to average in the the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrum processing feature. Valid IDs can be found with the sbapi_get_spectrum_processing_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
scansToAverage(Input) The number of spectrum scans used to generate a less noisy spectrum due to averaging
Returns
void
DLL_DECL unsigned char sbapi_spectrum_processing_boxcar_width_get ( long  deviceID,
long  spectrumProcessingFeatureID,
int *  error_code 
)

This function reads out an the width of the boxcar filter from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrum processing feature. Valid IDs can be found with the sbapi_get_spectrum_processing_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the width of the boxcar filter an unsigned char (values typically 0-15)
DLL_DECL void sbapi_spectrum_processing_boxcar_width_set ( long  deviceID,
long  spectrumProcessingFeatureID,
int *  error_code,
unsigned char  boxcarWidth 
)

This function sets width of the boxcar filter in the the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a spectrum processing feature. Valid IDs can be found with the sbapi_get_spectrum_processing_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
boxcarWidth(Input) The width of the boxcar smoothing function to be used. Values are typically 1 to 15.
Returns
void
DLL_DECL int sbapi_get_number_of_revision_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of revision feature instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of features that will be returned by a call to sbapi_get_revision_features().
DLL_DECL int sbapi_get_revision_features ( long  deviceID,
int *  error_code,
long *  revisionFeatures,
int  max_features 
)

This function returns IDs for accessing each revision feature instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) preallocated array to hold returned feature handles
max_features(Input) size of preallocated array
Returns
the number of revision feature IDs that were copied.
DLL_DECL unsigned char sbapi_revision_hardware_get ( long  deviceID,
long  revisionFeatureID,
int *  error_code 
)

This function reads out the hardware revision from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a temperature feature. Valid IDs can be found with the sbapi_get_revision_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the hardware revision as one unsigned char byte. (Note that both Ocean View and SpectraSuite display the hex value.)
DLL_DECL unsigned short int sbapi_revision_firmware_get ( long  deviceID,
long  revisionFeatureID,
int *  error_code 
)

This function reads out the firmware revision from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a temperature feature. Valid IDs can be found with the sbapi_get_revision_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the firmware revision as two unsigned short int bytes (Note that both Ocean View and SpectraSuite display the hex value.)
DLL_DECL int sbapi_get_number_of_optical_bench_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of optical bench feature instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of features that will be returned by a call to sbapi_get_optical_bench_features().
DLL_DECL int sbapi_get_optical_bench_features ( long  deviceID,
int *  error_code,
long *  opticalBenchFeatures,
int  max_features 
)

This function returns IDs for accessing each optical bench feature instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) preallocated array to hold returned feature handles
max_features(Input) size of preallocated array
Returns
the number of optical bench feature IDs that were copied.
DLL_DECL unsigned short int sbapi_optical_bench_get_fiber_diameter_microns ( long  deviceID,
long  opticalBenchFeatureID,
int *  error_code 
)

This function reads out the optical bench fiber diameter in microns

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
opticalBenchFeatureID(Input) The ID of a particular instance of a optical bench feature. Valid IDs can be found with the sbapi_get_optical_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the fiber diameter in microns
DLL_DECL unsigned short int sbapi_optical_bench_get_slit_width_microns ( long  deviceID,
long  opticalBenchFeatureID,
int *  error_code 
)

This function reads out the optical bench slit width in microns

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
opticalBenchFeatureID(Input) The ID of a particular instance of a optical bench feature. Valid IDs can be found with the sbapi_get_optical_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the slit width in microns
DLL_DECL int sbapi_optical_bench_get_id ( long  deviceID,
long  featureID,
int *  error_code,
char *  buffer,
int  buffer_length 
)

This reads the optical bench ID and fills the provided array (up to the given length) with it.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
opticalBenchFeatureID(Input) The ID of a particular instance of a serial number feature. Valid IDs can be found with the sbapi_get_optical_bench_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
buffer(Output) A pre-allocated array of characters that the serial number will be copied into
buffer_length(Input) The number of values to copy into the buffer (this should be no larger than the number of chars allocated in the buffer)
Returns
the number of bytes written into the buffer
DLL_DECL int sbapi_optical_bench_get_serial_number ( long  deviceID,
long  featureID,
int *  error_code,
char *  buffer,
int  buffer_length 
)

This reads the optical bench Serial Number and fills the provided array (up to the given length) with it.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
opticalBenchFeatureID(Input) The ID of a particular instance of a serial number feature. Valid IDs can be found with the sbapi_get_optical_bench_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
buffer(Output) A pre-allocated array of characters that the serial number will be copied into
buffer_length(Input) The number of values to copy into the buffer (this should be no larger than the number of chars allocated in the buffer)
Returns
the number of bytes written into the buffer
DLL_DECL int sbapi_optical_bench_get_coating ( long  deviceID,
long  featureID,
int *  error_code,
char *  buffer,
int  buffer_length 
)

This reads the optical bench Coating and fills the provided array (up to the given length) with it.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
opticalBenchFeatureID(Input) The ID of a particular instance of a serial number feature. Valid IDs can be found with the sbapi_get_optical_bench_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
buffer(Output) A pre-allocated array of characters that the serial number will be copied into
buffer_length(Input) The number of values to copy into the buffer (this should be no larger than the number of chars allocated in the buffer)
Returns
the number of bytes written into the buffer
DLL_DECL int sbapi_optical_bench_get_filter ( long  deviceID,
long  featureID,
int *  error_code,
char *  buffer,
int  buffer_length 
)

This reads the optical bench filter and fills the provided array (up to the given length) with it.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
opticalBenchFeatureID(Input) The ID of a particular instance of a serial number feature. Valid IDs can be found with the sbapi_get_optical_bench_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
buffer(Output) A pre-allocated array of characters that the serial number will be copied into
buffer_length(Input) The number of values to copy into the buffer (this should be no larger than the number of chars allocated in the buffer)
Returns
the number of bytes written into the buffer
DLL_DECL int sbapi_optical_bench_get_grating ( long  deviceID,
long  featureID,
int *  error_code,
char *  buffer,
int  buffer_length 
)

This reads the optical bench grating and fills the provided array (up to the given length) with it.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
opticalBenchFeatureID(Input) The ID of a particular instance of a serial number feature. Valid IDs can be found with the sbapi_get_optical_bench_features() function.
error_code(Output) pointer to an integer that can be used for storing error codes.
buffer(Output) A pre-allocated array of characters that the serial number will be copied into
buffer_length(Input) The number of values to copy into the buffer (this should be no larger than the number of chars allocated in the buffer)
Returns
the number of bytes written into the buffer
DLL_DECL int sbapi_get_number_of_stray_light_coeffs_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of stray light coefficient feature instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of features that will be returned by a call to sbapi_get_stray_light_coeffs_features().
DLL_DECL int sbapi_get_stray_light_coeffs_features ( long  deviceID,
int *  error_code,
long *  features,
int  max_features 
)

This function returns IDs for accessing each stray light coefficient feature instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) preallocated buffer to hold returned feature handles
max_features(Input) size of preallocated buffer
Returns
the number of stray light coefficient feature IDs that were copied.
DLL_DECL int sbapi_stray_light_coeffs_get ( long  deviceID,
long  featureID,
int *  error_code,
double *  buffer,
int  max_length 
)

This function reads out stray light coefficients from the device's internal memory if that feature is supported.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a stray light coefficient feature. Valid IDs can be found with the sbapi_get_stray_light_coeffs_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
buffer(Output) preallocated buffer to store stray light coefficients
max_length(Input) size of preallocated buffer
Returns
the number of doubles read from the device into the buffer
DLL_DECL int sbapi_get_number_of_data_buffer_features ( long  deviceID,
int *  error_code 
)

This function returns the total number of data buffer feature instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of features that will be returned by a call to sbapi_get_data_buffer_features().
DLL_DECL int sbapi_get_data_buffer_features ( long  deviceID,
int *  error_code,
long *  buffer,
unsigned int  maxLength 
)

This function returns IDs for accessing each data buffer feature instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) preallocated buffer to hold returned feature handles
max_features(Input) size of preallocated buffer
Returns
the number of data buffer feature IDs that were copied.
DLL_DECL void sbapi_data_buffer_clear ( long  deviceID,
long  featureID,
int *  error_code 
)

Clear the data buffer.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
DLL_DECL unsigned long sbapi_data_buffer_get_number_of_elements ( long  deviceID,
long  featureID,
int *  error_code 
)

Get the number of data elements currently in the buffer.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
A count of how many items are available for retrieval from the buffer
DLL_DECL unsigned long sbapi_data_buffer_get_buffer_capacity ( long  deviceID,
long  featureID,
int *  error_code 
)

Get the present limit of how many data elements will be retained by the buffer. This value can be changed with sbapi_data_buffer_set_buffer_capacity().

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
A count of how many items the buffer will store before data may be lost
DLL_DECL unsigned long sbapi_data_buffer_get_buffer_capacity_maximum ( long  deviceID,
long  featureID,
int *  error_code 
)

Get the maximum possible configurable size for the data buffer.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
The largest value that may be set with sbapi_data_buffer_set_buffer_capacity().
DLL_DECL unsigned long sbapi_data_buffer_get_buffer_capacity_minimum ( long  deviceID,
long  featureID,
int *  error_code 
)

Get the minimum possible configurable size for the data buffer.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
The smallest value that may be set with sbapi_data_buffer_set_buffer_capacity().
DLL_DECL void sbapi_data_buffer_set_buffer_capacity ( long  deviceID,
long  featureID,
int *  error_code,
unsigned long  capacity 
)

Set the number of data elements that the buffer should retain.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
capacity(Input) Limit on the number of data elements to store. This is bounded by what is returned by sbapi_data_buffer_get_buffer_capacity_minimum() and sbapi_data_buffer_get_buffer_capacity_maximum().
DLL_DECL int sbapi_get_number_of_acquisition_delay_features ( long  deviceID,
int *  errorCode 
)

This function returns the total number of acquisition delay feature instances available in the indicated device.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
the number of features that will be returned by a call to sbapi_get_data_buffer_features().
DLL_DECL int sbapi_get_acquisition_delay_features ( long  deviceID,
int *  errorCode,
long *  buffer,
unsigned int  maxLength 
)

This function returns IDs for accessing each data buffer feature instance for this device. The IDs are only valid when used with the deviceID used to obtain them.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
error_code(Output) A pointer to an integer that can be used for storing error codes.
features(Output) preallocated buffer to hold returned feature handles
max_features(Input) size of preallocated buffer
Returns
the number of data buffer feature IDs that were copied.
DLL_DECL void sbapi_acquisition_delay_set_delay_microseconds ( long  deviceID,
long  featureID,
int *  errorCode,
unsigned long  delay_usec 
)

Set the acquisition delay in microseconds. This may also be referred to as the trigger delay. In any event, it is the time between some event (such as a request for data, or an external trigger pulse) and when data acquisition begins.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
delay_usec(Input) The new delay to use in microseconds
DLL_DECL unsigned long sbapi_acquisition_delay_get_delay_microseconds ( long  deviceID,
long  featureID,
int *  errorCode 
)

Get the acquisition delay in microseconds. This may also be referred to as the trigger delay. In any event, it is the time between some event (such as a request for data, or an external trigger pulse) and when data acquisition begins.

Note that not all devices support reading this value back. In these cases, the returned value will be the last value sent to sbapi_acquisition_delay_set_delay_microseconds(). If no value has been set and the value cannot be read back, this function will indicate an error.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
The acquisition delay in microseconds
DLL_DECL unsigned long sbapi_acquisition_delay_get_delay_increment_microseconds ( long  deviceID,
long  featureID,
int *  errorCode 
)

Get the allowed step size for the acquisition delay in microseconds.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
The acquisition delay step size in microseconds
DLL_DECL unsigned long sbapi_acquisition_delay_get_delay_maximum_microseconds ( long  deviceID,
long  featureID,
int *  errorCode 
)

Get the maximum allowed acquisition delay in microseconds.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
The maximum acquisition delay in microseconds
DLL_DECL unsigned long sbapi_acquisition_delay_get_delay_minimum_microseconds ( long  deviceID,
long  featureID,
int *  errorCode 
)

Get the minimum allowed acquisition delay in microseconds.

Parameters
deviceID(Input) The index of a device previously opened with sbapi_open_device().
featureID(Input) The ID of a particular instance of a data buffer feature. Valid IDs can be found with the sbapi_get_data_buffer_features() function.
error_code(Output) A pointer to an integer that can be used for storing error codes.
Returns
The minimum acquisition delay in microseconds