IWDFUsbTargetDevice::RetrieveDescriptor-Methode (wudfusb.h)

Artikel
02/27/2024

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 in neueren Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die RetrieveDescriptor-Methode ruft einen USB-Deskriptor ab, der ein Gerät, eine Konfiguration oder eine Zeichenfolge beschreiben kann.

Syntax

HRESULT RetrieveDescriptor(
  [in]      UCHAR  DescriptorType,
  [in]      UCHAR  Index,
  [in]      USHORT LanguageID,
  [in, out] ULONG  *BufferLength,
  [out]     PVOID  Buffer
);

Parameter

[in] DescriptorType

Ein -Wert, der den Typ des zurückzugebenden Deskriptors angibt. Dieser Parameter entspricht dem bDescriptorType-Feld eines Standardgerätedeskriptors, dessen Werte in der Spezifikation für universelle seriellen Bus beschrieben werden. (Diese Ressource ist in einigen Sprachen möglicherweise nicht verfügbar.

und Länder.) Einige dieser Werte sind in der Beschreibung des DescriptorType-Elements der _URB_CONTROL_DESCRIPTOR_REQUEST-Struktur aufgeführt.

[in] Index

Der Index des Deskriptors gemäß der Universal Serial Bus-Spezifikation . (Diese Ressource ist in einigen Sprachen möglicherweise nicht verfügbar.

und Länder.)

[in] LanguageID

Der Bezeichner der Sprache, wenn der UMDF-Treiber einen Zeichenfolgendeskriptor anfordert; Andernfalls ist dieser Parameter null.

[in, out] BufferLength

Ein Zeiger auf eine Variable, die bei der Eingabe die Größe des Puffers in Bytes enthält, auf den der Puffer verweist. Wenn der Vorgang erfolgreich ist, empfängt die Variable die Anzahl der Bytes, die das Framework in den Puffer kopiert hat.

[out] Buffer

Ein Zeiger auf einen vom Aufrufer bereitgestellten Puffer, der den USB-Deskriptor empfängt. Der Typ des Puffers sollte mit dem in DescriptorType angegebenen Wert übereinstimmen.

Rückgabewert

RetrieveDescriptor gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
S_OK	RetrieveDescriptor hat den USB-Deskriptor erfolgreich abgerufen.
E_OUTOFMEMORY	Bei RetrieveDescriptor ist ein Zuordnungsfehler aufgetreten.
Ein Fehlercode, der in "Winerror.h" definiert ist	Dieser Wert entspricht dem Fehlercode, den die WinUsb-API zurückgegeben hat.

Hinweise

Informationen zu gültigen Deskriptortypen, die ein UMDF-Treiber für den DescriptorType-Parameter übergeben kann, finden Sie in der funktion WinUsb_GetDescriptor .

Die RetrieveDescriptor-Methode generiert eine UMDF-Anforderung und sendet die Anforderung synchron an das E/A-Ziel.

Beispiele

Im folgenden Codebeispiel wird ein USB-Konfigurationsdeskriptor abgerufen.

HRESULT
CUmdfHidDevice::RetrieveConfigDescriptor(
    __out_bcount(ConfigDescriptorCb) PUSB_CONFIGURATION_DESCRIPTOR *ConfigDescriptor,
    __out ULONG *ConfigDescriptorCb
    )
{
    ULONG descriptorCb = sizeof(USB_CONFIGURATION_DESCRIPTOR);
    USB_CONFIGURATION_DESCRIPTOR descriptorHeader;
    PBYTE descriptorBuffer;
    HRESULT hr;

    //
    // Get the configuration descriptor at index 0
    //

    hr = m_UsbTargetDevice->RetrieveDescriptor(
                            USB_CONFIGURATION_DESCRIPTOR_TYPE,
                            0,
                            0,
                            &descriptorCb,
                            &descriptorHeader
                            );
    //
    // Store the buffer in the output parameter, or delete it.
    //
    if (SUCCEEDED(hr)) {
        *ConfigDescriptor = (PUSB_CONFIGURATION_DESCRIPTOR) (descriptorHeader);
        *ConfigDescriptorCb = descriptorCb;
    }
    else {
        delete[] descriptorHeader;
    }
    return hr;
}

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform	Desktop
UMDF-Mindestversion	1.5
Kopfzeile	wudfusb.h (schließen Sie Wudfusb.h ein)
DLL	WUDFx.dll

Weitere Informationen

IWDFUsbTargetDevice

WinUsb_GetDescriptor

Freigeben über