diff options
| author | Martin Ling <martin-git@earth.li> | 2022-04-09 10:22:01 +0100 |
|---|---|---|
| committer | Tormod Volden <debian.tormod@gmail.com> | 2022-04-09 12:34:05 +0200 |
| commit | f1fafe8ac76f3c8bf7fdd8dcf7f5cbe414bf3cdf (patch) | |
| tree | f5fb2ecb093b057a7ae1e021424963d86bf3db6c | |
| parent | ff05357a839dd1f65caf736ded2476eaa135fe06 (diff) | |
| download | libusb-f1fafe8ac76f3c8bf7fdd8dcf7f5cbe414bf3cdf.tar.gz | |
darwin: Document OS-specific behaviour of libusb_cancel_transfer
The behaviour of libusb_cancel_transfer is different on Darwin:
- Cancellation cancels all transfers on the same endpoint.
- A ClearFeature(ENDPOINT_HALT) request is sent after cancellation.
This documents both differences and their implications.
Fixes #1110
Closes #1121
| -rw-r--r-- | libusb/io.c | 20 | ||||
| -rw-r--r-- | libusb/version_nano.h | 2 |
2 files changed, 21 insertions, 1 deletions
diff --git a/libusb/io.c b/libusb/io.c index b919e9d..9e3146c 100644 --- a/libusb/io.c +++ b/libusb/io.c @@ -1576,6 +1576,26 @@ int API_EXPORTED libusb_submit_transfer(struct libusb_transfer *transfer) * \ref libusb_transfer_status::LIBUSB_TRANSFER_CANCELLED * "LIBUSB_TRANSFER_CANCELLED." * + * This function behaves differently on Darwin-based systems (macOS and iOS): + * + * - Calling this function for one transfer will cause all transfers on the + * same endpoint to be cancelled. Your callback function will be invoked with + * a transfer status of + * \ref libusb_transfer_status::LIBUSB_TRANSFER_CANCELLED + * "LIBUSB_TRANSFER_CANCELLED" for each transfer that was cancelled. + + * - Calling this function also sends a \c ClearFeature(ENDPOINT_HALT) request + * for the transfer's endpoint. If the device does not handle this request + * correctly, the data toggle bits for the endpoint can be left out of sync + * between host and device, which can have unpredictable results when the + * next data is sent on the endpoint, including data being silently lost. + * A call to \ref libusb_clear_halt will not resolve this situation, since + * that function uses the same request. Therefore, if your program runs on + * Darwin and uses a device that does not correctly implement + * \c ClearFeature(ENDPOINT_HALT) requests, it may only be safe to cancel + * transfers when followed by a device reset using + * \ref libusb_reset_device. + * * \param transfer the transfer to cancel * \returns 0 on success * \returns LIBUSB_ERROR_NOT_FOUND if the transfer is not in progress, diff --git a/libusb/version_nano.h b/libusb/version_nano.h index 30dad67..0f40741 100644 --- a/libusb/version_nano.h +++ b/libusb/version_nano.h @@ -1 +1 @@ -#define LIBUSB_NANO 11722 +#define LIBUSB_NANO 11723 |