This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

usbd_parse_descriptors()

Parse device descriptors looking for a specific entry

Synopsis:

#include <sys/usbdi.h>

usbd_descriptors_t *usbd_parse_descriptors( 
                      struct usbd_device *device, 
                      struct usbd_desc_node *root, 
                      _uint8 type,
                      int index,
                      struct usbd_desc_node **node );

Arguments:

device: The opaque handle for the device whose descriptors you want to search.
root: Where in the tree to begin parsing (pass NULL to start at the base).
type: The type of descriptor to find (USB_DESC_*), or 0 to match any type.
index: The occurrence of the descriptor that you want to find.
node: A pointer to a location where the function stores a pointer to the descriptor that it found. You can use this as the root for future requests.

Description:

When you call it the first time, the usbd_parse_descriptors() function loads all the descriptors from the USB device:

device
configuration
interface
endpoint
hub
string

The function uses usbd_descriptor() to get each raw USB descriptor. The data is then endian-ized, made alignment-safe, and built into an in-memory tree structure to facilitate future parsing requests.

Each node in this tree is a struct usbd_desc_node. The root parameter lets you say where in the tree to begin parsing (NULL is base). The node parameter tells you where a descriptor was found to root future requests from.

The tree looks like this:

(ROOT)
  |
  (DEVICE)  -  (HUB)  -  (LANGUAGE TABLE)
    |
    (CONFIG)  -  .....   (CONFIG)
      |
      (INTERFACE)  -  .....    (INTERFACE)
        |
        (ENDPOINT)  -  .....    (ENDPOINT)

Any vendor-specific or class-specific descriptors that are embedded into the standard descriptor output are also inserted into this tree at the appropriate point.

Although a descriptor for endpoint 0 (control) isn't present on the wire, one is constructed and placed in the tree (to simplify enumeration within the class driver).

You use type for specifying the type of descriptor to find; index is the nth occurrence. Note that type 0 will match any descriptor type; you can use it to retrieve any embedded class or vendor-specific descriptors if you don't know their type.

Here's an example that will walk all endpoints for an interface:

for (eix = 0; (desc = usbd_parse_descriptors(device, ifc, USB_DESC_ENDPOINT, 
                eix, &ept)) != NULL; ++eix)
    ;

where ifc is the appropriate (INTERFACE) node (found by a previous call to usbd_parse_descriptors() or usbd_interface_descriptor().

Returns:

A pointer to the descriptor on success, or NULL on error.

Classification:

QNX Neutrino, QNX 4

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes