usbiopipe.java

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

package de.thesycon.usbio;

import de.thesycon.usbio.structs.*;

/**
 * This class implements the interface to an USB pipe that is exported
 * by the USBIO device driver.
 * It provides all pipe-related functions that can be executed
 * on a file handle that is bound to an USB endpoint.
 * Particularly, it provides the functions needed for a data transfer
 * from or to an endpoint.
 * <p>
 * Note that this class is derived from UsbIo.
 * All general and device-related functions can be executed
 * on an instance of UsbIoPipe as well.
 *
 * @author Thesycon
 * @version 2.0
 */
public class UsbIoPipe extends UsbIo

{
	private native int bind(HANDLE Handle,int DeviceNumber,byte EndpointAddress,int DeviceList,String InterfaceGuid);

	private native int unbind(HANDLE Handle);

	private native int abortPipe(HANDLE Handle);

	private native int resetPipe(HANDLE Handle);

	private native int resetPipeStatistics(HANDLE Handle);

	private native int setupPipeStatistics(HANDLE Handle, int AveragingInterval);

	private native int queryPipeStatistics(HANDLE Handle, byte[] PipeStatistics, int flags);

	private native int getPipeParameters(HANDLE Handle, byte[] PipeParameters);

	private native int setPipeParameters(HANDLE Handle, byte[] PipeParameters);

	private native int readSync(HANDLE Handle, byte[] data, int[] bytecount, int timeout);

	private native int read(HANDLE Handle, UsbIoBuf Buffer);

	private native int writeSync(HANDLE Handle, byte[] data, int[] bytecount, int timeout);

	private native int write(HANDLE Handle, UsbIoBuf Buffer);

	private native int waitForCompletion(HANDLE Handle, UsbIoBuf Buffer, int timeout);

	private native int pipeControlTransferIn(HANDLE Handle, byte[] data, int[] count, byte[] ControlTransfer);

	private native int pipeControlTransferOut(HANDLE Handle, byte[] data, int[] count, byte[] ControlTransfer);


