usbio.java

usbio Ver 2.40 source code!!! 做USB开发的值得

package de.thesycon.usbio;

import de.thesycon.usbio.structs.*;

/**
 * This class implements the interface to the USBIO device driver.
 * It contains only general device-related functions that can be executed
 * without a pipe context.
 * Pipe specific functions are implemented by the UsbIoPipe class.
 *
 * @author Thesycon
 * @version 2.0
 */
public class UsbIo implements UsbIoErrorCodes, UsbIoInterface, UsbSpec

{


	// internal

	protected HANDLE Handle;

	// UsbIo

	/**
	 * Creates an internal device list.
	 * <p>
	 * The function creates a windows-internal device list that contains all matching interfaces.
	 * The device interface is identified by InterfaceGuid. A handle for the list
	 * is returned in case of success, or 0 is returned in case of error.
	 * The device list can be iterated by means of Open.
	 * <p>
	 * The device list returned must be freed by a call to DestroyDeviceList.
	 * <p>
	 * Note that CreateDeviceList is declared static.
	 * It can be used independently of class instances.
	 *
	 * @param InterfaceGuid This is the predefined interface GUID of the USBIO device driver or a user defined
	 * GUID which must be inserted in the USBIO.INF file.
	 *
	 * @return Returns a handle to the device list if successful, or 0 otherwise.
	 *
     * @see de.thesycon.usbio.UsbIo#open(int, int, String)
     * @see de.thesycon.usbio.UsbIo#destroyDeviceList(int)
	*/
	public static native int createDeviceList(String InterfaceGuid);

	private native int open(HANDLE Handle, int DeviceNumber, int DeviceList, String InterfaceGuid);

	private native void close(HANDLE Handle);

	private native int acquireDevice(HANDLE Handle);

	private native int releaseDevice(HANDLE Handle);

	/**
	 * Destroy the internal device list.
	 * <p>
	 * Use this function to destroy a device list that was generated by a call to CreateDeviceList.
	 * <p>
	 * Note that DestroyDeviceList is declared static.
	 * It can be used independently of class instances.
	 *
	 * @param DeviceList A handle to a device list returned by CreateDeviceList.
	 *
     * @see de.thesycon.usbio.UsbIo#createDeviceList(String)
	*/
	public static native void destroyDeviceList(int DeviceList);

	private native int getDescriptor(HANDLE Handle, byte[] data, int[] bytecount, int Recipient, byte DescriptorType, byte DescriptorIndex, short LanguageId);

	private native int setDescriptor(HANDLE Handle, byte[] data, int[] bytecount, int Recipient, byte DescriptorType, byte DescriptorIndex, short LanguageId);

	private native int getStringDescriptor(HANDLE Handle, byte[] data,int[] bytecount, byte Index, int LanguageId);

	private native int getConfigurationDescriptor(HANDLE Handle, byte[] data,int[] bytecount, byte Index);

	private native int getDeviceDescriptor(HANDLE Handle, byte[] data);

	private native int getDeviceParameters(HANDLE Handle, byte[] data);

	private native int setDeviceParameters(HANDLE Handle, byte[] data);

	private native int getDriverInfo(HANDLE Handle, byte[] data);

	private native int setConfiguration(HANDLE Handle, byte[] data);

	private native int getConfiguration(HANDLE Handle, byte[] data);

	private native int getConfigurationInfo(HANDLE Handle, byte[] data);

	private native int unconfigureDevice(HANDLE Handle);

	private native int getDeviceInfo(HANDLE Handle, byte[] data);

	private native int getInterface(HANDLE Handle, byte[] AlternateSetting, short Interface);

	private native int setInterface(HANDLE Handle, byte[] data);

	private native int clearFeature(HANDLE Handle, int Recipient, short FeatureSelector, short Index);

	private native int setFeature(HANDLE Handle, int Recipient, short FeatureSelector, short Index);

	private native int cyclePort(HANDLE Handle);

	private native int resetDevice(HANDLE Handle);

	private native int getCurrentFrameNumber(HANDLE Handle, int[] FrameNumber);

	private native int getStatus(HANDLE Handle, short[] Status, int Recipient, short Index);

	private native int getDevicePowerState(HANDLE Handle, int[] DevicePowerState);

	private native int setDevicePowerState(HANDLE Handle, int DevicePowerState);

	private native int classOrVendorInRequest(HANDLE Handle, byte[] data, int[] count, byte[] Request);

	private native int classOrVendorOutRequest(HANDLE Handle, byte[] data, int[] count, byte[] Request);

	private native int getBandwidthInfo(HANDLE Handle, byte[] data);

