227 lines
8.3 KiB
C
227 lines
8.3 KiB
C
/***************************************************//**
|
|
* @file NativeUSB.h
|
|
* @date October 31, 2007
|
|
* @author Ocean Optics, Inc.
|
|
*
|
|
* This provides a relatively simple interface for
|
|
* opening, closing, writing to, and reading from Ocean
|
|
* Optics USB Devices. It has been extended to provide
|
|
* more complete USB functionality at least for Linux,
|
|
* and equivalent functionality should be brought back
|
|
* in for Windows and MacOSX.
|
|
*
|
|
* 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 NATIVEUSB_H
|
|
#define NATIVEUSB_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif /* cplusplus */
|
|
|
|
#define OPEN_OK 0
|
|
#define NO_DEVICE_FOUND -1
|
|
#define NO_DEVICE_MATCH -2
|
|
#define CLAIM_INTERFACE_FAILED -3
|
|
#define CLOSE_OK 0
|
|
#define CLOSE_ERROR -1
|
|
#define WRITE_FAILED -1
|
|
#define READ_FAILED -1
|
|
#define ABORT_OK 0
|
|
#define ABORT_FAILED -1
|
|
#define RESET_OK 0
|
|
#define RESET_FAILED -1
|
|
|
|
struct USBConfigurationDescriptor {
|
|
unsigned char bLength;
|
|
unsigned char bDescriptorType;
|
|
unsigned short wTotalLength;
|
|
unsigned char bNumInterfaces;
|
|
unsigned char bConfigurationValue;
|
|
unsigned char iConfiguration;
|
|
unsigned char bmAttributes;
|
|
unsigned char MaxPower;
|
|
};
|
|
|
|
struct USBDeviceDescriptor {
|
|
unsigned char bLength;
|
|
unsigned char bDescriptorType;
|
|
unsigned short bcdUSB;
|
|
unsigned char bDeviceClass;
|
|
unsigned char bDeviceSubClass;
|
|
unsigned char bDeviceProtocol;
|
|
unsigned char bMaxPacketSize0;
|
|
unsigned short idVendor;
|
|
unsigned short idProduct;
|
|
unsigned short bcdDevice;
|
|
unsigned char iManufacturer;
|
|
unsigned char iProduct;
|
|
unsigned char iSerialNumber;
|
|
unsigned char bNumConfigurations;
|
|
};
|
|
|
|
struct USBInterfaceDescriptor {
|
|
unsigned char bLength;
|
|
unsigned char bDescriptorType;
|
|
unsigned char bInterfaceNumber;
|
|
unsigned char bAlternateSetting;
|
|
unsigned char bNumEndpoints;
|
|
unsigned char bInterfaceClass;
|
|
unsigned char bInterfaceSubClass;
|
|
unsigned char bInterfaceProtocol;
|
|
unsigned char iInterface;
|
|
};
|
|
|
|
struct USBEndpointDescriptor {
|
|
unsigned char bLength;
|
|
unsigned char bDescriptorType;
|
|
unsigned char bEndpointAddress;
|
|
unsigned char bmAttributes;
|
|
unsigned short wMaxPacketSize;
|
|
unsigned char bInterval;
|
|
};
|
|
|
|
//------------------------------------------------------------------------------
|
|
// This function attempts to discover all devices with the given product
|
|
// and vendor IDs. Descriptors for each found device will be placed in the
|
|
// provided long buffer.
|
|
//
|
|
// PARAMETERS:
|
|
// vendorID: The vendor ID to match with devices on the bus
|
|
// productID: The product ID to match with devices on the bus
|
|
// output: A buffer of longs that will be populated with unique IDs for each
|
|
// device found that matches the VID and PID
|
|
// max_devices: A limit on how many IDs can be put into the output buffer
|
|
//
|
|
// RETURN VALUE:
|
|
// The number of devices successfully found, or -1 if there was an error.
|
|
int
|
|
USBProbeDevices(int vendorID, int productID, unsigned long *output,
|
|
int max_devices);
|
|
|
|
//------------------------------------------------------------------------------
|
|
// This function attempts to open a device with the given product and vendor
|
|
// ID's at the specified index.
|
|
//
|
|
// PARAMETERS:
|
|
// deviceID: The ID of a device that has been provided by probeDevices().
|
|
// errorCode: A pointer to an integer that will be set to an error code of
|
|
// either NO_DEVICE_FOUND or NO_DEVICE_MATCH if an error occured
|
|
// while trying to open the device or OPEN_OK if the device was
|
|
// found and opened.
|
|
//
|
|
// RETURN VALUE:
|
|
// Returns a void pointer which equals a handle to the device if the device was
|
|
// found and opened successfully, or NULL if the device was not opened
|
|
// successfully. The value of the 'errorCode' parameter should be checked
|
|
// against the following before using the handle:
|
|
// - NO_DEVICE_FOUND signifying that no device was found with the specified ID
|
|
// or that the device with the specified ID could not be opened
|
|
//------------------------------------------------------------------------------
|
|
void *
|
|
USBOpen(unsigned long deviceID, int *errorCode);
|
|
|
|
//------------------------------------------------------------------------------
|
|
// This function attempts to close the device attached to the given handle.
|
|
//
|
|
// PARAMETERS:
|
|
// handle: The device handle obtained via the open() function.
|
|
//
|
|
// RETURN VALUE:
|
|
// Returns an integer which will be equal to either:
|
|
// - CLOSE_OK if the device was closed successfully
|
|
// - CLOSE_ERROR if some error occured
|
|
//------------------------------------------------------------------------------
|
|
int
|
|
USBClose(void *handle);
|
|
|
|
//------------------------------------------------------------------------------
|
|
// This function writes the given data to the device attached to the given
|
|
// handle.
|
|
//
|
|
// PARAMETERS:
|
|
// handle: The device handle obtained via the open() function.
|
|
// endpoint: The endpoint on the device to write the data to.
|
|
// data: A pointer to the dynamically allocated byte array of data to be written
|
|
// size: The number of bytes to be written
|
|
//
|
|
// RETURN VALUE:
|
|
// Returns an integer which will be equal to either:
|
|
// - The number of bytes written to the endpoint if the write was successful
|
|
// - WRITE_FAILED if the data was not written to the device
|
|
//------------------------------------------------------------------------------
|
|
int
|
|
USBWrite(void *handle, unsigned char endpoint, char * data, int numberOfBytes);
|
|
|
|
//------------------------------------------------------------------------------
|
|
// This function reads data from the device attached to the given handle into
|
|
// the specified byte array.
|
|
//
|
|
// PARAMETERS:
|
|
// handle: The device handle obtained via the open() function.
|
|
// endpoint: The endpoint on the device to read the data from.
|
|
// data: A pointer to the dynamically allocated byte array to store the data.
|
|
// size: The number of bytes to be read.
|
|
//
|
|
// RETURN VALUE:
|
|
// Returns an integer which will be equal to either:
|
|
// - The number of bytes read from the endpoint if the read was successful
|
|
// - READ_FAILED if the data was not successfully read from the device
|
|
//------------------------------------------------------------------------------
|
|
int
|
|
USBRead(void *handle, unsigned char endpoint, char * data, int numberOfBytes);
|
|
|
|
//------------------------------------------------------------------------------
|
|
// This function attempts to clear any stall on the given endpoint.
|
|
//
|
|
// PARAMETERS:
|
|
// handle: The device handle obtained via the open() function.
|
|
// endpoint: The endpoint on the device to clear a stall condition on.
|
|
//
|
|
// RETURN VALUE:
|
|
// No value is returned (void).
|
|
//------------------------------------------------------------------------------
|
|
void
|
|
USBClearStall(void *handle, unsigned char endpoint);
|
|
|
|
int
|
|
USBGetDeviceDescriptor(void *handle, struct USBDeviceDescriptor *desc);
|
|
|
|
int
|
|
USBGetInterfaceDescriptor(void *handle, struct USBInterfaceDescriptor *desc);
|
|
|
|
int
|
|
USBGetEndpointDescriptor(void *handle, int endpoint_index, struct USBEndpointDescriptor *desc);
|
|
|
|
int
|
|
USBGetStringDescriptor(void *handle, unsigned int string_index, char *buffer, int maxLength);
|
|
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* _cplusplus */
|
|
|
|
#endif /* NATIVEUSB_H */
|