summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChris Dickens <christopher.a.dickens@gmail.com>2016-02-24 01:07:20 -0800
committerChris Dickens <christopher.a.dickens@gmail.com>2016-02-24 01:07:20 -0800
commit7ee92df12adb8015451aaecfeccd7dd62cc2314e (patch)
tree69aa53a859edd88b6a79fa21fb2b9f02e35aba4d
parent8a0c14372f98d56529556f18126a42fda2ab0137 (diff)
downloadlibusb-7ee92df12adb8015451aaecfeccd7dd62cc2314e.tar.gz
Misc: Prefix doxygen references in order to namespace libusb
This change add "libusb_" to every group and page definition (and updates all references accordingly) so that generated man pages are namespaced for libusb, thus avoiding possible conflict with other packages. Closes #131 Signed-off-by: Chris Dickens <christopher.a.dickens@gmail.com>
-rw-r--r--libusb/core.c96
-rw-r--r--libusb/descriptor.c34
-rw-r--r--libusb/hotplug.c8
-rw-r--r--libusb/io.c122
-rw-r--r--libusb/libusb.h138
-rw-r--r--libusb/strerror.c6
-rw-r--r--libusb/sync.c14
-rw-r--r--libusb/version_nano.h2
8 files changed, 210 insertions, 210 deletions
diff --git a/libusb/core.c b/libusb/core.c
index 4d6d377..9d64794 100644
--- a/libusb/core.c
+++ b/libusb/core.c
@@ -102,7 +102,7 @@ struct list_head active_contexts_list;
*
* \section API Application Programming Interface (API)
*
- * See the \ref api page for a complete list of the libusb functions.
+ * See the \ref libusb_api page for a complete list of the libusb functions.
*
* \section features Library features
*
@@ -114,7 +114,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 (on some platforms). See \ref hotplug.
+ * - Hotplug support (on some platforms). See \ref libusb_hotplug.
*
* \section gettingstarted Getting Started
*
@@ -122,7 +122,7 @@ struct list_head active_contexts_list;
* links to the different categories of libusb's functionality.
*
* One decision you will have to make is whether to use the synchronous
- * or the asynchronous data transfer interface. The \ref io documentation
+ * or the asynchronous data transfer interface. The \ref libusb_io documentation
* provides some insight into this topic.
*
* Some example programs can be found in the libusb source distribution under
@@ -133,7 +133,7 @@ struct list_head active_contexts_list;
*
* libusb functions typically return 0 on success or a negative error code
* on failure. These negative error codes relate to LIBUSB_ERROR constants
- * which are listed on the \ref misc "miscellaneous" documentation page.
+ * which are listed on the \ref libusb_misc "miscellaneous" documentation page.
*
* \section msglog Debug message logging
*
@@ -178,12 +178,12 @@ struct list_head active_contexts_list;
*
* \section remarks Other remarks
*
- * libusb does have imperfections. The \ref caveats "caveats" page attempts
+ * libusb does have imperfections. The \ref libusb_caveats "caveats" page attempts
* to document these.
*/
/**
- * \page caveats Caveats
+ * \page libusb_caveats Caveats
*
* \section devresets Device resets
*
@@ -299,7 +299,7 @@ if (cfg != desired)
*/
/**
- * \page contexts Contexts
+ * \page libusb_contexts Contexts
*
* It is possible that libusb may be used simultaneously from two independent
* libraries linked into the same executable. For example, if your application
@@ -338,7 +338,7 @@ if (cfg != desired)
*/
/**
- * \page api Application Programming Interface
+ * \page libusb_api Application Programming Interface
*
* This is the complete list of libusb functions, structures and
* enumerations in alphabetical order.
@@ -486,14 +486,14 @@ if (cfg != desired)
*/
/**
- * @defgroup lib Library initialization/deinitialization
+ * @defgroup libusb_lib Library initialization/deinitialization
* This page details how to initialize and deinitialize libusb. Initialization
* must be performed before using any libusb functionality, and similarly you
* must not call any libusb functions after deinitialization.
*/
/**
- * @defgroup dev Device handling and enumeration
+ * @defgroup libusb_dev Device handling and enumeration
* The functionality documented below is designed to help with the following
* operations:
* - Enumerating the USB devices currently attached to the system
@@ -603,7 +603,7 @@ libusb_free_device_list(list, 1);
* libusb_close().
*/
-/** @defgroup misc Miscellaneous */
+/** @defgroup libusb_misc Miscellaneous */
/* we traverse usbfs without knowing how many devices we are going to find.
* so we create this discovered_devs model which is similar to a linked-list
@@ -775,7 +775,7 @@ struct libusb_device *usbi_get_device_by_session_id(struct libusb_context *ctx,
return ret;
}
-/** @ingroup dev
+/** @ingroup libusb_dev
* Returns a list of USB devices currently attached to the system. This is
* your entry point into finding a USB device to operate.
*
@@ -855,7 +855,7 @@ out:
return len;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Frees a list of devices previously discovered using
* libusb_get_device_list(). If the unref_devices parameter is set, the
* reference count of each device in the list is decremented by 1.
@@ -878,7 +878,7 @@ void API_EXPORTED libusb_free_device_list(libusb_device **list,
free(list);
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Get the number of the bus that a device is connected to.
* \param dev a device
* \returns the bus number
@@ -888,7 +888,7 @@ uint8_t API_EXPORTED libusb_get_bus_number(libusb_device *dev)
return dev->bus_number;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* 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
@@ -907,7 +907,7 @@ uint8_t API_EXPORTED libusb_get_port_number(libusb_device *dev)
return dev->port_number;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Get the list of all port numbers from root for the specified device
*
* Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
@@ -941,7 +941,7 @@ int API_EXPORTED libusb_get_port_numbers(libusb_device *dev,
return port_numbers_len - i;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Deprecated please use libusb_get_port_numbers instead.
*/
int API_EXPORTED libusb_get_port_path(libusb_context *ctx, libusb_device *dev,
@@ -952,7 +952,7 @@ int API_EXPORTED libusb_get_port_path(libusb_context *ctx, libusb_device *dev,
return libusb_get_port_numbers(dev, port_numbers, port_numbers_len);
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Get the the parent from the specified device.
* \param dev a device
* \returns the device parent or NULL if not available
@@ -969,7 +969,7 @@ libusb_device * LIBUSB_CALL libusb_get_parent(libusb_device *dev)
return dev->parent_dev;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Get the address of the device on the bus it is connected to.
* \param dev a device
* \returns the device address
@@ -979,7 +979,7 @@ uint8_t API_EXPORTED libusb_get_device_address(libusb_device *dev)
return dev->device_address;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Get the negotiated connection speed for a device.
* \param dev a device
* \returns a \ref libusb_speed code, where LIBUSB_SPEED_UNKNOWN means that
@@ -1015,7 +1015,7 @@ static const struct libusb_endpoint_descriptor *find_endpoint(
return NULL;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Convenience function to retrieve the wMaxPacketSize value for a particular
* endpoint in the active device configuration.
*
@@ -1058,7 +1058,7 @@ out:
return r;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Calculate the maximum packet size which a specific endpoint is capable is
* sending or receiving in the duration of 1 microframe
*
@@ -1119,7 +1119,7 @@ out:
return r;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Increment the reference count of a device.
* \param dev the device to reference
* \returns the same device
@@ -1133,7 +1133,7 @@ libusb_device * LIBUSB_CALL libusb_ref_device(libusb_device *dev)
return dev;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Decrement the reference count of a device. If the decrement operation
* causes the reference count to reach zero, the device shall be destroyed.
* \param dev the device to unreference
@@ -1205,7 +1205,7 @@ int usbi_clear_event(struct libusb_context *ctx)
return 0;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Open a device and obtain a device handle. A handle allows you to perform
* I/O on the device in question.
*
@@ -1269,7 +1269,7 @@ int API_EXPORTED libusb_open(libusb_device *dev,
return 0;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Convenience function for finding a device with a particular
* <tt>idVendor</tt>/<tt>idProduct</tt> combination. This function is intended
* for those scenarios where you are using libusb to knock up a quick test
@@ -1379,7 +1379,7 @@ static void do_close(struct libusb_context *ctx,
free(dev_handle);
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Close a device handle. Should be called on all open handles before your
* application exits.
*
@@ -1435,7 +1435,7 @@ void API_EXPORTED libusb_close(libusb_device_handle *dev_handle)
libusb_unlock_events(ctx);
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Get the underlying device for a device handle. This function does not modify
* the reference count of the returned device, so do not feel compelled to
* unreference it when you are done.
@@ -1448,7 +1448,7 @@ libusb_device * LIBUSB_CALL libusb_get_device(libusb_device_handle *dev_handle)
return dev_handle->dev;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Determine the bConfigurationValue of the currently active configuration.
*
* You could formulate your own control request to obtain this information,
@@ -1499,7 +1499,7 @@ int API_EXPORTED libusb_get_configuration(libusb_device_handle *dev_handle,
return r;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Set the active configuration for a device.
*
* The operating system may or may not have already set an active
@@ -1553,7 +1553,7 @@ int API_EXPORTED libusb_set_configuration(libusb_device_handle *dev_handle,
return usbi_backend->set_configuration(dev_handle, configuration);
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Claim an interface on a given device handle. You must claim the interface
* you wish to use before you can perform I/O on any of its endpoints.
*
@@ -1606,7 +1606,7 @@ out:
return r;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Release an interface previously claimed with libusb_claim_interface(). You
* should release all claimed interfaces before closing a device handle.
*
@@ -1649,7 +1649,7 @@ out:
return r;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Activate an alternate setting for an interface. The interface must have
* been previously claimed with libusb_claim_interface().
*
@@ -1694,7 +1694,7 @@ int API_EXPORTED libusb_set_interface_alt_setting(libusb_device_handle *dev_hand
alternate_setting);
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Clear the halt/stall condition for an endpoint. Endpoints with halt status
* are unable to receive or transmit data until the halt condition is stalled.
*
@@ -1720,7 +1720,7 @@ int API_EXPORTED libusb_clear_halt(libusb_device_handle *dev_handle,
return usbi_backend->clear_halt(dev_handle, endpoint);
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Perform a USB port reset to reinitialize a device. The system will attempt
* to restore the previous configuration and alternate settings after the
* reset has completed.
@@ -1748,7 +1748,7 @@ int API_EXPORTED libusb_reset_device(libusb_device_handle *dev_handle)
return usbi_backend->reset_device(dev_handle);
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Allocate up to num_streams usb bulk streams on the specified endpoints. This
* function takes an array of endpoints rather then a single endpoint because
* some protocols require that endpoints are setup with similar stream ids.
@@ -1784,7 +1784,7 @@ int API_EXPORTED libusb_alloc_streams(libusb_device_handle *dev_handle,
return LIBUSB_ERROR_NOT_SUPPORTED;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Free usb bulk streams allocated with libusb_alloc_streams().
*
* Note streams are automatically free-ed when releasing an interface.
@@ -1811,7 +1811,7 @@ int API_EXPORTED libusb_free_streams(libusb_device_handle *dev_handle,
return LIBUSB_ERROR_NOT_SUPPORTED;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Determine if a kernel driver is active on an interface. If a kernel driver
* is active, you cannot claim the interface, and libusb will be unable to
* perform I/O.
@@ -1842,7 +1842,7 @@ int API_EXPORTED libusb_kernel_driver_active(libusb_device_handle *dev_handle,
return LIBUSB_ERROR_NOT_SUPPORTED;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Detach a kernel driver from an interface. If successful, you will then be
* able to claim the interface and perform I/O.
*
@@ -1877,7 +1877,7 @@ int API_EXPORTED libusb_detach_kernel_driver(libusb_device_handle *dev_handle,
return LIBUSB_ERROR_NOT_SUPPORTED;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Re-attach an interface's kernel driver, which was previously detached
* using libusb_detach_kernel_driver(). This call is only effective on
* Linux and returns LIBUSB_ERROR_NOT_SUPPORTED on all other platforms.
@@ -1911,7 +1911,7 @@ int API_EXPORTED libusb_attach_kernel_driver(libusb_device_handle *dev_handle,
return LIBUSB_ERROR_NOT_SUPPORTED;
}
-/** \ingroup dev
+/** \ingroup libusb_dev
* Enable/disable libusb's automatic kernel driver detachment. When this is
* enabled libusb will automatically detach the kernel driver on an interface
* when claiming the interface, and attach it when releasing the interface.
@@ -1943,7 +1943,7 @@ int API_EXPORTED libusb_set_auto_detach_kernel_driver(
return LIBUSB_SUCCESS;
}
-/** \ingroup lib
+/** \ingroup libusb_lib
* Set log message verbosity.
*
* The default level is LIBUSB_LOG_LEVEL_NONE, which means no messages are ever
@@ -1975,7 +1975,7 @@ void API_EXPORTED libusb_set_debug(libusb_context *ctx, int level)
ctx->debug = level;
}
-/** \ingroup lib
+/** \ingroup libusb_lib
* Initialize libusb. This function must be called before calling any other
* libusb function.
*
@@ -1986,7 +1986,7 @@ void API_EXPORTED libusb_set_debug(libusb_context *ctx, int level)
* \param context Optional output location for context pointer.
* Only valid on return code 0.
* \returns 0 on success, or a LIBUSB_ERROR code on failure
- * \see contexts
+ * \see libusb_contexts
*/
int API_EXPORTED libusb_init(libusb_context **context)
{
@@ -2097,7 +2097,7 @@ err_unlock:
return r;
}
-/** \ingroup lib
+/** \ingroup libusb_lib
* Deinitialize libusb. Should be called after closing all open devices and
* before your application terminates.
* \param ctx the context to deinitialize, or NULL for the default context
@@ -2168,7 +2168,7 @@ void API_EXPORTED libusb_exit(struct libusb_context *ctx)
free(ctx);
}
-/** \ingroup misc
+/** \ingroup libusb_misc
* Check at runtime if the loaded library has a given capability.
* This call should be performed after \ref libusb_init(), to ensure the
* backend has updated its capability set.
@@ -2390,7 +2390,7 @@ void usbi_log(struct libusb_context *ctx, enum libusb_log_level level,
va_end (args);
}
-/** \ingroup misc
+/** \ingroup libusb_misc
* Returns a constant NULL-terminated string with the ASCII name of a libusb
* error or transfer status code. The caller must not free() the returned
* string.
@@ -2450,7 +2450,7 @@ DEFAULT_VISIBILITY const char * LIBUSB_CALL libusb_error_name(int error_code)
}
}
-/** \ingroup misc
+/** \ingroup libusb_misc
* Returns a pointer to const struct libusb_version with the version
* (major, minor, micro, nano and rc) of the running library.
*/
diff --git a/libusb/descriptor.c b/libusb/descriptor.c
index 402c91d..ccf7fe4 100644
--- a/libusb/descriptor.c
+++ b/libusb/descriptor.c
@@ -35,7 +35,7 @@
#define ENDPOINT_DESC_LENGTH 7
#define ENDPOINT_AUDIO_DESC_LENGTH 9
-/** @defgroup desc USB descriptors
+/** @defgroup libusb_desc USB descriptors
* This page details how to examine the various standard USB descriptors
* for detected devices
*/
@@ -532,7 +532,7 @@ int usbi_device_cache_descriptor(libusb_device *dev)
return LIBUSB_SUCCESS;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Get the USB device descriptor for a given device.
*
* This is a non-blocking function; the device descriptor is cached in memory.
@@ -553,7 +553,7 @@ int API_EXPORTED libusb_get_device_descriptor(libusb_device *dev,
return 0;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Get the USB configuration descriptor for the currently active configuration.
* This is a non-blocking function which does not involve any requests being
* sent to the device.
@@ -600,7 +600,7 @@ int API_EXPORTED libusb_get_active_config_descriptor(libusb_device *dev,
return r;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Get a USB configuration descriptor based on its index.
* This is a non-blocking function which does not involve any requests being
* sent to the device.
@@ -683,7 +683,7 @@ int usbi_get_config_index_by_value(struct libusb_device *dev,
return 0;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Get a USB configuration descriptor with a specific bConfigurationValue.
* This is a non-blocking function which does not involve any requests being
* sent to the device.
@@ -723,7 +723,7 @@ int API_EXPORTED libusb_get_config_descriptor_by_value(libusb_device *dev,
return libusb_get_config_descriptor(dev, (uint8_t) idx, config);
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Free a configuration descriptor obtained from
* libusb_get_active_config_descriptor() or libusb_get_config_descriptor().
* It is safe to call this function with a NULL config parameter, in which
@@ -741,7 +741,7 @@ void API_EXPORTED libusb_free_config_descriptor(
free(config);
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Get an endpoints superspeed endpoint companion descriptor (if any)
*
* \param ctx the context to operate on, or NULL for the default context
@@ -791,7 +791,7 @@ int API_EXPORTED libusb_get_ss_endpoint_companion_descriptor(
return LIBUSB_ERROR_NOT_FOUND;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Free a superspeed endpoint companion descriptor obtained from
* libusb_get_ss_endpoint_companion_descriptor().
* It is safe to call this function with a NULL ep_comp parameter, in which
@@ -884,7 +884,7 @@ static int parse_bos(struct libusb_context *ctx,
return LIBUSB_SUCCESS;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Get a Binary Object Store (BOS) descriptor
* This is a BLOCKING function, which will send requests to the device.
*
@@ -937,7 +937,7 @@ int API_EXPORTED libusb_get_bos_descriptor(libusb_device_handle *dev_handle,
return r;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Free a BOS descriptor obtained from libusb_get_bos_descriptor().
* It is safe to call this function with a NULL bos parameter, in which
* case the function simply returns.
@@ -956,7 +956,7 @@ void API_EXPORTED libusb_free_bos_descriptor(struct libusb_bos_descriptor *bos)
free(bos);
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Get an USB 2.0 Extension descriptor
*
* \param ctx the context to operate on, or NULL for the default context
@@ -1000,7 +1000,7 @@ int API_EXPORTED libusb_get_usb_2_0_extension_descriptor(
return LIBUSB_SUCCESS;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Free a USB 2.0 Extension descriptor obtained from
* libusb_get_usb_2_0_extension_descriptor().
* It is safe to call this function with a NULL usb_2_0_extension parameter,
@@ -1014,7 +1014,7 @@ void API_EXPORTED libusb_free_usb_2_0_extension_descriptor(
free(usb_2_0_extension);
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Get a SuperSpeed USB Device Capability descriptor
*
* \param ctx the context to operate on, or NULL for the default context
@@ -1058,7 +1058,7 @@ int API_EXPORTED libusb_get_ss_usb_device_capability_descriptor(
return LIBUSB_SUCCESS;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Free a SuperSpeed USB Device Capability descriptor obtained from
* libusb_get_ss_usb_device_capability_descriptor().
* It is safe to call this function with a NULL ss_usb_device_cap
@@ -1072,7 +1072,7 @@ void API_EXPORTED libusb_free_ss_usb_device_capability_descriptor(
free(ss_usb_device_cap);
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Get a Container ID descriptor
*
* \param ctx the context to operate on, or NULL for the default context
@@ -1115,7 +1115,7 @@ int API_EXPORTED libusb_get_container_id_descriptor(struct libusb_context *ctx,
return LIBUSB_SUCCESS;
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Free a Container ID descriptor obtained from
* libusb_get_container_id_descriptor().
* It is safe to call this function with a NULL container_id parameter,
@@ -1129,7 +1129,7 @@ void API_EXPORTED libusb_free_container_id_descriptor(
free(container_id);
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Retrieve a string descriptor in C style ASCII.
*
* Wrapper around libusb_get_string_descriptor(). Uses the first language
diff --git a/libusb/hotplug.c b/libusb/hotplug.c
index 85d44af..5db8d0b 100644
--- a/libusb/hotplug.c
+++ b/libusb/hotplug.c
@@ -34,14 +34,14 @@
#include "hotplug.h"
/**
- * @defgroup hotplug Device hotplug event notification
+ * @defgroup libusb_hotplug Device hotplug event notification
* 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
+ * \page libusb_hotplug Device hotplug event notification
*
* \section hotplug_intro Introduction
*
@@ -83,8 +83,8 @@
* safe to call any libusb function that takes a libusb_device. It also safe to
* open a device and submit asynchronous transfers. However, most other functions
* that take a libusb_device_handle are <b>not</b> safe to call. Examples of such
- * functions are any of the \ref syncio "synchronous API" functions or the blocking
- * functions that retrieve various \ref desc "USB descriptors". These functions must
+ * functions are any of the \ref libusb_syncio "synchronous API" functions or the blocking
+ * functions that retrieve various \ref libusb_desc "USB descriptors". These functions must
* be used outside of the context of the hotplug callback.
*
* When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function
diff --git a/libusb/io.c b/libusb/io.c
index 908acfd..74dba4b 100644
--- a/libusb/io.c
+++ b/libusb/io.c
@@ -41,7 +41,7 @@
#include "hotplug.h"
/**
- * \page io Synchronous and asynchronous device I/O
+ * \page libusb_io Synchronous and asynchronous device I/O
*
* \section io_intro Introduction
*
@@ -55,8 +55,8 @@
*
* Once you have read through the following discussion, you should consult the
* detailed API documentation pages for the details:
- * - \ref syncio
- * - \ref asyncio
+ * - \ref libusb_syncio
+ * - \ref libusb_asyncio
*
* \section theory Transfers at a logical level
*
@@ -124,7 +124,7 @@ if (r == 0 && actual_length == sizeof(data)) {
* request has been submitted.
*
* For details on how to use the synchronous API, see the
- * \ref syncio "synchronous I/O API documentation" pages.
+ * \ref libusb_syncio "synchronous I/O API documentation" pages.
*
* \section async The asynchronous interface
*
@@ -165,12 +165,12 @@ if (r == 0 && actual_length == sizeof(data)) {
* calls to the asynchronous interface.
*
* For details on how to use the asynchronous API, see the
- * \ref asyncio "asynchronous I/O API" documentation pages.
+ * \ref libusb_asyncio "asynchronous I/O API" documentation pages.
*/
/**
- * \page packetoverflow Packets and overflows
+ * \page libusb_packetoverflow Packets and overflows
*
* \section packets Packet abstraction
*
@@ -212,13 +212,13 @@ if (r == 0 && actual_length == sizeof(data)) {
*/
/**
- * @defgroup asyncio Asynchronous device I/O
+ * @defgroup libusb_asyncio Asynchronous device I/O
*
* This page details libusb's asynchronous (non-blocking) API for USB device
* I/O. This interface is very powerful but is also quite complex - you will
* need to read this page carefully to understand the necessary considerations
* and issues surrounding use of this interface. Simplistic applications
- * may wish to consider the \ref syncio "synchronous I/O API" instead.
+ * may wish to consider the \ref libusb_syncio "synchronous I/O API" instead.
*
* The asynchronous interface is built around the idea of separating transfer
* submission and handling of transfer completion (the synchronous model
@@ -296,8 +296,8 @@ if (r == 0 && actual_length == sizeof(data)) {
* <b>Important Note</b>: The user-specified callback is called from an event
* handling context. It is therefore important that no calls are made into
* libusb that will attempt to perform any event handling. Examples of such
- * functions are any listed in the \ref syncio "synchronous API" and any of
- * the blocking functions that retrieve \ref desc "USB descriptors".
+ * functions are any listed in the \ref libusb_syncio "synchronous API" and any of
+ * the blocking functions that retrieve \ref libusb_desc "USB descriptors".
*
* \subsection Deallocation
*
@@ -343,7 +343,7 @@ if (r == 0 && actual_length == sizeof(data)) {
* your application may submit a request for data on an IN endpoint which is
* smaller than the data that the device wishes to send. In some circumstances
* this will cause an overflow, which is a nasty condition to deal with. See
- * the \ref packetoverflow page for discussion.
+ * the \ref libusb_packetoverflow page for discussion.
*
* \section asyncctrl Considerations for control transfers
*
@@ -534,7 +534,7 @@ if (r == 0 && actual_length == sizeof(data)) {
* below for details.
*
* If you prefer a single threaded approach with a single central event loop,
- * see the \ref poll "polling and timing" section for how to integrate libusb
+ * see the \ref libusb_poll "polling and timing" section for how to integrate libusb
* into your application's main event loop.
*
* \section eventthread Using an event handling thread
@@ -561,7 +561,7 @@ void *event_thread_func(void *ctx)
* libusb_handle_events() will not return.
*
* There are 2 different ways of dealing with this, depending on if your
- * application uses libusb' \ref hotplug "hotplug" support or not.
+ * application uses libusb' \ref libusb_hotplug "hotplug" support or not.
*
* Applications which do not use hotplug support, should not start the event
* thread until after their first call to libusb_open(), and should stop the
@@ -586,7 +586,7 @@ void my_close_handle(libusb_device_handle *dev_handle)
* should stop the thread at program exit as follows:
\code
void my_libusb_exit(void)
-{
+{
event_thread_run = 0;
libusb_hotplug_deregister_callback(ctx, hotplug_cb_handle); // This wakes up libusb_handle_events()
pthread_join(event_thread);
@@ -596,12 +596,12 @@ void my_libusb_exit(void)
*/
/**
- * @defgroup poll Polling and timing
+ * @defgroup libusb_poll Polling and timing
*
* This page documents libusb's functions for polling events and timing.
* These functions are only necessary for users of the
- * \ref asyncio "asynchronous API". If you are only using the simpler
- * \ref syncio "synchronous API" then you do not need to ever call these
+ * \ref libusb_asyncio "asynchronous API". If you are only using the simpler
+ * \ref libusb_syncio "synchronous API" then you do not need to ever call these
* functions.
*
* The justification for the functionality described here has already been
@@ -653,7 +653,7 @@ while (user_has_not_requested_exit)
* sets of file descriptors or handling timeouts. libusb_handle_events() will
* handle those details internally.
*
- * \section pollmain The more advanced option
+ * \section libusb_pollmain The more advanced option
*
* \note This functionality is currently only available on Unix-like platforms.
* On Windows, libusb_get_pollfds() simply returns NULL. Applications which
@@ -768,10 +768,10 @@ while (user has not requested application exit) {
* entities are added to solve these problems. You do not need to be concerned
* with these entities otherwise.
*
- * See the extra documentation: \ref mtasync
+ * See the extra documentation: \ref libusb_mtasync
*/
-/** \page mtasync Multi-threaded applications and asynchronous I/O
+/** \page libusb_mtasync Multi-threaded applications and asynchronous I/O
*
* libusb is a thread-safe library, but extra considerations must be applied
* to applications which interact with libusb from multiple threads.
@@ -779,8 +779,8 @@ while (user has not requested application exit) {
* The underlying issue that must be addressed is that all libusb I/O
* revolves around monitoring file descriptors through the poll()/select()
* system calls. This is directly exposed at the
- * \ref asyncio "asynchronous interface" but it is important to note that the
- * \ref syncio "synchronous interface" is implemented on top of the
+ * \ref libusb_asyncio "asynchronous interface" but it is important to note that the
+ * \ref libusb_syncio "synchronous interface" is implemented on top of the
* asynchonrous interface, therefore the same considerations apply.
*
* The issue is that if two or more threads are concurrently calling poll()
@@ -1230,7 +1230,7 @@ static int calculate_timeout(struct usbi_transfer *transfer)
return 0;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Allocate a libusb transfer with a specified number of isochronous packet
* descriptors. The returned transfer is pre-initialized for you. When the new
* transfer is no longer needed, it should be freed with
@@ -1275,7 +1275,7 @@ struct libusb_transfer * LIBUSB_CALL libusb_alloc_transfer(
return transfer;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Free a transfer structure. This should be called for all transfers
* allocated with libusb_alloc_transfer().
*
@@ -1453,7 +1453,7 @@ static int remove_from_flying_list(struct usbi_transfer *transfer)
return r;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Submit a transfer. This function will fire off the USB transfer and then
* return immediately.
*
@@ -1528,7 +1528,7 @@ out:
return r;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Asynchronously cancel a previously submitted transfer.
* This function returns immediately, but this does not indicate cancellation
* is complete. Your callback function will be invoked at some later time
@@ -1577,7 +1577,7 @@ out:
return r;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Set a transfers bulk stream id. Note users are advised to use
* libusb_fill_bulk_stream_transfer() instead of calling this function
* directly.
@@ -1597,7 +1597,7 @@ void API_EXPORTED libusb_transfer_set_stream_id(
itransfer->stream_id = stream_id;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Get a transfers bulk stream id.
*
* Since version 1.0.19, \ref LIBUSB_API_VERSION >= 0x01000103
@@ -1699,7 +1699,7 @@ void usbi_signal_transfer_completion(struct usbi_transfer *transfer)
usbi_mutex_unlock(&ctx->event_data_lock);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Attempt to acquire the event handling lock. This lock is used to ensure that
* only one thread is monitoring libusb event sources at any one time.
*
@@ -1716,7 +1716,7 @@ void usbi_signal_transfer_completion(struct usbi_transfer *transfer)
* \param ctx the context to operate on, or NULL for the default context
* \returns 0 if the lock was obtained successfully
* \returns 1 if the lock was not obtained (i.e. another thread holds the lock)
- * \ref mtasync
+ * \ref libusb_mtasync
*/
int API_EXPORTED libusb_try_lock_events(libusb_context *ctx)
{
@@ -1742,7 +1742,7 @@ int API_EXPORTED libusb_try_lock_events(libusb_context *ctx)
return 0;
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Acquire the event handling lock, blocking until successful acquisition if
* it is contended. This lock is used to ensure that only one thread is
* monitoring libusb event sources at any one time.
@@ -1758,7 +1758,7 @@ int API_EXPORTED libusb_try_lock_events(libusb_context *ctx)
* as soon as possible.
*
* \param ctx the context to operate on, or NULL for the default context
- * \ref mtasync
+ * \ref libusb_mtasync
*/
void API_EXPORTED libusb_lock_events(libusb_context *ctx)
{
@@ -1767,13 +1767,13 @@ void API_EXPORTED libusb_lock_events(libusb_context *ctx)
ctx->event_handler_active = 1;
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Release the lock previously acquired with libusb_try_lock_events() or
* libusb_lock_events(). Releasing this lock will wake up any threads blocked
* on libusb_wait_for_event().
*
* \param ctx the context to operate on, or NULL for the default context
- * \ref mtasync
+ * \ref libusb_mtasync
*/
void API_EXPORTED libusb_unlock_events(libusb_context *ctx)
{
@@ -1789,7 +1789,7 @@ void API_EXPORTED libusb_unlock_events(libusb_context *ctx)
usbi_mutex_unlock(&ctx->event_waiters_lock);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Determine if it is still OK for this thread to be doing event handling.
*
* Sometimes, libusb needs to temporarily pause all event handlers, and this
@@ -1797,7 +1797,7 @@ void API_EXPORTED libusb_unlock_events(libusb_context *ctx)
* this is the case.
*
* If this function instructs your thread to give up the events lock, you
- * should just continue the usual logic that is documented in \ref mtasync.
+ * should just continue the usual logic that is documented in \ref libusb_mtasync.
* On the next iteration, your thread will fail to obtain the events lock,
* and will hence become an event waiter.
*
@@ -1829,14 +1829,14 @@ int API_EXPORTED libusb_event_handling_ok(libusb_context *ctx)
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Determine if an active thread is handling events (i.e. if anyone is holding
* the event handling lock).
*
* \param ctx the context to operate on, or NULL for the default context
* \returns 1 if a thread is handling events
* \returns 0 if there are no threads currently handling events
- * \ref mtasync
+ * \ref libusb_mtasync
*/
int API_EXPORTED libusb_event_handler_active(libusb_context *ctx)
{
@@ -1856,7 +1856,7 @@ int API_EXPORTED libusb_event_handler_active(libusb_context *ctx)
return ctx->event_handler_active;
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Interrupt any active thread that is handling events. This is mainly useful
* for interrupting a dedicated event handling thread when an application
* wishes to call libusb_exit().
@@ -1864,7 +1864,7 @@ int API_EXPORTED libusb_event_handler_active(libusb_context *ctx)
* Since version 1.0.21, \ref LIBUSB_API_VERSION >= 0x01000105
*
* \param ctx the context to operate on, or NULL for the default context
- * \ref mtasync
+ * \ref libusb_mtasync
*/
void API_EXPORTED libusb_interrupt_event_handler(libusb_context *ctx)
{
@@ -1879,7 +1879,7 @@ void API_EXPORTED libusb_interrupt_event_handler(libusb_context *ctx)
usbi_mutex_unlock(&ctx->event_data_lock);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Acquire the event waiters lock. This lock is designed to be obtained under
* the situation where you want to be aware when events are completed, but
* some other thread is event handling so calling libusb_handle_events() is not
@@ -1896,7 +1896,7 @@ void API_EXPORTED libusb_interrupt_event_handler(libusb_context *ctx)
* locking.
*
* \param ctx the context to operate on, or NULL for the default context
- * \ref mtasync
+ * \ref libusb_mtasync
*/
void API_EXPORTED libusb_lock_event_waiters(libusb_context *ctx)
{
@@ -1904,10 +1904,10 @@ void API_EXPORTED libusb_lock_event_waiters(libusb_context *ctx)
usbi_mutex_lock(&ctx->event_waiters_lock);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Release the event waiters lock.
* \param ctx the context to operate on, or NULL for the default context
- * \ref mtasync
+ * \ref libusb_mtasync
*/
void API_EXPORTED libusb_unlock_event_waiters(libusb_context *ctx)
{
@@ -1915,7 +1915,7 @@ void API_EXPORTED libusb_unlock_event_waiters(libusb_context *ctx)
usbi_mutex_unlock(&ctx->event_waiters_lock);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Wait for another thread to signal completion of an event. Must be called
* with the event waiters lock held, see libusb_lock_event_waiters().
*
@@ -1938,7 +1938,7 @@ void API_EXPORTED libusb_unlock_event_waiters(libusb_context *ctx)
* indicates unlimited timeout.
* \returns 0 after a transfer completes or another thread stops event handling
* \returns 1 if the timeout expired
- * \ref mtasync
+ * \ref libusb_mtasync
*/
int API_EXPORTED libusb_wait_for_event(libusb_context *ctx, struct timeval *tv)
{
@@ -2289,7 +2289,7 @@ static int get_next_timeout(libusb_context *ctx, struct timeval *tv,
return 0;
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Handle any pending events.
*
* libusb determines "pending events" by checking if any timeouts have expired
@@ -2313,7 +2313,7 @@ static int get_next_timeout(libusb_context *ctx, struct timeval *tv,
* timeval struct for non-blocking mode
* \param completed pointer to completion integer to check, or NULL
* \returns 0 on success, or a LIBUSB_ERROR code on failure
- * \ref mtasync
+ * \ref libusb_mtasync
*/
int API_EXPORTED libusb_handle_events_timeout_completed(libusb_context *ctx,
struct timeval *tv, int *completed)
@@ -2368,7 +2368,7 @@ already_done:
return 0;
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Handle any pending events
*
* Like libusb_handle_events_timeout_completed(), but without the completed
@@ -2390,7 +2390,7 @@ int API_EXPORTED libusb_handle_events_timeout(libusb_context *ctx,
return libusb_handle_events_timeout_completed(ctx, tv, NULL);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Handle any pending events in blocking mode. There is currently a timeout
* hardcoded at 60 seconds but we plan to make it unlimited in future. For
* finer control over whether this function is blocking or non-blocking, or
@@ -2412,7 +2412,7 @@ int API_EXPORTED libusb_handle_events(libusb_context *ctx)
return libusb_handle_events_timeout_completed(ctx, &tv, NULL);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Handle any pending events in blocking mode.
*
* Like libusb_handle_events(), with the addition of a completed parameter
@@ -2424,7 +2424,7 @@ int API_EXPORTED libusb_handle_events(libusb_context *ctx)
* \param ctx the context to operate on, or NULL for the default context
* \param completed pointer to completion integer to check, or NULL
* \returns 0 on success, or a LIBUSB_ERROR code on failure
- * \ref mtasync
+ * \ref libusb_mtasync
*/
int API_EXPORTED libusb_handle_events_completed(libusb_context *ctx,
int *completed)
@@ -2435,7 +2435,7 @@ int API_EXPORTED libusb_handle_events_completed(libusb_context *ctx,
return libusb_handle_events_timeout_completed(ctx, &tv, completed);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Handle any pending events by polling file descriptors, without checking if
* any other threads are already doing so. Must be called with the event lock
* held, see libusb_lock_events().
@@ -2450,7 +2450,7 @@ int API_EXPORTED libusb_handle_events_completed(libusb_context *ctx,
* \param tv the maximum time to block waiting for events, or zero for
* non-blocking mode
* \returns 0 on success, or a LIBUSB_ERROR code on failure
- * \ref mtasync
+ * \ref libusb_mtasync
*/
int API_EXPORTED libusb_handle_events_locked(libusb_context *ctx,
struct timeval *tv)
@@ -2468,12 +2468,12 @@ int API_EXPORTED libusb_handle_events_locked(libusb_context *ctx,
return handle_events(ctx, &poll_timeout);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Determines whether your application must apply special timing considerations
* when monitoring libusb's file descriptors.
*
* This function is only useful for applications which retrieve and poll
- * libusb's file descriptors in their own main loop (\ref pollmain).
+ * libusb's file descriptors in their own main loop (\ref libusb_pollmain).
*
* Ordinarily, libusb's event handler needs to be called into at specific
* moments in time (in addition to times when there is activity on the file
@@ -2494,7 +2494,7 @@ int API_EXPORTED libusb_handle_events_locked(libusb_context *ctx,
* \returns 0 if you must call into libusb at times determined by
* libusb_get_next_timeout(), or 1 if all timeout events are handled internally
* or through regular activity on the file descriptors.
- * \ref pollmain "Polling libusb file descriptors for event handling"
+ * \ref libusb_pollmain "Polling libusb file descriptors for event handling"
*/
int API_EXPORTED libusb_pollfds_handle_timeouts(libusb_context *ctx)
{
@@ -2507,7 +2507,7 @@ int API_EXPORTED libusb_pollfds_handle_timeouts(libusb_context *ctx)
#endif
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Determine the next internal timeout that libusb needs to handle. You only
* need to use this function if you are calling poll() or select() or similar
* on libusb's file descriptors yourself - you do not need to use it if you
@@ -2592,7 +2592,7 @@ int API_EXPORTED libusb_get_next_timeout(libusb_context *ctx,
return 1;
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Register notification functions for file descriptor additions/removals.
* These functions will be invoked for every new or removed file descriptor
* that libusb uses as an event source.
@@ -2691,7 +2691,7 @@ void usbi_remove_pollfd(struct libusb_context *ctx, int fd)
ctx->fd_removed_cb(fd, ctx->fd_cb_user_data);
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Retrieve a list of file descriptors that should be polled by your main loop
* as libusb event sources.
*
@@ -2736,7 +2736,7 @@ out:
#endif
}
-/** \ingroup poll
+/** \ingroup libusb_poll
* Free a list of libusb_pollfd structures. This should be called for all
* pollfd lists allocated with libusb_get_pollfds().
*
diff --git a/libusb/libusb.h b/libusb/libusb.h
index 7fe01db..5b0d522 100644
--- a/libusb/libusb.h
+++ b/libusb/libusb.h
@@ -84,7 +84,7 @@ typedef unsigned __int32 uint32_t;
#endif /* __GNUC__ */
/** \def LIBUSB_CALL
- * \ingroup misc
+ * \ingroup libusb_misc
* libusb's Windows calling convention.
*
* Under Windows, the selection of available compilers and configurations
@@ -122,7 +122,7 @@ typedef unsigned __int32 uint32_t;
#endif
/** \def LIBUSB_API_VERSION
- * \ingroup misc
+ * \ingroup libusb_misc
* libusb's API version.
*
* Since version 1.0.13, to help with feature detection, libusb defines
@@ -151,7 +151,7 @@ extern "C" {
#endif
/**
- * \ingroup misc
+ * \ingroup libusb_misc
* Convert a 16-bit value from host-endian to little-endian format. On
* little endian systems, this function does nothing. On big endian systems,
* the bytes are swapped.
@@ -170,7 +170,7 @@ static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
}
/** \def libusb_le16_to_cpu
- * \ingroup misc
+ * \ingroup libusb_misc
* Convert a 16-bit value from little-endian to host-endian format. On
* little endian systems, this function does nothing. On big endian systems,
* the bytes are swapped.
@@ -181,7 +181,7 @@ static inline uint16_t libusb_cpu_to_le16(const uint16_t x)
/* standard USB stuff */
-/** \ingroup desc
+/** \ingroup libusb_desc
* Device and/or Interface Class codes */
enum libusb_class_code {
/** In the context of a \ref libusb_device_descriptor "device descriptor",
@@ -243,7 +243,7 @@ enum libusb_class_code {
LIBUSB_CLASS_VENDOR_SPEC = 0xff
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* Descriptor types as defined by the USB specification. */
enum libusb_descriptor_type {
/** Device descriptor. See libusb_device_descriptor. */
@@ -311,7 +311,7 @@ enum libusb_descriptor_type {
#define LIBUSB_ENDPOINT_ADDRESS_MASK 0x0f /* in bEndpointAddress */
#define LIBUSB_ENDPOINT_DIR_MASK 0x80
-/** \ingroup desc
+/** \ingroup libusb_desc
* Endpoint direction. Values for bit 7 of the
* \ref libusb_endpoint_descriptor::bEndpointAddress "endpoint address" scheme.
*/
@@ -325,7 +325,7 @@ enum libusb_endpoint_direction {
#define LIBUSB_TRANSFER_TYPE_MASK 0x03 /* in bmAttributes */
-/** \ingroup desc
+/** \ingroup libusb_desc
* Endpoint transfer type. Values for bits 0:1 of the
* \ref libusb_endpoint_descriptor::bmAttributes "endpoint attributes" field.
*/
@@ -346,7 +346,7 @@ enum libusb_transfer_type {
LIBUSB_TRANSFER_TYPE_BULK_STREAM = 4,
};
-/** \ingroup misc
+/** \ingroup libusb_misc
* Standard requests, as defined in table 9-5 of the USB 3.0 specifications */
enum libusb_standard_request {
/** Request status of the specific recipient */
@@ -394,7 +394,7 @@ enum libusb_standard_request {
LIBUSB_SET_ISOCH_DELAY = 0x31,
};
-/** \ingroup misc
+/** \ingroup libusb_misc
* Request type bits of the
* \ref libusb_control_setup::bmRequestType "bmRequestType" field in control
* transfers. */
@@ -412,7 +412,7 @@ enum libusb_request_type {
LIBUSB_REQUEST_TYPE_RESERVED = (0x03 << 5)
};
-/** \ingroup misc
+/** \ingroup libusb_misc
* Recipient bits of the
* \ref libusb_control_setup::bmRequestType "bmRequestType" field in control
* transfers. Values 4 through 31 are reserved. */
@@ -432,7 +432,7 @@ enum libusb_request_recipient {
#define LIBUSB_ISO_SYNC_TYPE_MASK 0x0C
-/** \ingroup desc
+/** \ingroup libusb_desc
* Synchronization type for isochronous endpoints. Values for bits 2:3 of the
* \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
* libusb_endpoint_descriptor.
@@ -453,7 +453,7 @@ enum libusb_iso_sync_type {
#define LIBUSB_ISO_USAGE_TYPE_MASK 0x30
-/** \ingroup desc
+/** \ingroup libusb_desc
* Usage type for isochronous endpoints. Values for bits 4:5 of the
* \ref libusb_endpoint_descriptor::bmAttributes "bmAttributes" field in
* libusb_endpoint_descriptor.
@@ -469,7 +469,7 @@ enum libusb_iso_usage_type {
LIBUSB_ISO_USAGE_TYPE_IMPLICIT = 2,
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A structure representing the standard USB device descriptor. This
* descriptor is documented in section 9.6.1 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format.
@@ -523,7 +523,7 @@ struct libusb_device_descriptor {
uint8_t bNumConfigurations;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A structure representing the standard USB endpoint descriptor. This
* descriptor is documented in section 9.6.6 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format.
@@ -573,7 +573,7 @@ struct libusb_endpoint_descriptor {
int extra_length;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A structure representing the standard USB interface descriptor. This
* descriptor is documented in section 9.6.5 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format.
@@ -623,7 +623,7 @@ struct libusb_interface_descriptor {
int extra_length;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A collection of alternate settings for a particular USB interface.
*/
struct libusb_interface {
@@ -635,7 +635,7 @@ struct libusb_interface {
int num_altsetting;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A structure representing the standard USB configuration descriptor. This
* descriptor is documented in section 9.6.3 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format.
@@ -682,7 +682,7 @@ struct libusb_config_descriptor {
int extra_length;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A structure representing the superspeed endpoint companion
* descriptor. This descriptor is documented in section 9.6.7 of
* the USB 3.0 specification. All multiple-byte fields are represented in
@@ -714,7 +714,7 @@ struct libusb_ss_endpoint_companion_descriptor {
uint16_t wBytesPerInterval;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A generic representation of a BOS Device Capability descriptor. It is
* advised to check bDevCapabilityType and call the matching
* libusb_get_*_descriptor function to get a structure fully matching the type.
@@ -738,7 +738,7 @@ struct libusb_bos_dev_capability_descriptor {
;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A structure representing the Binary Device Object Store (BOS) descriptor.
* This descriptor is documented in section 9.6.2 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format.
@@ -769,7 +769,7 @@ struct libusb_bos_descriptor {
;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A structure representing the USB 2.0 Extension descriptor
* This descriptor is documented in section 9.6.2.1 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format.
@@ -795,7 +795,7 @@ struct libusb_usb_2_0_extension_descriptor {
uint32_t bmAttributes;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A structure representing the SuperSpeed USB Device Capability descriptor
* This descriptor is documented in section 9.6.2.2 of the USB 3.0 specification.
* All multiple-byte fields are represented in host-endian format.
@@ -837,7 +837,7 @@ struct libusb_ss_usb_device_capability_descriptor {
uint16_t bU2DevExitLat;
};
-/** \ingroup desc
+/** \ingroup libusb_desc
* A structure representing the Container ID descriptor.
* This descriptor is documented in section 9.6.2.3 of the USB 3.0 specification.
* All multiple-byte fields, except UUIDs, are represented in host-endian format.
@@ -863,7 +863,7 @@ struct libusb_container_id_descriptor {
uint8_t ContainerID[16];
};
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Setup packet for control transfers. */
struct libusb_control_setup {
/** Request type. Bits 0:4 determine recipient, see
@@ -899,7 +899,7 @@ struct libusb_context;
struct libusb_device;
struct libusb_device_handle;
-/** \ingroup lib
+/** \ingroup libusb_lib
* Structure providing the version of the libusb runtime
*/
struct libusb_version {
@@ -922,7 +922,7 @@ struct libusb_version {
const char* describe;
};
-/** \ingroup lib
+/** \ingroup libusb_lib
* Structure representing a libusb session. The concept of individual libusb
* sessions allows for your program to use two libraries (or dynamically
* load two modules) which both independently use libusb. This will prevent
@@ -937,11 +937,11 @@ struct libusb_version {
* every function call where a context is required. The default context
* will be used.
*
- * For more information, see \ref contexts.
+ * For more information, see \ref libusb_contexts.
*/
typedef struct libusb_context libusb_context;
-/** \ingroup dev
+/** \ingroup libusb_dev
* Structure representing a USB device detected on the system. This is an
* opaque type for which you are only ever provided with a pointer, usually
* originating from libusb_get_device_list().
@@ -959,7 +959,7 @@ typedef struct libusb_context libusb_context;
typedef struct libusb_device libusb_device;
-/** \ingroup dev
+/** \ingroup libusb_dev
* Structure representing a handle on a USB device. This is an opaque type for
* which you are only ever provided with a pointer, usually originating from
* libusb_open().
@@ -969,7 +969,7 @@ typedef struct libusb_device libusb_device;
*/
typedef struct libusb_device_handle libusb_device_handle;
-/** \ingroup dev
+/** \ingroup libusb_dev
* Speed codes. Indicates the speed at which the device is operating.
*/
enum libusb_speed {
@@ -989,7 +989,7 @@ enum libusb_speed {
LIBUSB_SPEED_SUPER = 4,
};
-/** \ingroup dev
+/** \ingroup libusb_dev
* Supported speeds (wSpeedSupported) bitfield. Indicates what
* speeds the device supports.
*/
@@ -1007,7 +1007,7 @@ enum libusb_supported_speed {
LIBUSB_SUPER_SPEED_OPERATION = 8,
};
-/** \ingroup dev
+/** \ingroup libusb_dev
* Masks for the bits of the
* \ref libusb_usb_2_0_extension_descriptor::bmAttributes "bmAttributes" field
* of the USB 2.0 Extension descriptor.
@@ -1017,7 +1017,7 @@ enum libusb_usb_2_0_extension_attributes {
LIBUSB_BM_LPM_SUPPORT = 2,
};
-/** \ingroup dev
+/** \ingroup libusb_dev
* Masks for the bits of the
* \ref libusb_ss_usb_device_capability_descriptor::bmAttributes "bmAttributes" field
* field of the SuperSpeed USB Device Capability descriptor.
@@ -1027,7 +1027,7 @@ enum libusb_ss_usb_device_capability_attributes {
LIBUSB_BM_LTM_SUPPORT = 2,
};
-/** \ingroup dev
+/** \ingroup libusb_dev
* USB capability types
*/
enum libusb_bos_type {
@@ -1044,7 +1044,7 @@ enum libusb_bos_type {
LIBUSB_BT_CONTAINER_ID = 4,
};
-/** \ingroup misc
+/** \ingroup libusb_misc
* Error codes. Most libusb functions return 0 on success or one of these
* codes on failure.
* You can call libusb_error_name() to retrieve a string representation of an
@@ -1101,7 +1101,7 @@ enum libusb_error {
/* Total number of error codes in enum libusb_error */
#define LIBUSB_ERROR_COUNT 14
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Transfer status codes */
enum libusb_transfer_status {
/** Transfer completed without error. Note that this does not indicate
@@ -1131,7 +1131,7 @@ enum libusb_transfer_status {
when adding new status codes here. */
};
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* libusb_transfer.flags values */
enum libusb_transfer_flags {
/** Report short frames as errors */
@@ -1172,7 +1172,7 @@ enum libusb_transfer_flags {
LIBUSB_TRANSFER_ADD_ZERO_PACKET = 1 << 3,
};
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Isochronous packet descriptor. */
struct libusb_iso_packet_descriptor {
/** Length of data to request in this packet */
@@ -1187,18 +1187,18 @@ struct libusb_iso_packet_descriptor {
struct libusb_transfer;
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Asynchronous transfer callback function type. When submitting asynchronous
* transfers, you pass a pointer to a callback function of this type via the
* \ref libusb_transfer::callback "callback" member of the libusb_transfer
* structure. libusb will call this function later, when the transfer has
- * completed or failed. See \ref asyncio for more information.
+ * completed or failed. See \ref libusb_asyncio for more information.
* \param transfer The libusb_transfer struct the callback function is being
* notified about.
*/
typedef void (LIBUSB_CALL *libusb_transfer_cb_fn)(struct libusb_transfer *transfer);
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* 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
@@ -1262,7 +1262,7 @@ struct libusb_transfer {
;
};
-/** \ingroup misc
+/** \ingroup libusb_misc
* 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().
@@ -1282,7 +1282,7 @@ enum libusb_capability {
LIBUSB_CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101
};
-/** \ingroup lib
+/** \ingroup libusb_lib
* Log message levels.
* - LIBUSB_LOG_LEVEL_NONE (0) : no messages ever printed by the library (default)
* - LIBUSB_LOG_LEVEL_ERROR (1) : error messages are printed to stderr
@@ -1403,7 +1403,7 @@ int LIBUSB_CALL libusb_set_auto_detach_kernel_driver(
/* async I/O */
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Get the data section of a control transfer. This convenience function is here
* to remind you that the data does not start until 8 bytes into the actual
* buffer, as the setup packet comes first.
@@ -1421,7 +1421,7 @@ static inline unsigned char *libusb_control_transfer_get_data(
return transfer->buffer + LIBUSB_CONTROL_SETUP_SIZE;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Get the control setup packet of a control transfer. This convenience
* function is here to remind you that the control setup occupies the first
* 8 bytes of the transfer data buffer.
@@ -1439,7 +1439,7 @@ static inline struct libusb_control_setup *libusb_control_transfer_get_setup(
return (struct libusb_control_setup *)(void *) transfer->buffer;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Helper function to populate the setup packet (first 8 bytes of the data
* buffer) for a control transfer. The wIndex, wValue and wLength values should
* be given in host-endian byte order.
@@ -1483,7 +1483,7 @@ void LIBUSB_CALL libusb_transfer_set_stream_id(
uint32_t LIBUSB_CALL libusb_transfer_get_stream_id(
struct libusb_transfer *transfer);
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Helper function to populate the required \ref libusb_transfer fields
* for a control transfer.
*
@@ -1529,7 +1529,7 @@ static inline void libusb_fill_control_transfer(
transfer->callback = callback;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Helper function to populate the required \ref libusb_transfer fields
* for a bulk transfer.
*
@@ -1557,7 +1557,7 @@ static inline void libusb_fill_bulk_transfer(struct libusb_transfer *transfer,
transfer->callback = callback;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Helper function to populate the required \ref libusb_transfer fields
* for a bulk transfer using bulk streams.
*
@@ -1585,7 +1585,7 @@ static inline void libusb_fill_bulk_stream_transfer(
libusb_transfer_set_stream_id(transfer, stream_id);
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Helper function to populate the required \ref libusb_transfer fields
* for an interrupt transfer.
*
@@ -1613,7 +1613,7 @@ static inline void libusb_fill_interrupt_transfer(
transfer->callback = callback;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Helper function to populate the required \ref libusb_transfer fields
* for an isochronous transfer.
*
@@ -1643,7 +1643,7 @@ static inline void libusb_fill_iso_transfer(struct libusb_transfer *transfer,
transfer->callback = callback;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Convenience function to set the length of all packets in an isochronous
* transfer, based on the num_iso_packets field in the transfer structure.
*
@@ -1659,7 +1659,7 @@ static inline void libusb_set_iso_packet_lengths(
transfer->iso_packet_desc[i].length = length;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Convenience function to locate the position of an isochronous packet
* within the buffer of an isochronous transfer.
*
@@ -1698,7 +1698,7 @@ static inline unsigned char *libusb_get_iso_packet_buffer(
return transfer->buffer + offset;
}
-/** \ingroup asyncio
+/** \ingroup libusb_asyncio
* Convenience function to locate the position of an isochronous packet
* within the buffer of an isochronous transfer, for transfers where each
* packet is of identical size.
@@ -1749,7 +1749,7 @@ int LIBUSB_CALL libusb_interrupt_transfer(libusb_device_handle *dev_handle,
unsigned char endpoint, unsigned char *data, int length,
int *actual_length, unsigned int timeout);
-/** \ingroup desc
+/** \ingroup libusb_desc
* Retrieve a descriptor from the default control pipe.
* This is a convenience function which formulates the appropriate control
* message to retrieve the descriptor.
@@ -1769,7 +1769,7 @@ static inline int libusb_get_descriptor(libusb_device_handle *dev_handle,
0, data, (uint16_t) length, 1000);
}
-/** \ingroup desc
+/** \ingroup libusb_desc
* Retrieve a descriptor from a device.
* This is a convenience function which formulates the appropriate control
* message to retrieve the descriptor. The string returned is Unicode, as
@@ -1818,7 +1818,7 @@ int LIBUSB_CALL libusb_pollfds_handle_timeouts(libusb_context *ctx);
int LIBUSB_CALL libusb_get_next_timeout(libusb_context *ctx,
struct timeval *tv);
-/** \ingroup poll
+/** \ingroup libusb_poll
* File descriptor for polling
*/
struct libusb_pollfd {
@@ -1832,7 +1832,7 @@ struct libusb_pollfd {
short events;
};
-/** \ingroup poll
+/** \ingroup libusb_poll
* Callback function, invoked when a new file descriptor should be added
* to the set of file descriptors monitored for events.
* \param fd the new file descriptor
@@ -1845,7 +1845,7 @@ struct libusb_pollfd {
typedef void (LIBUSB_CALL *libusb_pollfd_added_cb)(int fd, short events,
void *user_data);
-/** \ingroup poll
+/** \ingroup libusb_poll
* Callback function, invoked when a file descriptor should be removed from
* the set of file descriptors being monitored for events. After returning
* from this callback, do not use that file descriptor again.
@@ -1863,7 +1863,7 @@ void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb,
void *user_data);
-/** \ingroup hotplug
+/** \ingroup libusb_hotplug
* Callback handle.
*
* Callbacks handles are generated by libusb_hotplug_register_callback()
@@ -1873,11 +1873,11 @@ void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
*
* Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
- * For more information, see \ref hotplug.
+ * For more information, see \ref libusb_hotplug.
*/
typedef int libusb_hotplug_callback_handle;
-/** \ingroup hotplug
+/** \ingroup libusb_hotplug
*
* Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
@@ -1890,7 +1890,7 @@ typedef enum {
LIBUSB_HOTPLUG_ENUMERATE = 1<<0,
} libusb_hotplug_flag;
-/** \ingroup hotplug
+/** \ingroup libusb_hotplug
*
* Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
@@ -1905,11 +1905,11 @@ typedef enum {
LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT = 0x02,
} libusb_hotplug_event;
-/** \ingroup hotplug
+/** \ingroup libusb_hotplug
* Wildcard matching for hotplug events */
#define LIBUSB_HOTPLUG_MATCH_ANY -1
-/** \ingroup hotplug
+/** \ingroup libusb_hotplug
* Hotplug callback function type. When requesting hotplug event notifications,
* you pass a pointer to a callback function of this type.
*
@@ -1917,7 +1917,7 @@ typedef enum {
* recommended the callback do minimal processing before returning.
*
* libusb will call this function later, when a matching event had happened on
- * a matching device. See \ref hotplug for more information.
+ * a matching device. See \ref libusb_hotplug for more information.
*
* It is safe to call either libusb_hotplug_register_callback() or
* libusb_hotplug_deregister_callback() from within a callback function.
@@ -1936,7 +1936,7 @@ typedef int (LIBUSB_CALL *libusb_hotplug_callback_fn)(libusb_context *ctx,
libusb_hotplug_event event,
void *user_data);
-/** \ingroup hotplug
+/** \ingroup libusb_hotplug
* Register a hotplug callback function
*
* Register a callback with the libusb_context. The callback will fire
@@ -1979,7 +1979,7 @@ int LIBUSB_CALL libusb_hotplug_register_callback(libusb_context *ctx,
void *user_data,
libusb_hotplug_callback_handle *callback_handle);
-/** \ingroup hotplug
+/** \ingroup libusb_hotplug
* Deregisters a hotplug callback.
*
* Deregister a callback from a libusb_context. This function is safe to call from within
diff --git a/libusb/strerror.c b/libusb/strerror.c
index a534041..d2be0e2 100644
--- a/libusb/strerror.c
+++ b/libusb/strerror.c
@@ -34,7 +34,7 @@
static size_t usbi_locale = 0;
-/** \ingroup misc
+/** \ingroup libusb_misc
* How to add a new \ref libusb_strerror() translation:
* <ol>
* <li> Download the latest \c strerror.c from:<br>
@@ -125,7 +125,7 @@ static const char* usbi_localized_errors[ARRAYSIZE(usbi_locale_supported)][LIBUS
}
};
-/** \ingroup misc
+/** \ingroup libusb_misc
* Set the language, and only the language, not the encoding! used for
* translatable libusb messages.
*
@@ -176,7 +176,7 @@ int API_EXPORTED libusb_setlocale(const char *locale)
return LIBUSB_SUCCESS;
}
-/** \ingroup misc
+/** \ingroup libusb_misc
* Returns a constant string with a short description of the given error code,
* this description is intended for displaying to the end user and will be in
* the language set by libusb_setlocale().
diff --git a/libusb/sync.c b/libusb/sync.c
index 668909c..c8514dd 100644
--- a/libusb/sync.c
+++ b/libusb/sync.c
@@ -27,11 +27,11 @@
#include "libusbi.h"
/**
- * @defgroup syncio Synchronous device I/O
+ * @defgroup libusb_syncio Synchronous device I/O
*
* This page documents libusb's synchronous (blocking) API for USB device I/O.
* This interface is easy to use but has some limitations. More advanced users
- * may wish to consider using the \ref asyncio "asynchronous I/O API" instead.
+ * may wish to consider using the \ref libusb_asyncio "asynchronous I/O API" instead.
*/
static void LIBUSB_CALL sync_transfer_cb(struct libusb_transfer *transfer)
@@ -60,7 +60,7 @@ static void sync_transfer_wait_for_completion(struct libusb_transfer *transfer)
}
}
-/** \ingroup syncio
+/** \ingroup libusb_syncio
* Perform a USB control transfer.
*
* The direction of the transfer is inferred from the bmRequestType field of
@@ -221,7 +221,7 @@ static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle,
return r;
}
-/** \ingroup syncio
+/** \ingroup libusb_syncio
* Perform a USB bulk transfer. The direction of the transfer is inferred from
* the direction bits of the endpoint address.
*
@@ -259,7 +259,7 @@ static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle,
* <tt>transferred</tt>)
* \returns LIBUSB_ERROR_PIPE if the endpoint halted
* \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
- * \ref packetoverflow
+ * \ref libusb_packetoverflow
* \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
* \returns LIBUSB_ERROR_BUSY if called from event handling context
* \returns another LIBUSB_ERROR code on other failures
@@ -272,7 +272,7 @@ int API_EXPORTED libusb_bulk_transfer(struct libusb_device_handle *dev_handle,
transferred, timeout, LIBUSB_TRANSFER_TYPE_BULK);
}
-/** \ingroup syncio
+/** \ingroup libusb_syncio
* Perform a USB interrupt transfer. The direction of the transfer is inferred
* from the direction bits of the endpoint address.
*
@@ -311,7 +311,7 @@ int API_EXPORTED libusb_bulk_transfer(struct libusb_device_handle *dev_handle,
* \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
* \returns LIBUSB_ERROR_PIPE if the endpoint halted
* \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
- * \ref packetoverflow
+ * \ref libusb_packetoverflow
* \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
* \returns LIBUSB_ERROR_BUSY if called from event handling context
* \returns another LIBUSB_ERROR code on other error
diff --git a/libusb/version_nano.h b/libusb/version_nano.h
index bb4ce8e..a3134a0 100644
--- a/libusb/version_nano.h
+++ b/libusb/version_nano.h
@@ -1 +1 @@
-#define LIBUSB_NANO 11055
+#define LIBUSB_NANO 11056