Tizen(Headed) Native API  6.5
USB Host Device

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

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]devDevice that should be closed
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_DEVICE_NOT_OPENEDIf device is not opened
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devDevice
[out]device_addressDevice address
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed
USB_HOST_ERROR_NOT_SUPPORTEDNot 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]devA device
[out]device_bcdDevice release number
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devA device
[out]bcd_usbBcd release number of USB
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devDevice handle
[out]bus_numberDevice bus number
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
int usb_host_device_get_class ( usb_host_device_h  dev,
int *  device_class 
)

Gets device class.

Since :
3.0
Parameters:
[in]devA device
[out]device_classDevice class
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devDevice
[in]config_indexindex of configuration to retrieve (counting from 0)
[out]configOutput location for USB configuration
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_FOUNDThe configuration does not exist
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed
USB_HOST_ERROR_NOT_SUPPORTEDNot 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]devA device
[out]product_idProduct id of dev
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devA device
[out]vendor_idVendor id of dev
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devA handle to opened device
[in,out]lengthData buffer size/how much was actually used
[out]dataBuffer to store string
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_OVERFLOWThere was no space in buffer
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devA device
[out]max_packet_sizeMaximum size of single packet, in bytes
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devA device
[out]num_configurationsNumber of configurations for given device
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devDevice
[out]port_numbersArray to be filled with port numbers
[in]port_numbers_lenMax length of array
[out]ports_countNumber of all ports obtained from device
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed
USB_HOST_ERROR_OUT_OF_MEMORYInsufficient memory
USB_HOST_ERROR_NOT_SUPPORTEDNot 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]devA handle to opened device
[in,out]lengthData buffer size/how much was actually used
[out]dataBuffer to store string
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_OVERFLOWThere was no space in buffer
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devA device
[out]protocolDevice protocol
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devA handle to opened device
[in,out]lengthData buffer size/how much was actually used
[out]dataBuffer to store string
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_OVERFLOWThere was no space in buffer
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devA device
[out]subclassDevice subclass
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed

Opens a device.

This function opens a device, which allows performing operations on it (including transfer operations and strings introspection).

Since :
3.0
Remarks:
An application having platform privilege level can use this api without user confirmation by declaring http://tizen.org/privilege/usb.host, which has been added since 6.5.
Parameters:
[in]devDevice to open
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_OUT_OF_MEMORYMemory allocation failure
USB_HOST_ERROR_NO_SUCH_DEVICEThere is no device connected
USB_HOST_ERROR_PERMISSION_DENIEDNo proper permission to access device
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed
USB_HOST_ERROR_NOT_SUPPORTEDOperation 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
Remarks:
An application having platform privilege level can use this api without user confirmation by declaring http://tizen.org/privilege/usb.host, which has been added since 6.5.
Parameters:
[in]ctxContext
[in]vendor_ididVendor of connected device
[in]product_ididProduct of connected device
[out]device_handleOpened device handle
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_OUT_OF_MEMORYInsufficient memory
USB_HOST_ERROR_NO_SUCH_DEVICENo device
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed

Puts a device in unconfigured state.

Since :
4.0
Parameters:
[in]devDevice to be unconfigured
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_RESOURCE_BUSYInterfaces are currently claimed
USB_HOST_ERROR_NO_SUCH_DEVICEDevice has been disconnected
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devsList of devices
[in]unref_devicesSet 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_NONESuccessful
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed
Precondition:
usb_host_get_device_list() must be called before using this function.

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]devA device
[out]configHandle to active configuration
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NO_SUCH_DEVICEthe dev has been disconnected
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed
USB_HOST_ERROR_DEVICE_NOT_OPENEDThe device was not opened
USB_HOST_ERROR_NOT_SUPPORTEDNot 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]ctxContext handle
[out]devsAn array of devices
[out]lengthNumber of devices
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_OUT_OF_MEMORYOut of memory
USB_HOST_ERROR_NOT_SUPPORTEDOperation not supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]devA device
[out]is_openedTrue if device is opened, false otherwise
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_SUPPORTEDNot supported
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed

Refs a device.

Increment ref count of device.

Since :
3.0
Parameters:
[in]devDevice to reference
Returns:
0 on success, error code otherwise
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_INVALID_PARAMETERInvalid 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]configurationHandle to configuration to be activated
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_NOT_FOUNDRequested configuration does not exist
USB_HOST_ERROR_RESOURCE_BUSYInterfaces are currently claimed
USB_HOST_ERROR_NO_SUCH_DEVICEThe device has been disconnected
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed
USB_HOST_ERROR_DEVICE_NOT_OPENEDThe device was not opened
USB_HOST_ERROR_NOT_SUPPORTEDNot supported

Unrefs a device.

Decrements ref count of device. If ref count reaches zero, device will be destroyed.

Since :
3.0
Parameters:
[in]devDevice to unreference
Returns:
0 on success, otherwise a negative error value
Return values:
USB_HOST_ERROR_NONESuccessful
USB_HOST_ERROR_INVALID_PARAMETERInvalid parameter was passed