	/**
	 * Translate an USBIO error code to a description string.
	 * <p>
	 * This function supports private USBIO error codes only.
	 * These codes start with a prefix of 0xE.
	 * The function cannot be used to translate general Windows error codes.
	 * <p>
	 * Note that ErrorText is declared static.
	 * It can be used independently of class instances.
	 *
	 * @param ErrorCode The error code to be translated.
	 *
	 * @return The function returns a String with the error text.
	*/
	public static native String errorText(int ErrorCode);

	private native boolean isCheckedBuild(HANDLE Handle);

	private native boolean isDemoVersion(HANDLE Handle);

	private native boolean isLightVersion(HANDLE Handle);

	private native boolean isOperatingAtHighSpeed(HANDLE Handle);

	private native boolean isOpen(HANDLE Handle);


	// load dll

	static {
		System.loadLibrary("USBIOJAVA");
	}

    /**
     * Returns <code>true</code> if the class instance is attached to a device.
     *
     * @return <code>true</code> if the class instance is attached to a device, <code>false</code> otherwise.
     *
     * @see de.thesycon.usbio.UsbIo#open(int, int, String)
     * @see de.thesycon.usbio.UsbIo#close()
     */
	public boolean isOpen() {
		return isOpen(Handle);
	}

    /**
     * Returns <code>true</code> if the USB 2.0 device is operating at high speed (480 Mbit/s).
     * <p>
	 * If this function returns <code>true</code> then the USB device operates in high speed mode.
	 * The USB 2.0 device is connected to a hub port that is high speed capable.
	 * <p>
	 * Note that this function does not indicate whether a device is capable of high speed
	 * operation, but rather whether it is in fact operating at high speed.
	 * <p>
	 * This function calls {@link de.thesycon.usbio.UsbIo#getDeviceInfo(USBIO_DEVICE_INFO) getDeviceInfo} to get the requested information.
	 * <p>
	 * The device must have been opened before this function is called.
     *
     * @return <code>true</code> if the USB device is operating at high speed, <code>false</code> otherwise.
     *
     * @see de.thesycon.usbio.UsbIo#open(int, int, String)
     * @see de.thesycon.usbio.UsbIo#getDeviceInfo(USBIO_DEVICE_INFO)
     */
	public boolean isOperatingAtHighSpeed() {
		return isOperatingAtHighSpeed(Handle);
	}

    /**
     * Returns <code>true</code> if a checked build (debug version) of the USBIO driver was detected.
     * <p>
	 * The device must have been opened before this function is called.
     *
     * @return <code>true</code> if the checked build of the USBIO driver is running, <code>false</code> otherwise.
     *
     * @see de.thesycon.usbio.UsbIo#open(int, int, String)
     * @see de.thesycon.usbio.UsbIo#isDemoVersion()
     * @see de.thesycon.usbio.UsbIo#isLightVersion()
     */
	public boolean isCheckedBuild() {
		return isCheckedBuild(Handle);
	}

    /**
     * Returns <code>true</code> if the Demo version of the USBIO driver was detected.
     * <p>
	 * The device must have been opened before this function is called.
     *
     * @return <code>true</code> if the Demo version of the USBIO driver is running, <code>false</code> otherwise.
     *
     * @see de.thesycon.usbio.UsbIo#open(int, int, String)
     * @see de.thesycon.usbio.UsbIo#isCheckedBuild()
     * @see de.thesycon.usbio.UsbIo#isLightVersion()
     */
	public boolean isDemoVersion() {
		return isDemoVersion(Handle);
	}

    /**
     * Returns <code>true</code> if the Light version of the USBIO driver was detected.
     * <p>
	 * The device must have been opened before this function is called.
     *
     * @return <code>true</code> if the Light version of the USBIO driver is running, <code>false</code> otherwise.
     *
     * @see de.thesycon.usbio.UsbIo#open(int, int, String)
     * @see de.thesycon.usbio.UsbIo#isCheckedBuild()
     * @see de.thesycon.usbio.UsbIo#isDemoVersion()
     */
	public boolean isLightVersion() {
		return isLightVersion(Handle);
	}

