libusb описание.

Предисловие

Введение

1. Обзор

Эта документация даст обзор работе API v0.1 libusb и какое имеет это отношение к USB. Работа быстро развивается в новую версию libusb, чтобы стать v1.0,в которой будет переработанны API и собирается устаревший v0.1. Вы можете желать проверить сайт libusb, чтобы видеть - стабильное и рекомендуемое.

Эта документация допускает что вы имеете хорошее понимание USB и как это работает. Если у вас нет хорошего понимания USB, рекомендовано, чтобы вы почитали спецификацию USB v2.0.

libusb работает с USB 1.1, тем не менее в перспективах libusb, USB 2.0 не будет значительно изменен для libusb.

2. Поддержка современных ОС

Linux (2.2, 2.4 and on)
FreeBSD, NetBSD and OpenBSD
Darwin/MacOS X
API

Это внешний API для использования в приложений.
API - сравнительно небольшой и разработанн, чтобы иметь закрытые аналогий в спецификации USB. v0.1 API по большей части был хакнут и kludged вместе без значительной преднамеренности и в результате, пропускается довольно много особенностей. В v1.0 собираемся исправить это.

Устройства и интерфейсы
libusb API связывают открытое устройство со специфическим интерфейсом. Это означает, что если Вы хотите потребовать многочисленные интерфейсы на устройстве, вы должны открывать долгое время устройства, чтобы получать один usb_dev_handle для каждого интерфейса с которого вы хотите передавать. Не забывайте вызывать usb_claim_interface.

Тайм-ауты
Тайм-аут в libusb всегда определены в течение миллисекунд.

Типы Данных
libusb использует как абстрагировавшее так и не абстрагированные структуры, чтобы поддерживать мобильность.

Синхронный
Все функции в libusb v0.1 синхронные, это означает, что функции блокируют и ждут операцию, чтобы завершиться или тайм-аут перед обратным выполнением в вызывающее приложение. Асинхронная операция будет поддержана в v1.0, но не v0.1.

Обратные величины
Есть два типов возвращения величин использованных в libusb v0.1. Первое - handle возвращается usb_open. Второй - int. Во всех случаях где int возвращано >= 0 имеется успех и < 0 - условие ошибки.

Функции

I. Ядро
usb_init - Инициализировать libusb
void usb_init(void);

Just like the name implies, usb_init sets up some internal structures. usb_init must be called before any other libusb functions.

usb_find_busses - Находит все шины USB в системе

int usb_find_busses(void);

usb_find_busses will find all of the busses on the system. Returns the number of changes since previous call to this function (total of new busses and busses removed).

usb_find_devices - Находить все устройства на всех устройствах USB

int usb_find_devices(void);

usb_find_devices will find all of the devices on each bus. This should be called after usb_find_busses. Returns the number of changes since the previous call to this function (total of new device and devices removed).

usb_get_busses - Возврат список обнаруженных шин USB

struct usb_bus *usb_get_busses(void);

usb_get_busses simply returns the value of the global variable usb_busses. This was implemented for those languages that support C calling convention and can use shared libraries, but don’t support C global variables (like Delphi).

II. Операции устройства
usb_open - Открыть устройство USB

usb_dev_handle *usb_open(struct *usb_device dev);

usb_open is to be used to open up a device for use. usb_open must be called before attempting to perform any operations to the device. Returns a handle used in future communication with the device.
usb_close - Закрытие устройство USB

int usb_close(usb_dev_handle *dev);

usb_close closes a device opened with usb_open. No further operations may be performed on the handle after usb_close is called. Returns 0 on success or < 0 on error. 

usb_set_configuration - устанавливает активную конфигурацию устройства

int usb_set_configuration(usb_dev_handle *dev, int configuration);

usb_set_configuration sets the active configuration of a device. The configuration parameter is the value as specified in the descriptor field bConfigurationValue. Returns 0 on success or < 0 on error.
usb_set_altinterface - устанавливает активную альтернативную установку текущего интерфейса

int usb_set_altinterface(usb_dev_handle *dev, int alternate);

usb_set_altinterface sets the active alternate setting of the current interface. The alternate parameter is the value as specified in the descriptor field bAlternateSetting. Returns 0 on success or < 0 on error.
usb_resetep - Восстанавливает состояние для конечной точки

int usb_resetep(usb_dev_handle *dev, unsigned int ep);

usb_resetep resets all state (like toggles) for the specified endpoint. The ep parameter is the value specified in the descriptor field bEndpointAddress. Returns 0 on success or < 0 on error.

Deprecated: usb_resetep is deprecated. You probably want to use usb_clear_halt.
usb_clear_halt - Очистка любого статуса останова в конечной точке

int usb_clear_halt(usb_dev_handle *dev, unsigned int ep);

usb_clear_halt clears any halt status on the specified endpoint. The ep parameter is the value specified in the descriptor field bEndpointAddress. Returns 0 on success or < 0 on error.
usb_reset - Восстанавливает(резетит) устройство

int usb_reset(usb_dev_handle *dev);

usb_reset resets the specified device by sending a RESET down the port it is connected to. Returns 0 on success or < 0 on error.

