Kernel Functions for Drivers             usbgetstringdescr(9F)



NAME
     usbgetstringdescr - Get string descriptor from device

SYNOPSIS
     #include 



     int usbgetstringdescr(devinfot *dip,
          uint16t langid, uint8t index,
          char *buf, sizet buflen);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
     dip       Pointer to the device's devinfo structure.


     langid    Language ID. Currently only  USBLANGID  (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  usbgetstringdescr()  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  descrip-
     tors,  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  Sec-
     tions 9.5 and 9.6 of the USB 2.0 specification.)  For  exam-
     ple,  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.




SunOS 5.11           Last change: 5 Jan 2004                    1






Kernel Functions for Drivers             usbgetstringdescr(9F)



RETURN VALUES
     USBSUCES         String descriptor is returned in buf.


     USBINVALIDARGS    dip or buf are NUL, or index or  buflen
                         is 0.


     USBFAILURE         Descriptor cannot be retrieved.


CONTEXT
     May be called from user or kernel context.

EXAMPLES
          /* Get the first string descriptor. */

           char buf[SIZE];

           if (usbgetstringdescr(
               dip, USBLANGID, 0, buf, SIZE) == USBSUCES) {
                   cmnerr (CENOTE, "%s%d: %s",
                       ddidrivername(dip), ddigetinstance(dip), buf);
           }


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Architecture                 PCI-based systems           
    
     Interface stability          Committed                   
    
     Availability                 SUNWusb                     
    


SEE ALSO
     attributes(5), usbgetdevdata(9F), usbstringdescr(9S)










SunOS 5.11           Last change: 5 Jan 2004                    2