	/**
	 * Open an USB device.
	 *
	 * @param DeviceNumber Specifies the index number of the USB Device.
	 * The index is zero-based.
	 * Note that the association between this number and the USB device
	 * can change with each call to CreateDeviceList.
	 *
	 * @param DeviceList A handle to the internal device list which was returned by the function
	 * CreateDeviceList or 0.
	 *
	 * @param InterfaceGuid The specified GUID is the predefined interface GUID of the USBIO device driver,
	 * or a user-defined GUID which has to be defined in the USBIO.INF file.
	 * This parameter will be ignored if DeviceList is set to NULL.
	 * For more information, see below.
	 *
	 * @return The function returns 0 if successful, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIo#createDeviceList(String)
	 * @see de.thesycon.usbio.UsbIo#destroyDeviceList(int)
	 * @see de.thesycon.usbio.UsbIo#close()
	 * @see de.thesycon.usbio.UsbIo#isOpen()
	 * @see de.thesycon.usbio.UsbIo#isCheckedBuild()
	 * @see de.thesycon.usbio.UsbIo#isDemoVersion()
	 * @see de.thesycon.usbio.UsbIo#isLightVersion()
	*/
	public int open(int DeviceNumber, int DeviceList, String InterfaceGuid) {
		if (Handle.getHANDLE() != 0) {
			close();
		}
		return open(Handle, DeviceNumber,DeviceList,InterfaceGuid);
	}

	/**
	 * Standard constructor of the UsbIo class.
	 *
	 * @see de.thesycon.usbio.UsbIo#open(int, int, String)
	 */
	public UsbIo() {
		Handle = new HANDLE();
		Handle.setHANDLE(0);
	}

	/**
	 * Close the USB device.
	 * <p>
	 * This function can be called if the device is not open. It does nothing in this case.
	 * <p>
	 * Any thread associated with the class instance should have been stopped
	 * before this function is called. See {@link de.thesycon.usbio.UsbIoThread#shutdownThread() shutdownThread}.
	 *
	 * @see de.thesycon.usbio.UsbIo#createDeviceList(String)
	 * @see de.thesycon.usbio.UsbIo#destroyDeviceList(int)
	 * @see de.thesycon.usbio.UsbIo#open(int, int, String)
	 * @see de.thesycon.usbio.UsbIoThread#shutdownThread()
	*/
	public void close() {
		if (Handle.getHANDLE() != 0) {
			close(Handle);
			Handle.setHANDLE(0);
		}
	}



	/**
	 * Acquire the USB device for exclusive use.
	 * <p>
	 * If the function returns with success, no other process can open the same device.
	 *
	 * @see de.thesycon.usbio.UsbIo#open(int, int, String)
	 * @see de.thesycon.usbio.UsbIo#releaseDevice()
	*/
	public int acquireDevice() {
		return acquireDevice(Handle);
	}



	/**
	 * Release the USB device. 
	 * <p>
	 * If the function returns with success, other processes can open the device.
	 *
	 * @see de.thesycon.usbio.UsbIo#open(int, int, String)
	 * @see de.thesycon.usbio.UsbIo#acquireDevice()
	*/
	public int releaseDevice() {
		return releaseDevice(Handle);
	}


	/**
	 * Get information on the current USB bandwidth consumption.
	 * <p>
	 * The function enables an application to check the bandwidth that is available on the USB.
	 * Depending on this information an application can select an appropriate
	 * device configuration, if desired.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_GET_BANDWIDTH_INFO operation.
	 *
	 * @param BandwidthInfo Reference to a caller-provided variable.
	 * The structure returns information on the bandwidth that is available on the USB.
	 *
	 * @return The function returns 0 if successful, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIo#open(int, int, String)
	 * @see de.thesycon.usbio.structs.USBIO_BANDWIDTH_INFO#USBIO_BANDWIDTH_INFO
	*/
	public int getBandwidthInfo(USBIO_BANDWIDTH_INFO BandwidthInfo) {
		if (BandwidthInfo == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] data = BandwidthInfo.buildByteArray();
		int Status = getBandwidthInfo(Handle, data);
		BandwidthInfo.parseByteArray(data);
		return Status;
	}

	/**
	 * Get information about the USB device.
	 * <p>
	 * This function can be used to detect if the device operates in high speed mode.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_GET_DEVICE_INFO operation.
	 *
	 * @param DeviceInfo Reference to a caller-provided variable.
	 * The structure returns information on the USB device.
	 * This includes a flag that indicates whether the device operates in
	 * high speed mode or not.
	 *
	 * @return The function returns 0 if successful, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIo#open(int, int, String)
	 * @see de.thesycon.usbio.structs.USBIO_DEVICE_INFO#USBIO_DEVICE_INFO
	*/
	public int getDeviceInfo(USBIO_DEVICE_INFO DeviceInfo) {
		if (DeviceInfo == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] data = DeviceInfo.buildByteArray();
		int Status = getDeviceInfo(Handle, data);
		DeviceInfo.parseByteArray(data);
		return Status;
	}

	/**
	 * Sends a class or vendor specific request with a data phase in device to host (IN) direction.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_CLASS_OR_VENDOR_IN_REQUEST operation.