USB_GET_STRING_DESCR(9F) Kernel Functions for Drivers

NAME

usb_get_string_descr - Get string descriptor from device

SYNOPSIS

#include <sys/usb/usba.h>


int usb_get_string_descr(dev_info_t *dip,
uint16_t langid, uint8_t index,
char *buf, size_t buflen);

INTERFACE LEVEL

illumos DDI specific (illumos DDI)

PARAMETERS

dip
Pointer to the device's dev_info structure.


langid
Language ID. Currently only USB_LANG_ID (English ascii) is
valid.


index
String index indicating descriptor to retrieve.


buf
Address into which the string descriptor is placed.


buflen
Size of buf in bytes.

DESCRIPTION

The usb_get_string_descr() function retrieves a parsed string
descriptor from a device. dip specifies the device, while index
indicates which descriptor to return.


String descriptors provide information about other descriptors, or
information that is encoded in other descriptors, in readable form.
Many descriptor types have one or more index fields which identify
string descriptors. (See Sections 9.5 and 9.6 of the USB 2.0
specification.) For example, a configuration descriptor's seventh
byte contains the string descriptor index describing a specific
configuration.


Retrieved descriptors that do not fit into buflen bytes are
truncated. All returned descriptors are null-terminated.

RETURN VALUES

USB_SUCCESS
String descriptor is returned in buf.


USB_INVALID_ARGS
dip or buf are NULL, or index or buflen is 0.


USB_FAILURE
Descriptor cannot be retrieved.

CONTEXT

May be called from user or kernel context.

EXAMPLES

/* Get the first string descriptor. */

char buf[SIZE];

if (usb_get_string_descr(
dip, USB_LANG_ID, 0, buf, SIZE) == USB_SUCCESS) {
cmn_err (CE_NOTE, "%s%d: %s",
ddi_driver_name(dip), ddi_get_instance(dip), buf);
}

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------+
|Architecture | PCI-based systems |
+--------------------+-------------------+
|Interface stability | Committed |
+--------------------+-------------------+

SEE ALSO

attributes(7), usb_get_dev_data(9F), usb_string_descr(9S)

January 5, 2004 USB_GET_STRING_DESCR(9F)