usbiopipe.java

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

	 * For more details see also {@link de.thesycon.usbio.UsbIo#open(int, int, String) open}.
	 * Note that this parameter is ignored if the device has already been opened.
	 *
	 * @param EndpointAddress Specifies the address of the endpoint to bind the object to.
	 * The endpoint address is specified as reported in the
	 * corresponding endpoint descriptor.
	 * The endpoint address includes the direction flag at bit position 7 (MSB).
	 * For example, an IN endpoint with endpoint number 1 has the endpoint address 0x81.
	 *
	 * @param DeviceList A handle to the internal device list which was returned by the function
	 * {@link de.thesycon.usbio.UsbIo#createDeviceList(String) createDeviceList} or 0.
	 * For more details see also {@link de.thesycon.usbio.UsbIo#open(int, int, String) open}.
	 * Note that this parameter is ignored if the device has already been opened.
	 *
	 * @param InterfaceGuid The provided 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.
	 * For more details see also {@link de.thesycon.usbio.UsbIo#open(int, int, String) open}.
	 * Note that this parameter is ignored if the device has already been opened.
	 *
	 * @return The function returns 0 if successful, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#unbind()
	 * @see de.thesycon.usbio.UsbIo#createDeviceList(String)
	 * @see de.thesycon.usbio.UsbIo#open(int, int, String)
	 * @see de.thesycon.usbio.UsbIo#close()
	 * @see de.thesycon.usbio.UsbIo#setConfiguration(USBIO_SET_CONFIGURATION)
	*/
	public int bind(int DeviceNumber,byte EndpointAddress, int DeviceList,String InterfaceGuid) {
		return bind(Handle, DeviceNumber, EndpointAddress, DeviceList, InterfaceGuid);
	}

	/**
	 * Delete the association between the object and an endpoint.
	 * <p>
	 * A call to this function causes all pending
	 * read and write requests to be aborted.
	 * <p>
	 * After this function was called the object can be bound
	 * to another endpoint.
	 * However, it is recommended to use a separate object for each endpoint.
	 * See also the comments on {@link de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String) bind}.
	 * <p>
	 * It is not an error to call Unbind when no endpoint is currently bound.
	 * The function does nothing in this case.
	 * <p>
	 * Note that closing the device either by means of {@link de.thesycon.usbio.UsbIo#close() close}
	 * or by destructing the object will also cause an unbind.
	 * Thus, normally there is no need to call Unbind explicitly.
	 * <p>
	 * This function is a wrapper for the IOCTL_USBIO_UNBIND_PIPE operation.
	 *
	 * @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.UsbIo#close()
	*/
	public int unbind() {
		return unbind(Handle);
	}

	/**
	 * Cancel all pending read and write requests on this pipe.
	 * <p>
	 * This function is used to abort pending I/O operations on the pipe.
	 * All pending buffers will be returned to the application with an error status.
	 * Note that it is not possible to determine the number of bytes already transferred
	 * from or to an aborted buffer.
	 * <p>
	 * After a call to this function and before the data transfer is restarted
	 * the state of the pipe should be reset by means of {@link de.thesycon.usbio.UsbIoPipe#resetPipe() resetPipe}.
	 * See also the comments on {@link de.thesycon.usbio.UsbIoPipe#resetPipe() resetPipe}.
	 * <p>
	 * Note that it will take some milliseconds to cancel all buffers.
	 * Therefore, AbortPipe should not be called periodically.
	 * <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_ABORT_PIPE operation.
	 *
	 * @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#abortPipe()
	*/
	public int abortPipe() {
		return abortPipe(Handle);
	}

	/**
	 * Reset pipe.
	 * <p>
	 * This function resets the software state of a pipe in the USB driver stack.
	 * Besides, on a bulk or interrupt pipe a CLEAR_FEATURE Endpoint Stall request
	 * will be generated on the USB.
	 * This should reset the endpoint state in the device as well.
	 * <p>
	 * This function has to be used after an error condition occurred on the
	 * pipe and the pipe was halted by the USB drivers.
	 * <p>
	 * It is recommended to call ResetPipe every time
	 * a data transfer is initialized on the pipe.
	 * <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_RESET_PIPE operation.
	 *
	 * @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#abortPipe()
	*/
	public int resetPipe() {
		return resetPipe(Handle);
	}

	/**
	 * Submit a read request on the pipe.
	 * <p>
	 * The function submits the buffer memory that is attached to Buffer
	 * to the USBIO device driver.
	 * The caller has to prepare the buffer descriptor pointed to by Buffer.
	 * Particularly, the NumberOfBytesToTransfer member has to be set
	 * to the number of bytes to read.
	 * <p>
	 * The call returns immediately (asynchronous behavior).
	 * After the function succeeded the read operation is pending.
	 * It will be completed later on by the USBIO driver when
	 * data is received from the device.
	 * To determine when the operation has been completed the function
	 * {@link de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf) waitForCompletion} should be called.
	 * <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 Buffer Reference to a buffer descriptor the read buffer is attached to.
	 * The buffer descriptor has to be prepared by the caller.
	 *
	 * @return Returns <code>true</code> if the request was successfully submitted, <code>false</code> otherwise.
	 * If <code>false</code> is returned then the Status member of Buffer
	 * contains an error code.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#readSync(USBIO_DATA_BUFFER)
	 * @see de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf)
	*/
	public int read(UsbIoBuf Buffer) {
		if (Buffer == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		return read(Handle, Buffer);
	}

	/**
	 * Submit a write request on the pipe.
	 * <p>
	 * The function submits the buffer memory that is attached to Buffer
	 * to the USBIO device driver.
	 * The buffer contains the data to be written.
	 * The caller has to prepare the buffer descriptor pointed to by Buffer.
	 * Particularly, the NumberOfBytesToTransfer member has to be set
	 * to the number of bytes to write.
	 * <p>
	 * The call returns immediately (asynchronous behavior).
	 * After the function succeeded the write operation is pending.
	 * It will be completed later on by the USBIO driver when
	 * data has been sent to the device.
	 * To determine when the operation has been completed the function
	 * {@link de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf) waitForCompletion} should be called.
	 * <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 Buffer Reference to a buffer descriptor the write buffer is attached to.
	 * The buffer descriptor has to be prepared by the caller.
	 *
	 * @return Returns <code>true</code> if the request was successfully submitted, <code>false</code> otherwise.
	 * If <code>false</code> is returned then the Status member of Buffer
	 * contains an error code.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#writeSync(USBIO_DATA_BUFFER)
	 * @see de.thesycon.usbio.UsbIoPipe#waitForCompletion(UsbIoBuf)
	*/
	public int write(UsbIoBuf Buffer) {
		if (Buffer == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		return write(Handle, Buffer);
	}

	/**
	 * Wait for completion of a pending read or write operation.
	 * <p>
	 * After a buffer was submitted to the USBIO device driver by means of
	 * {@link de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf) read} or {@link de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf) write}
	 * this function is used to wait for the completion of the data transfer.
	 * Note that WaitForCompletion can be called regardless of the return status
	 * of the {@link de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf) read} or {@link de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf) write} function.
	 * It returns always the correct status of the buffer.
	 * <p>
	 * Optionally, a timeout interval for the wait operation may be specified.
	 * When the interval elapses before the read or write operation is
	 * finished the function returns with a special status of USBIO_ERR_TIMEOUT.
	 * The data transfer operation is still pending in this case.
	 * WaitForCompletion should be called again until the operation is finished.
	 * <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 Buffer Reference to the buffer descriptor that has been submitted by means of
	 * {@link de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf) read} or {@link de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf) write}.
	 *
	 * @param Timeout Specifies a timeout interval, in milliseconds.
	 * The function returns with a status code of USBIO_ERR_TIMEOUT if
	 * the interval elapses and the read or write operation is still pending.
	 *
	 * @return The function returns USBIO_ERR_TIMEOUT if the timeout interval elapsed.
	 * It returns USBIO_ERR_ADDITIONAL_EVENT_SIGNALLED if an additional event object
	 * has been specified and this event was signalled before the buffer completed or
	 * the timeout interval elapsed.
	 * If the read or write operation has been finished the return value is
	 * the final completion status of the operation.
	 * Note that the Status member of Buffer will also be
	 * set to the final completion status in this case.
	 * The completion status is 0 if the read or write operation has been successfully
	 * finished, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf)
	*/
	public int waitForCompletion(UsbIoBuf Buffer, int Timeout) {
		if (Buffer == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		return waitForCompletion(Handle, Buffer, Timeout);
	}

	/**
	 * Wait for completion of a pending read or write operation.
	 * <p>
	 * After a buffer was submitted to the USBIO device driver by means of
	 * {@link de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf) read} or {@link de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf) write}
	 * this function is used to wait for the completion of the data transfer.
	 * Note that WaitForCompletion can be called regardless of the return status
	 * of the {@link de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf) read} or {@link de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf) write} function.
	 * It returns always the correct status of the buffer.
	 * <p>
	 * The timeout interval for the wait operation is INFINITE.
	 * <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 Buffer Reference to the buffer descriptor that has been submitted by means of
	 * {@link de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf) read} or {@link de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf) write}.
	 *
	 * @return It returns USBIO_ERR_ADDITIONAL_EVENT_SIGNALLED if an additional event object
	 * has been specified and this event was signalled before the buffer completed or
	 * the timeout interval elapsed.
	 * If the read or write operation has been finished the return value is
	 * the final completion status of the operation.
	 * Note that the Status member of Buffer will also be
	 * set to the final completion status in this case.
	 * The completion status is 0 if the read or write operation has been successfully
	 * finished, an USBIO error code otherwise.
	 *
	 * @see de.thesycon.usbio.UsbIoPipe#bind(int, byte, int, String)
	 * @see de.thesycon.usbio.UsbIoPipe#read(UsbIoBuf)
	 * @see de.thesycon.usbio.UsbIoPipe#write(UsbIoBuf)
	*/
	public int waitForCompletion(UsbIoBuf Buffer) {
		if (Buffer == null) {
			return USBIO_ERR_INVALID_PARAM;
		}
		return waitForCompletion(Handle, Buffer, INFINITE);
	}
}