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 值。
注解
驱动程序可以从其 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 |