doc: Explain default options in libusb_set_option documentation

[platform/upstream/libusb.git] / libusb / libusb.h

diff --git a/libusb/libusb.h b/libusb/libusb.h
index e9f5253..7ec3fcf 100644 (file)
--- a/libusb/libusb.h
+++ b/libusb/libusb.h
@@ -31,8 +31,11 @@
 #define inline __inline
 #endif
 /* ssize_t is also not available */
+#ifndef _SSIZE_T_DEFINED
+#define _SSIZE_T_DEFINED
 #include <basetsd.h>
 typedef SSIZE_T ssize_t;
+#endif /* _SSIZE_T_DEFINED */
 #endif /* _MSC_VER */
 
 #include <limits.h>
@@ -231,6 +234,9 @@ enum libusb_class_code {
        /** Wireless class */
        LIBUSB_CLASS_WIRELESS = 0xe0,
 
+       /** Miscellaneous class */
+       LIBUSB_CLASS_MISCELLANEOUS = 0xef,
+
        /** Application class */
        LIBUSB_CLASS_APPLICATION = 0xfe,
 
@@ -901,7 +907,7 @@ struct libusb_container_id_descriptor {
 
 /** \ingroup libusb_asyncio
  * Setup packet for control transfers. */
-#if defined(_MSC_VER)
+#if defined(_MSC_VER) || defined(__WATCOMC__)
 #pragma pack(push, 1)
 #endif
 struct libusb_control_setup {
@@ -929,7 +935,7 @@ struct libusb_control_setup {
        /** Number of bytes to transfer */
        uint16_t wLength;
 } LIBUSB_PACKED;
-#if defined(_MSC_VER)
+#if defined(_MSC_VER) || defined(__WATCOMC__)
 #pragma pack(pop)
 #endif
 
@@ -976,8 +982,9 @@ struct libusb_version {
  * Sessions are created by libusb_init() and destroyed through libusb_exit().
  * If your application is guaranteed to only ever include a single libusb
  * user (i.e. you), you do not have to worry about contexts: pass NULL in
- * every function call where a context is required. The default context
- * will be used.
+ * every function call where a context is required, and the default context
+ * will be used. Note that libusb_set_option(NULL, ...) is special, and adds
+ * an option to a list of default options for new contexts.
  *
  * For more information, see \ref libusb_contexts.
  */
@@ -986,7 +993,7 @@ typedef struct libusb_context libusb_context;
 /** \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().
+ * originating from libusb_get_device_list() or libusb_hotplug_register_callback().
  *
  * Certain operations can be performed on a device, but in order to do any
  * I/O you will have to first obtain a device handle using libusb_open().
@@ -1322,13 +1329,16 @@ enum libusb_log_level {
 
 /** \ingroup libusb_lib
  *  Log callback mode.
+ *
+ *  Since version 1.0.23, \ref LIBUSB_API_VERSION >= 0x01000107
+ *
  * \see libusb_set_log_cb()
  */
 enum libusb_log_cb_mode {
-       /** Callback function handling all log mesages. */
+       /** Callback function handling all log messages. */
        LIBUSB_LOG_CB_GLOBAL = (1 << 0),
 
-       /** Callback function handling context related log mesages. */
+       /** Callback function handling context related log messages. */
        LIBUSB_LOG_CB_CONTEXT = (1 << 1)
 };
 
@@ -1338,6 +1348,9 @@ enum libusb_log_cb_mode {
  * is a global log message
  * \param level the log level, see \ref libusb_log_level for a description
  * \param str the log message
+ *
+ * Since version 1.0.23, \ref LIBUSB_API_VERSION >= 0x01000107
+ *
  * \see libusb_set_log_cb()
  */
 typedef void (LIBUSB_CALL *libusb_log_cb)(libusb_context *ctx,
@@ -1921,7 +1934,7 @@ void LIBUSB_CALL libusb_set_pollfd_notifiers(libusb_context *ctx,
  * Callbacks handles are generated by libusb_hotplug_register_callback()
  * and can be used to deregister callbacks. Callback handles are unique
  * per libusb_context and it is safe to call libusb_hotplug_deregister_callback()
- * on an already deregisted callback.
+ * on an already deregistered callback.
  *
  * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
  *
@@ -2087,7 +2100,32 @@ enum libusb_option {
         *
         * Only valid on Windows.
         */
-       LIBUSB_OPTION_USE_USBDK = 1
+       LIBUSB_OPTION_USE_USBDK = 1,
+
+       /** Do not scan for devices
+        *
+        * With this option set, libusb will skip scanning devices in
+        * libusb_init(). Must be set before calling libusb_init().
+        *
+        * Hotplug functionality will also be deactivated.
+        *
+        * The option is useful in combination with libusb_wrap_sys_device(),
+        * which can access a device directly without prior device scanning.
+        *
+        * This is typically needed on Android, where access to USB devices
+        * is limited.
+        *
+        * Only valid on Linux.
+        */
+       LIBUSB_OPTION_NO_DEVICE_DISCOVERY = 2,
+
+       /** Flag that libusb has weak authority.
+        *
+        * (Deprecated) alias for LIBUSB_OPTION_NO_DEVICE_DISCOVERY
+        */
+       LIBUSB_OPTION_WEAK_AUTHORITY = 3,
+
+       LIBUSB_OPTION_MAX = 4
 };
 
 int LIBUSB_CALL libusb_set_option(libusb_context *ctx, enum libusb_option option, ...);