Tizen Native API
5.5
|
This API is used to manage USB devices.
Overview
Operations described here help with enumerating, opening and closing devices.
Opening a device node
In order to communicate with device, you must open a device. The easiest way to do this is to use usb_host_device_open_with_vid_pid() function. However, it is not recommended in most of real-life applications, since there can be more than one device with given vendor id and product id. Another way is to list all available devices and choose the one we want to communicate with.
usb_host_device_h *devs; usb_host_device_h found = NULL; n = usb_host_get_device_list(ctx, &devs); for (i = 0; i < n; ++i) { if (check(devs[i]) { found = devs[i]; break; } } if (found) { usb_host_device_open(found); //perform communication ... usb_host_device_close(dev); } usb_host_free_device_list(devs);
The example code above shows how to open a device for communication and clean up allocated resources afterwards. First, we iterate through all connected devices looking for the one we want to communicate with. The check() function can be implemented based on any device parameters. Use usb_host_get_* functions to get these parameters, e.g. usb_host_get_device_descriptor(). If we found a device, we can open it by usb_host_device_open() and perform communication with it. After performing communication we should close device and free device list.
You can check if device is opened by calling usb_host_is_device_opened().
Each device has reference counter. Functions usb_host_ref_device() and usb_host_unref_device() are used to ref or unref device. When ref counter reach 0 device will be freed. Devices reached by calling usb_host_get_devices() have a reference count of 1, and usb_host_free_device_list() can optionally decrease the reference count on all devices in the list. usb_host_device_open() adds another reference which is later destroyed by usb_host_device_close().
Preparing Communication
Before communicating with device, you should claim the interface you want to communicate on. Kernel driver can be attached to the interface and you should detach it if you want to use that interface. You can do it directly by calling usb_host_kernel_driver_active() and usb_host_detach_kernel_driver or pass force flag to usb_host_claim_interface();
ret = usb_host_claim_interface(interface);
In this case driver will be detached if there is an active one and will be re-attached when you release it by usb_host_release_interface().
Remember to release claimed interfaces after communication and re-attach manually detached kernel drivers.
Related Features
This API is related with the following features:
- http://tizen.org/feature/usb.host
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature List.
Functions | |
int | usb_host_get_device_list (usb_host_context_h ctx, usb_host_device_h **devs, int *length) |
Gets USB device list. | |
int | usb_host_free_device_list (usb_host_device_h *devs, bool unref_devices) |
Frees devices list. | |
int | usb_host_ref_device (usb_host_device_h dev) |
Refs a device. | |
int | usb_host_unref_device (usb_host_device_h dev) |
Unrefs a device. | |
int | usb_host_device_open (usb_host_device_h dev) |
Opens a device. | |
int | usb_host_device_close (usb_host_device_h dev) |
Closes device. | |
int | usb_host_device_open_with_vid_pid (usb_host_context_h ctx, int vendor_id, int product_id, usb_host_device_h *device_handle) |
Opens device with valid idVendor and idProduct. | |
int | usb_host_device_get_bus_number (usb_host_device_h dev, int *bus_number) |
Gets bus number. | |
int | usb_host_device_get_address (usb_host_device_h dev, int *device_address) |
Gets address. | |
int | usb_host_device_get_port_numbers (usb_host_device_h dev, int *port_numbers, int port_numbers_len, int *ports_count) |
Gets list of port numbers. | |
int | usb_host_device_get_config (usb_host_device_h dev, int config_index, usb_host_config_h *config) |
Gets a configuration. | |
int | usb_host_get_active_config (usb_host_device_h dev, usb_host_config_h *config) |
Gets an active config. | |
int | usb_host_set_config (usb_host_config_h configuration) |
Sets a configuration. | |
int | usb_host_device_unconfigure (usb_host_device_h dev) |
Puts a device in unconfigured state. | |
int | usb_host_device_get_bcd_usb (usb_host_device_h dev, int *bcd_usb) |
Gets USB specification release number. | |
int | usb_host_device_get_class (usb_host_device_h dev, int *device_class) |
Gets device class. | |
int | usb_host_device_get_sub_class (usb_host_device_h dev, int *subclass) |
Gets device sub class. | |
int | usb_host_device_get_protocol (usb_host_device_h dev, int *protocol) |
Gets device protocol. | |
int | usb_host_device_get_max_packet_size_0 (usb_host_device_h dev, int *max_packet_size) |
Gets maximum packet size for endpoint 0. | |
int | usb_host_device_get_id_vendor (usb_host_device_h dev, int *vendor_id) |
Gets vendor id. | |
int | usb_host_device_get_id_product (usb_host_device_h dev, int *product_id) |
Gets product id. | |
int | usb_host_device_get_bcd_device (usb_host_device_h dev, int *device_bcd) |
Gets device release number in binary-coded decimal. | |
int | usb_host_device_get_num_configurations (usb_host_device_h dev, int *num_configurations) |
Gets number of configurations for given device. | |
int | usb_host_is_device_opened (usb_host_device_h dev, bool *is_opened) |
Checks if device is opened. | |
int | usb_host_device_get_manufacturer_str (usb_host_device_h dev, int *length, unsigned char *data) |
Gets string describing device manufacturer, in ASCII. | |
int | usb_host_device_get_product_str (usb_host_device_h dev, int *length, unsigned char *data) |
Gets product string of device, in ASCII. | |
int | usb_host_device_get_serial_number_str (usb_host_device_h dev, int *length, unsigned char *data) |
Gets serial number of a device, in ASCII. | |
Typedefs | |
typedef struct usb_host_device_s * | usb_host_device_h |
Structure representing USB device. |
Typedef Documentation
typedef struct usb_host_device_s* usb_host_device_h |
Structure representing USB device.
This structure represents USB device found on USB bus.
This can be obtained by usb_host_get_device_list() or usb_host_device_open_with_vid_pidi(). Some basic operations can be performed on closed device obtained by usb_host_device_list(). To perform any I/O operations the device must be opened by calling usb_host_device_open() or usb_host_device_open_with_vid_pid().
- Since :
- 3.0
Function Documentation
int usb_host_device_close | ( | usb_host_device_h | dev | ) |
Closes device.
Function should be called before usb_host_destroy(). It destroys reference that was added by usb_host_device_open().
- Since :
- 3.0
- Parameters:
-
[in] dev Device that should be closed
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_DEVICE_NOT_OPENED If device is not opened USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_get_address | ( | usb_host_device_h | dev, |
int * | device_address | ||
) |
Gets address.
Gets device address. This is address of device on the bus that device is connected to.
- Since :
- 3.0
- Parameters:
-
[in] dev Device [out] device_address Device address
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed USB_HOST_ERROR_NOT_SUPPORTED Not supported
int usb_host_device_get_bcd_device | ( | usb_host_device_h | dev, |
int * | device_bcd | ||
) |
Gets device release number in binary-coded decimal.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] device_bcd Device release number
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_get_bcd_usb | ( | usb_host_device_h | dev, |
int * | bcd_usb | ||
) |
Gets USB specification release number.
Gets binary-coded decimal USB specification release number. This value is equal to bcdUSB field of device descriptor. See USB specification for more info.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] bcd_usb Bcd release number of USB
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_get_bus_number | ( | usb_host_device_h | dev, |
int * | bus_number | ||
) |
Gets bus number.
Gets device bus number. This is number of the bus that device is connected to.
- Since :
- 3.0
- Parameters:
-
[in] dev Device handle [out] bus_number Device bus number
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed USB_HOST_ERROR_NOT_SUPPORTED Not supported
int usb_host_device_get_class | ( | usb_host_device_h | dev, |
int * | device_class | ||
) |
Gets device class.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] device_class Device class
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_get_config | ( | usb_host_device_h | dev, |
int | config_index, | ||
usb_host_config_h * | config | ||
) |
Gets a configuration.
Gets a USB configuration from a device.
- Since :
- 3.0
- Remarks:
- config must be freed with usb_host_config_destroy().
- Parameters:
-
[in] dev Device [in] config_index index of configuration to retrieve (counting from 0) [out] config Output location for USB configuration
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_FOUND The configuration does not exist USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed USB_HOST_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- Returned configuration should be destroyed by usb_host_config_destroy() when no longer needed.
int usb_host_device_get_id_product | ( | usb_host_device_h | dev, |
int * | product_id | ||
) |
Gets product id.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] product_id Product id of dev
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_get_id_vendor | ( | usb_host_device_h | dev, |
int * | vendor_id | ||
) |
Gets vendor id.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] vendor_id Vendor id of dev
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_get_manufacturer_str | ( | usb_host_device_h | dev, |
int * | length, | ||
unsigned char * | data | ||
) |
Gets string describing device manufacturer, in ASCII.
- Since :
- 3.0
- Parameters:
-
[in] dev A handle to opened device [in,out] length Data buffer size/how much was actually used [out] data Buffer to store string
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_OVERFLOW There was no space in buffer USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- Precondition:
- dev must point to device opened by usb_host_device_open() or usb_host_device_open_with_vid_pid().
int usb_host_device_get_max_packet_size_0 | ( | usb_host_device_h | dev, |
int * | max_packet_size | ||
) |
Gets maximum packet size for endpoint 0.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] max_packet_size Maximum size of single packet, in bytes
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_get_num_configurations | ( | usb_host_device_h | dev, |
int * | num_configurations | ||
) |
Gets number of configurations for given device.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] num_configurations Number of configurations for given device
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_get_port_numbers | ( | usb_host_device_h | dev, |
int * | port_numbers, | ||
int | port_numbers_len, | ||
int * | ports_count | ||
) |
Gets list of port numbers.
Gets list of all port numbers from a device.
- Since :
- 3.0
- Parameters:
-
[in] dev Device [out] port_numbers Array to be filled with port numbers [in] port_numbers_len Max length of array [out] ports_count Number of all ports obtained from device
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed USB_HOST_ERROR_OUT_OF_MEMORY Insufficient memory USB_HOST_ERROR_NOT_SUPPORTED Not supported
int usb_host_device_get_product_str | ( | usb_host_device_h | dev, |
int * | length, | ||
unsigned char * | data | ||
) |
Gets product string of device, in ASCII.
- Since :
- 3.0
- Parameters:
-
[in] dev A handle to opened device [in,out] length Data buffer size/how much was actually used [out] data Buffer to store string
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_OVERFLOW There was no space in buffer USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- Precondition:
- dev must point to device opened by usb_host_device_open() or usb_host_device_open_with_vid_pid().
int usb_host_device_get_protocol | ( | usb_host_device_h | dev, |
int * | protocol | ||
) |
Gets device protocol.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] protocol Device protocol
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_get_serial_number_str | ( | usb_host_device_h | dev, |
int * | length, | ||
unsigned char * | data | ||
) |
Gets serial number of a device, in ASCII.
- Since :
- 3.0
- Parameters:
-
[in] dev A handle to opened device [in,out] length Data buffer size/how much was actually used [out] data Buffer to store string
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_OVERFLOW There was no space in buffer USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- Precondition:
- dev must point to device opened by usb_host_device_open() or usb_host_device_open_with_vid_pid().
int usb_host_device_get_sub_class | ( | usb_host_device_h | dev, |
int * | subclass | ||
) |
Gets device sub class.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] subclass Device subclass
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_open | ( | usb_host_device_h | dev | ) |
Opens a device.
This function opens a device, which allows performing operations on it (including transfer operations and strings introspection).
- Since :
- 3.0
- Parameters:
-
[in] dev Device to open
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_OUT_OF_MEMORY Memory allocation failure USB_HOST_ERROR_NO_SUCH_DEVICE There is no device connected USB_HOST_ERROR_PERMISSION_DENIED No proper permission to access device USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed USB_HOST_ERROR_NOT_SUPPORTED Operation not supported
- See also:
- usb_host_is_device_opened()
int usb_host_device_open_with_vid_pid | ( | usb_host_context_h | ctx, |
int | vendor_id, | ||
int | product_id, | ||
usb_host_device_h * | device_handle | ||
) |
Opens device with valid idVendor and idProduct.
This 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 opened.
- Since :
- 3.0
- Parameters:
-
[in] ctx Context [in] vendor_id idVendor of connected device [in] product_id idProduct of connected device [out] device_handle Opened device handle
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_OUT_OF_MEMORY Insufficient memory USB_HOST_ERROR_NO_SUCH_DEVICE No device USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_device_unconfigure | ( | usb_host_device_h | dev | ) |
Puts a device in unconfigured state.
- Since :
- 4.0
- Parameters:
-
[in] dev Device to be unconfigured
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_RESOURCE_BUSY Interfaces are currently claimed USB_HOST_ERROR_NO_SUCH_DEVICE Device has been disconnected USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_free_device_list | ( | usb_host_device_h * | devs, |
bool | unref_devices | ||
) |
Frees devices list.
This function needs to be called to free device list. This function can also unref devices if unref_devices is set to non-zero value. Do not unref device and then open it.
- Since :
- 3.0
- Parameters:
-
[in] devs List of devices [in] unref_devices Set to true to unreference devices, set to false to not unref
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- Precondition:
- usb_host_get_device_list() must be called before using this function.
int usb_host_get_active_config | ( | usb_host_device_h | dev, |
usb_host_config_h * | config | ||
) |
Gets an active config.
Gets handle to active configuration. This function will return 0 value in config parameter :if device is unconfigured.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] config Handle to active configuration
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NO_SUCH_DEVICE the dev has been disconnected USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed USB_HOST_ERROR_DEVICE_NOT_OPENED The device was not opened USB_HOST_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- Obtained configuration should be destroyed by usb_host_config_destroy() when no longer needed.
int usb_host_get_device_list | ( | usb_host_context_h | ctx, |
usb_host_device_h ** | devs, | ||
int * | length | ||
) |
Gets USB device list.
This function returns list of USB devices attached to system. To free obtained device list usb_host_free_device_list() should be used, this function can also unref devices. Do not unref device and then open it.
All devices have reference counter. Functions usb_host_ref_device() and usb_host_unref_device() are used to ref or unref device. When ref counter reaches 0 device will be freed. Devices reached by calling usb_host_get_device_list() have a reference count of 1, and usb_host_free_device_list() can optionally decrease the reference count on all devices in the list. usb_host_device_open() adds another reference which is later destroyed by usb_host_device_close().
- Since :
- 3.0
- Parameters:
-
[in] ctx Context handle [out] devs An array of devices [out] length Number of devices
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_OUT_OF_MEMORY Out of memory USB_HOST_ERROR_NOT_SUPPORTED Operation not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
- Postcondition:
- devs must be freed with usb_host_free_device_list() when no longer needed.
int usb_host_is_device_opened | ( | usb_host_device_h | dev, |
bool * | is_opened | ||
) |
Checks if device is opened.
- Since :
- 3.0
- Parameters:
-
[in] dev A device [out] is_opened True if device is opened, false otherwise
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_SUPPORTED Not supported USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_ref_device | ( | usb_host_device_h | dev | ) |
Refs a device.
Increment ref count of device.
- Since :
- 3.0
- Parameters:
-
[in] dev Device to reference
- Returns:
- 0 on success, error code otherwise
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed
int usb_host_set_config | ( | usb_host_config_h | configuration | ) |
Sets a configuration.
Set active configuration for a device.
- Since :
- 3.0
- Parameters:
-
[in] configuration Handle to configuration to be activated
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_NOT_FOUND Requested configuration does not exist USB_HOST_ERROR_RESOURCE_BUSY Interfaces are currently claimed USB_HOST_ERROR_NO_SUCH_DEVICE The device has been disconnected USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed USB_HOST_ERROR_DEVICE_NOT_OPENED The device was not opened USB_HOST_ERROR_NOT_SUPPORTED Not supported
int usb_host_unref_device | ( | usb_host_device_h | dev | ) |
Unrefs a device.
Decrements ref count of device. If ref count reaches zero, device will be destroyed.
- Since :
- 3.0
- Parameters:
-
[in] dev Device to unreference
- Returns:
- 0 on success, otherwise a negative error value
- Return values:
-
USB_HOST_ERROR_NONE Successful USB_HOST_ERROR_INVALID_PARAMETER Invalid parameter was passed