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终止字符串，表示与基础内核模式设备关联的文件的全名，如果提供的指针不是非NULL，并且 RetrieveFileName 成功。

[in, out] pdwFileNameLengthInChars

指向调用方提供的变量的指针，该变量接收 pFileName 指向的完整文件名的大小（以字符为单位）。 如果 pFileName 的缓冲区是非NULL，则框架将返回文件名字符串的大小（以字符为单位）。

在输入时，驱动程序将此变量设置为 pFileName 指向的缓冲区的大小（以字符为单位）。 如果驱动程序为 pFileName 提供 NULL，并且 pdwFileNameLengthInChars 的变量为零，则框架会将变量设置为文件名字符串所需的大小（以字符为单位）。

返回值

RetrieveFileName 返回以下方案的S_OK：

• pFileName 参数指向的缓冲区是非NULL，并且足够大，可以容纳名称字符串（包括 NULL 字符），框架成功将字符串复制到提供的缓冲区中，并将 pdwFileNameLengthInChars 参数指向的变量设置为字符串中的字符数。
• pFileName 的缓冲区 NULL，驱动程序将变量预设在 pdwFileNameLengthInChars 为 0，框架将变量设置为 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);
    }

要求

另请参阅

IWDFFile