usbio.java

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

	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_GET_DESCRIPTOR operation.
	 *
	 * @param BufDesc Reference to a caller-provided buffer descriptor.
	 * The buffer receives the requested descriptor.
	 * When the function is called the buffer descriptor specifies the size, in bytes, of the
	 * buffer.
	 * After the function successfully returned the buffer descriptor contains
	 * the number of valid bytes returned in the buffer.
	 *
	 * @param Recipient Specifies the recipient of the request.
	 *
	 * @param DescriptorType The type of the descriptor to request.
	 *
	 * @param DescriptorIndex The index of the descriptor to request.
	 *
	 * @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.UsbIo#getDeviceDescriptor(USB_DEVICE_DESCRIPTOR)
	 * @see de.thesycon.usbio.UsbIo#getConfigurationDescriptor(USBIO_DATA_BUFFER, byte)
	 * @see de.thesycon.usbio.UsbIo#getStringDescriptor(USB_STRING_DESCRIPTOR, byte, int)
	 * @see de.thesycon.usbio.UsbIo#setDescriptor(USBIO_DATA_BUFFER, int, byte, byte, short)
	*/
	public int getDescriptor(USBIO_DATA_BUFFER BufDesc, int Recipient, byte DescriptorType, byte DescriptorIndex) {
		return getDescriptor(BufDesc, Recipient, DescriptorType, DescriptorIndex, (short)0);
	}

	/**
	 * Set a descriptor of the device.
	 * <p>
	 * Note that most devices do not support the set descriptor request.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_SET_DESCRIPTOR operation.
	 *
	 * @param BufDesc Reference to a caller-provided buffer descriptor.
	 * The buffer contains the descriptor data to be set.
	 * When the function is called the buffer descriptor specifies the size, in bytes, of the
	 * buffer.
	 * After the function successfully returned the buffer descriptor contains
	 * the number of bytes transferred.
	 *
	 * @param Recipient Specifies the recipient of the request.
	 *
	 * @param DescriptorType The type of the descriptor to set.
	 *
	 * @param DescriptorIndex The index of the descriptor to set.
	 *
	 * @param LanguageId The language ID of the descriptor to set.
	 * Used for string descriptors only.
	 *
	 * @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.UsbIo#getDescriptor(USBIO_DATA_BUFFER, int, byte, byte)
	 * @see de.thesycon.usbio.UsbIo#getDeviceDescriptor(USB_DEVICE_DESCRIPTOR)
	 * @see de.thesycon.usbio.UsbIo#getConfigurationDescriptor(USBIO_DATA_BUFFER, byte)
	 * @see de.thesycon.usbio.UsbIo#getStringDescriptor(USB_STRING_DESCRIPTOR, byte, int)
	*/
	public int setDescriptor(USBIO_DATA_BUFFER BufDesc, int Recipient, byte DescriptorType, byte DescriptorIndex, short LanguageId) {
		if (BufDesc == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		if (BufDesc.Buffer() == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		int[] bytecount = new int[1];
		bytecount[0] = BufDesc.getNumberOfBytesToTransfer();
		int Status = setDescriptor(Handle, BufDesc.Buffer(), bytecount, Recipient, DescriptorType, DescriptorIndex, LanguageId);
		BufDesc.setBytesTransferred(bytecount[0]);
		return Status;
	}

	/**
	 * Get a string descriptor from the device.
	 * <p>
	 * GetStringDescriptor calls GetDescriptor to retrieve the descriptor.
	 * Thus, for detailed information see also GetDescriptor.
	 * <p>
	 * If this function is called with Index set to 0 the device returns a
	 * list of language IDs it supports.
	 * An application can select the correct language ID and use it
	 * in subsequent calls to this function.
	 * <p>
	 * The device must have been opened before this function is called.
	 *
	 * @param Desc Reference to a caller-provided buffer that receives the requested descriptor.
	 * Note that according to the USB specification the maximum size of a string
	 * descriptor is 256 bytes.
	 *
	 * @param Index The index of the descriptor to request.
	 * Set to 0 to retrieve a list of supported language IDs.
	 *
	 * @param LanguageId The language ID of the string descriptor to request.
	 *
	 * @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.UsbIo#getDescriptor(USBIO_DATA_BUFFER, int, byte, byte)
	 * @see de.thesycon.usbio.UsbIo#getConfigurationDescriptor(USBIO_DATA_BUFFER, byte)
	 * @see de.thesycon.usbio.UsbIo#getDeviceDescriptor(USB_DEVICE_DESCRIPTOR)
	*/
	public int getStringDescriptor(USB_STRING_DESCRIPTOR Desc,byte Index, int LanguageId) {
		if (Desc == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] Buffer = new byte[USB_STRING_DESCRIPTOR.MAX_DESCRIPTOR_BUFFER_SIZE];
		int[] bytecount = new int[]{USB_STRING_DESCRIPTOR.MAX_DESCRIPTOR_BUFFER_SIZE};
		int Status = getStringDescriptor(Handle, Buffer, bytecount, Index, LanguageId);
		Desc.parseByteArray(Buffer,bytecount[0]);
		return Status;
	}

	/**
	 * Get a configuration descriptor from the device.
	 * <p>
	 * GetConfigurationDescriptor calls GetDescriptor to retrieve the descriptor.
	 * Thus, for detailed information see also GetDescriptor.
	 * <p>
	 * If the total size of the configuration descriptor is not known
	 * it can be retrieved in a two step process.
	 * With a first call to this function the fixed part of the descriptor
	 * which is defined by USB_CONFIGURATION_DESCRIPTOR is retrieved.
	 * The total size of the descriptor is indicated by the wTotalLength
	 * field of the structure.
	 * In a second step a buffer of the required size can be allocated and the
	 * complete descriptor can be retrieved with another call to this function.
	 * <p>
	 * The device must have been opened before this function is called.
	 *
	 * @param BufDesc Reference to a caller-provided buffer descriptor that receives the requested descriptor.
	 * Note that the size of the configuration descriptor depends on the USB device.
	 * See also the comments below.
	 * When the function is called the buffer descriptor specifies the size, in bytes, of the
	 * buffer.
	 * After the function successfully returned the buffer descriptor contains
	 * the number of valid bytes returned in the buffer.
	 *
	 * @param Index The index of the descriptor to request.
	 *
	 * @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.UsbIo#getDescriptor(USBIO_DATA_BUFFER, int, byte, byte)
	 * @see de.thesycon.usbio.UsbIo#getStringDescriptor(USB_STRING_DESCRIPTOR, byte, int)
	 * @see de.thesycon.usbio.UsbIo#getDeviceDescriptor(USB_DEVICE_DESCRIPTOR)
	*/
	public int getConfigurationDescriptor(USBIO_DATA_BUFFER BufDesc, byte Index) {
		if (BufDesc == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		if (BufDesc.Buffer() == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		int[] bytecount = new int[1];
		bytecount[0] = BufDesc.getNumberOfBytesToTransfer();
		int Status = getConfigurationDescriptor(Handle, BufDesc.Buffer(), bytecount, Index);
		BufDesc.setBytesTransferred(bytecount[0]);
		return Status;
	}

	/**
	 * This function returns the current configuration value.
	 * <p>
	 * The configuration value returned by this function corresponds to the
	 * bConfiguration field of the active configuration descriptor.
	 * Note that the configuration value does not necessarily correspond
	 * to the index of the configuration descriptor.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_GET_CONFIGURATION operation.
	 *
	 * @param ConfigurationValue If the function call is successful this variable returns the
	 * current configuration value.
	 * A value of 0 means the USB device is not configured.
	 *
	 * @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.UsbIo#setConfiguration(USBIO_SET_CONFIGURATION)
	*/
	public int getConfiguration(byte[] ConfigurationValue) {
		if (ConfigurationValue == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		return getConfiguration(Handle, ConfigurationValue);
	}

	/**
	 * Get information on the interfaces and endpoints available in the current configuration.
	 * <p>
	 * The information returned is retrieved from the USBIO driver's internal
	 * data base.
	 * This function does not cause any action on the USB.
	 * <p>
	 * The device must have been opened before this function is called.
	 *
	 * @param ConfigurationInfo Reference to a caller-provided variable that receives the
 	 * configuration information.
 	 *
	 * @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.UsbIo#setConfiguration(USBIO_SET_CONFIGURATION)
	 * @see de.thesycon.usbio.structs.USBIO_CONFIGURATION_INFO#USBIO_CONFIGURATION_INFO
	*/
	public int getConfigurationInfo(USBIO_CONFIGURATION_INFO ConfigurationInfo) {
		if (ConfigurationInfo == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] data = ConfigurationInfo.buildByteArray();
		int Status = getConfigurationInfo(Handle, data);
		ConfigurationInfo.parseByteArray(data);
		return Status;
	}

	/**
	 * Get the device descriptor from the device.
	 * <p>
	 * GetDeviceDescriptor calls {@link de.thesycon.usbio.UsbIo#getDescriptor(USBIO_DATA_BUFFER, int, byte, byte) getDescriptor} to retrieve the descriptor.
	 * Thus, for detailed information see also {@link de.thesycon.usbio.UsbIo#getDescriptor(USBIO_DATA_BUFFER, int, byte, byte) getDescriptor}.
	 * <p>
	 * The device must have been opened before this function is called.
	 *
	 * @param Desc Reference to a caller-provided variable that receives the requested descriptor.
	 *
	 * @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.UsbIo#getDescriptor(USBIO_DATA_BUFFER, int, byte, byte)
	 * @see de.thesycon.usbio.UsbIo#getConfigurationDescriptor(USBIO_DATA_BUFFER, byte)
	 * @see de.thesycon.usbio.UsbIo#getStringDescriptor(USB_STRING_DESCRIPTOR, byte, int)
	 * @see de.thesycon.usbio.structs.USB_DEVICE_DESCRIPTOR#USB_DEVICE_DESCRIPTOR
	*/
	public int getDeviceDescriptor(USB_DEVICE_DESCRIPTOR Desc) {
		if (Desc == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] Buffer = new byte[Desc.getSize()];
		int Status = getDeviceDescriptor(Handle, Buffer);
		Desc.parseByteArray(Buffer);
		return Status;
	}

	/**
	 * Query device-related parameters from the USBIO device driver.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_GET_DEVICE_PARAMETERS operation.
	 *
	 * @param DevParam Reference to a caller-provided variable that receives the
	 * current parameter settings.
	 *
	 * @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.UsbIo#setDeviceParameters(USBIO_DEVICE_PARAMETERS)
	 * @see de.thesycon.usbio.structs.USBIO_DEVICE_PARAMETERS#USBIO_DEVICE_PARAMETERS
	*/
	public int getDeviceParameters(USBIO_DEVICE_PARAMETERS DevParam) {
		if (DevParam == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] Buffer = new byte[DevParam.getSize()];
		int Status = getDeviceParameters(Handle, Buffer);
		DevParam.parseByteArray(Buffer);
		return Status;
	}

	/**
	 * Set device-related parameters in the USBIO device driver.
	 * <p>
	 * Default device parameters are stored in the registry during USBIO driver installation.
	 * The default value can be changed in the INF file or in the registry.
	 * Device parameters set by means of this function are valid until the device
	 * is removed from the PC or the PC is booted.
	 * A modification during run-time does not change the default in the registry.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_SET_DEVICE_PARAMETERS operation.
	 *
	 * @param DevParam Reference to a caller-provided variable that receives the
	 * current parameter settings.
	 *
	 * @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.UsbIo#getDeviceDescriptor(USB_DEVICE_DESCRIPTOR)
	 * @see de.thesycon.usbio.structs.USBIO_DEVICE_PARAMETERS#USBIO_DEVICE_PARAMETERS
	*/
	public int setDeviceParameters(USBIO_DEVICE_PARAMETERS DevParam) {
		if (DevParam == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] Buffer = DevParam.buildByteArray();
		int Status = setDeviceParameters(Handle, Buffer);
		return Status;
	}

	/**
	 * Get information on the USBIO device driver.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_GET_DRIVER_INFO operation.
	 *
	 * @param DriverInfo Reference to a caller-provided variable. The structure returns the API version, the driver version, and the build number.
	 *
	 * @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.UsbIo#close()
	 * @see de.thesycon.usbio.structs.USBIO_DRIVER_INFO#USBIO_DRIVER_INFO
	*/
	public int getDriverInfo(USBIO_DRIVER_INFO DriverInfo) {
		if (DriverInfo == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] buffer = new byte[DriverInfo.getSize()];
		int Status =  getDriverInfo(Handle, buffer);
		DriverInfo.parseByteArray(buffer);
		return Status;
	}

	/**
	 * Set the device to the configured state.
	 * <p>
	 * The device has to be configured before any data transfer from or to
	 * its endpoints can take place.
	 * Only those endpoints that are included in the configuration
	 * will be activated and can be subsequently used for data transfers.
	 * <p>
	 * If the device provides more than one interface all interfaces
	 * must be configured in one call to this function.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_SET_CONFIGURATION operation.
	 *
	 * @param Conf Reference to a caller-provided buffer.
	 *
	 * @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.UsbIo#unconfigureDevice()
	 * @see de.thesycon.usbio.UsbIo#getConfiguration(byte[])
	 * @see de.thesycon.usbio.UsbIo#setInterface(USBIO_INTERFACE_SETTING)
	 * @see de.thesycon.usbio.structs.USBIO_SET_CONFIGURATION#USBIO_SET_CONFIGURATION
	*/
	public int setConfiguration(USBIO_SET_CONFIGURATION Conf) {
		if (Conf == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		return setConfiguration(Handle, Conf.buildByteArray());
	}

	/**
	 * Set the device to the unconfigured state.
	 * <p>
	 * The device must have been opened before this function is called.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_UNCONFIGURE_DEVICE operation.
	 *
	 * @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.UsbIo#setConfiguration(USBIO_SET_CONFIGURATION)
	 * @see de.thesycon.usbio.UsbIo#getConfiguration(byte[])
	*/
	public int unconfigureDevice() {
		return unconfigureDevice(Handle);
	}

	protected void finalize() throws Throwable {
		try {
			close();
		} finally {
			super.finalize();
		}
	}
}