IWDFFile：：RetrieveFileName 方法 (wudfddi.h)

[警告： UMDF 2 是最新版的 UMDF，並取代 UMDF 1。 所有新的UMDF驅動程式都應該使用UMDF 2撰寫。 未將新功能新增至 UMDF 1，且較新版本的 #D5AF4712C93FF43F5B05E3CAA604DD9AD 上，UMDF 1 的支援有限。 通用 Windows 驅動程式必須使用 UMDF 2。 如需詳細資訊，請參閱使用 UMDF 使用者入門。]

RetrieveFileName 方法會擷取與基礎核心模式裝置相關聯之檔案的完整名稱。

語法

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

參數

[out] pFileName

呼叫端提供的緩衝區指標，如果提供的指標為非 NULL 且 RetrieveFileName 成功，則接收 NULL 終止字串，代表與基礎核心模式裝置相關聯之檔案的完整名稱。

[in, out] pdwFileNameLengthInChars

呼叫端提供之變數的指標，可接收 pFileName 指向之完整檔名的大小，以字元為單位。 如果 pFileName 的緩衝區不是 NULL，架構會傳回檔名字符串的大小，以字元為單位。

在輸入時，驅動程式會將此變數設定為 pFileName 所指向緩衝區的大小，以字元為單位。 如果驅動程式為 pFileName 提供 NULL，而 pdwFileNameLengthInChars 指向的變數則架構會將變數設定為大小，以字元為單位，檔名字符串需要。

傳回值

RetrieveFileName 會針對下列案例傳回S_OK：

• pFileName 參數指向的緩衝區不是 NULL 且足以保存名稱字串，包括 NULL 字元，而且架構已成功將字串複製到提供的緩衝區，並將 pdwFileNameLengthInChars 參數指向的變數設定為字元串中的字元數。
• pFileName 的緩衝區是 NULL，驅動程式會將 pdwFileNameLengthInChars 的變數預設為 0，而架構會將 pdwFileNameLengthInChars 的變數設定為字串所需的字元數。

RetrieveFileName 會傳回HRESULT_FROM_WIN32 (ERROR_INSUFFICIENT_BUFFER) ，指出提供的緩衝區為非 NULL ，且未包含足夠的空間來保存檔名。 架構會將 pdwFileNameLengthInChars 的變數設定為字串所需的字元數。

RetrieveFileName 也可能傳回其他 HRESULT 值。

備註

您的驅動程式可能會從其 IQueueCallbackCreate：：OnCreateFile 回呼函式呼叫 RetrieveFileName。 如需詳細資訊，請參閱 在UMDF驅動程式中使用裝置介面。

範例

下列程式代碼範例示範如何擷取檔名。

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

規格需求

需求	值
終止支援	在 UMDF 2.0 和更新版本中無法使用。
目標平台	桌面
最低UMDF版本	1.5
標頭	wudfddi.h (包含 Wudfddi.h)
Dll	WUDFx.dll

另請參閱

IWDFFile