#include <stdint.h>
+/**
+ * @brief Context of library
+ * @details This structure represents libhusb session.
+ * Using own session allow to use of library independently.
+ * For example calling libhusb_exit() will ont destroy resources
+ * that are being used by another user of library.
+ *
+ * To create session there is need to call libhusb_init(), to
+ * to destroy libhusb_exit(). Each session created by libhusb_init()
+ * hast to be destroyed using libhusb_exit()
+ */
struct libhusb_context;
typedef struct libhusb_context libhusb_context;
+/**
+ * @brief Structure representing USB device.
+ * @details This structure represents libhusb device found on USB bus.
+ *
+ * Some basic operations can be performed on a device using this struct.
+ * To perform any I/O a device handle must be obtain by opening device
+ * using libhusb_open() or libhusb_device_open_with_vid_pid().
+ *
+ */
struct libhusb_device;
typedef struct libhusb_device libhusb_device;
+/**
+ * @brief libhusb_device_handle struct
+ * @details This opaqe type, and represents handle to USB device.
+ *
+ * Hendle is used to perform I/O operations, when finished libhusb_close()
+ * should be called.
+ */
struct libhusb_device_handle;
typedef struct libhusb_device_handle libhusb_device_handle;
+/**
+ * @brief libhusb_cfg_descriptor struct
+ * @details Structure represents the standard USB configuration descriptor.
+ *
+ * All multiple-byte fields are represented in host-endian format.
+ */
struct libhusb_cfg_descriptor;
typedef struct libhusb_cfg_descriptor libhusb_cfg_descriptor;
+/**
+ * @brief libhusb_supported_speed
+ * @details This field contain speed that USB device can support.
+ */
enum libhusb_supported_speed {
LIBHUSB_SPEED_UNKNOWN = 0,
LIBHUSB_SPEED_SUPER = 4,
};
+/**
+ * @brief libhusb_device_descriptor struct
+ * @details This structure presents standard USB device descriptor.
+ */
struct libhusb_device_descriptor {
uint8_t bLength;
uint8_t bDescriptorType;
uint8_t bNumConfigurations;
};
+/**
+ * @brief libhusb_cfg_descriptor struct
+ * @details This structure presents standard USB configuration descriptor.
+ */
struct libhusb_cfg_descriptor {
uint8_t bLength;
uint8_t bDescriptorType;
int extra_length;
};
+/**
+ * @brief libhusb_interface struct
+ * @details This is collection of alternate settings for USB interface.
+ */
struct libhusb_interface {
struct libhusb_interface_descriptor *altsetting;
int num_altsetting;
};
+/**
+ * @brief libhusb_interface_descriptor struct
+ * @details This structure presents standard USB interface descriptor.
+ */
struct libhusb_interface_descriptor {
uint8_t bLength;
uint8_t bDescriptorType;
int extra_length;
};
+/**
+ * @brief libhusb_interface_descriptor struct
+ * @details This structure presents standard USB endpoint descriptor.
+ */
struct libhusb_endpoint_descriptor {
uint8_t bLength;
uint8_t bDescriptorType;
int extra_length;
};
+/**
+ * @brief usb_device_error
+ * @details This field contain error codes.
+ * Library return 0 on success or negative number on error.
+ *
+ * libhusb_error_name() can be used to translate error number
+ * to string representation.
+ */
enum usb_device_error {
LIBHUSB_SUCCESS = 0,
LIBHUSB_ERROR_IO = -1,
LIBHUSB_ERROR_OTHER = -99,
};
+/**
+ * @brief usb_device_transfer_status
+ * @details Transfer status codes.
+ */
enum usb_device_transfer_status {
LIBHUSB_TRANSFER_COMPLETED,
LIBHUSB_TRANSFER_ERROR,
LIBHUSB_TRANSFER_OVERFLOW,
};
+/**
+ * @brief Initalize libhusb.
+ * @details Function must be called befor any other function.
+ * @param ctx Context pointer, can`t be NULL.
+ * @return 0 on success or LIBHUSB_ERROR code on failure.
+ */
int libhusb_init(libhusb_context **ctx);
+/**
+ * @brief Deinitalize libhusb.
+ * @details Function must be called after closing all devices
+ * and before application close. It has to be called to cleanup
+ * the memory used by library.
+ * @param ctx context to deinitalize.
+ */
void libhusb_exit(libhusb_context *ctx);
+/**
+ * @brief Opens device.
+ * @details Function open device and return device handle.
+ * Device handle allow to perform operations on USB device.
+ * @param dev Device to open.
+ * @return 0 on success
+ * @return LIBHUSB_ERROR_NO_MEM mem allocation failure
+ * @return LIBHUSB_ERROR_ACCESS if no proper permission to access device
+ * @return LIBHUSB_ERROR_NO_DEVICE if there is no device connected
+ * @return other error on failure
+ */
libhusb_device_handle *libhusb_open(libhusb_device *dev);
+/**
+ * @brief Close device.
+ * @details Function should be called before libhusb_exit().
+ * It destroy reference that was added by libhusb_open().
+ * @param handle Handle to device that should be closed.
+ */
void libhusb_close(libhusb_device_handle *handle);
+/**
+ * @brief Opens device with vaild idVendor and idProduct
+ * @details Function can be used to open device with known idVendor and
+ * idProduct. If two or more devices have same vendor and product id only
+ * first will be open.
+ * @param ctx Context
+ * @param vendor_id idVendor of connected device.
+ * @param product_id idProduct of connected device.
+ * @return handle to the first found device, NULL if no device found
+ * or error occurred.
+ */
libhusb_device_handle *libhusb_device_open_with_vid_pid(libhusb_context *ctx,
uint16_t vendor_id, uint16_t product_id);
+/**
+ * @brief Get device.
+ * @details Function get elementary device for handle. Function does
+ * not modify ref count of returned device. User can use returned device
+ * as long as handle is opened.
+ * @param handle Device handle.
+ * @return Elementary device.
+ */
libhusb_device *libhusb_get_device(libhusb_device_handle *handle);
+/**
+ * @brief Get USB device list.
+ * @details This function return list of USB devices attached to system.
+ * To free device list libhusb_free_devices() should be used, this
+ * function can also unref devices. Do not unref device and
+ * then open it.
+ *
+ * Each devices have reference counter. Functions libhusb_ref_device() and
+ * libhusb_unref_device() are used to ref or unref device. When ref counter
+ * reach 0 device will be freed.
+ * Devices reached by calling libhusb_get_devices() have a reference count of
+ * 1, and libhusb_free_devices() can optionally decrease the reference count
+ * on all devices in the list. libhusb_open() adds another reference which is
+ * later destroyed by libhusb_close().
+ *
+ * @param ctx Context.
+ * @param devs List of devices. Mus be freed with libhusb_free_devices().
+ * @return numbers of connected devices or libhusb_error() code.
+ */
ssize_t libhusb_get_devices(libhusb_context *ctx, libhusb_device ***devs);
+/**
+ * @brief Free devices list.
+ * @details Function need to be called to free device list. This
+ * function can also unref devices if unref_devices is set.
+ * Do not unref device and then open it.
+ * @param list List of devices.
+ * @param unref_devices Set to unref devices.
+ */
void libhusb_free_devices(libhusb_device **list, int unref_devices);
+/**
+ * @brief Ref a device.
+ * @details Increment ref count of device.
+ * @param dev Device to reference.
+ * @return The same device.
+ */
libhusb_device *libhusb_ref_device(libhusb_device *dev);
+/**
+ * @brief Unef a device.
+ * @details Decrement ref count of device. If ref count reach zero,
+ * device should be destroyed.
+ * @param dev Device to reference.
+ */
void libhusb_unref_device(libhusb_device *dev);
+/**
+ * @brief Get max packet size.
+ * @details Function will retrieve the wMaxPacketSize for particular endpoint
+ * in active device configuration.
+ * @param dev Device.
+ * @param endpoint Address of endpoint.
+ * @return the wMaxPacketSize value.
+ * @return LIBHUSB_ERROR_NOT_FOUND if the endpoint does not exist.
+ * @return LIBHUSB_ERROR_OTHER on other failure.
+ */
int libhusb_get_max_packet_size(libhusb_device *dev, uint8_t endpoint);
+/**
+ * @brief Get bus number.
+ * @details Get device bus number. This is number of the bus
+ * that device is connected to.
+ * @param dev Device.
+ * @return Bus number.
+ */
uint8_t libhusb_get_bus_number(libhusb_device *dev);
+/**
+ * @brief Get address.
+ * @details Get device addres. This is addres of device on the bus
+ * that device is connected to.
+ * @param dev Device.
+ * @return Device address.
+ */
uint8_t libhusb_get_address(libhusb_device *dev);
+/**
+ * @brief Get list of port numbers.
+ * @details Get list of all port numbers from a device.
+ * @param dev Device.
+ * @param port_numbers Array containing port numbers.
+ * @param port_numbers_len Max lenght of array.
+ * @return Number of elements.
+ */
int libhusb_get_port_numbers(libhusb_device *dev, uint8_t *port_numbers, int port_numbers_len);
+/**
+ * @brief Get device descriptor.
+ * @details Get device descriptor for a device.
+ * @param dev Device.
+ * @param desc Location for descriptor data.
+ * @return 0 on success or a LIBHUSB_ERROR code on failure.
+ */
int libhusb_get_device_descriptor(libhusb_device *dev, struct libhusb_device_descriptor *desc);
+/**
+ * @brief Get active config.
+ * @details Get bConfigurationValue of active configuration.
+ * Function will return 0 value in configparameter
+ * if device is unconfigured.
+ * @param handle Device handle
+ * @param config Location for bConfigurationValue (valid on ret 0)
+ * @return 0 on success
+ * @return LIBHUSB_ERROR_NO_DEVICE if the dev has been disconnected
+ * @return another LIBHUSB_ERROR code on other failure
+ */
int libhusb_get_active_config(libhusb_device_handle *handle, int *config);
+/**
+ * @brief Set configuration.
+ * @details Set active configuration for a device.
+ * @param handle Device handle.
+ * @param configuration bConfigurationValue of configuration to active.
+ * @return 0 on success
+ * @return LIBHUSB_ERROR_NOT_FOUND if the req configuration does not exist
+ * @return LIBHUSB_ERROR_BUSY if interfaces are currently claimed
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected
+ * @return another LIBHUSB_ERROR code on other failure
+ */
int libhusb_set_config(libhusb_device_handle *handle, int configuration);
+/**
+ * @brief Claim interface.
+ * @details Claim interface on a device handle.
+ * To perform I/O operations on interface user has to claim it.
+ * Remember to call libhusb_release_interface() when communication
+ * with the device is finished.
+ * @param handle Device Handle
+ * @param interface_number The bInterfaceNumber of interface to claim.
+ * @param force Set force to auto detach kernel driver.
+ * @return 0 on success.
+ * @return LIBHUSB_ERROR_NOT_FOUND if the requested interface does not exist.
+ * @return LIBHUSB_ERROR_BUSY if another program or driver has claimed the
+ * interface.
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected.
+ * @return a LIBHUSB_ERROR code on other failure
+ */
int libhusb_claim_interface(libhusb_device_handle *handle, int interface_number, int force);
+/**
+ * @brief Release interface.
+ * @details Release interface previously claimed by libhusb_claim_interface().
+ * This is a blocking function.
+ * @param handle Device handle.
+ * @param interface_number The bInterfaceNumber of interface to release.
+ * @return 0 on success
+ * @return LIBHUSB_ERROR_NOT_FOUND if the interface was not claimed
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected
+ * @return another LIBHUSB_ERROR code on other failure
+ */
int libhusb_release_interface(libhusb_device_handle *handle, int interface_number);
+/**
+ * @brief Clear the halt/stall condition.
+ * @details Clear the halt/stall condition for an endpoint.
+ * @param handle Device handle.
+ * @param endpoint The endpoint to clear halt status.
+ * @return 0 on success
+ * @return LIBHUSB_ERROR_NOT_FOUND if the endpoint does not exist
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected
+ * @return another LIBHUSB_ERROR code on other failure
+ */
int libhusb_clear_halt(libhusb_device_handle *handle, uint8_t endpoint);
+/**
+ * @brief Reset a device.
+ * @details Reset USB port to reinitalize a device.
+ * This is a blocking function.
+ * @param handle Device handle.
+ * @return 0 on success.
+ * @return LIBHUSB_ERROR_NOT_FOUND if re-enumeration is required, or if the
+ * device has been disconnected.
+ * @return another LIBHUSB_ERROR code on other failure.
+ */
int libhusb_reset_device(libhusb_device_handle *handle);
+/**
+ * @brief Determine active kernel driver.
+ * @details Determine if a kernel driver is active on an interface.
+ * Interface can't be claimed if driver is active unless force
+ * option is used.
+ * @param handle Device handle.
+ * @param interface_number number of interface to check
+ * @return 0 if no kernel driver is active
+ * @return 1 if a kernel driver is active
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected.
+ * @return LIBHUSB_ERROR_NOT_SUPPORTED on platforms where the functionality
+ * is not available.
+ * @return another LIBHUSB_ERROR code on other failure.
+ * @see libhusb_detach_kernel_driver()
+ */
int libhusb_kernel_driver_active(libhusb_device_handle *handle, int interface_number);
+/**
+ * @brief Detach kernel driver.
+ * @details Detach a kernel driver from an interface.
+ * @param handle Device handle.
+ * @param interface_number Number of interface on which detach kernel driver.
+ * @return 0 on success
+ * @return LIBHUSB_ERROR_NOT_FOUND if no kernel driver was active
+ * @return LIBHUSB_ERROR_INVALID_PARAM if the interface does not exist
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected
+ * @return LIBHUSB_ERROR_NOT_SUPPORTED on platforms where the functionality
+ * is not available
+ * @return another LIBHUSB_ERROR code on other failure
+ * @see libhusb_kernel_driver_active()
+ */
int libhusb_detach_kernel_driver(libhusb_device_handle *handle, int interface_number);
+/**
+ * @brief Attach kernel driver
+ * @details Re-attach an interface's kernel driver, which was previously detached
+ * using libhusb_detach_kernel_driver().
+ * @param handle Device handle.
+ * @param interface_number Interface to attach the driver.
+ * @return 0 on success.
+ * @return LIBHUSB_ERROR_NOT_FOUND if no kernel driver was active.
+ * @return LIBHUSB_ERROR_INVALID_PARAM if the interface does not exist.
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected.
+ * @return LIBHUSB_ERROR_NOT_SUPPORTED on platforms where the functionality
+ * is not available.
+ * @return LIBHUSB_ERROR_BUSY if the driver cannot be attached because the
+ * interface is claimed by a program or driver.
+ * @return another LIBHUSB_ERROR code on other failure
+ * @see libhusb_kernel_driver_active()
+ */
int libhusb_attach_kernel_driver(libhusb_device_handle *handle, int interface_number);
+/**
+ * @brief Get config descriptor.
+ * @details Get a USB configuration descriptor.
+ * @param dev Device
+ * @param config_index index of configuration to retrieve.
+ * @param config Output location for USB configuration descriptor.
+ * Must be freed with libhusb_free_config_descriptor().
+ * @return 0 on success
+ * @return LIBHUSB_ERROR_NOT_FOUND if the configuration does not exist.
+ * @return another LIBHUSB_ERROR code on error.
+ */
int libhusb_get_config_descriptor(libhusb_device *dev, uint8_t config_index,
struct libhusb_cfg_descriptor **config);
+/**
+ * @brief Free config descriptor.
+ * @details Free configuration descriptor obtained from
+ * libhusb_get_config_descriptor().
+ * @param config Configuration to free.
+ */
void libhusb_free_config_descriptor(struct libhusb_cfg_descriptor *config);
+/**
+ * @brief Get string descriptor.
+ * @details Retrieve a string descriptor in ASCII.
+ * @param handle Device handle.
+ * @param desc_index Index of descriptor to retrieve.
+ * @param data Out buffer for ASCII string descriptor.
+ * @param length Data bufer size.
+ * @return number of bytes returned in data, or LIBHUSB_ERROR code on failure.
+ */
int libhusb_get_string_descriptor_ascii(libhusb_device_handle *handle,
uint8_t desc_index, unsigned char *data, int length);
/* sync IO */
+/**
+ * @brief Perform USB control transfer.
+ * @details
+ *
+ * The wValue, wIndex and wLength fields values should be given in host-endian
+ * byte order
+ *
+ * @param handle Device handle.
+ * @param request_type Request type field for the setup packet
+ * @param bRequest Request field for the setup packet
+ * @param wValue Value field for the setup packet
+ * @param wIndex Index field for the setup packet
+ * @param data Suitably-sized data buffer for either input or output
+ * (depending on direction bits within bmRequestType)
+ * @param wLength Length field for the setup packet. The data buffer should
+ * be at least this size.
+ * @param timeout Timeout (in millseconds) that this function should wait
+ * before giving up due to no response being received. For an unlimited
+ * timeout, 0 value should be used.
+ * @return on success, the number of bytes actually transferred
+ * @return LIBHUSB_ERROR_TIMEOUT if the transfer timed out
+ * @return LIBHUSB_ERROR_PIPE if the control request was not supported by the
+ * device
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected
+ * @return another LIBHUSB_ERROR code on other failures
+ */
int libhusb_control_transfer(libhusb_device_handle *handle,
uint8_t request_type, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
unsigned char *data, uint16_t wLength, unsigned int timeout);
+/**
+ * @brief Perform a bulk transfer.
+ * @details Perform a USB bulk transfer. The direction of the transfer is inferred from
+ * the direction bits of the endpoint address.
+ *
+ * @param handle Device handle.
+ * @param endpoint Address of a valid endpoint to communicate with
+ * @param data Suitably-sized data buffer for either input or output
+ * (depending on endpoint)
+ * @param length For bulk writes, the number of bytes from data to be sent. for
+ * bulk reads, the maximum number of bytes to receive into the data buffer.
+ * @param transferred Output location for the number of bytes actually
+ * transferred.
+ * @param timeout Timeout (in millseconds) that this function should wait
+ * before giving up due to no response being received. For an unlimited
+ * timeout, 0 value should be used.
+ * @return 0 on success (and populates transferred)
+ * @return LIBHUSB_ERROR_TIMEOUT if the transfer timed out (and populates
+ * transferred)
+ * @return LIBHUSB_ERROR_PIPE if the endpoint halted
+ * @return LIBHUSB_ERROR_OVERFLOW if the device offered more data
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected
+ * @return another LIBHUSB_ERROR code on other failures
+ */
int libhusb_bulk_transfer(libhusb_device_handle *handle,
uint8_t endpoint, unsigned char *data, int length,
int *transferred, unsigned int timeout);
+/**
+ * @brief Perform interrupt transfer.
+ * @details Perform a USB interrupt transfer. The direction of the transfer is inferred
+ * from the direction bits of the endpoint address.
+ *
+ * @param handle Device handle.
+ * @param endpoint Address of a valid endpoint to communicate with
+ * @param data Suitably-sized data buffer for either input or output
+ * (depending on endpoint)
+ * @param length For bulk writes, the number of bytes from data to be sent. for
+ * bulk reads, the maximum number of bytes to receive into the data buffer.
+ * @param transferred Output location for the number of bytes actually
+ * transferred.
+ * @param timeout Timeout (in millseconds) that this function should wait
+ * before giving up due to no response being received. For an unlimited
+ * timeout, 0 value should be used.
+ * @return 0 on success (and populates transferred)
+ * @return LIBHUSB_ERROR_TIMEOUT if the transfer timed out (and populates
+ * transferred)
+ * @return 0 on success (and populates <tt>transferred</tt>)
+ * @return LIBHUSB_ERROR_TIMEOUT if the transfer timed out
+ * @return LIBHUSB_ERROR_PIPE if the endpoint halted
+ * @return LIBHUSB_ERROR_OVERFLOW if the device offered more data
+ * @return LIBHUSB_ERROR_NO_DEVICE if the device has been disconnected
+ * @return another LIBHUSB_ERROR code on other error
+ */
int libhusb_interrupt_transfer(libhusb_device_handle *handle,
uint8_t endpoint, unsigned char *data, int length,
int *transferred, unsigned int timeout);
+/**
+ * @brief Translate error name
+ * @details Translates error code to NULL terminated libhusb
+ * error or status code.
+ * @param error_code Error code to translate.
+ * @return Error name
+ */
const char *libhusb_error_name(int error_code);
#ifdef __cplusplus
projects / platform / core / api / usb-host.git / commitdiff