diff options
author | Chris Dickens <christopher.a.dickens@gmail.com> | 2016-02-24 01:07:20 -0800 |
---|---|---|
committer | Chris Dickens <christopher.a.dickens@gmail.com> | 2016-02-24 01:07:20 -0800 |
commit | 7ee92df12adb8015451aaecfeccd7dd62cc2314e (patch) | |
tree | 69aa53a859edd88b6a79fa21fb2b9f02e35aba4d | |
parent | 8a0c14372f98d56529556f18126a42fda2ab0137 (diff) | |
download | libusb-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.c | 96 | ||||
-rw-r--r-- | libusb/descriptor.c | 34 | ||||
-rw-r--r-- | libusb/hotplug.c | 8 | ||||
-rw-r--r-- | libusb/io.c | 122 | ||||
-rw-r--r-- | libusb/libusb.h | 138 | ||||
-rw-r--r-- | libusb/strerror.c | 6 | ||||
-rw-r--r-- | libusb/sync.c | 14 | ||||
-rw-r--r-- | libusb/version_nano.h | 2 |
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 |