IWDFFile2::RetrieveCountedFileName-Methode (wudfddi.h)

Artikel
02/07/2025

Warnung

UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. Es werden keine neuen Features zu UMDF 1 hinzugefügt, und es gibt eingeschränkte Unterstützung für UMDF 1 für neuere Versionen von Windows 10. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF-.

Die RetrieveCountedFileName Methode ruft den vollständig gezählten Dateinamen für eine Datei ab, die einem Gerät zugeordnet ist.

Syntax

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

Parameter

[out] pCountedFileName

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer. Dieser Puffer empfängt eine NULL- beendete Zeichenfolge, die den vollständigen Namen der Datei darstellt, die dem Gerät zugeordnet ist. Wenn der Zeiger NULL-ist, ruft RetrieveCountedFileName nur die Zeichenfolgenlänge ab.

[in, out] pdwCountedFileNameLengthInChars

Ein Zeiger auf eine vom Aufrufer zugewiesene Variable. Bei eingaben legt der Treiber die Variable auf die Länge des Puffers in Zeichen fest, auf die pdwCountedFileNameLengthInChars Punkte. Bei der Ausgabe legt das Framework die Variable auf die Länge (in Zeichen) der Zeichenfolge (einschließlich des beendenden NULL- Zeichens) fest, das sie im Puffer platziert hat. Wenn kein gezählter Dateiname vorhanden ist, legt das Framework die Variable auf Null fest.

Rückgabewert

RetrieveCountedFileName gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
E_POINTER	Der pdwCountedFileNameLength Zeiger ist NULL-.
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	Der gezählte Dateiname ist ungültig.
E_NOT_SUFFICIENT_BUFFER	Der Puffer , auf den pCountedFileName verweist, ist zu klein.

Diese Methode gibt möglicherweise einen der anderen Werte in Winerror.h zurück.

Bemerkungen

Ein gezählter Dateiname ist eine Zeichenfolge, die eingebettete NULL- ('\0')-Zeichen zusätzlich zu einem endenden NULL-enthalten kann. Um eine Namenszeichenfolge ohne eingebettete NULL- Zeichen abzurufen, können Treiber IWDFFile::RetrieveFileNameaufrufen.

In der Regel ruft ein Treiber RetrieveCountedFileName zweimal auf, wobei die folgenden Schritte ausgeführt werden:

Der Treiber ruft RetrieveCountedFileName auf, wobei der pCountedFileName-Parameter auf NULL-festgelegt ist, um die erforderliche Pufferlänge abzurufen.
Der Treiber weist einen Puffer der erforderlichen Größe zu.
Der Treiber ruft RetrieveCountedFileName erneut auf, um die Dateinamenzeichenfolge abzurufen.

Beispiele

Im folgenden Codebeispiel wird die IWDFFile2- Schnittstelle aus der IWDFFile- Schnittstelle abgerufen, die ein Treiber IQueueCallbackCreate::OnCreateFile Rückruffunktion empfängt. Im Beispiel wird zweimal RetrieveCountedFileName aufgerufen. einmal zum Abrufen der Länge des Dateinamens und einmal zum Abrufen der Dateinamenzeichenfolge.

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

Anforderungen

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

Freigeben über