IWDFFile2::RetrieveCountedFileName-Methode (wudfddi.h)

  • Artikel

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 RetrieveCountedFileName-Methode ruft den vollständigen 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-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 der Eingabe legt der Treiber die Variable auf die Länge des Puffers in Zeichen fest, auf den pdwCountedFileNameLengthInChars verweist. Bei der Ausgabe legt das Framework die Variable auf die Länge (in Zeichen) der Zeichenfolge (einschließlich des beendenden NULL-Zeichens ) fest, die es 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.

Hinweise

Ein gezählter Dateiname ist eine Zeichenfolge, die neben einem beendenden NULL auch eingebettete NULL -Zeichen ('\0') enthalten kann. Um eine Namenszeichenfolge ohne eingebettete NULL-Zeichen abzurufen, können Treiber IWDFFile::RetrieveFileName aufrufen.

In der Regel ruft ein Treiber RetrieveCountedFileName mit den folgenden Schritten zweimal auf:

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

Beispiele

Im folgenden Codebeispiel wird die IWDFFile2-Schnittstelle von der IWDFFile-Schnittstelle abgerufen, die die Rückruffunktion IQueueCallbackCreate::OnCreateFile eines Treibers empfängt. Im Beispiel wird RetrieveCountedFileName zweimal aufgerufen. einmal, um die Länge des Dateinamens abzurufen, und einmal, um die Dateinamenzeichenfolge abzurufen.

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
UMDF-Mindestversion 1.9
Kopfzeile wudfddi.h (include Wudfddi.h)
DLL WUDFx.dll

Weitere Informationen