NativeUSB.h

Go to the documentation of this file.

/***************************************************/
#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 */