From b4c18fac65a594502eec5edd2611d5953e7950f7 Mon Sep 17 00:00:00 2001 From: Pete Batard Date: Wed, 3 Jul 2013 22:41:55 +0100 Subject: [PATCH] Doc: update hotplug, topology and descriptor documentation * Also fix some typos * Closes #95 --- libusb/core.c | 21 +++++++++++++++------ libusb/descriptor.c | 3 +++ libusb/hotplug.c | 20 ++++++++++++++------ libusb/libusb.h | 6 +++--- libusb/version_nano.h | 2 +- 5 files changed, 36 insertions(+), 16 deletions(-) diff --git a/libusb/core.c b/libusb/core.c index 0795597..e29e8df 100644 --- a/libusb/core.c +++ b/libusb/core.c @@ -97,7 +97,7 @@ struct list_head active_contexts_list; * usually won't need to thread) * - Lightweight with lean API * - Compatible with libusb-0.1 through the libusb-compat-0.1 translation layer - * - Hotplug support (see \ref hotplug) + * - Hotplug support (on some platforms). See \ref hotplug. * * \section gettingstarted Getting Started * @@ -737,7 +737,16 @@ uint8_t API_EXPORTED libusb_get_bus_number(libusb_device *dev) } /** \ingroup dev - * Get the number of the port that a device is connected to + * Get the number of the port that a device is connected to. + * Unless the OS does something funky, or you are hot-plugging USB extension cards, + * the port number returned by this call is usually guaranteed to be uniquely tied + * to a physical port, meaning that different devices plugged on the same physical + * port should return the same port number. + * + * But outside of this, there is no guarantee that the port number returned by this + * call will remain the same, or even match the order in which ports have been + * numbered by the HUB/HCD manufacturer. + * * \param dev a device * \returns the port number (0 if not available) */ @@ -792,12 +801,12 @@ int API_EXPORTED libusb_get_port_path(libusb_context *ctx, libusb_device *dev, } /** \ingroup dev - * Get the the parent from the specified device [EXPERIMENTAL] + * Get the the parent from the specified device. * \param dev a device * \returns the device parent or NULL if not available - * You should issue a libusb_get_device_list() before calling this + * You should issue a \ref libusb_get_device_list() before calling this * function and make sure that you only access the parent before issuing - * libusb_free_device_list(). The reason is that libusbx currently does + * \ref libusb_free_device_list(). The reason is that libusbx currently does * not maintain a permanent list of device instances, and therefore can * only guarantee that parents are fully instantiated within a * libusb_get_device_list() - libusb_free_device_list() block. @@ -897,7 +906,7 @@ int API_EXPORTED libusb_get_max_packet_size(libusb_device *dev, * Calculate the maximum packet size which a specific endpoint is capable is * sending or receiving in the duration of 1 microframe * - * Only the active configution is examined. The calculation is based on the + * Only the active configuration is examined. The calculation is based on the * wMaxPacketSize field in the endpoint descriptor as described in section * 9.6.6 in the USB 2.0 specifications. * diff --git a/libusb/descriptor.c b/libusb/descriptor.c index ec5c344..ba6d146 100644 --- a/libusb/descriptor.c +++ b/libusb/descriptor.c @@ -541,6 +541,9 @@ int usbi_device_cache_descriptor(libusb_device *dev) * * This is a non-blocking function; the device descriptor is cached in memory. * + * Note since libusbx-1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102, this + * function always succeeds. + * * \param dev the device * \param desc output location for the descriptor data * \returns 0 on success or a LIBUSB_ERROR code on failure diff --git a/libusb/hotplug.c b/libusb/hotplug.c index 77ccb31..4bc4cbd 100644 --- a/libusb/hotplug.c +++ b/libusb/hotplug.c @@ -35,25 +35,33 @@ /** * @defgroup hotplug Device hotplug event notification - * This page details how to use the libusb hotplug interface. + * This page details how to use the libusb hotplug interface, where available. + * + * Be mindful that not all platforms currently implement hotplug notification and + * that you should first call on \ref libusb_has_capability() with parameter + * \ref LIBUSB_CAP_HAS_HOTPLUG to confirm that hotplug support is available. * * \page hotplug Device hotplug event notification * * \section intro Introduction * * Version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102, has added support - * for hotplug events. This interface allows you to request notification for - * the arrival and departure of matching USB devices. + * for hotplug events on some platforms (you should test if your platform + * supports hotplug notification by calling \ref libusb_has_capability() with + * parameter \ref LIBUSB_CAP_HAS_HOTPLUG). + * + * This interface allows you to request notification for the arrival and departure + * of matching USB devices. * * To receive hotplug notification you register a callback by calling - * libusb_hotplug_register_callback(). This function will optionally return - * a handle that can be passed to libusb_hotplug_deregister_callback(). + * \ref libusb_hotplug_register_callback(). This function will optionally return + * a handle that can be passed to \ref libusb_hotplug_deregister_callback(). * * A callback function must return an int (0 or 1) indicating whether the callback is * expecting additional events. Returning 0 will rearm the callback and 1 will cause * the callback to be deregistered. * - * Callbacks for a particulat context are automatically deregistered by libusb_exit(). + * Callbacks for a particular context are automatically deregistered by libusb_exit(). * * As of 1.0.16 there are two supported hotplug events: * - LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use diff --git a/libusb/libusb.h b/libusb/libusb.h index 5e1c23c..e8e1201 100644 --- a/libusb/libusb.h +++ b/libusb/libusb.h @@ -1260,14 +1260,14 @@ struct libusb_transfer { }; /** \ingroup misc - * Capabilities supported by this instance of libusb. Test if the loaded - * library supports a given capability by calling + * Capabilities supported by an instance of libusb on the current running + * platform. Test if the loaded library supports a given capability by calling * \ref libusb_has_capability(). */ enum libusb_capability { /** The libusb_has_capability() API is available. */ LIBUSB_CAP_HAS_CAPABILITY = 0x0000, - /** Hotplug support is available. */ + /** Hotplug support is available on this platform. */ LIBUSB_CAP_HAS_HOTPLUG = 0x0001, /** The library can access HID devices without requiring user intervention. * Note that before being able to actually access an HID device, you may diff --git a/libusb/version_nano.h b/libusb/version_nano.h index cfcd51f..88625ac 100644 --- a/libusb/version_nano.h +++ b/libusb/version_nano.h @@ -1 +1 @@ -#define LIBUSB_NANO 10767 +#define LIBUSB_NANO 10768 -- 2.7.4