com.embeddedunveiled.serial.usb

Class SerialComUSBHID

java.lang.Object

com.embeddedunveiled.serial.hid.SerialComHIDTransport

com.embeddedunveiled.serial.usb.SerialComUSBHID

public final class SerialComUSBHID
extends SerialComHIDTransport

Provides methods to communicate with USB HID devices.

A USB HID device should have standard device descriptor, standard configuration descriptor, standard interface descriptor for the HID class, class specific HID descriptor, standard endpoint descriptor for Interrupt IN endpoint and class specific report descriptor.

Author:

Rishi Gupta

Field Summary

Fields inherited from class com.embeddedunveiled.serial.hid.SerialComHIDTransport

mHIDJNIBridge, osType

Constructor Summary

Constructors

Constructor and Description
SerialComUSBHID(SerialComHIDJNIBridge mHIDJNIBridge, int osType) Construct and allocates a new SerialComUSBHID object with given details.

Method Summary

Methods

Modifier and Type	Method and Description
SerialComHIDdevice[]	listUSBHIDdevicesWithInfo(int vendorFilter) Returns an array of SerialComHIDdevice objects containing information about USB-HID devices as found by this library.
long	openHidDeviceByUSBAttributes(int usbVidToMatch, int usbPidToMatch, String serialNumber, int locationID, int usbBusNumber, int usbDevNumber) Opens a HID device for communication using the given USB attributes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SerialComUSBHID

public SerialComUSBHID(SerialComHIDJNIBridge mHIDJNIBridge,
               int osType)

Construct and allocates a new SerialComUSBHID object with given details.

Parameters:

mHIDJNIBridge - interface class to native library for calling platform specific routines.

osType - operating system this library is running on.

Method Detail

listUSBHIDdevicesWithInfo

public SerialComHIDdevice[] listUSBHIDdevicesWithInfo(int vendorFilter)
                                               throws SerialComException

Returns an array of SerialComHIDdevice objects containing information about USB-HID devices as found by this library. Application can call various methods on returned SerialComHIDdevice object to get specific information like vendor id and product id etc.

The information about HID device returned includes, transport, vendor ID, product ID, serial number, product, manufacturer, location etc. In situations where two or more devices with exactly same vendor ID, product ID and serial number are present into system, information like location can be used to further categories them into unique devices. Application can also use some custom protocol to identify devices that are of interest to them.

[1] Some bluetooth HID keyboard and mouse use a USB dongle which make them appear as USB HID device to system. The keyboard/mouse communicate with dongle over bluetooth frequency while dongle communicate with computer as USB HID device. This is also the reason why sometimes bluetooth keyboard/mouse works even when there is no bluetooth stack installed in system.

Parameters:

vendorFilter - vendor whose devices should be listed (one of the constants SerialComUSB.V_xxxxx or any valid USB-IF VID).

Returns:

list of the HID devices with information about them or empty array if no device matching given criteria found.

Throws:

SerialComException - if an I/O error occurs.

IllegalArgumentException - if vendorFilter is negative or invalid number.

openHidDeviceByUSBAttributes

public long openHidDeviceByUSBAttributes(int usbVidToMatch,
                                int usbPidToMatch,
                                String serialNumber,
                                int locationID,
                                int usbBusNumber,
                                int usbDevNumber)
                                  throws SerialComException

Opens a HID device for communication using the given USB attributes. If two or more devices have same USB vendor ID, USB product ID and serial number, then location ID, USB bus number and device number can be used to further reduce the scope of the device to be opened. Information about devices attached to system can be obtained by listing them.

Parameters:

usbVidToMatch - USB vendor ID to match. It must be supplied and must be valid.

usbPidToMatch - USB product ID to match. It must be supplied and must be valid.

serialNumber - USB device serial number to match (case insensitive) or null if matching is not required (optional).

locationID - location ID to match (OS assigned location ID to this device) or -1 if matching is not required (optional).

usbBusNumber - USB bus number to match (USB device should be found on this bus) or -1 if matching is not required (optional).

usbDevNumber - USB device number to match (device number assigned by OS) or -1 if matching is not required (optional).

Throws:

SerialComException - if an I/O error occurs.

IllegalArgumentException - if usbVidToMatch or usbPidToMatch is negative or or invalid number.

See Also:

listUSBHIDdevicesWithInfo(int)