diff options
author | Daniel Drake <dsd@gentoo.org> | 2008-08-27 22:44:24 -0500 |
---|---|---|
committer | Daniel Drake <dsd@gentoo.org> | 2008-08-27 22:44:24 -0500 |
commit | 94936cbcfe3f02eb65c8b91e29896604316259d8 (patch) | |
tree | 18893d0f3558dc03812ede8ce605d8c9047d51d3 | |
parent | 2f8f1b1a900f5b9828e5e2ff93c2b26a44fd9de2 (diff) | |
download | libusb-94936cbcfe3f02eb65c8b91e29896604316259d8.tar.gz |
Async I/O documentation touchups
-rw-r--r-- | libusb/io.c | 19 | ||||
-rw-r--r-- | libusb/libusb.h | 5 |
2 files changed, 18 insertions, 6 deletions
diff --git a/libusb/io.c b/libusb/io.c index ab36bf9..50033ca 100644 --- a/libusb/io.c +++ b/libusb/io.c @@ -231,11 +231,14 @@ if (r == 0 && actual_length == sizeof(data)) { * \section asynctrf Asynchronous transfers * * We can view asynchronous I/O as a 5 step process: - * -# Allocation - * -# Filling - * -# Submission - * -# Completion handling - * -# Deallocation + * -# <b>Allocation</b>: allocate a libusb_transfer + * -# <b>Filling</b>: populate the libusb_transfer instance with information + * about the transfer you wish to perform + * -# <b>Submission</b>: ask libusb to submit the transfer + * -# <b>Completion handling</b>: examine transfer results in the + * libusb_transfer structure + * -# <b>Deallocation</b>: clean up resources + * * * \subsection asyncalloc Allocation * @@ -276,6 +279,12 @@ if (r == 0 && actual_length == sizeof(data)) { * be invoked. It is up to the callback function to determine which of the * above actually happened and to act accordingly. * + * The user-specified callback is passed a pointer to the libusb_transfer + * structure which was used to setup and submit the transfer. At completion + * time, libusb has populated this structure with results of the transfer: + * success or failure reason, number of bytes of data transferred, etc. See + * the libusb_transfer structure documentation for more information. + * * \subsection Deallocation * * When a transfer has completed (i.e. the callback function has been invoked), diff --git a/libusb/libusb.h b/libusb/libusb.h index d2b0972..fedd624 100644 --- a/libusb/libusb.h +++ b/libusb/libusb.h @@ -693,7 +693,10 @@ struct libusb_transfer; typedef void (*libusb_transfer_cb_fn)(struct libusb_transfer *transfer); /** \ingroup asyncio - * The generic USB transfer structure. + * The generic USB transfer structure. The user populates this structure and + * then submits it in order to request a transfer. After the transfer has + * completed, the library populates the transfer with the results and passes + * it back to the user. */ struct libusb_transfer { /** Handle of the device that this transfer will be submitted to */ |