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_device_get_* functions to get these parameters, e.g. usb_host_device_get_id_vendor(). 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_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().

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

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] 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

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]	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

Overview

Opening a device node

Preparing Communication

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation