usb_get_string_descr(9F)				   Kernel Functions for Drivers 				  usb_get_string_descr(9F)

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

       Solaris DDI specific (Solaris 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 specifica-
       tion.) 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(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Architecture		     |PCI-based systems 	   |
       +-----------------------------+-----------------------------+
       |Interface stability	     |Evolving			   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWusb			   |
       +-----------------------------+-----------------------------+

SEE ALSO

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

SunOS 5.10							    5 Jan 2004						  usb_get_string_descr(9F)