|
| Home |
|
|
Pipe I/OClients communicate with a device's endpoint using pipes. A pipe to an endpoint is created with function RTUOpenPipe. All required pipes should be opened in or after the RTUConnect event of the attachment/detachment callback after RTUClaimInterface has been called. Function RTUClosePipe closes a pipe and invalidates the specified pipe handle. With RTUSB-32, I/O transactions on Control endpoints are always synchronous. Function RTUSendSetup can be used to perform a complete two stage or three stage Control transaction. The default timeout period for Control transactions is defined in global configuration structure RTUSBConfig (1 second by default) and can be changed for each pipe using RTUSetPipeOption. I/O on all other endpoint types (Bulk, Interrupt, and Isochronous) is asynchronous and the application can choose how it should be notified about the completion of a transaction. RTUSB-32 supports notification modes Asynch, Message, and Callback, with Asynch being the default. Regardless of the selected notification mode, all I/O operations are started with function RTUStartIO, which returns immediately without waiting for the transaction to complete. Several I/O transactions can be started on one or several pipes before any previous transactions have completed. How an application is notified of a transaction completion depends on the notification mode of the respective pipe: Asynch notification requires an application to call RTUIOWait or RTUIOWaitTimed to detect the completion of a transaction. These functions wait until the next transaction on the given pipe completes (either successfully or with an error). Unlike RTUIOWait, RTUIOWaitTimed can return error code RTU_TIMEOUT, which is not a real error but only means that no transaction has completed within the given timeout period. It may well complete at a later time if the application does not call RTUCancelIO. RTUIOWaitTimed does not automatically cancel transactions if it times out. Asynch pipes have an additional property: delayed pipe deallocation. When RTUClosePipe is called to close an asynch pipe, and I/O transactions are still pending, the pipe and its associated device continue to exist until all transactions have completed and all notifications have been retrieved with RTUIOWait or RTUIOWaitTimed. This ensures that no pipes and devices are deallocated while a client is still working with them. Message notification must be enabled by calling RTUSetPipeMsgQ after the pipe has been opened and before it is used for I/O the first time. For such pipes, RTUSB-32 sends a message to a message queue which must be maintained (created, read, destroyed) by the application. Message queues can be maintained with functions such as RTUCreateMsgQ, RTUDeleteMsgQ, RTUGetMsgQ, and RTUGetMsgQTimed. The actual messages are pointers to structures of type RTUSBMessage. Once a USB client has processed a message, it must free it using RTUFreeBuffer. Callback notification is enabled by calling RTUSetPipeCallback after the pipe has been opened and before it is used for I/O the first time. When a transaction completes on a callback notification pipe, the respective callback is called by the interrupt handler of the host controller driver. This notification method has the best real-time characteristics, but should be used with care. The callback must adhere to any restrictions applicable to interrupt service routines. Note that RTUSB-32 API functions such as RTUStartIO may not be called from interrupt service routines. Please note that transactions on Isochronous endpoints exhibit a few subtle differences to other transfer types. See section Isochronous Transfers in chapter Advanced Topics for further details.
|
