An opaque handle representing a USB configuration interface.

This type represents USB interface. An interface is a part of configuration and can have multiple endpoints. This handle can be obtained by usb_host_config_get_interface().

Since :

3.0

Claims a USB interface on a device for further I/O.

Claims interface on a device. To perform I/O operations on interface user has to claim it. Remember to call usb_host_release_interface() when communication with the device is finished.

Since :

3.0

Parameters:

[in]	interface	The bInterfaceNumber of interface to claim
[in]	force	Set to true to auto detach kernel driver, set to false to not detach it

Returns:

0 on success, otherwise a negative error value

Return values:

USB_HOST_ERROR_NONE	Successful
USB_HOST_ERROR_NOT_FOUND	Requested interface does not exist
USB_HOST_ERROR_RESOURCE_BUSY	Another program or driver has claimed the interface
USB_HOST_ERROR_NO_SUCH_DEVICE	Device has been disconnected
USB_HOST_ERROR_INVALID_PARAMETER	Invalid parameter was passed
USB_HOST_ERROR_DEVICE_NOT_OPENED	The device was not opened

#include <usb_host.h>

void use_interface(usb_host_interface_h interface)
{
    int ret;

    ret = usb_host_claim_interface(interface, true);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    // Use the interface here

    ret = usb_host_release_interface(interface, true);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

Gets current alternative setting from an interface.

Retrieves the currently selected alternative setting.

Since :

4.0

Parameters:

[in]	interface	Interface handle
[out]	altsetting	Index of alternative setting set for the given interface

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_current_altsetting(usb_host_interface_h interface)
{
    int ret, altsetting;

    ret = usb_host_interface_get_altsetting(interface, &altsetting);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Current alternative setting index: %d\n");
}

Gets an endpoint via index from given USB interface.

Returns the correct endpoint of the provided interface by its index.

Since :

3.0

Parameters:

[in]	interface	Interface handle
[in]	ep_index	index of endpoint to retrieve (counting from 0)
[out]	ep	Endpoint handle

Remarks:

ep handle is no longer valid when config will be destroyed. There is no need to destroy it, it is done automatically when the configuration is destroyed.

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>

#define ENDPOINT_INDEX 3

usb_host_endpoint_h get_endpoint(usb_host_interface_h interface)
{
    int ret;
    usb_host_endpoint_h ep;

    ret = usb_host_interface_get_endpoint(interface, ENDPOINT_INDEX, &ep);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    return ret;
}

Gets the number of endpoints in given USB interface.

Gets the number of endpoints supported by the provided interface.

Since :

3.0

Parameters:

[in]	interface	An interface
[out]	num_endpoints	Number of endpoints in interface

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_num_endpoints(usb_host_interface_h interface)
{
    int ret, num_endpoints;

    ret = usb_host_interface_get_num_endpoints(inteface, &num_endpoints);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Number of endpoints: %d\n", num_endpoints);
}

Gets the "number" of the given USB interface handle.

Gets the index of the interface, as passed to usb_host_config_get_interface().

Since :

3.0

Parameters:

[in]	interface	An interface
[out]	number	Number of given interface

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_interface_index(usb_host_interface_h interface)
{
    int ret, number;

    ret = usb_host_interface_get_number(dev, &number);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    printf("Interface index: %d\n", number);
}

Gets a string describing the given USB interface into a buffer.

Returns a string representation of the given USB interface.

Since :

3.0

Parameters:

[in]	interface	An interface
[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_NOT_SUPPORTED	Not supported
USB_HOST_ERROR_OVERFLOW	There was no space in buffer
USB_HOST_ERROR_INVALID_PARAMETER	Invalid parameter was passed

Precondition:

device which interface is part of must be 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_interface_str(usb_host_interface_h interface)
{
    int ret, length = BUFFER_SIZE - 1;
    unsigned char data[BUFFER_SIZE];

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

    data[length] = '\0';

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

Sets an alternative setting for given USB interface.

Selects an alternative setting represented by the provided index.

Since :

3.0

Parameters:

[in]	interface	Interface handle
[in]	altsetting	Index of new alternative setting for given interface

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 set_0_altsetting(usb_host_interface_h interface)
{
    int ret = usb_host_interface_set_altsetting(interface, 0);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}

Releases a previously claimed interface on a device.

Releases interface previously claimed by usb_host_claim_interface(). This is a blocking function.

Since :

3.0

Parameters:

[in]

interface

The bInterfaceNumber of interface to release

Returns:

0 on success, otherwise a negative error value

Return values:

USB_HOST_ERROR_NONE	Successful
USB_HOST_ERROR_NOT_FOUND	Interface was not claimed
USB_HOST_ERROR_NO_SUCH_DEVICE	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 use_interface(usb_host_interface_h interface)
{
    int ret;

    ret = usb_host_claim_interface(interface, true);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);

    // Use the interface here

    ret = usb_host_release_interface(interface, true);
    if (ret != USB_HOST_ERROR_NONE)
        handle_error(ret);
}