Metodo IWDFFile2::RetrieveCountedFileName (wudfddi.h)

Articolo
02/07/2025

Avvertimento

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 informazioni, vedere Introduzione a UMDF.

Il metodo RetrieveCountedFileName recupera il nome di file con conteggio completo per un file associato a un dispositivo.

Sintassi

HRESULT RetrieveCountedFileName(
  [out]     WCHAR *pCountedFileName,
  [in, out] DWORD *pdwCountedFileNameLengthInChars
);

Parametri

[out] pCountedFileName

Puntatore a un buffer allocato dal chiamante. Questo buffer riceve un NULL stringa di caratteri con terminazione che rappresenta il nome completo del file associato al dispositivo. Se il puntatore è NULL, RetrieveCountedFileName recupera solo la lunghezza della stringa.

[in, out] pdwCountedFileNameLengthInChars

Puntatore a una variabile allocata dal chiamante. All'input, il driver imposta la variabile sulla lunghezza, in caratteri, del buffer a cui pdwCountedFileNameLengthInChars punti. Nell'output, il framework imposta la variabile sulla lunghezza, in caratteri, della stringa di caratteri (inclusa la terminazione carattere NULL) inserita nel buffer. Se non esiste un nome di file con conteggio, il framework imposta la variabile su zero.

Valore restituito

RetrieveCountedFileName restituisce S_OK se l'operazione ha esito positivo. In caso contrario, il metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
E_POINTER	Il puntatore pdwCountedFileNameLength è NULL.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Il nome del file con conteggio non è valido.
E_NOT_SUFFICIENT_BUFFER	Il buffer che pCountedFileName punta a è troppo piccolo.

Questo metodo potrebbe restituire uno degli altri valori in Winerror.h.

Osservazioni

Un nome di file con conteggio è una stringa che può includere caratteri NULL ('\0') oltre a un NULLdi terminazione. Per ottenere una stringa di nome senza caratteri null incorporati, i driver possono chiamare IWDFFile::RetrieveFileName.

In genere, un driver chiama RetrieveCountedFileName due volte, seguendo questa procedura:

Il driver chiama RetrieveCountedFileName con il parametro pCountedFileName impostato su NULL, per ottenere la lunghezza del buffer richiesta.
Il driver alloca un buffer delle dimensioni necessarie.
Il driver chiama RetrieveCountedFileName di nuovo per ottenere la stringa del nome file.

Esempi

Nell'esempio di codice seguente viene ottenuta l'interfaccia IWDFFile2 dall'interfaccia IWDFFile che riceve la funzione di callback IQueueCallbackCreate::OnCreateFile del driver. L'esempio chiama RetrieveCountedFileName due volte; una volta per ottenere la lunghezza del nome file e una volta per recuperare la stringa del nome file.

VOID
STDMETHODCALLTYPE
CMyQueue::OnCreateFile(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in IWDFFile*  pWdfFileObject
    )
 ...
    IWDFFile2*  pWdfFileObject2 = NULL;
    WCHAR*  countedFileName = NULL;
    DWORD  countedFileNameCch = 0;
    HRESULT  hr = S_OK;
 
    //
    // Obtain IWDFFile2 interface from IWDFFile.
    //
    hr = pWdfFileObject->QueryInterface(IID_PPV_ARGS(&pWdfFileObject2));
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    //
    // Get length of counted filename.
    //
    hr = pWdfFileObject2->RetrieveCountedFileName(NULL,
                                                  &countedFileNameCch);
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    if (countedFileNameCch != 0)
    {
        //
        // Allocate a buffer.
        //
        countedFileName = new WCHAR[countedFileNameCch];
        if (countedFileName == NULL)
        {
            hr = E_OUTOFMEMORY;
            goto Done;
        }
        //
        // Get counted file name.
        //
        hr = pWdfFileObject2->RetrieveCountedFileName(countedFileName, 
                                                      &countedFileNameCch);
        if (!SUCCEEDED(hr))
        {
            goto Done;
        }
    }
    ...

Fabbisogno

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
piattaforma di destinazione	Desktop
versione minima di UMDF	1.9
intestazione	wudfddi.h (include Wudfddi.h)
dll	WUDFx.dll

Condividi tramite