* reason for the callback.  Attach codes are defined as:** .IP "USBD_DYNA_ATTACH"* USBD is notifying the client that nodeId is a device which is now attached * to the system.* .IP "USBD_DYNA_REMOVE"* USBD is notifying the client that nodeId has been detached (removed) from * the system.** When the <attachAction> is USBD_DYNA_REMOVE the <nodeId> refers to a Node Id * which is no longer valid.  The client should interrogate its internal data * structures and delete any references to the specified Node Id.  If the client * had outstanding requests to the specified <nodeId>, such as data transfer * requests, then the USBD will fail those outstanding requests prior to calling * the <attachCallback> to notify the client that the device has been removed.  * In general, therefore, transfer requests related to removed devices should * already be taken care of before the <attachCallback> is called.** A client may re-use a single <attachCallback> for multiple notification * registrations.  As a convenience to the <attachCallback> routine, the USBD * also passes the <deviceClass>, <deviceSubClass>, and <deviceProtocol> of the * attached/removed <nodeId> each time it calls the <attachCallback>.  ** Finally, clients need to be aware that not all USB devices report their class* information at the "device" level.  Rather, some devices report class types* on an interface-by-interface basis.  When the device reports class information* at the device level, then the USBD passes a <configuration> value of zero to * the attach callback and calls the callback only a single time for each device.* When the device reports class information at the interface level, then the* USBD invokes the attach callback once for each interface which matches the* client's <deviceClass>/<deviceSubClass>/<deviceProtocol> specification.  In this* case, the USBD also passes the corresponding configuration & interface numbers* in <configuration> and <interface> each time it invokes the callback.** RETURNS: OK, or ERROR if unable to register for attach/removal notification.*/STATUS usbdDynamicAttachRegister    (    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */    UINT16 deviceClass, 		/* USB class code */    UINT16 deviceSubClass,		/* USB sub-class code */    UINT16 deviceProtocol,		/* USB device protocol code */    USBD_ATTACH_CALLBACK attachCallback /* User-supplied callback routine */    )    {    URB_DYNA_ATTACH_REG_UNREG urb;    /* Initalize URB */    urbInit (&urb.header, clientHandle, USBD_FNC_DYNA_ATTACH_REG, NULL, NULL,	sizeof (urb));    urb.deviceClass = deviceClass;    urb.deviceSubClass = deviceSubClass;    urb.deviceProtocol = deviceProtocol;    urb.attachCallback = attachCallback;    /* Execute URB */    return urbExecBlock (&urb.header);    }/***************************************************************************** usbdDynamicAttachUnRegister - Unregisters client for attach notification** This function cancels a client抯 earlier request to be notified for the * attachment and removal of devices within the specified class.  <deviceClass>,* <deviceSubClass>, <deviceProtocol>, and <attachCallback> are defined as for the * usbdDynamicAttachRegister() function and must match exactly the parameters* passed in an earlier call to usbdDynamicAttachRegister.** RETURNS: OK, or ERROR if unable to unregister for attach/removal notification.*/STATUS usbdDynamicAttachUnRegister    (    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */    UINT16 deviceClass, 		/* USB class code */    UINT16 deviceSubClass,		/* USB sub-class code */    UINT16 deviceProtocol,		/* USB device protocol code */    USBD_ATTACH_CALLBACK attachCallback /* user-supplied callback routine */    )    {    URB_DYNA_ATTACH_REG_UNREG urb;    /* Initalize URB */    urbInit (&urb.header, clientHandle, USBD_FNC_DYNA_ATTACH_UNREG, NULL, 	NULL, sizeof (urb));    urb.deviceClass = deviceClass;    urb.deviceSubClass = deviceSubClass;    urb.deviceProtocol = deviceProtocol;    urb.attachCallback = attachCallback;    /* Execute URB */    return urbExecBlock (&urb.header);    }/***************************************************************************** usbdFeatureClear - Clears a USB feature** This function allows a client to "clear" a USB feature.  <nodeId> specifies * the Node Id of the desired device and <requestType> specifies whether the * feature is related to the device, to an interface, or to an endpoint as:** .IP "USB_RT_DEVICE"* Device* .IP "USB_RT_INTERFACE"* Interface* .IP "USB_RT_ENDPOINT"* Endpoint** <requestType> also specifies if the request is standard, class-specific,* etc., as:** .IP "USB_RT_STANDARD"* Standard* .IP "USB_RT_CLASS"* Class-specific* .IP "USB_RT_VENDOR"* Vendor-specific** For example, USB_RT_STANDARD | USB_RT_DEVICE in <requestType> specifies a* standard device request.  ** The client must pass the device抯 feature selector in <feature>.  If * <featureType> specifies an interface or endpoint, then <index> must contain * the interface or endpoint index.  <index> should be zero when <featureType> * is USB_SELECT_DEVICE.** RETURNS: OK, or ERROR if unable to clear feature.*/STATUS usbdFeatureClear    (    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */    USBD_NODE_ID nodeId,		/* Node Id of device/hub */    UINT16 requestType, 		/* Selects request type */    UINT16 feature,			/* Feature selector */    UINT16 index			/* Interface/endpoint index */    )    {    URB_FEATURE_CLEAR_SET urb;    /* Initalize URB */    urbInit (&urb.header, clientHandle, USBD_FNC_FEATURE_CLEAR, NULL, NULL,	sizeof (urb));    urb.nodeId = nodeId;    urb.requestType = requestType;    urb.feature = feature;    urb.index = index;    /* Execute URB */    return urbExecBlock (&urb.header);    }/***************************************************************************** usbdFeatureSet - Sets a USB feature** This function allows a client to "set" a USB feature.  <nodeId> specifies * the Node Id of the desired device and <requestType> specifies the nature* of the feature feature as defined for the usbdFeatureClear() function.* * The client must pass the device抯 feature selector in <feature>.  If * <requestType> specifies an interface or endpoint, then <index> must contain * the interface or endpoint index.  <index> should be zero when <requestType>* includes USB_SELECT_DEVICE.** RETURNS: OK, or ERROR if unable to set feature.*/STATUS usbdFeatureSet    (    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */    USBD_NODE_ID nodeId,		/* Node Id of device/hub */    UINT16 requestType, 		/* Selects request type */    UINT16 feature,			/* Feature selector */    UINT16 index			/* Interface/endpoint index */    )    {    URB_FEATURE_CLEAR_SET urb;    /* Initalize URB */    urbInit (&urb.header, clientHandle, USBD_FNC_FEATURE_SET, NULL, NULL,	sizeof (urb));    urb.nodeId = nodeId;    urb.requestType = requestType;    urb.feature = feature;    urb.index = index;    /* Execute URB */    return urbExecBlock (&urb.header);    }/***************************************************************************** usbdConfigurationGet - Gets USB configuration for a device** This function returns the currently selected configuration for the device * or hub indicated by <nodeId>.  The current configuration value is returned * in the low byte of <pConfiguration>.	The high byte is currently reserved * and will be 0.** RETURNS: OK, or ERROR if unable to get configuration.*/STATUS usbdConfigurationGet    (    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */    USBD_NODE_ID nodeId,		/* Node Id of device/hub */    pUINT16 pConfiguration		/* bfr to receive config value */    )    {    URB_CONFIG_GET_SET urb;    STATUS s;    /* Initalize URB */    urbInit (&urb.header, clientHandle, USBD_FNC_CONFIG_GET, NULL, NULL,	sizeof (urb));    urb.nodeId = nodeId;    /* Execute URB */    s = urbExecBlock (&urb.header);    /* Return result */    if (pConfiguration != NULL)	*pConfiguration = urb.configuration;    return s;    }/***************************************************************************** usbdConfigurationSet - Sets USB configuration for a device** This function sets the current configuration for the device identified * by <nodeId>.	The client should pass the desired configuration value in * the low byte of <configuration>.  The high byte is currently reserved and * should be 0.** The client must also pass the maximum current which will be used by this* configuration in <maxPower>.	Typically, the maximum power will be* determined by reading the corresponding configuration descriptor for a* device.  Prior to setting the chosen configuration, the USBD will verify* that the hub port to which <pNode> is connected is capable of providing* the requested current.  If the port cannot provide <maxPower>, then* the configuration will not be set and the function will return an error.* <maxPower> should be expressed in milliamps (e.g., 100 = 100mA).  For* self-powered devices, the caller may pass zero in <maxPower>.** RETURNS: OK, or ERROR if unable to set configuration.*/STATUS usbdConfigurationSet    (    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */    USBD_NODE_ID nodeId,		/* Node Id of device/hub */    UINT16 configuration,		/* New configuration to be set */    UINT16 maxPower			/* max power this config will draw */    )    {    URB_CONFIG_GET_SET urb;    /* Initalize URB */    urbInit (&urb.header, clientHandle, USBD_FNC_CONFIG_SET, NULL, NULL,	sizeof (urb));    urb.nodeId = nodeId;    urb.configuration = configuration;    urb.maxPower = maxPower;    /* Execute URB */    return urbExecBlock (&urb.header);    }/***************************************************************************** usbdDescriptorGet - Retrieves a USB descriptor** A client uses this function to retrieve a descriptor from the USB device * identified by <nodeId>.  <requestType> is defined as documented for the* usbdFeatureClear() function.	<descriptorType> specifies the type of the * descriptor to be retrieved and must be one of the following values:** .IP "USB_DESCR_DEVICE"* Specifies the DEVICE descriptor.* .IP "USB_DESCR_CONFIG"* Specifies the CONFIGURATION descriptor.* .IP "USB_DESCR_STRING"* Specifies a STRING descriptor.* .IP "USB_DESCR_INTERFACE"* Specifies an INTERFACE descriptor.* .IP "USB_DESCR_ENDPOINT"* Specifies an ENDPOINT descriptor.** <descriptorIndex> is the index of the desired descriptor.** For string descriptors the <languageId> should specify the desired * language for the string.  According to the USB Specification, strings * descriptors are returned in UNICODE format and the <languageId> should * be the "sixteen-bit language ID (LANGID) defined by Microsoft for * Windows as described in .I "Developing International Software for Windows * 95 and Windows NT."  Please refer to Section 9.6.5 of revision 1.1 of the * USB Specification for more detail.  For device and configuration * descriptors, <languageId> should be 0.** The caller must provide a buffer to receive the descriptor data.  <pBfr> * is a pointer to a caller-supplied buffer of length <bfrLen>.	If the * descriptor is too long to fit in the buffer provided, the descriptor will * be truncated.  If a non-NULL pointer is passed in <pActLen>, the actual * length of the data transferred will be stored in <pActLen> upon return.** RETURNS: OK, or ERROR if unable to get descriptor.*/STATUS usbdDescriptorGet    (    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */    USBD_NODE_ID nodeId,		/* Node Id of device/hub */    UINT8 requestType,			/* specifies type of request */    UINT8 descriptorType,		/* Type of descriptor */    UINT8 descriptorIndex,		/* Index of descriptor */    UINT16 languageId,			/* Language ID */    UINT16 bfrLen,			/* Max length of data to be returned */    pUINT8 pBfr,			/* Pointer to bfr to receive data */    pUINT16 pActLen			/* bfr to receive actual length */    )    {    URB_DESCRIPTOR_GET_SET urb;    STATUS s;    /* Initalize URB */    urbInit (&urb.header, clientHandle, USBD_FNC_DESCRIPTOR_GET, NULL, NULL,	sizeof (urb));    urb.nodeId = nodeId;    urb.requestType = requestType;    urb.descriptorType = descriptorType;    urb.descriptorIndex = descriptorIndex;    urb.languageId = languageId;    urb.bfrLen = bfrLen;    urb.pBfr = pBfr;    /* Execute URB */    s = urbExecBlock (&urb.header);    /* Return result */    if (pActLen != NULL)	*pActLen = urb.actLen;    return s;    }/***************************************************************************** usbdDescriptorSet - Sets a USB descriptor** A client uses this function to set a descriptor on the USB device identified * by <nodeId>.	The parameters <requestType>, <descriptorType>, * <descriptorIndex>, and <languageId> are the same as those described for the * usbdDescriptorGet() function.  <pBfr> is a pointer to a buffer of length * <bfrLen> which contains the descriptor data to be sent to the device.** RETURNS: OK, or ERROR if unable to set descriptor.*/STATUS usbdDescriptorSet    (    USBD_CLIENT_HANDLE clientHandle,	/* Client handle */    USBD_NODE_ID nodeId,		/* Node Id of device/hub */    UINT8 requestType,			/* selects request type */    UINT8 descriptorType,		/* Type of descriptor */    UINT8 descriptorIndex,		/* Index of descriptor */    UINT16 languageId,			/* Language ID */    UINT16 bfrLen,			/* Max length of data to be returned */    pUINT8 pBfr 			/* Pointer to bfr to receive data */    )    {    URB_DESCRIPTOR_GET_SET urb;    /* Initalize URB */    urbInit (&urb.header, clientHandle, USBD_FNC_DESCRIPTOR_SET, NULL, NULL,	sizeof (urb));