IWDFFile2::RetrieveCountedFileName-Methode (wudfddi.h)

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:

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

Weitere Informationen

• IWDFFile2
• IWDFFile::RetrieveFileName