IWDFDevice::RetrieveDeviceName-Methode (wudfddi.h)

Artikel
02/07/2025

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

Die RetrieveDeviceName Methode ruft den Namen eines zugrunde liegenden Kernelmodusgeräts ab.

Syntax

HRESULT RetrieveDeviceName(
  [out]     PWSTR pDeviceName,
  [in, out] DWORD *pdwDeviceNameLength
);

Parameter

[out] pDeviceName

Ein Zeiger auf einen Puffer, der eine NULL--terminated-Zeichenfolge empfängt, die den Namen des zugrunde liegenden Kernelmodusgeräts darstellt, wenn der Puffer nichtNULL- und RetrieveDeviceName- erfolgreich ist.

[in, out] pdwDeviceNameLength

Ein Zeiger auf eine Variable, die die Anzahl von Zeichen erhält, einschließlich des NULL- Zeichens, im Gerätenamen.

Wenn der Puffer bei pDeviceNameNULL-ist, ist der Vom Treiber bereitgestellte Wert Null. Das Framework gibt dann die Größe in Zeichen zurück, die für die Gerätenamenzeichenfolge erforderlich ist.

Wenn der Puffer bei pDeviceName nichtNULL-ist, gibt das Framework die Größe der Gerätenamenzeichenfolge in Zeichen zurück.

Rückgabewert

RetrieveDeviceName- gibt S_OK für die folgenden Szenarien zurück:

Der Puffer, auf den der pDeviceName-Parameter verweist, war nichtNULL- und groß genug, um die Namenszeichenfolge aufzunehmen, einschließlich des NULL- Zeichens, und das Framework hat die Zeichenfolge erfolgreich in den angegebenen Puffer kopiert und die Variable festgelegt, auf die von pdwDeviceNameLength auf die Anzahl der Zeichen in der Zeichenfolge verwiesen wird.
Der Puffer bei pDeviceName war NULL-, der Treiber hat die Variable bei pdwDeviceNameLength auf 0 festgelegt, und das Framework legt die Variable auf pdwDeviceNameLength auf die Anzahl der Zeichen fest, die für die Zeichenfolge erforderlich waren.

RetrieveDeviceName gibt HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) zurück, um anzugeben, dass der angegebene Puffer nichtNULL- war und nicht genügend Speicherplatz zum Speichern des Gerätenamens enthält. Das Framework legt die Variable bei pdwDeviceNameLength auf die Anzahl der Zeichen fest, die für die Zeichenfolge erforderlich sind.

RetrieveDeviceName- können auch andere HRESULT-Werte zurückgeben.

Bemerkungen

Der Gerätename ist nicht der Name des physischen Geräteobjekts (PDO). Stattdessen ist der Gerätename der Name des Reflektors. Der Treiber muss alle E/A-Objekte auf dieses Geräteobjekt ausrichten.

Beispiele

Das folgende Codebeispiel zeigt, wie der Name eines zugrunde liegenden Kernelmodusgeräts abgerufen wird.

    PWSTR deviceName = NULL;
    DWORD deviceNameCch = 0;
    HRESULT hr;
    //
    // Get the length of the device name to allocate a buffer
    //
    hr = m_FxDevice->RetrieveDeviceName(NULL, &deviceNameCch);
    //
    // Allocate the buffer
    //
    deviceName = new WCHAR[deviceNameCch];

    if (deviceName == NULL) {
        hr = E_OUTOFMEMORY;
        goto Exit1;
    }
    //
    // Get the device name
    //
    hr = m_FxDevice->RetrieveDeviceName(deviceName,
                                        &deviceNameCch);

    // Open the device and get the handle

    m_Handle = CreateFile(deviceName, 
                         (GENERIC_READ | GENERIC_WRITE), 
                         0, 
                         NULL, 
                         OPEN_EXISTING, 
                         FILE_FLAG_OVERLAPPED, 
                         NULL);

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform-	Desktop
Mindest-UMDF-Version	1.5
Header-	wudfddi.h (include Wudfddi.h)
DLL-	WUDFx.dll

Siehe auch

IWDFDevice-

Freigeben über