USBD_SelectInterfaceUrbAllocateAndBuild-Funktion (usbdlib.h)
Die USBD_SelectInterfaceUrbAllocateAndBuild Routine weist eine URB- Struktur zu, die für eine Anforderung erforderlich ist, um eine Schnittstelle auszuwählen oder ihre alternative Einstellung zu ändern.
Syntax
NTSTATUS USBD_SelectInterfaceUrbAllocateAndBuild(
[in] USBD_HANDLE USBDHandle,
[in] USBD_CONFIGURATION_HANDLE ConfigurationHandle,
PUSBD_INTERFACE_LIST_ENTRY InterfaceListEntry,
[out] PURB *Urb
);
Parameter
[in] USBDHandle
USBD-Handle, das vom Clienttreiber in einem vorherigen Aufruf der USBD_CreateHandle Routine abgerufen wird.
[in] ConfigurationHandle
Handle, das vom USB-Treiberstapel im UrbSelectConfiguration.ConfigurationHandle Member der URB--Struktur zurückgegeben wird, nachdem der Treiberstapel eine Auswahlkonfigurationsanforderung abgeschlossen hat.
InterfaceListEntry
Zeiger auf eine vom Aufrufer zugewiesene USBD_INTERFACE_LIST_ENTRY Struktur. Weitere Informationen finden Sie in den Hinweisen.
[out] Urb
Zeiger auf eine URB--Struktur, die die von USBD_SelectInterfaceUrbAllocateAndBuildzugeordnete URB empfängt. Der Clienttreiber muss die URB freigeben, wenn der Treiber die Verwendung beendet hat, indem er USBD_UrbFreeaufruft.
Rückgabewert
Die Routine gibt einen NTSTATUS-Code zurück. Mögliche Werte sind jedoch nicht beschränkt auf die Statuscodes, die in der folgenden Tabelle aufgeführt sind.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Routineaufruf war erfolgreich. |
|
Der Aufrufer hat NULL in einem der Parameter übergeben. |
|
Nicht genügend Arbeitsspeicher verfügbar, um den Anruf abzuschließen. |
Bemerkungen
Der Clienttreiber muss die USBD_SelectInterfaceUrbAllocateAndBuild Routine aufrufen, nachdem eine Konfiguration auf dem Gerät ausgewählt wurde. Nach Abschluss einer Auswahlkonfigurationsanforderung empfängt der Clienttreiber ein Konfigurationshandle im UrbSelectConfiguration.ConfigurationHandle Mitglied der URB. Dieses Handle muss im ConfigurationHandle Parameter von USBD_SelectInterfaceUrbAllocateAndBuildangegeben werden.
Ein Clienttreiber ruft USBD_SelectInterfaceUrbAllocateAndBuild auf, um eine URB für eine Auswahlschnittstellenanforderung zuzuweisen und zu erstellen, um die alternative Einstellung einer Schnittstelle in der ausgewählten Konfiguration zu ändern. Im Aufruf von USBD_SelectInterfaceUrbAllocateAndBuildmuss der Clienttreiber einen Zeiger auf eine USBD_INTERFACE_LIST_ENTRY Struktur zuweisen und bereitstellen. Der Clienttreiber muss die Strukturmmber wie folgt festlegen:
- Der InterfaceDescriptor Member muss auf eine USB_INTERFACE_DESCRIPTOR Struktur zeigen, die den Schnittstellendeskriptor mit der alternativen Einstellung zum Auswählen enthält. Der Schnittstellendeskriptor wurde in einer vorherigen Anforderung abgerufen, um einen Konfigurationsdeskriptor und die zugehörigen Schnittstellen- und Endpunktdeskriptoren abzurufen.
- Das Interface Member muss NULL sein.
Ein Clienttreiber kann keine alternativen Einstellungen in mehreren Schnittstellen in einer einzigen Auswahlschnittstellenanforderung ändern. Jede Anforderung zielt nur auf eine Schnittstelle ab.
Nach Abschluss der Auswahlschnittstellenanforderung füllt der USB-Treiberstapel USBD_INTERFACE_INFORMATION mit Informationen zu Rohren auf, die für Endpunkte geöffnet sind, die in der ausgewählten alternativen Einstellung definiert sind. Der Clienttreiber kann diese Rohrziehpunkte abrufen, indem das Array überprüft wird, auf das vom Pipes Member von USBD_INTERFACE_INFORMATIONverwiesen wird, und die Handles für zukünftige Datenübertragungsanforderungen speichern.
Der Clienttreiber kann einen URB wiederverwenden, der von USBD_SelectInterfaceUrbAllocateAndBuild nur für eine andere Auswahlschnittstellenanforderung für dieselbe alternative Einstellung. Der Clienttreiber darf die URB nicht für einen anderen Anforderungstyp oder für eine andere Auswahlschnittstellenanforderung für eine andere alternative Einstellung wiederverwenden. Anstatt einen neuen URB zuzuweisen, ist die Erneute Nutzung eines vorhandenen URB in bestimmten Szenarien der bevorzugte Ansatz. Erwägen Sie ein USB-Audiogerät mit einer Schnittstelle mit zwei alternativen Einstellungen, die für zwei Bandbreitenanforderungen definiert sind. Einstellung 0 ist für null Bandbreite definiert; Einstellung 1 ist definiert, um eine bestimmte Bandbreite zu verwenden. Der Clienttreiber möchte häufig zwischen den beiden Einstellungen wechseln, je nachdem, ob das Gerät verwendet wird. Um dieses Szenario zu implementieren, kann der Clienttreiber zwei URBs für Auswahlschnittstellenanforderungen zuordnen, eine pro Einstellung. Der Clienttreiber kann eine URB für eine Auswahlschnittstellenanforderung verwenden (und wiederverwenden), um Einstellung 1 auszuwählen, wenn Sounds zum Senden an das Gerät vorhanden sind. Um Bandbreite zu sparen, wenn keine Sounds vorhanden sind, kann der Clienttreiber die andere URB verwenden (und wiederverwenden), um zu "Einstellung 0" zu wechseln. Diese Implementierung verhindert, dass der Clienttreiber URBs für jede dieser Auswahlschnittstellenanforderungen angibt, jedes Mal, wenn der Treiber die Einstellung ändern muss.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Erfordert WDK für Windows 8. Zielt auf Windows Vista und höhere Versionen des Windows-Betriebssystems ab. |
| Zielplattform- | Desktop |
| Header- | usbdlib.h |
| Library | Usbdex.lib |
| IRQL- | DISPATCH_LEVEL |