The device module API is used to manage USB devices.

This module can be used to find and connect to the device, as well as inspect and configure it.

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.

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 one of the USB configurations for an USB device.
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 subclass 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 of this 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 for the given USB device.
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 the manufacturer string for the connected device.
int	usb_host_device_get_product_str (usb_host_device_h dev, int length, unsigned char data)
	Gets the product string for the connected device.
int	usb_host_device_get_serial_number_str (usb_host_device_h dev, int length, unsigned char data)
	Gets the serial number string for the connected device.
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().

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

#include <usb_host.h>

void work_on_device(usb_host_device_h dev)
{
    int ret;

    ret = usb_host_device_open(dev);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    // Use the device here

    ret = usb_host_device_close(dev);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

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

#include <usb_host.h>
#include <stdio.h>

void print_address(usb_host_device_h dev)
{
    int ret, device_address;

    ret = usb_host_device_get_address(dev, &device_address);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Device address: %d\n", device_address);
}

int usb_host_device_get_bcd_device	(	usb_host_device_h	dev,
		int *	device_bcd
	)

Gets device release number for the given USB device.

Gets device release number. The number will be returned as a binary-coded decimal.

Since :: 3.0

Parameters:

[in]	dev	A device
[out]	device_bcd	Device release number

Remarks:: Each hexadecimal digit corresponds to a single decimal digit, so you should expect only digits between 0x0 and 0x9 inclusively. The meaning of the value depends on the 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

#include <usb_host.h>
#include <stdio.h>

void print_device_product_id(usb_host_device_h dev)
{
    int ret, device_bcd;

    ret = usb_host_device_get_id_product(dev, &device_bcd);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    int release_number = 0;
    int mult = 1;

    while (device_bcd > 0) {
        release_number += mult * (device_bcd & 0xf);
        device_bcd >>= 4;
        mult *= 10;
    }

    printf("Release number: %d\n", release_number);
}

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

Remarks:: Each hexadecimal digit represents a single decimal digit, and there are two major version digits and two minor version digits. For instance, 0x1234 represents version 12.34.

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

#include <usb_host.h>
#include <stdio.h>

void print_usb_spec(usb_host_device_h dev)
{
    int ret, bcd_usb;

    ret = usb_host_device_get_bcd_usb(dev, &bcd_usb);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("USB specification version: %d%d.%d%d\n",
        (bcd_usb << 12) & 0xf,
        (bcd_usb << 8) & 0xf,
        (bcd_usb << 4) & 0xf,
        (bcd_usb << 0) & 0xf,
    );
}

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

#include <usb_host.h>
#include <stdio.h>

void print_bus_number(usb_host_device_h dev)
{
    int ret, bus_number;

    ret = usb_host_device_get_bus_number(dev, &bus_number);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Bus number: %d\n", bus_number);
}

int usb_host_device_get_class	(	usb_host_device_h	dev,
		int *	device_class
	)

Gets the numerical device class of given USB device.

Returns the numerical device class, which represents in high level the functionality of the 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

#include <usb_host.h>
#include <stdio.h>

void print_device_class(usb_host_device_h dev)
{
    int ret, device_class;

    ret = usb_host_device_get_class(dev, &device_class);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Device class: %d\n", device_class);
}

int usb_host_device_get_config	(	usb_host_device_h	dev,
		int	config_index,
		usb_host_config_h *	config
	)

Gets one of the USB configurations for an USB device.

Gets one of the USB configurations by its 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.

#include <usb_host.h>

void select_configuration(usb_host_device_h dev)
{
    int ret, num_configurations;
    usb_host_config_h config;

    ret = usb_host_device_get_num_configurations(dev, &num_configurations);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    for (int i = 0; i < num_configurations; ++i) {
        ret = usb_host_device_get_config(dev, i, &config);
        if (ret != USB_HOST_ERROR_NONE)
            handle_error(ret);

        if (interesting(config)) {
            ret = usb_host_set_config(config);
            if (ret != USB_HOST_ERROR_NONE)
                handle_error(ret);
        }

        ret = usb_host_config_destroy(config);
        if (ret != USB_HOST_ERROR_NONE)
            handle_error(ret);
    }
}

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.

Returns the numerical product identifier, representing a specific product of a vendor.

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

#include <usb_host.h>
#include <stdio.h>

void print_device_product_id(usb_host_device_h dev)
{
    int ret, product_id;

    ret = usb_host_device_get_id_product(dev, &vendor_id);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Product ID: %d\n", product_id);
}

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.

Returns the numerical vendor identifier, representing the vendor who produced the 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

#include <usb_host.h>
#include <stdio.h>

void print_device_vendor_id(usb_host_device_h dev)
{
    int ret, vendor_id;

    ret = usb_host_device_get_id_vendor(dev, &vendor_id);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Vendor ID: %d\n", vendor_id);
}

int usb_host_device_get_manufacturer_str	(	usb_host_device_h	dev,
		int *	length,
		unsigned char *	data
	)

Gets the manufacturer string for the connected device.

Gets string describing an open device's manufacturer, in ASCII.

Since :: 3.0

Parameters:

[in]	dev	A handle to opened device
[in,out]	length	Pointer to a variable containing the current size of the buffer, which will be modified to actual usage
[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().

#include <usb_host.h>
#include <stdio.h>

#define BUFFER_SIZE 128

void print_manufacturer_str(usb_host_device_h dev)
{
    int ret, length = BUFFER_SIZE - 1;
    unsigned char data[BUFFER_SIZE];

    ret = usb_host_device_get_manufacturer_str(dev, &length, data);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    data[length] = '\0';

    printf("Manufacturer: %s\n", data);
}

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 of this device.

Returns the maximum packet size for endpoint 0 on the 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

#include <usb_host.h>
#include <stdio.h>

void print_device_max_packet_size_0(usb_host_device_h dev)
{
    int ret, max_packet_size;

    ret = usb_host_device_get_max_packet_size_0(dev, &max_packet_size);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Maximum packet size for endpoint 0: %d bytes\n", max_packet_size);
}

int usb_host_device_get_num_configurations	(	usb_host_device_h	dev,
		int *	num_configurations
	)

Gets the number of configurations for given USB device.

Returns the number of configurations supported by the 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

#include <usb_host.h>

void select_configuration(usb_host_device_h dev)
{
    int ret, num_configurations;
    usb_host_config_h config;

    ret = usb_host_device_get_num_configurations(dev, &num_configurations);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    for (int i = 0; i < num_configurations; ++i) {
        ret = usb_host_device_get_config(dev, i, &config);
        if (ret != USB_HOST_ERROR_NONE)
            handle_error(ret);

        if (interesting(config)) {
            ret = usb_host_set_config(config);
            if (ret != USB_HOST_ERROR_NONE)
                handle_error(ret);
        }

        ret = usb_host_config_destroy(config);
        if (ret != USB_HOST_ERROR_NONE)
            handle_error(ret);
    }
}

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

#include <usb_host.h>
#include <stdio.h>

#define MAX_PORT_NUMBER 128

void print_port_numbers(usb_host_device_h dev)
{
    int ret, port_numbers[MAX_PORT_NUMBER], ports_count;

    ret = usb_host_device_get_port_numbers(dev, port_numbers, MAX_PORT_NUMBER, &ports_count);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    for (int i = 0; i < ports_count; ++i)
        printf("Available port: %d\n", port_numbers[i]);
}

int usb_host_device_get_product_str	(	usb_host_device_h	dev,
		int *	length,
		unsigned char *	data
	)

Gets the product string for the connected device.

Gets the product string of an open USB device, in ASCII.

Since :: 3.0

Parameters:

[in]	dev	A handle to opened device
[in,out]	length	Pointer to a variable containing the current size of the buffer, which will be modified to actual usage
[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().

#include <usb_host.h>
#include <stdio.h>

#define BUFFER_SIZE 128

void print_product_str(usb_host_device_h dev)
{
    int ret, length = BUFFER_SIZE - 1;
    unsigned char data[BUFFER_SIZE];

    ret = usb_host_device_get_product_str(dev, &length, data);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    data[length] = '\0';

    printf("Product: %s\n", data);
}

int usb_host_device_get_protocol	(	usb_host_device_h	dev,
		int *	protocol
	)

Gets the protocol being used by the given USB device.

Returns the ID of the protocol, which refines the subclass code returned by usb_host_device_get_sub_class().

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

#include <usb_host.h>
#include <stdio.h>

void print_device_protocol_id(usb_host_device_h dev)
{
    int ret, protocol;

    ret = usb_host_device_get_protocol(dev, &protocol);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Device protocol ID: %d\n", protocol);
}

int usb_host_device_get_serial_number_str	(	usb_host_device_h	dev,
		int *	length,
		unsigned char *	data
	)

Gets the serial number string for the connected device.

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	Pointer to a variable containing the current size of the buffer, which will be modified to actual usage
[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().

#include <usb_host.h>
#include <stdio.h>

#define BUFFER_SIZE 128

void print_serial_number_str(usb_host_device_h dev)
{
    int ret, length = BUFFER_SIZE - 1;
    unsigned char data[BUFFER_SIZE];

    ret = usb_host_device_get_serial_number_str(dev, &length, data);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    data[length] = '\0';

    printf("Serial number: %s\n", data);
}

int usb_host_device_get_sub_class	(	usb_host_device_h	dev,
		int *	subclass
	)

Gets the numerical subclass of given USB device.

Returns the numerical device subclass, which refines the class code returned by usb_host_device_get_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

#include <usb_host.h>
#include <stdio.h>

void print_device_subclass(usb_host_device_h dev)
{
    int ret, subclass;

    ret = usb_host_device_get_sub_class(dev, &subclass);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Device subclass: %d\n", subclass);
}

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()

#include <usb_host.h>

void work_on_device(usb_host_device_h dev)
{
    int ret;

    ret = usb_host_device_open(dev);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    // Use the device here

    ret = usb_host_device_close(dev);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

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

#include <usb_host.h>

#define VENDOR_ID 0x04e8
#define PRODUCT_ID 0x685e

void work_on_device(usb_host_context_h ctx)
{
    int ret;
    usb_host_device_h dev;

    ret = usb_host_device_open_with_vid_pid(ctx, VENDOR_ID, PRODUCT_ID, &dev);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    // Use the device here

    ret = usb_host_device_close(dev);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    // It is still required to unreference the device,
    // as usb_host_device_close only closes the connection,
    // it does not deallocate the object.
    ret = usb_host_unref_device(dev);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

int usb_host_device_unconfigure ( usb_host_device_h dev )

Returns a USB device back to the unconfigured state.

Make the device not configured with any configuration.

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

#include <usb_host.h>

void unconfigure_device(usb_host_device_h dev)
{
    int ret;

    ret = usb_host_device_unconfigure(dev);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

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.

#include <usb_host.h>

void iterate_devices(usb_host_context_h ctx)
{
    int ret, length;
    usb_host_device_h *devs;

    ret = usb_host_get_device_list(ctx, &devs, &length);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    for (int i = 0; i < length; ++i)
        handle_device(devs[i]);

    ret = usb_host_free_device_list(devs, true);
    // Or if handle_device unreferences the devices:
    // ret = usb_host_free_device_list(devs, false);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

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 the currently 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.

#include <usb_host.h>

void inspect_configuration(usb_host_device_h dev)
{
    int ret;
    usb_host_config_h config;

    ret = usb_host_get_active_config(config);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    // Read the configuration here

    ret = usb_host_config_destroy(config);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

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.

#include <usb_host.h>

void iterate_devices(usb_host_context_h ctx)
{
    int ret, length;
    usb_host_device_h *devs;

    ret = usb_host_get_device_list(ctx, &devs, &length);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    for (int i = 0; i < length; ++i)
        handle_device(devs[i]);

    ret = usb_host_free_device_list(devs, true);
    // Or if handle_device unreferences the devices:
    // ret = usb_host_free_device_list(devs, false);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

int usb_host_is_device_opened	(	usb_host_device_h	dev,
		bool *	is_opened
	)

Checks whether given USB device is currently opened.

Returns information about if the device is opened at the moment.

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

#include <usb_host.h>
#include <stdio.h>

void check_if_device_opened(usb_host_device_h dev)
{
    int ret;
    bool is_opened;

    ret = usb_host_is_device_opened(dev, &is_opened);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Device is %s\n", is_opened ? "opened" : "closed");
}

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

#include <usb_host.h>

usb_host_device_h pick_device(usb_host_device_h *device_list, int list_len)
{
    int ret;
    usb_host_device_h out = NULL;

    for (int i = 0; ++i; i < list_len) {
        if (interesting(device_list[i])) {
            // Reference the device that we will use
            ret = usb_host_ref_device(device_list[i]);
            if (ret != USB_HOST_ERROR_NONE)
                handle_error(ret);

            out = device_list[i];
            break;
        }
    }

    // Free the devices and the list
    ret = usb_host_free_device_list(devs, true);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    // The device we referenced is the only device that remains valid
    return out;
}

int usb_host_set_config ( usb_host_config_h configuration )

Sets a configuration as the currently active on a device.

Makes one of the configurations currently active on the device.

Since :: 3.0

Parameters:

[in] configuration Handle to configuration to be activated

Remarks:: Initially, the device might be configured with any configuration.

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

#include <usb_host.h>

void select_configuration(usb_host_device_h dev)
{
    int ret, num_configurations;
    usb_host_config_h config;

    ret = usb_host_device_get_num_configurations(dev, &num_configurations);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    for (int i = 0; i < num_configurations; ++i) {
        ret = usb_host_device_get_config(dev, i, &config);
        if (ret != USB_HOST_ERROR_NONE)
            handle_error(ret);

        if (interesting(config)) {
            ret = usb_host_set_config(config);
            if (ret != USB_HOST_ERROR_NONE)
                handle_error(ret);
        }

        ret = usb_host_config_destroy(config);
        if (ret != USB_HOST_ERROR_NONE)
            handle_error(ret);
    }
}

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

#include <usb_host.h>

void free_device_list_manually(usb_host_device_h *device_list, int list_len)
{
    int ret;

    for (int i = 0; ++i; i < list_len) {
        ret = usb_host_unref_device(device_list[i]);
        if (ret != USB_HOST_ERROR_NONE)
            handle_error(ret);
    }

    // Now we only need to free the list and not the devices, hence false
    ret = usb_host_free_device_list(devs, false);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

Overview

Opening a device node

Preparing Communication

Related Features

Functions

Typedefs

Typedef Documentation

Function Documentation