TowerOptoSifAndSpectral/othersoft/shuttercali/source/OSIF/include/api/SeaBreezeWrapper.h

/***************************************************//**
 * @file    SeaBreezeWrapper.h
 * @date    July 2009
 * @author  Ocean Optics, Inc.
 *
 * This is a trivial interface to SeaBreeze that allows
 * the user to connect to devices over USB.
 * 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.
 *******************************************************/

#ifndef SEABREEZE_WRAPPER_H
#define SEABREEZE_WRAPPER_H

#define SEABREEZE_API_VERSION "3.0.11"  //!< current version of the SeaBreezeWrapper API
#define SEABREEZE_MAX_DEVICES 32        //!< how many different spectrometer types we support

#include "api/DllDecl.h"

#ifdef __cplusplus

/**
* @brief Encapsulates all SeaBreeze classes
*/
namespace seabreeze {
	class Device;
}

/**
    Original interface to SeaBreeze.  SeaBreezeAPI represents a proposed architecture for
    future development.
*/
class DLL_DECL SeaBreezeWrapper {
public:

    //! get handle to Singleton
    static SeaBreezeWrapper *getInstance();

    //! free some static memory under Microsoft profiler
    static void shutdown();

    // lifecycle
    int    openSpectrometer          (int index, int *errorCode);
    int    closeSpectrometer         (int index, int *errorCode);

    // metadata
    int    getModel                  (int index, int *errorCode, char *buf, int len);
    int    getSerialNumber           (int index, int *errorCode, char *buf, int len);

    // basic acquisitions
    void   setIntegrationTimeMicrosec(int index, int *errorCode, unsigned long integration_time_micros);
    int    getWavelengths            (int index, int *errorCode, double *wavelengths, int length);
    int    getFormattedSpectrum      (int index, int *errorCode, double* buffer, int buffer_length);
    int    getUnformattedSpectrum    (int index, int *errorCode, unsigned char *buffer, int buffer_length);
    int    getFormattedSpectrumLength(int index, int *errorCode);
    int    getUnformattedSpectrumLength(int index, int *errorCode);
    long   getMinIntegrationTimeMicrosec(int index, int *errorCode);
    long   getMaxIntegrationTimeMicrosec(int index, int *errorCode);
    int    getMaximumIntensity(int index, int *errorCode);

    // advanced features
    int    getElectricDarkPixelIndices(int index, int *errorCode, int *indices, int length);
    void   setTriggerMode            (int index, int *errorCode, int mode);
    void   setStrobeEnable           (int index, int *errorCode, unsigned char strobe_enable);
    void   setShutterOpen            (int index, int *errorCode, unsigned char opened);
    void   setContinuousStrobePeriodMicrosec(int index, int *errorCode, unsigned short strobe_id, unsigned long period_usec);
    void   setAcquisitionDelayMicrosec(int index, int *errorCode, unsigned long delay_usec);

    // Buffering features
    void   clearBuffer               (int index, int *errorCode);
    unsigned long getBufferElementCount(int index, int *errorCode);
    unsigned long getBufferCapacity  (int index, int *errorCode);
    unsigned long getBufferCapacityMaximum(int index, int *errorCode);
    unsigned long getBufferCapacityMinimum(int index, int *errorCode);
    void   setBufferCapacity         (int index, int *errorCode, unsigned long capacity);

    // EEPROM access
    int    readEEPROMSlot            (int index, int *errorCode, int slot_number, unsigned char *buffer, int buffer_length);
    int    writeEEPROMSlot           (int index, int *errorCode, int slot_number, unsigned char *buffer, int buffer_length);

    // irradiance calibration
    int    readIrradCalibration      (int index, int *errorCode, float *buffer, int buffer_length);
    int    writeIrradCalibration     (int index, int *errorCode, float *buffer, int buffer_length);
    int    hasIrradCollectionArea    (int index, int *errorCode);
    float  readIrradCollectionArea   (int index, int *errorCode);
    void   writeIrradCollectionArea  (int index, int *errorCode, float area);