	/**
	 * Generates a control transfer (SETUP token) on the pipe with a data phase in
	 * device to host (IN) direction.
	 * <p>
	 * This function is used to send a SETUP token to a Control type endpoint.
	 * <p>
	 * Note: This function cannot be used to send a SETUP request
	 * to the default endpoint 0.
	 * <p>
	 * The device must have been opened and the object must have been bound to an endpoint
	 * before this function is called, see {@link de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String) bind}.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_PIPE_CONTROL_TRANSFER_IN operation.
	 *
	 * @param BufDesc Reference to a caller-provided buffer descriptor.
	 * The buffer receives the data transferred in the IN data phase.
	 * 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 ControlTransfer Reference to a caller-provided variable that defines the request to be generated.
	 *
	 * @return The function returns 0 if successful, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#pipeControlTransferOut(USBIO_DATA_BUFFER, USBIO_PIPE_CONTROL_TRANSFER)
	 * @see de.thesycon.usbio.structs.USBIO_PIPE_CONTROL_TRANSFER#USBIO_PIPE_CONTROL_TRANSFER USBIO_PIPE_CONTROL_TRANSFER
	*/
	public int pipeControlTransferIn(USBIO_DATA_BUFFER BufDesc, USBIO_PIPE_CONTROL_TRANSFER ControlTransfer) {
		if (BufDesc == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		if (BufDesc.Buffer() == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		if (ControlTransfer == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] ContTransfer = ControlTransfer.buildByteArray();
		int[] bytecount = new int[1];
		bytecount[0] = BufDesc.getNumberOfBytesToTransfer();
		int Status = pipeControlTransferIn(Handle, BufDesc.Buffer(), bytecount, ContTransfer);
		BufDesc.setBytesTransferred(bytecount[0]);
		ControlTransfer.parseByteArray(ContTransfer);
		return Status;
	}

	/**
	 * Generates a control transfer (SETUP token) on the pipe with a data phase in
	 * host to device (OUT) direction.
	 * <p>
	 * This function is used to send a SETUP token to a Control type endpoint.
	 * <p>
	 * Note: This function cannot be used to send a SETUP request
	 * to the default endpoint 0.
	 * <p>
	 * The device must have been opened and the object must have been bound to an endpoint
	 * before this function is called, see {@link de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String) bind}.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_PIPE_CONTROL_TRANSFER_OUT operation.
	 *
	 * @param BufDesc to a caller-provided buffer descriptor that contains the data
	 * to be transferred in the OUT data phase.
	 * 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 ControlTransfer Reference to a caller-provided variable that defines the request to be generated.
	 *
	 * @return The function returns 0 if successful, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#pipeControlTransferIn(USBIO_DATA_BUFFER, USBIO_PIPE_CONTROL_TRANSFER)
	 * @see de.thesycon.usbio.structs.USBIO_PIPE_CONTROL_TRANSFER#USBIO_PIPE_CONTROL_TRANSFER USBIO_PIPE_CONTROL_TRANSFER
	*/
	public int pipeControlTransferOut(USBIO_DATA_BUFFER BufDesc, USBIO_PIPE_CONTROL_TRANSFER ControlTransfer) {
		if (BufDesc == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		if (BufDesc.Buffer() == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		if (ControlTransfer == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] ContTransfer = ControlTransfer.buildByteArray();
		int[] bytecount = new int[1];
		bytecount[0] = BufDesc.getNumberOfBytesToTransfer();
		int Status = pipeControlTransferOut(Handle, BufDesc.Buffer(), bytecount, ContTransfer);
		BufDesc.setBytesTransferred(bytecount[0]);
		ControlTransfer.parseByteArray(ContTransfer);
		return Status;
	}

	/**
	 * Reset the statistics counters of the pipe.
	 * <p>
	 * The USBIO driver internally maintains some statistical data per pipe object.
	 * This function resets the counters BytesTransferred, RequestsSucceeded, and RequestsFailed
	 * to zero.
	 * <p>
	 * Note that this function calls {@link de.thesycon.usbio.UsbIoPipe#queryPipeStatistics(USBIO_PIPE_STATISTICS, int) queryPipeStatistics} to
	 * reset the counters.
	 * <p>
	 * The device must have been opened and the object must have been bound to an endpoint
	 * before this function is called, see {@link de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String) bind}.
	 *
	 * @return The function returns 0 if successful, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#setupPipeStatistics(int)
	 * @see de.thesycon.usbio.UsbIoPipe#queryPipeStatistics(USBIO_PIPE_STATISTICS, int)
	*/
	public int resetPipeStatistics() {
		return resetPipeStatistics(Handle);
	}

	/**
	 * Enables or disables a statistical analysis
	 * of the data transfer on the pipe.
	 * <p>
	 * The USBIO driver is able to analyse the data transfer (outgoing or incoming) on a pipe
	 * and to calculate the average data rate on that pipe.
	 * A time averaging algorithm is used to continuously compute the mean value of the
	 * data transfer rate.
	 * In order to save resources (kernel memory and CPU cycles) the average data rate
	 * computation is disabled by default.
	 * It has to be enabled and to be configured by means of this function
	 * before it is available to an application.
	 * See also QueryPipeStatistics and USBIO_PIPE_STATISTICS
	 * for more information on pipe statistics.
	 * <p>
	 * The device must have been opened and the object must have been bound to an endpoint
	 * before this function is called, see {@link de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String) bind}.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_SETUP_PIPE_STATISTICS operation.
	 *
	 * @param AveragingInterval Specifies the time interval, in milliseconds, that is used to calculate the average
	 * data rate of the pipe.
	 * A time averaging algorithm is used to continuously compute the mean value of the
	 * data transfer rate.
	 * If AveragingInterval is set to zero then the average data rate
	 * computation is disabled.
	 * This is the default state.
	 * An application should only enable the average data rate computation if it is needed.
	 * This will save resources (kernel memory and CPU cycles).
	 *
	 * @return The function returns 0 if successful, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#queryPipeStatistics(USBIO_PIPE_STATISTICS, int)
	*/
	public int setupPipeStatistics(int AveragingInterval) {
		return setupPipeStatistics(Handle, AveragingInterval);
	}

	/**
	 * Returns statistical data related to the pipe.
	 * <p>
	 * The USBIO driver internally maintains some statistical data per pipe object.
	 * This function allows an application to query the actual values of the
	 * various statistics counters.
	 * Optionally, individual counters can be reset to zero after queried.
	 * See also {@link de.thesycon.usbio.UsbIoPipe#setupPipeStatistics(int) setupPipeStatistics} and USBIO_PIPE_STATISTICS
	 * for more information on pipe statistics.
	 * <p>
	 * The USBIO driver is able to analyse the data transfer (outgoing or incoming) on a pipe
	 * and to calculate the average data rate on that pipe.
	 * In order to save resources (kernel memory and CPU cycles) this feature
	 * is disabled by default.
	 * It has to be enabled and to be configured by means of the function
	 * {@link de.thesycon.usbio.UsbIoPipe#setupPipeStatistics(int) setupPipeStatistics} before it is available to an application.
	 * Thus, before an application starts to (periodically) query the value of
	 * AverageRate} that is included in the data structure USBIO_PIPE_STATISTICS
	 * it has to enable the continuous computation of this value by a call to
	 * {@link de.thesycon.usbio.UsbIoPipe#setupPipeStatistics(int) setupPipeStatistics}.
	 * The other statistical counters contained in the USBIO_PIPE_STATISTICS structure
	 * will be updated by default and do not need to be enabled explicitly.
	 * <p>
	 * Note that the statistical data is maintained for each pipe object separately.
	 * <p>
	 * The device must have been opened and the object must have been bound to an endpoint
	 * before this function is called, see {@link de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String) bind}.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_QUERY_PIPE_STATISTICS operation.
	 *
	 * @param PipeStatistics Reference to a caller-provided variable that receives the statistical data.
	 *
	 * @param Flags This parameter is set to zero or any combination (bit-wise or) of the following values.
	 * USBIO_QPS_FLAG_RESET_BYTES_TRANSFERRED, USBIO_QPS_FLAG_RESET_REQUESTS_SUCCEEDED, USBIO_QPS_FLAG_RESET_REQUESTS_FAILED
	 * and USBIO_QPS_FLAG_RESET_ALL_COUNTERS.
	 *
	 * @return The function returns 0 if successful, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#setupPipeStatistics(int)
	*/
	public int queryPipeStatistics(USBIO_PIPE_STATISTICS PipeStatistics, int Flags) {
		if (PipeStatistics == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] data = PipeStatistics.buildByteArray();
		int Status =  queryPipeStatistics(Handle, data, Flags);
		PipeStatistics.parseByteArray(data);
		return Status;
	}

	/**
	 * Set pipe-related parameters in the USBIO device driver.
	 * <p>
	 * The device must have been opened and the object must have been bound to an endpoint
	 * before this function is called, see {@link de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String) bind}.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_SET_PIPE_PARAMETERS operation.
	 *
	 * @param PipeParameters Reference to a caller-provided variable that specifies the
	 * parameters to be set.
	 *
	 * @return The function returns 0 if successful, an USBIO error codeotherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#getPipeParameters(USBIO_PIPE_PARAMETERS)
	 * @see de.thesycon.usbio.structs.USBIO_PIPE_PARAMETERS#USBIO_PIPE_PARAMETERS
	*/
	public int setPipeParameters(USBIO_PIPE_PARAMETERS PipeParameters) {