/*
- * Public libusbx header file
+ * Public libusb header file
* Copyright © 2001 Johannes Erdfelt <johannes@erdfelt.com>
* Copyright © 2007-2008 Daniel Drake <dsd@gentoo.org>
* Copyright © 2012 Pete Batard <pete@akeo.ie>
* Copyright © 2012 Nathan Hjelm <hjelmn@cs.unm.edu>
- * For more information, please visit: http://libusbx.org
+ * For more information, please visit: http://libusb.info
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include <sys/types.h>
#endif
-#if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__)
+#if defined(__linux) || defined(__APPLE__) || defined(__CYGWIN__) || defined(__HAIKU__)
#include <sys/time.h>
#endif
#include <limits.h>
/* 'interface' might be defined as a macro on Windows, so we need to
- * undefine it so as not to break the current libusbx API, because
+ * undefine it so as not to break the current libusb API, because
* libusb_config_descriptor has an 'interface' member
* As this can be problematic if you include windows.h after libusb.h
* in your sources, we force windows.h to be included first. */
/** \def LIBUSB_CALL
* \ingroup misc
- * libusbx's Windows calling convention.
+ * libusb's Windows calling convention.
*
* Under Windows, the selection of available compilers and configurations
* means that, unlike other platforms, there is not <em>one true calling
* convention</em> (calling convention: the manner in which parameters are
- * passed to funcions in the generated assembly code).
+ * passed to functions in the generated assembly code).
*
- * Matching the Windows API itself, libusbx uses the WINAPI convention (which
+ * Matching the Windows API itself, libusb uses the WINAPI convention (which
* translates to the <tt>stdcall</tt> convention) and guarantees that the
* library is compiled in this way. The public header file also includes
* appropriate annotations so that your own software will use the right
* your codebase.
*
* The one consideration that you must apply in your software is to mark
- * all functions which you use as libusbx callbacks with this LIBUSB_CALL
+ * all functions which you use as libusb callbacks with this LIBUSB_CALL
* annotation, so that they too get compiled for the correct calling
* convention.
*
* means that you can apply it to your code without worrying about
* cross-platform compatibility.
*/
-/* LIBUSB_CALL must be defined on both definition and declaration of libusbx
+/* LIBUSB_CALL must be defined on both definition and declaration of libusb
* functions. You'd think that declaration would be enough, but cygwin will
* complain about conflicting types unless both are marked this way.
* The placement of this macro is important too; it must appear after the
#define LIBUSB_CALL
#endif
-/** \def LIBUSBX_API_VERSION
+/** \def LIBUSB_API_VERSION
* \ingroup misc
- * libusbx's API version.
+ * libusb's API version.
*
- * Since version 1.0.13, to help with feature detection, libusbx defines
- * a LIBUSBX_API_VERSION macro that gets increased every time there is a
+ * Since version 1.0.13, to help with feature detection, libusb defines
+ * a LIBUSB_API_VERSION macro that gets increased every time there is a
* significant change to the API, such as the introduction of a new call,
* the definition of a new macro/enum member, or any other element that
- * libusbx applications may want to detect at compilation time.
+ * libusb applications may want to detect at compilation time.
*
* The macro is typically used in an application as follows:
* \code
- * #if defined(LIBUSBX_API_VERSION) && (LIBUSBX_API_VERSION >= 0x01001234)
- * // Use one of the newer features from the libusbx API
+ * #if defined(LIBUSB_API_VERSION) && (LIBUSB_API_VERSION >= 0x01001234)
+ * // Use one of the newer features from the libusb API
* #endif
* \endcode
*
- * Another feature of LIBUSBX_API_VERSION is that it can be used to detect
- * whether you are compiling against the libusb or the libusbx library.
- *
- * Internally, LIBUSBX_API_VERSION is defined as follows:
- * (libusbx major << 24) | (libusbx minor << 16) | (16 bit incremental)
+ * Internally, LIBUSB_API_VERSION is defined as follows:
+ * (libusb major << 24) | (libusb minor << 16) | (16 bit incremental)
*/
-#define LIBUSBX_API_VERSION 0x01000102
+#define LIBUSB_API_VERSION 0x01000105
+
+/* The following is kept for compatibility, but will be deprecated in the future */
+#define LIBUSBX_API_VERSION LIBUSB_API_VERSION
#ifdef __cplusplus
extern "C" {
LIBUSB_TRANSFER_TYPE_BULK = 2,
/** Interrupt endpoint */
- LIBUSB_TRANSFER_TYPE_INTERRUPT = 3
+ LIBUSB_TRANSFER_TYPE_INTERRUPT = 3,
+
+ /** Stream endpoint */
+ LIBUSB_TRANSFER_TYPE_BULK_STREAM = 4,
};
/** \ingroup misc
/** For audio devices only: the address if the synch endpoint */
uint8_t bSynchAddress;
- /** Extra descriptors. If libusbx encounters unknown endpoint descriptors,
+ /** Extra descriptors. If libusb encounters unknown endpoint descriptors,
* it will store them here, should you wish to parse them. */
const unsigned char *extra;
* by the bNumEndpoints field. */
const struct libusb_endpoint_descriptor *endpoint;
- /** Extra descriptors. If libusbx encounters unknown interface descriptors,
+ /** Extra descriptors. If libusb encounters unknown interface descriptors,
* it will store them here, should you wish to parse them. */
const unsigned char *extra;
uint8_t bmAttributes;
/** Maximum power consumption of the USB device from this bus in this
- * configuration when the device is fully opreation. Expressed in units
- * of 2 mA. */
+ * configuration when the device is fully operation. Expressed in units
+ * of 2 mA when the device is operating in high-speed mode and in units
+ * of 8 mA when the device is operating in super-speed mode. */
uint8_t MaxPower;
/** Array of interfaces supported by this configuration. The length of
* this array is determined by the bNumInterfaces field. */
const struct libusb_interface *interface;
- /** Extra descriptors. If libusbx encounters unknown configuration
+ /** Extra descriptors. If libusb encounters unknown configuration
* descriptors, it will store them here, should you wish to parse them. */
const unsigned char *extra;
/** The maximum number of packets the endpoint can send or
- * recieve as part of a burst. */
+ * receive as part of a burst. */
uint8_t bMaxBurst;
/** In bulk EP: bits 4:0 represents the maximum number of
#define LIBUSB_CONTROL_SETUP_SIZE (sizeof(struct libusb_control_setup))
-/* libusbx */
+/* libusb */
struct libusb_context;
struct libusb_device;
struct libusb_device_handle;
-struct libusb_hotplug_callback;
/** \ingroup lib
- * Structure providing the version of the libusbx runtime
+ * Structure providing the version of the libusb runtime
*/
struct libusb_version {
/** Library major version. */
};
/** \ingroup lib
- * Structure representing a libusbx session. The concept of individual libusbx
+ * 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
- * interference between the individual libusbx users - for example
+ * interference between the individual libusb users - for example
* libusb_set_debug() will not affect the other user of the library, and
* libusb_exit() will not destroy resources that the other user is still
* using.
*
* Sessions are created by libusb_init() and destroyed through libusb_exit().
- * If your application is guaranteed to only ever include a single libusbx
+ * 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.
};
/** \ingroup misc
- * Error codes. Most libusbx functions return 0 on success or one of these
+ * 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
* error code or libusb_strerror() to get an end-user suitable description of
* 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. libusbx will call this function later, when the transfer has
+ * structure. libusb will call this function later, when the transfer has
* completed or failed. See \ref asyncio for more information.
* \param transfer The libusb_transfer struct the callback function is being
* notified about.
LIBUSB_CAP_HAS_HOTPLUG = 0x0001,
/** The library can access HID devices without requiring user intervention.
* Note that before being able to actually access an HID device, you may
- * still have to call additional libusbx functions such as
+ * still have to call additional libusb functions such as
* \ref libusb_detach_kernel_driver(). */
LIBUSB_CAP_HAS_HID_ACCESS = 0x0100,
/** The library supports detaching of the default USB driver, using
unsigned char endpoint);
int LIBUSB_CALL libusb_reset_device(libusb_device_handle *dev);
+int LIBUSB_CALL libusb_alloc_streams(libusb_device_handle *dev,
+ uint32_t num_streams, unsigned char *endpoints, int num_endpoints);
+int LIBUSB_CALL libusb_free_streams(libusb_device_handle *dev,
+ unsigned char *endpoints, int num_endpoints);
+
int LIBUSB_CALL libusb_kernel_driver_active(libusb_device_handle *dev,
int interface_number);
int LIBUSB_CALL libusb_detach_kernel_driver(libusb_device_handle *dev,
int LIBUSB_CALL libusb_submit_transfer(struct libusb_transfer *transfer);
int LIBUSB_CALL libusb_cancel_transfer(struct libusb_transfer *transfer);
void LIBUSB_CALL libusb_free_transfer(struct libusb_transfer *transfer);
+void LIBUSB_CALL libusb_transfer_set_stream_id(
+ struct libusb_transfer *transfer, uint32_t stream_id);
+uint32_t LIBUSB_CALL libusb_transfer_get_stream_id(
+ struct libusb_transfer *transfer);
/** \ingroup asyncio
* Helper function to populate the required \ref libusb_transfer fields
/** \ingroup asyncio
* Helper function to populate the required \ref libusb_transfer fields
+ * for a bulk transfer using bulk streams.
+ *
+ * Since version 1.0.19, \ref LIBUSB_API_VERSION >= 0x01000103
+ *
+ * \param transfer the transfer to populate
+ * \param dev_handle handle of the device that will handle the transfer
+ * \param endpoint address of the endpoint where this transfer will be sent
+ * \param stream_id bulk stream id for this transfer
+ * \param buffer data buffer
+ * \param length length of data buffer
+ * \param callback callback function to be invoked on transfer completion
+ * \param user_data user data to pass to callback function
+ * \param timeout timeout for the transfer in milliseconds
+ */
+static inline void libusb_fill_bulk_stream_transfer(
+ struct libusb_transfer *transfer, libusb_device_handle *dev_handle,
+ unsigned char endpoint, uint32_t stream_id,
+ unsigned char *buffer, int length, libusb_transfer_cb_fn callback,
+ void *user_data, unsigned int timeout)
+{
+ libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer,
+ length, callback, user_data, timeout);
+ transfer->type = LIBUSB_TRANSFER_TYPE_BULK_STREAM;
+ libusb_transfer_set_stream_id(transfer, stream_id);
+}
+
+/** \ingroup asyncio
+ * Helper function to populate the required \ref libusb_transfer fields
* for an interrupt transfer.
*
* \param transfer the transfer to populate
void LIBUSB_CALL libusb_unlock_events(libusb_context *ctx);
int LIBUSB_CALL libusb_event_handling_ok(libusb_context *ctx);
int LIBUSB_CALL libusb_event_handler_active(libusb_context *ctx);
+void LIBUSB_CALL libusb_interrupt_event_handler(libusb_context *ctx);
void LIBUSB_CALL libusb_lock_event_waiters(libusb_context *ctx);
void LIBUSB_CALL libusb_unlock_event_waiters(libusb_context *ctx);
int LIBUSB_CALL libusb_wait_for_event(libusb_context *ctx, struct timeval *tv);
const struct libusb_pollfd ** LIBUSB_CALL libusb_get_pollfds(
libusb_context *ctx);
+void LIBUSB_CALL libusb_free_pollfds(const struct libusb_pollfd **pollfds);
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);
* per libusb_context and it is safe to call libusb_hotplug_deregister_callback()
* on an already deregisted callback.
*
- * Since version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102
+ * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* For more information, see \ref hotplug.
*/
/** \ingroup hotplug
*
- * Since version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102
+ * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* Flags for hotplug events */
typedef enum {
+ /** Default value when not using any flags. */
+ LIBUSB_HOTPLUG_NO_FLAGS = 0,
+
/** Arm the callback and fire it for all matching currently attached devices. */
- LIBUSB_HOTPLUG_ENUMERATE = 1,
+ LIBUSB_HOTPLUG_ENUMERATE = 1<<0,
} libusb_hotplug_flag;
/** \ingroup hotplug
*
- * Since version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102
+ * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* Hotplug events */
typedef enum {
* This callback may be called by an internal event thread and as such it is
* recommended the callback do minimal processing before returning.
*
- * libusbx will call this function later, when a matching event had happened on
+ * libusb will call this function later, when a matching event had happened on
* a matching device. See \ref hotplug for more information.
*
* It is safe to call either libusb_hotplug_register_callback() or
* libusb_hotplug_deregister_callback() from within a callback function.
*
- * Since version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102
+ * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* \param ctx context of this notification
* \param device libusb_device this event occurred on
*
* If the \ref LIBUSB_HOTPLUG_ENUMERATE is passed the callback will be
* called with a \ref LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED for all devices
- * already plugged into the machine. Note that libusbx modifies its internal
+ * already plugged into the machine. Note that libusb modifies its internal
* device list from a separate thread, while calling hotplug callbacks from
* libusb_handle_events(), so it is possible for a device to already be present
* on, or removed from, its internal device list, while the hotplug callbacks
* from libusb_handle_events(); and/or your callback may be called for the
* removal of a device for which an arrived call was never made.
*
- * Since version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102
+ * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* \param[in] ctx context to register this callback with
* \param[in] events bitwise or of events that will trigger this callback. See \ref
* Deregister a callback from a libusb_context. This function is safe to call from within
* a hotplug callback.
*
- * Since version 1.0.16, \ref LIBUSBX_API_VERSION >= 0x01000102
+ * Since version 1.0.16, \ref LIBUSB_API_VERSION >= 0x01000102
*
* \param[in] ctx context this callback is registered with
* \param[in] handle the handle of the callback to deregister
projects / platform / upstream / libusb.git / blobdiff