From f1fafe8ac76f3c8bf7fdd8dcf7f5cbe414bf3cdf Mon Sep 17 00:00:00 2001 From: Martin Ling Date: Sat, 9 Apr 2022 10:22:01 +0100 Subject: 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 --- libusb/io.c | 20 ++++++++++++++++++++ libusb/version_nano.h | 2 +- 2 files changed, 21 insertions(+), 1 deletion(-) 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 -- cgit v1.2.1