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
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 @@
* \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
