IWDFFile：：RetrieveFileName 方法 (wudfddi.h)

[警告： UMDF 2 是最新版本的 UMDF，并取代 UMDF 1。 所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。 不会向 UMDF 1 添加任何新功能，并且较新版本的 Windows 10 上对 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