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

指向调用方提供的缓冲区的指针,如果提供的指针为非 NULLRetrieveFileName 成功,该缓冲区接收以 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