IWDFFile::RetrieveFileName-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 für neuere 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 RetrieveFileName-Methode ruft den vollständigen Namen der Datei ab, die dem zugrunde liegenden Kernelmodusgerät zugeordnet ist.

Syntax

HRESULT RetrieveFileName(
  [out]     PWSTR pFileName,
  [in, out] DWORD *pdwFileNameLengthInChars
);

Parameter

[out] pFileName

Ein Zeiger auf einen vom Aufrufer bereitgestellten Puffer, der eine NULL-beendete Zeichenfolge empfängt, die den vollständigen Namen der Datei darstellt, die dem zugrunde liegenden Kernelmodusgerät zugeordnet ist, wenn der angegebene Zeiger nicht NULL ist und RetrieveFileName erfolgreich ist.

[in, out] pdwFileNameLengthInChars

Ein Zeiger auf eine vom Aufrufer bereitgestellte Variable, die die Größe des vollständigen Dateinamens in Zeichen empfängt, auf den pFileName verweist. Wenn der Puffer bei pFileName nicht NULL ist, gibt das Framework die Größe der Dateinamenzeichenfolge in Zeichen zurück.

Bei der Eingabe legt der Treiber diese Variable auf die Größe des Puffers in Zeichen fest, auf den pFileName verweist. Wenn der Treiber NULL für pFileName und null für die Variable bereitstellt, auf die pdwFileNameLengthInChars verweist, legt das Framework die Variable auf die Größe in Zeichen fest, die die Dateinamenzeichenfolge benötigt.

Rückgabewert

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

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

RetrieveFileName gibt HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) zurück, um anzugeben, dass der angegebene Puffer nicht NULL ist und nicht genügend Speicherplatz für den Dateinamen enthielt. Das Framework legt die Variable bei pdwFileNameLengthInChars auf die Anzahl der Zeichen fest, die für die Zeichenfolge erforderlich sind.

RetrieveFileName kann auch andere HRESULT-Werte zurückgeben.

Hinweise

Ihr Treiber ruft möglicherweise RetrieveFileName von seiner IQueueCallbackCreate::OnCreateFile-Rückruffunktion auf. Weitere Informationen finden Sie unter Verwenden von Geräteschnittstellen in UMDF-Treibern.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie den Namen einer Datei abrufen.

    ULONG fileNameCch = 0;
    PWSTR fileName = NULL;
    ULONG index;

    CComObject<CUmdfHidFile> *file = NULL;

    HRESULT hr;

    // Get the length of the file name to allocate a buffer.
    hr = WdfFile->RetrieveFileName(NULL, &fileNameCch);
    //
    // Allocate the buffer.
    //
    if (SUCCEEDED(hr))
    {
        fileName = new WCHAR[fileNameCch];

        if (fileName == NULL)
        {
            hr = E_OUTOFMEMORY;
        }
    }
    //
    // Get the file name.
    //
    if (SUCCEEDED(hr))
    {
        hr = WdfFile->RetrieveFileName(fileName, &fileNameCch);
    }

Anforderungen

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

Weitere Informationen

IWDFFile