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 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 |