IWDFDevice::RetrieveDeviceName-Methode (wudfddi.h)

[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 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-beendete Zeichenfolge empfängt, die den Namen des zugrunde liegenden Kernelmodusgeräts darstellt, wenn der Puffer nicht NULL ist und RetrieveDeviceName erfolgreich ist.

[in, out] pdwDeviceNameLength

Ein Zeiger auf eine Variable, die die Anzahl der Zeichen, einschließlich des NULL-Zeichens , im Gerätenamen empfängt.

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 ungleich NULL ist, gibt das Framework die Größe der Gerätenamenzeichenfolge in Zeichen zurück.

Rückgabewert

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

• Der Puffer, auf den der pDeviceName-Parameter verweist, war nicht NULL und groß genug, um die Namenszeichenfolge, einschließlich des NULL-Zeichens , aufzunehmen. 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 bereitgestellte Puffer ungleich NULL war und nicht genügend Speicherplatz für den Gerätenamen enthielt. Das Framework legt die Variable unter pdwDeviceNameLength auf die Anzahl der Zeichen fest, die für die Zeichenfolge erforderlich sind.

RetrieveDeviceName gibt möglicherweise auch andere HRESULT-Werte zurück.

Hinweise

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-Vorgänge auf dieses Geräteobjekt ausrichten.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie den Namen eines zugrunde liegenden Kernelmodusgeräts abrufen.

    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

Weitere Informationen

IWDFDevice