    // thermal-electric cooler
    double readTECTemperature        (int index, int *errorCode);
    void   setTECTemperature         (int index, int *errorCode, double temperature_degrees_celsius);
    void   setTECEnable              (int index, int *errorCode, unsigned char tec_enable);
    void   setTECFanEnable           (int index, int *errorCode, unsigned char tec_fan_enable);

    // Wrapper features
    void   setVerbose                (bool flag);
    void   setLogfile                (char *path, int length);
    int    getAPIVersionString       (char *buffer, int length);
    int    getErrorString            (int errorCode, char *buffer, int buffer_length);

    // raw USB access
    int    writeUSB                  (int index, int *errorCode, unsigned char endpoint, unsigned char *buffer, unsigned int length);
    int    readUSB                   (int index, int *errorCode, unsigned char endpoint, unsigned char *buffer, unsigned int length);
    int    getUSBDescriptorString    (int index, int *errorCode, int id, unsigned char *buffer, int length);

    // light sources (JAZ?)
    int    getLightSourceCount       (int index, int *errorCode);
    void   setLightSourceEnable      (int index, int *errorCode, int lightIndex, unsigned char enable);
    void   setLightSourceIntensity   (int index, int *errorCode, int lightIndex, double intensity);

private:
    SeaBreezeWrapper();
    virtual ~SeaBreezeWrapper();

    //! Singleton
    static SeaBreezeWrapper *instance;

    //! types of supported Ocean Optics devices (not actual devices found enumerated on the USB bus)
    seabreeze::Device *devices[SEABREEZE_MAX_DEVICES];
};

