The device module API is used to manage USB devices.

The device module 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)
	Returns a list of USB devices attached to the system.
int	usb_host_free_device_list (usb_host_device_h *devs, bool unref_devices)
	Frees devices list and optionally unrefs its contents.
int	usb_host_ref_device (usb_host_device_h dev)
	Increments the reference counter of given USB device.
int	usb_host_unref_device (usb_host_device_h dev)
	Decrements the reference counter of given USB device.
int	usb_host_device_open (usb_host_device_h dev)
	Opens a device obtained from the list of devices to allow operations.
int	usb_host_device_close (usb_host_device_h dev)
	Closes an opened but not destroyed USB device handle.
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, known idVendor and idProduct.
int	usb_host_device_get_bus_number (usb_host_device_h dev, int *bus_number)
	Gets the number of the bus the given device is connected to.
int	usb_host_device_get_address (usb_host_device_h dev, int *device_address)
	Gets the address on the bus the given device is connected to.
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 available from a device.
int	usb_host_device_get_config (usb_host_device_h dev, int config_index, usb_host_config_h *config)
	Gets a USB configuration from a device given an index.
int	usb_host_get_active_config (usb_host_device_h dev, usb_host_config_h *config)
	Gets a handle to the configuration currently active on the device.
int	usb_host_set_config (usb_host_config_h configuration)
	Sets a configuration as the currently active on a device.
int	usb_host_device_unconfigure (usb_host_device_h dev)
	Returns a USB device back to the unconfigured state.
int	usb_host_device_get_bcd_usb (usb_host_device_h dev, int *bcd_usb)
	Gets USB specification release number supported by given device.
int	usb_host_device_get_class (usb_host_device_h dev, int *device_class)
	Gets the numerical device class of given USB device.
int	usb_host_device_get_sub_class (usb_host_device_h dev, int *subclass)
	Gets the numerical sub class of given USB device.
int	usb_host_device_get_protocol (usb_host_device_h dev, int *protocol)
	Gets the protocol being used by the given USB device.
int	usb_host_device_get_max_packet_size_0 (usb_host_device_h dev, int *max_packet_size)
	Gets the maximum packet size for endpoint 0 on given USB device.
int	usb_host_device_get_id_vendor (usb_host_device_h dev, int *vendor_id)
	Gets the numerical vendor identifier of the given USB device.
int	usb_host_device_get_id_product (usb_host_device_h dev, int *product_id)
	Gets the numerical product identifier of the given USB device.
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 the number of configurations for given USB device.
int	usb_host_is_device_opened (usb_host_device_h dev, bool *is_opened)
	Checks whether given USB device is currently opened.
int	usb_host_device_get_manufacturer_str (usb_host_device_h dev, int length, unsigned char data)
	Gets string describing an open device's manufacturer, in ASCII.
int	usb_host_device_get_product_str (usb_host_device_h dev, int length, unsigned char data)
	Gets product string of an open USB device, in ASCII.
int	usb_host_device_get_serial_number_str (usb_host_device_h dev, int length, unsigned char data)
	Gets the serial number of an open USB device, in ASCII.
Typedefs
typedef struct usb_host_device_s *	usb_host_device_h
	An opaque handle representing a USB device on the bus.

Typedef Documentation

typedef struct usb_host_device_s* usb_host_device_h

An opaque handle representing a USB device on the bus.

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_pid(). Some basic operations can be performed on closed device obtained by usb_host_get_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 an opened but not destroyed USB device handle.

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 the address on the bus the given device is connected to.

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 supported by given device.

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 the number of the bus the given device is connected to.

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 the numerical device class of given USB device.

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 USB configuration from a device given an index.

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 the numerical product identifier of the given USB device.

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 the numerical vendor identifier of the given USB device.

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 an open device's 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 the maximum packet size for endpoint 0 on given USB device.

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 the number of configurations for given USB 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 available from a device.

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 an open USB 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 the protocol being used by the given USB device.

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 the serial number of an open USB 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 the numerical sub class of given USB device.

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 obtained from the list of devices to allow operations.

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, known 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 )

Returns a USB device back to the 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 and optionally unrefs its contents.

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 a handle to the configuration currently active on the device.

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
	)

Returns a list of USB devices attached to the system.

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 whether given USB device is currently 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 )

Increments the reference counter of given USB device.

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

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 as the currently active on 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 )

Decrements the reference counter of given USB 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