usbiopipe.java

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

		if (PipeParameters == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] data = PipeParameters.buildByteArray();
		int Status =  setPipeParameters(Handle, data);
		PipeParameters.parseByteArray(data);
		return Status;
	}

	/**
	 * Query pipe-related parameters from 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_GET_PIPE_PARAMETERS operation.
	 *
	 * @param PipeParameters 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.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#setPipeParameters(USBIO_PIPE_PARAMETERS)
	 * @see de.thesycon.usbio.structs.USBIO_PIPE_PARAMETERS#USBIO_PIPE_PARAMETERS
	*/
	public int getPipeParameters(USBIO_PIPE_PARAMETERS PipeParameters) {
		if (PipeParameters == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		byte[] data = PipeParameters.buildByteArray();
		int Status =  getPipeParameters(Handle, data);
		PipeParameters.parseByteArray(data);
		return Status;
	}

	/**
	 * Submit a read request on the pipe and wait for its completion.
	 * <p>
	 * The function transfers data from the endpoint attached to the object
	 * to the specified buffer.
	 * The function does not return to the caller until the data transfer
	 * has been finished or aborted due to a timeout.
	 * It behaves in a synchronous manner.
	 * <p>
	 * Optionally, a timeout interval for the synchronous read operation may be specified.
	 * When the interval elapses before the operation is
	 * finished the function aborts the operation and returns with a special
	 * status of USBIO_ERR_TIMEOUT.
	 * In this case, it is not possible to determine the number of bytes already
	 * transferred.
	 * After a timeout error occurred {@link de.thesycon.usbio.UsbIoPipe#resetPipe() resetPipe} should be called.
	 * <p>
	 * Note that there is some overhead involved when this function is used.
	 * This is due to a temporary Win32 Event object that is created and destroyed
	 * internally.
	 * <p>
	 * Note: Using synchronous read requests does make sense in
	 * rare cases only and can lead to unpredictable results.
	 * It is recommended to handle read operations asynchronously by means of
	 * {@link de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf) read} and {@link de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf) waitForCompletion}.
	 * <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}.
	 *
	 * @param BufDesc Reference to a caller-provided buffer descriptor.
	 * The buffer receives the data transferred from the device.
	 * When the function is called the buffer descriptor specifies the size, in bytes, of the
	 * buffer.
	 * After the function succeeds the buffer descriptor contains
	 * the number of bytes successfully read.
	 *
	 * @param Timeout Specifies a timeout interval, in milliseconds.
	 * If the interval elapses and the read operation is not yet finished
	 * the function aborts the operation and returns with USBIO_ERR_TIMEOUT
	 * When INFINITE is specified then the interval never elapses.
	 * The function does not return until the read operation is finished.
	 *
	 * @return The function returns USBIO_ERR_TIMEOUT if the timeout interval elapsed
	 * and the read operation was aborted.
	 * If the read operation has been finished the return value is
	 * the completion status of the operation which is 0 for success,
	 * or an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#writeSync(USBIO_DATA_BUFFER, int)
	 * @see de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#resetPipe()
	*/
	public int readSync(USBIO_DATA_BUFFER BufDesc, int Timeout) {
		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 = readSync(Handle, BufDesc.Buffer(), bytecount, Timeout);
		BufDesc.setBytesTransferred(bytecount[0]);
		return Status;
	}

	/**
	 * Submit a read request on the pipe and wait for its completion.
	 * <p>
	 * The function transfers data from the endpoint attached to the object
	 * to the specified buffer.
	 * The function does not return to the caller until the data transfer
	 * has been finished or aborted due to a timeout.
	 * It behaves in a synchronous manner.
	 * <p>
	 * The timeout interval for the synchronous read operation may is INFINITE.
	 * <p>
	 * Note that there is some overhead involved when this function is used.
	 * This is due to a temporary Win32 Event object that is created and destroyed
	 * internally.
	 * <p>
	 * Note: Using synchronous read requests does make sense in
	 * rare cases only and can lead to unpredictable results.
	 * It is recommended to handle read operations asynchronously by means of
	 * {@link de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf) read} and {@link de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf) waitForCompletion}.
	 * <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}.
	 *
	 * @param BufDesc Reference to a caller-provided buffer descriptor.
	 * The buffer receives the data transferred from the device.
	 * When the function is called the buffer descriptor specifies the size, in bytes, of the
	 * buffer.
	 * After the function succeeds the buffer descriptor contains
	 * the number of bytes successfully read.
	 *
	 * @return If the read operation has been finished the return value is
	 * the completion status of the operation which is 0 for success,
	 * or an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#writeSync(USBIO_DATA_BUFFER)
	 * @see de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#resetPipe()
	*/
	public int readSync(USBIO_DATA_BUFFER BufDesc) {
		return readSync(BufDesc, INFINITE);
	}

	/**
	 * Submit a write request on the pipe and wait for its completion.
	 * <p>
	 * The function transfers data from the endpoint attached to the object
	 * to the specified buffer.
	 * The function does not return to the caller until the data transfer
	 * has been finished or aborted due to a timeout.
	 * It behaves in a synchronous manner.
	 * <p>
	 * Optionally, a timeout interval for the synchronous write operation may be specified.
	 * When the interval elapses before the operation is
	 * finished the function aborts the operation and returns with a special
	 * status of USBIO_ERR_TIMEOUT.
	 * In this case, it is not possible to determine the number of bytes already
	 * transferred.
	 * After a timeout error occurred {@link de.thesycon.usbio.UsbIoPipe#resetPipe() resetPipe} should be called.
	 * <p>
	 * Note that there is some overhead involved when this function is used.
	 * This is due to a temporary Win32 Event object that is created and destroyed
	 * internally.
	 * <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}.
	 *
	 * @param BufDesc Reference to a caller-provided buffer descriptor that contains the data to be
	 * transferred to the device.
	 * When the function is called the buffer descriptor specifies the size, in bytes, of the
	 * buffer.
	 * After the function succeeds the buffer descriptor contains
	 * the number of bytes successfully written.
	 *
	 * @param Timeout Specifies a timeout interval, in milliseconds.
	 * If the interval elapses and the write operation is not yet finished
	 * the function aborts the operation and returns with USBIO_ERR_TIMEOUT.
	 * When INFINITE is specified then the interval never elapses.
	 * The function does not return until the write operation is finished.
	 *
	 * @return The function returns USBIO_ERR_TIMEOUT if the timeout interval elapsed
	 * and the read operation was aborted.
	 * If the read operation has been finished the return value is
	 * the completion status of the operation which is 0 for success,
	 * or an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#readSync(USBIO_DATA_BUFFER, int)
	 * @see de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#resetPipe()
	*/
	public int writeSync(USBIO_DATA_BUFFER BufDesc, int Timeout) {
		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 = writeSync(Handle, BufDesc.Buffer(), bytecount, Timeout);
		BufDesc.setBytesTransferred(bytecount[0]);
		return Status;
	}

	/**
	 * Submit a write request on the pipe and wait for its completion.
	 * <p>
	 * The function transfers data from the endpoint attached to the object
	 * to the specified buffer.
	 * The function does not return to the caller until the data transfer
	 * has been finished or aborted due to a timeout.
	 * It behaves in a synchronous manner.
	 * <p>
	 * The timeout interval for the synchronous write operation may is INFINITE.
	 * <p>
	 * Note that there is some overhead involved when this function is used.
	 * This is due to a temporary Win32 Event object that is created and destroyed
	 * internally.
	 * <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}.
	 *
	 * @param BufDesc Reference to a caller-provided buffer descriptor that contains the data to be
	 * transferred to the device.
	 * When the function is called the buffer descriptor specifies the size, in bytes, of the
	 * buffer.
	 * After the function succeeds the buffer descriptor contains
	 * the number of bytes successfully written.
	 *
	 * @return If the read operation has been finished the return value is
	 * the completion status of the operation which is 0 for success,
	 * or an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#readSync(USBIO_DATA_BUFFER)
	 * @see de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#resetPipe()
	*/
	public int writeSync(USBIO_DATA_BUFFER BufDesc) {
		return writeSync(BufDesc, INFINITE);
	}


	/**
	 * Bind the object to an endpoint of the USB device.
	 * <p>
	 * If an USB device has not already been opened this function calls
	 * {@link de.thesycon.usbio.UsbIo#open(int, int, String) open} to attach the object to a device.
	 * It passes the parameters DeviceNumber, DeviceList,
	 * and InterfaceGuid unmodified to {@link de.thesycon.usbio.UsbIo#open(int, int, String) open}.
	 * Thus, a device and an endpoint can be attached to the object in one step.
	 * <p>
	 * Alternatively, an application can attach a device first by means
	 * of {@link de.thesycon.usbio.UsbIo#open(int, int, String) open} (derived from UsbIo, and then in a second
	 * step attach an endpoint by means of Bind.
	 * The parameters DeviceNumber, DeviceList,
	 * and InterfaceGuid will be ignored in this case.
	 * <p>
	 * The device must be set to the configured state before an endpoint can be bound,
	 * see {@link de.thesycon.usbio.UsbIo#setConfiguration(USBIO_SET_CONFIGURATION) setConfiguration}.
	 * Only endpoints that are included in the active configuration can be
	 * bound by this function and subsequently used for a data transfer.
	 * <p>
	 * Note that an instance of the UsbIoPipe class can be bound to exactly
	 * one endpoint only.
	 * Consequently, one instance has to be created for each endpoint to be
	 * activated.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_BIND_PIPE operation.
	 *
	 * @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 {@link de.thesycon.usbio.UsbIo#createDeviceList(String) createDeviceList}.