extern "C" {
#endif /* __cplusplus */

    /* All of these C functions start with seabreeze_ to prevent namespace
     * collisions.
     */

    /**
     * @brief This function opens a device attached to the system.
     * @param index (Input) The index of a USB device to try to open.
     *        Valid values will range from 0 to N-1 for N connected devices.
     * @param error_code (Output) A pointer to an integer that can be used
     *        for storing error codes.
     * @return int: The function will return an integer of 0 if it opened a
     *      device successfully, or 1 if no device was opened (in which
     *      case the error_code variable will be set).
     *
     * This can be called repeatedly with incrementing index values (until
     * it returns 1) to open all connected devices.
     *
     * Note that the index used to open a device with this function should also
     * be used to communicate with that same device in the other functions
     * provided here.
     */
    DLL_DECL int
    seabreeze_open_spectrometer(int index, int *error_code);

    /**
     * @brief This function closes the spectrometer attached to the system.
     * @param index (Input) The index of a device previously opened with
     *        open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used
     *        for storing error codes.
     * @return int: This function will return 1 no matter what!  (MZ)
     */
    DLL_DECL int
    seabreeze_close_spectrometer(int index, int *error_code);

    /**
     * @brief This function returns a description of the error denoted by
     *        error_code.
     * @param error_code (Input) The integer error code to look up.  Error
     *        codes not be zero, but can be any non-zero integer (positive or
     *        negative).
     * @param buffer (Output) A character buffer allocated to contain at least
     *        'buffer_length' bytes, which will be populated with the string
     *        description of the given error code.
     * @param buffer_length (Input) allocated size of the output buffer
     * @return int: Number of bytes written to buffer.
     */
    DLL_DECL int
    seabreeze_get_error_string(int error_code, char *buffer, int buffer_length);

    /**
     * @brief This function returns a string denoting the type of the device.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *      error codes.  This may be NULL.
     * @param buffer (Output)  A character buffer allocated to contain at least
     *      'buffer_length' bytes, which will be populated with the
     *      spectrometer type.
     * @param buffer_length (Input) allocated size of the buffer
     * @return int: Number of bytes written to the buffer.
     *
     * The populated buffer will hold one of the following strings:
     *
     * \verbatim
     *      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
     *      MAYALSL:     Represents a Maya-LSL Spectrometer
     *      MAYA2000PRO: Represents a Maya2000 Pro Spectrometer
     *      NIRQUEST256: Represents an NIRQuest256 Spectrometer
     *      NIRQUEST512: Represents an NIRQuest512 Spectrometer
     *      QE65000:     Represents a QE65000 Spectrometer
     *      QE-PRO:      Represents a QE-Pro 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
     * \endverbatim
     */
    DLL_DECL int
    seabreeze_get_model(int index, int *error_code, char *buffer, int buffer_length);

    /**
     * @brief This function sets the trigger mode for the specified device.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *      error codes.
     * @param mode (Input) a trigger mode (0 = normal, 1 = software, 2 = synchronization,
     *        3 = external hardware, etc.)
     *
     * Note that requesting an unsupported mode will result in an error.
     */

    DLL_DECL void
    seabreeze_set_trigger_mode(int index, int *error_code, int mode);

    /**
     * @brief This function sets the integration time for the specified device.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *      error codes.
     * @param integration_time_micros (Input) The new integration time in units of
     *      microseconds
     *
     * This function does not automatically perform a stability scan.
     * If your application requires a stability scan following a change
     * in integration time, you need to command that yourself.
     */
    DLL_DECL void
    seabreeze_set_integration_time_microsec(int index, int *error_code,
            unsigned long integration_time_micros);

    /**
     * @brief This function returns the smallest integration time setting,
     *        in microseconds, that is valid for the spectrometer.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @return Returns minimum legal integration time in microseconds if > 0.
     *        On error, returns -1 and error_code will be set accordingly.
     */
    DLL_DECL long
    seabreeze_get_min_integration_time_microsec(int index, int *error_code);

    /**
     * @brief This function sets the shutter state on the spectrometer.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param opened (Input) A logical 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 void
    seabreeze_set_shutter_open(int index, int *error_code, unsigned char opened);

    /**
     * @brief This function sets the strobe enable on the spectrometer.  Note that
     *        this refers to a particular set of one or more digital pins on the
     *        device: lamp enable, single strobe, and continuous strobe may all
     *        be affected by this setting, and these generally control lamps
     *        that are external to the device.  Note that this is related to, but
     *        different from, the light source interface which allows the intensity
     *        and/or enable status of individual light sources (e.g. lamp bulbs,
     *        LEDs, or lasers) in attached modules to be controlled.  Refer to
     *        the seabreeze_xxx_light_source_ functions for finer control of
     *        certain light source modules that are more closely integrated with
     *        the spectrometer.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output)  A pointer to an integer that can be used for storing
     *        error codes.
     * @param strobe_enable (Input) A logical boolean 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 void
    seabreeze_set_strobe_enable(int index, int *error_code, unsigned char strobe_enable);

    /**
     * @brief This function gets the number of attached light sources that can
     *        be programmatically controlled.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output)  A pointer to an integer that can be used for storing
     *        error codes.
     * @return The number of light sources that can be controlled
     */
    DLL_DECL int
    seabreeze_get_light_source_count(int index, int *error_code);

    /**
     * @brief This function sets the enable status on a connected light source.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output)  A pointer to an integer that can be used for storing
     *        error codes.
     * @param light_index (Input)  The index of the light source.  This will
     *      usually be zero, but if the light module contains multiple LEDs,
     *      bulbs, lasers, etc. then this may be higher.  Use
     *      seabreeze_get_light_source_count() to bound the maximum value .
     * @param enable (Input) A logical boolean used for denoting whether to enable
     *      the indicated light source.   If the value of
     *      enable is zero, then the light source should be disabled.  If the value
     *      of enable is non-zero, then the light source should be enabled.
     */
    DLL_DECL void
    seabreeze_set_light_source_enable(int index, int *error_code,
            int light_index, unsigned char enable);

    /**
     * @brief This function sets the intensity of a connected light source.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output)  A pointer to an integer that can be used for storing
     *        error codes.
     * @param light_index (Input)  The index of the light source.  This will
     *      usually be zero, but if the light module contains multiple LEDs,
     *      bulbs, lasers, etc. then this may be higher.  Use
     *      seabreeze_get_light_source_count() to bound the maximum value.
     * @param intensity (Input) The desired intensity of the light source.  The
     *      range of intensities is normalized over [0, 1], where 0 is the
     *      minimum controllable intensity of the light source, and 1 is the
     *      maximum.
     *
     * @warning SETTING THE INTENSITY TO ZERO MAY NOT CAUSE THE LIGHT SOURCE
     *      TO TURN OFF COMPLETELY.  The light source will go to the
     *      dimmest level it can reach without changing its enable status.
     *      To switch the light source off, try using the
     *      seabreeze_set_light_source_enable() function or provide the
     *      operator with another way to disable or block the light source.
     */
    DLL_DECL void
    seabreeze_set_light_source_intensity(int index, int *error_code,
            int light_index, double intensity);

    /**
     * @brief This function reads a string out of the spectrometer's EEPROM slot
     *        and returns the result.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param slot_number (Input) The number of the slot to read out.  Possible
     *        values are 0 through 16*.
     * @param buffer (Output)  A buffer (with memory already allocated) to hold the
     *        value read out of the EEPROM slot
     * @param buffer_length (Input) The length of the allocated output buffer (typically 16)
     * @return int: The number of bytes read from the EEPROM slot into the buffer
     *
     * (*) Actual maximum slot count varies by spectrometer model.  For the number of supported
     *     slots on your spectrometer, see EEPROMSlotFeature instantiation in appropriate
     *     device file under src/vendors/OceanOptics/devices.
     */
    DLL_DECL int
    seabreeze_read_eeprom_slot(int index, int *error_code, int slot_number, unsigned char *buffer,
            int buffer_length);

    /**
     * @brief This function writes a string to a spectrometer's EEPROM slot
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer for storing error codes.
     * @param slot_number (Input) The number of the slot being written (e.g. 0-16*).
     * @param buffer (Input) A buffer containing the text to write to the slot.
     * @param buffer_length (Input) The length of the text to write (typically 15)
     * @return number of bytes written
     *
     * @warning CARELESS USE OF THIS FUNCTION CAN RENDER YOUR SPECTROMETER INOPERABLE,
     *          POSSIBLY REQUIRING R.M.A. OR REFLASHING TO RESTORE FUNCTIONALITY.
     *          PLEASE READ YOUR SPECTROMETER'S DATA SHEET CAREFULLY BEFORE USE.
     *
     * (*) See note in seabreeze_read_eeprom_slot() regarding per-device slot limits.
     */
    DLL_DECL int
    seabreeze_write_eeprom_slot(int index, int *error_code, int slot_number, unsigned char *buffer,
            int buffer_length);

    /**
     * @brief This function reads out an irradiance calibration from the spectrometer's
     *        internal memory if that feature is supported.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param buffer (Output) array of floating point values into which calibration values are stored
     * @param buffer_length (Input) maximum number of values to copy from the device into buffer
     * @return int: the number of floats read from the device into the buffer
     */
    DLL_DECL int
    seabreeze_read_irrad_calibration(int index, int *error_code, float *buffer,
        int buffer_length);

    /**
     * @brief This function writes an irradiance calibration to the spectrometer's
     *        internal memory if that feature is supported.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param buffer (Output) array of floating point values to store into the device
     * @param buffer_length (Input) number of calibration factors to write
     * @return int: the number of floats written from the buffer to the device
     */
    DLL_DECL int
    seabreeze_write_irrad_calibration(int index, int *error_code, float *buffer,
        int buffer_length);

    /**
     * @brief This function checks for an irradiance collection area in the spectrometer's
     *        internal memory if that feature is supported.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @return int: 0 if no collection area available, 1 if available.
     */
    DLL_DECL int
    seabreeze_has_irrad_collection_area(int index, int *error_code);

    /**
     * @brief This function reads an irradiance collection area from the spectrometer's
     *        internal memory if that feature is supported.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @return float: collection area (typically in units of cm^2) read from device
     */
    DLL_DECL float
    seabreeze_read_irrad_collection_area(int index, int *error_code);

    /**
     * @brief This function writes an irradiance collection area to the spectrometer's
     *        internal memory if that feature is supported.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param area (Input) collection area to save to the EEPROM (presumably cm^2)
     */
    DLL_DECL void
    seabreeze_write_irrad_collection_area(int index, int *error_code, float area);

    /**
     * @brief This function reads the value of the TEC and returns the value in
     *        degrees celsius.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @return int: The TEC temperature in degrees Celsius.
     */
    DLL_DECL double
    seabreeze_read_tec_temperature(int index, int *error_code);

    /**
     * @brief This function sets the TEC temperature.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param temperature_degrees_celsius (Input) The desired temperature, in degrees
     *        Celsius.
     */
    DLL_DECL void
    seabreeze_set_tec_temperature(int index, int *error_code,
            double temperature_degrees_celsius);

    /**
     * @brief This function enables the TEC feature on the spectrometer.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param tec_enable (Input) A logical boolean 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 void
    seabreeze_set_tec_enable(int index, int *error_code, unsigned char tec_enable);

    /**
     * @brief This function enables the TEC Fan on the spectrometer.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param tec_fan_enable (Input) A logical boolean that denotes the desired TEC fan enable
     *        state.  If the value of tec_fan_enable is zero, the TEC fan should be disabled.
     *        If the value of tec_fan_enable is non-zero, the TEC fan should be enabled.
     */
    DLL_DECL void
    seabreeze_set_tec_fan_enable(int index, int *error_code, unsigned char tec_fan_enable);

    /**
     * @brief This acquires a spectrum and returns the answer in raw, unformatted bytes.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param buffer (Output) A buffer (with memory already allocated) to hold the
     *        spectral data
     * @param buffer_length (Input) The length of the buffer in bytes (not pixels)
     * @return int: The number of bytes read into the buffer
     * @see   sample-code/c/demo-unformatted-spectrum.c
     *
     * An unformatted spectrum is the raw sequence of bytes returned by the spectrometer to 
     * the PC over USB.  The bytes have not been broken down into pixels, they're in the 
     * original endianness, absolutely nothing has been done to them.  The caller is expected 
     * to know how many bytes are returned by each spectrometer model, which bytes indicate 
     * synchronization points or whatever, etc.  
     */
    DLL_DECL int
    seabreeze_get_unformatted_spectrum(int index, int *error_code,
            unsigned char *buffer, int buffer_length);

    /**
     * @brief 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.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param buffer (Output) A buffer (with memory already allocated) to hold the
     *        spectral data
     * @param buffer_length (Input) The length of the buffer in floats (not bytes)
     * @return int: The number of floats read into the buffer
     *
     * A formatted spectrum returns exactly one double-precision floating-point IEEE value 
     * per pixel, as opposed to a raw byte stream.  It has also had autonulling (gain control) 
     * applied, meaning it has been scaled up to the spectrometer's full dynamic range using 
     * the gain setting recorded in that spectrometer’s EEPROM.
     */
    DLL_DECL int
    seabreeze_get_formatted_spectrum(int index, int *error_code,
            double* buffer, int buffer_length);

    /**
     * @brief This returns an integer denoting the length of a raw spectrum
     *        (as returned by get_unformatted_spectrum(...)).
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *      error codes.
     * @return int: An integer denoting the length of an unformatted spectrum in bytes
     *
     * The caller is expected to know the number of bytes per pixel and the endian
     * ordering, but it will normally be 2 bytes per pixel, LSB-MSB order.
     */
    DLL_DECL int
    seabreeze_get_unformatted_spectrum_length(int index, int *error_code);

    /**
     * @brief This returns an integer denoting the number of pixels in a
     *        formatted spectrum (as returned by get_formatted_spectrum(...)).
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @return int: An integer denoting the length of a formatted spectrum (in pixels)
     */
    DLL_DECL int
    seabreeze_get_formatted_spectrum_length(int index, int *error_code);

    /**
     * @brief This computes the wavelengths for the spectrometer and fills in the
     *        provided array (up to the given length) with those values.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param wavelengths (Output) A pre-allocated array of doubles into which the
     *        wavelengths will be copied
     * @param 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)
     * @return int: An integer denoting the number of wavelengths written to the buffer
     */
    DLL_DECL int
    seabreeze_get_wavelengths(int index, int *error_code, double *wavelengths, int length);

    /**
     * @brief This reads the device's serial number and fills the
     *        provided array (up to the given length) with it.
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param buffer (Output) A pre-allocated array of characters into which the serial number
     *        will be copied
     * @param 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) (typically 16)
     * @return int: An integer denoting the number of bytes written into the buffer
     *
     * Note that "serial numbers" may include both digits and letters
     */
    DLL_DECL int
    seabreeze_get_serial_number(int index, int *error_code, char *buffer, int buffer_length);

    /**
     * @brief 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).
     * @param index (Input) The index of a device previously opened with open_spectrometer().
     * @param error_code (Output) A pointer to an integer that can be used for storing
     *        error codes.
     * @param indices (Output) A pre-allocated array of ints into which the pixel indices
     *        will be copied
     * @param 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)
     * @return int: An integer denoting the number of indices written into the indices buffer
     *
     * Note that not all detectors have optically masked pixels; in that case,
     * this function will return zero.
     */
    DLL_DECL int
    seabreeze_get_electric_dark_pixel_indices(int index, int *error_code,
        int *indices, int length);

    /**
     * @brief Shutdown SeaBreeze completely, releasing all resources and destroying
     *        any cached device handles.
     *
     * This function is not normally needed (Singletons are destroyed automatically
     * at process end), but calling this explicitly can resolve some spurious warnings
     * in highly paranoid memory leak profilers.
     */
    DLL_DECL void
    seabreeze_shutdown();

    /**
    * @brief Write a raw array of bytes to a USB spectrometer.
    * @param index (Input) index of an opened spectrometer
    * @param errorCode (Output) pointer to an allocated integer field for receiving error codes
    * @param endpoint (Input) USB endpoint for write operation
    *        (see src/vendors/OceanOptics/features/raw_bus_access/RawUSBBusAccessFeature.cpp)
    * @param buffer (Input) array of bytes to send to USB spectrometer
    * @param length (Input) number of bytes to write from buffer to spectrometer
    * @return number of bytes written
    *
    * Write the bytes in the buffer according to the two command bytes at the
    * start of the buffer.
    *
    * \section Endpoints
    *
    * You may wonder why the caller needs to specify an explicit endpoint for
    * raw read and write operations; does not SeaBreeze already know the appro-
    * priate endpoints for any open spectrometer, for example.  Yes it does,
    * but currently there is no easy way to extract endpoints from a generic
    * spectrometer, due to the fact that OOIUSBCypressEndpointMap and
    * OOIUSBSTSEndpointMap do not share a common base class (see
    * OOIUSBEndpointMaps.h).
    *
    * We could attempt to extract them from the TransferHelpers held by
    * OOIUSBInterface, but without a Hint to use as a key, we would likely
    * obtain unmatched or inappropriate versions for control exchanges.
    * As ControlHint and OBPControlHint share no common ancestor or type data
    * to associate them while distinguishing from other hint types, we cannot
    * automatically infer appropriate control endpoints.
    *
    * And finally, we have no way of knowing that the user really wants to
    * use control endpoints anyway: they may actually desire high-speed
    * spectral retrieval.  So really, this needs to remain a manual external
    * operation until such time as we provide a much richer, generic query
    * interface over our internal endpoint lookup tables.
    *
    * \section Example
    *
    * For instance, for most USB spectrometers, the hex values <tt>05 00</tt> in
    * the buffer means 'read EEPROM slot 0'. Writing this command, and following
    * it with the \c seabreeze_read_usb command and the same hex <tt>05 00</tt>
    * in the buffer, will result in the spectrometer's serial number, in ASCII
    * characters, being delivered to the subsequent bytes in the buffer array.
    * This would appear in the output buffer as:
    *
    * \code
    *   05 00 55 53 42 32 2B 48 30 31 34 31 36 00 00 00 00 (hex)
    * \endcode
    *
    * (<tt>USB2+H01416</tt> ASCII, skipping the two command bytes)
    *
    * A C or C++ program could use the data as-is, but a C# program could
    * append to a string, each byte, cast as char, stopping on the first null
    * character:
    *
    * \code
    *   string serial = "";
    *   for (int i = 0; i < length && buffer[i] != '\0'; i++)
    *     serial += (char)buffer[i];
    * \endcode
    *
    * This is equivalent to:
    *
    * \code
    *   string serial = System.Text.ASCIIEncoding.ASCII.GetString(buffer).Trim('\0');
    * \endcode
    *
    * For C# and VB.NET, the trailing zero-fill must be removed. Those null
    * characters would not print or display on a screen but would make a file
    * name invalid.
    */
    DLL_DECL int
    seabreeze_write_usb(int index, int *errorCode, unsigned char endpoint, unsigned char* buffer, unsigned int length);

    /**
    * @brief Read a raw array of bytes from a USB spectrometer.
    * @param index (Input) index of a previously opened spectrometer
    * @param errorCode (Output) pointer to an allocated integer field for receiving error codes
    * @param endpoint (Input) USB endpoint for read operation
    *        (see src/vendors/OceanOptics/features/raw_bus_access/RawUSBBusAccessFeature.cpp)
    * @param buffer (Input) array of allocated bytes at which to recieve USB data
    * @param length (Input) maximum number of bytes to read from spectrometer
    * @return number of received bytes written to buffer
    *
    * Read bytes from the spectrometer into the buffer. The buffer starts with
    * two bytes of command information that will be followed by the transferred
    * bytes. The read and write USB functions allow low-level control of the
    * spectrometer via USB commands. The higher-level SeaBreeze functions issue
    * USB commands internally.
    *
    * Reading USB data takes two steps. First a seabreeze_write_usb call requests
    * the transfer, then a seabreeze_read_usb call delivers the data. Writing a buffer
    * to USB takes one step. The operating system handle for the spectrometer is
    * managed by SeaBreeze. USB has a concept of "end points". These are implicitly
    * addressed by the seabreeze_read_usb and seabreeze_write_usb functions.
    */
    DLL_DECL int
    seabreeze_read_usb(int index, int *errorCode, unsigned char endpoint, unsigned char* buffer, unsigned int length);

    /**
    * @brief Get the SeaBreeze library's internal version identifier.
    * @param buffer (Output) pointer to an allocated character array
    *                        to hold the returned version string
    * @param len    (Input)  size of the allocated buffer
    * @return number of bytes written to buffer
    */
    DLL_DECL int
    seabreeze_get_api_version_string(char *buffer, int len);

    /**
    * @brief Get a USB descriptor string by number
    * @param index     (Input)  Which spectrometer to set
    * @param errorCode (Output) pointer to allocated integer to receive error code
    * @param id        (Input)  numeric ID of the desired USB descriptor string
    * @param buffer    (Output) pointer to an allocated character array to hold
    *                           the returned descriptor string
    * @param len       (Input)  size of the allocated buffer
    * @return number of bytes written to buffer
    */
    DLL_DECL int
    seabreeze_get_usb_descriptor_string(int index, int *errorCode, int id, unsigned char *buffer, int len);

    /**
    * @brief Set the continuous strobe period in microseconds
    * @param index (Input) Which spectrometer to set
    * @param errorCode (Output) pointer to allocated integer to receive error code
    * @param strobe_id (Input) index of the strobe generator (currently always zero)
    * @param period_usec (Input) total period of the strobe, in microseconds
    * @return zero (on success or failure; check errorCode)
    *
    * The resolution is 0.1 milliseconds (100 microseconds).
    */
    DLL_DECL void
    seabreeze_set_continuous_strobe_period_microsec(int index, int *errorCode,
        unsigned short strobe_id, unsigned long period_usec);

    /**
    * @brief Set the acquisition delay (trigger delay) in microseconds.  This
    *        controls the amount of time between a particular event
    *        (usually a request for spectrum or an external trigger pulse)
    *        and the start of acquisition.
    */
    DLL_DECL void
    seabreeze_set_acquisition_delay_microsec(int index,
        int *errorCode, unsigned long delay_usec);

    /**
    * @brief Clear the spectrum buffer (if equipped)
    * @param index (Input) Which spectrometer should have its buffer cleared
    * @param error_code (Output) Pointer to allocated integer to receive error code
    */
    DLL_DECL void
    seabreeze_clear_buffer(int index, int *error_code);

    /**
    * @brief Get the number of spectra presently in the buffer (if equipped)
    * @param index (Input) Which spectrometer should have its buffer queried
    * @param error_code (Output) Pointer to allocated integer to receive error code
    * @return Number of spectra in the buffer
    */
    DLL_DECL unsigned long
    seabreeze_get_buffer_element_count(int index, int *error_code);

    /**
    * @brief Get the currently configured size of the data buffer (if equipped)
    * @param index (Input) Which spectrometer should have its buffer queried
    * @param error_code (Output) Pointer to allocated integer to receive error code
    * @return The present limit on the number of spectra that will be retained.
    */
    DLL_DECL unsigned long
    seabreeze_get_buffer_capacity(int index, int *error_code);

    /**
    * @brief Get the maximum possible configurable size for the data buffer (if equipped)
    * @param index (Input) Which spectrometer should have its buffer queried
    * @param error_code (Output) Pointer to allocated integer to receive error code
    * @return Maximum allowed value for the buffer size
    */
    DLL_DECL unsigned long
    seabreeze_get_buffer_capacity_maximum(int index, int *error_code);

    /**
    * @brief Get the minimum possible configurable size for the data buffer (if equipped)
    * @param index (Input) Which spectrometer should have its buffer queried
    * @param error_code (Output) Pointer to allocated integer to receive error code
    * @return Minimum allowed value for the buffer size
    */
    DLL_DECL unsigned long
    seabreeze_get_buffer_capacity_minimum(int index, int *error_code);

    /**
    * @brief Set the number of spectra that the buffer should keep
    * @param index (Input) Which spectrometer should have its buffer modified
    * @param error_code (Output) Pointer to allocated integer to receive error code
    * @param capacity (Input) Limit on number of spectra to store.
    *        Note that this must be within the range defined by the capacity minimum
    *        and maximum values.
    */
    DLL_DECL void
    seabreeze_set_buffer_capacity(int index, int *error_code, unsigned long capacity);

    /**
    * @brief Programmatically enable debug outputs to stderr
    * @param flag (Input) zero to disable (default), non-zero to enable
    */
    DLL_DECL void
    seabreeze_set_verbose(int flag);

    /**
    * @brief redirect verbose logging to named file
    * @param flag (Input) NULL for default behavior (stderr), non-null for valid OS path
    */
    DLL_DECL void
    seabreeze_set_logfile(char* pathname, int len);

#ifdef __cplusplus
};
#endif /* __cplusplus */

#endif /* SEABREEZE_WRAPPER_H */