Metodo IWDFFile::RetrieveFileName (wudfddi.h)

Articolo
02/27/2024

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre info, vedi Introduzione con UMDF.]

Il metodo RetrieveFileName recupera il nome completo del file associato al dispositivo in modalità kernel sottostante.

Sintassi

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

Parametri

[out] pFileName

Puntatore a un buffer fornito dal chiamante che riceve una stringa con terminazione NULL che rappresenta il nome completo del file associato al dispositivo in modalità kernel sottostante, se il puntatore fornito è diverso da NULL e RetrieveFileName ha esito positivo.

[in, out] pdwFileNameLengthInChars

Puntatore a una variabile fornita dal chiamante che riceve le dimensioni, in caratteri, del nome file completo a cui punta pFileName . Se il buffer in pFileName è diverso da NULL, il framework restituisce le dimensioni, in caratteri, della stringa del nome file.

All'input, il driver imposta questa variabile sulle dimensioni, in caratteri, del buffer a cui punta pFileName . Se il driver fornisce NULL per pFileName e zero per la variabile a cui punta pdwFileNameLengthInChars , il framework imposta la variabile sulle dimensioni, in caratteri, richiesta dalla stringa del nome file.

Valore restituito

RetrieveFileName restituisce S_OK per gli scenari seguenti:

Il buffer a cui punta il parametro pFileName è diverso da NULL e ha dimensioni sufficienti per contenere la stringa del nome, incluso il carattere NULL , e il framework ha copiato correttamente la stringa nel buffer fornito e impostare la variabile a cui punta il parametro pdwFileNameLengthInChars sul numero di caratteri nella stringa.
Il buffer in pFileName è NULL, il driver imposta la variabile in pdwFileNameLengthInChars su 0 e il framework imposta la variabile su pdwFileNameLengthInChars sul numero di caratteri necessari per la stringa.

RetrieveFileName restituisce HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) per indicare che il buffer fornito non è NULL e non contiene spazio sufficiente per contenere il nome del file. Il framework imposta la variabile in pdwFileNameLengthInChars sul numero di caratteri necessari per la stringa.

RetrieveFileName potrebbe restituire anche altri valori HRESULT.

Commenti

Il driver potrebbe chiamare RetrieveFileName dalla relativa funzione di callback IQueueCallbackCreate::OnCreateFile . Per altre informazioni, vedere Uso delle interfacce di dispositivo nei driver UMDF.

Esempio

Nell'esempio di codice seguente viene illustrato come recuperare il nome di un file.

    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);
    }

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1.5
Intestazione	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Vedi anche

IWDFFile

Condividi tramite