Causes re-enumeration: After calling usb_reset, the device will need to re-enumerate and thusly, requires you to find the new device and open a new handle. The handle used to call usb_reset will no longer work.
usb_claim_interface - Требует интерфейс устройства

int usb_claim_interface(usb_dev_handle *dev, int interface);

usb_claim_interface claims the interface with the Operating System. The interface parameter is the value as specified in the descriptor field bInterfaceNumber. Returns 0 on success or < 0 on error.

Must be called!: usb_claim_interface must be called before you perform any operations related to this interface (like usb_set_altinterface, usb_bulk_write, etc).

Return Codescode description
-EBUSY Interface is not available to be claimed
-ENOMEM Insufficient memory
usb_release_interface - Выпуск прежде предъявленного интерфейса

int usb_release_interface(usb_dev_handle *dev, int interface);

usb_release_interface releases an interface previously claimed with usb_claim_interface. The interface parameter is the value as specified in the descriptor field bInterfaceNumber. Returns 0 on success or < 0 on error.

III. Управляющие Передачи 

usb_control_msg - Посылать управляющее сообщение на устройство

int usb_control_msg(usb_dev_handle *dev, int requesttype, int request, int value, int index, char *bytes, int size, int timeout);

usb_control_msg performs a control request to the default control pipe on a device. The parameters mirror the types of the same name in the USB specification. Returns number of bytes written/read or < 0 on error.
usb_get_string - Извлекает дескриптор строки с устройства

int usb_get_string(usb_dev_handle *dev, int index, int langid, char *buf, size_t buflen);

usb_get_string retrieves the string descriptor specified by index and langid from a device. The string will be returned in Unicode as specified by the USB specification. Returns the number of bytes returned in buf or < 0 on error.

usb_get_string_simple - Извлекает дескриптор строки с устройства, использовавшего первый язык

int usb_get_string_simple(usb_dev_handle *dev, int index, char *buf, size_t buflen);

usb_get_string_simple is a wrapper around usb_get_string that retrieves the string description specified by index in the first language for the descriptor and converts it into C style ASCII. Returns number of bytes returned in buf or < 0 on error.
usb_get_descriptor - Извлекает дескриптор из встроенной управляющей трубы устройства(default control pipe)

int usb_get_descriptor(usb_dev_handle *dev, unsigned char type, unsigned char index, void *buf, int size);

usb_get_descriptor retrieves a descriptor from the device identified by the type and index of the descriptor from the default control pipe. Returns number of bytes read for the descriptor or < 0 on error.

See usb_get_descriptor_by_endpoint for a function that allows the control endpoint to be specified.

usb_get_descriptor_by_endpoint - Извлекает дескриптор с устройства 

int usb_get_descriptor_by_endpoint(usb_dev_handle *dev, int ep, unsigned char type, unsigned char index, void *buf, int size);

usb_get_descriptor_by_endpoint retrieves a descriptor from the device identified by the type and index of the descriptor from the control pipe identified by ep. Returns number of bytes read for the descriptor or < 0 on error

IV. Булк перадачи (Bulk Transfers)
usb_bulk_write - записывает данные в булк конечной точки

int usb_bulk_write(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);

usb_bulk_write performs a bulk write request to the endpoint specified by ep. Returns number of bytes written on success or < 0 on error.
usb_bulk_read - читает данные из конечной точки прерывания булка

int usb_bulk_read(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);

usb_bulk_read performs a bulk read request to the endpoint specified by ep. Returns number of bytes read on success or < 0 on error.

V. Передачи Прерывания
usb_interrupt_write - записывает данные по прерыванию конечной точки
int usb_interrupt_write(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);

usb_interrupt_write performs an interrupt write request to the endpoint specified by ep. Returns number of bytes written on success or < 0 on error.
usb_interrupt_read - читает данные из прерывания конечной точки

int usb_interrupt_read(usb_dev_handle *dev, int ep, char *bytes, int size, int timeout);

usb_interrupt_read performs a interrupt read request to the endpoint specified by ep. Returns number of bytes read on success or < 0 on error.

VI. Не Портативные
usb_get_driver_np - Получать драйверное имя связыванное с интерфейсом

int usb_get_driver_np(usb_dev_handle *dev, int interface, char *name, int namelen);

This function will obtain the name of the driver bound to the interface specified by the parameter interface and place it into the buffer named name limited to namelen characters. Returns 0 on success or < 0 on error.

Implemented on Linux only.
usb_detach_kernel_driver_np - удалять драйвер ядра с интерфейса

int usb_detach_kernel_driver_np(usb_dev_handle *dev, int interface);

This function will detach a kernel driver from the interface specified by parameter interface. Applications using libusb can then try claiming the interface. Returns 0 on success or < 0 on error.

Implemented on Linux only.

Примеры использования.
Есть некоторые не интуитивные части libusb v0.1, которые не трудны, но вероятно легче понимать их с некоторыми примерами.
Прежде, чем любая связь может произойти с устройством, она должна быть обнаружена. Это выполняется обнаружением всех шин и затем обнаруживаются все устройства во всех шинах: