IWDFFile2：：RetrieveCountedFileName 方法 (wudfddi.h)

  • 项目

警告

UMDF 2 是 UMDF 的最新版本，取代了 UMDF 1。 所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。 不会向 UMDF 1 添加任何新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。 通用 Windows 驱动程序必须使用 UMDF 2。 有关详细信息，请参阅使用 UMDF 入门。

RetrieveCountedFileName 方法检索与设备关联的文件的完整计数文件名。

语法

HRESULT RetrieveCountedFileName(
  [out]     WCHAR *pCountedFileName,
  [in, out] DWORD *pdwCountedFileNameLengthInChars
);

参数

[out] pCountedFileName

指向调用方分配的缓冲区的指针。 此缓冲区接收一个 以 NULL 结尾的字符串，该字符串表示与设备关联的文件的全名。 如果指针为 NULL， 则 RetrieveCountedFileName 仅检索字符串长度。

[in, out] pdwCountedFileNameLengthInChars

指向调用方分配的变量的指针。 在输入时，驱动程序将变量设置为 pdwCountedFileNameLengthInChars 指向的缓冲区的长度（以字符为单位）。 在输出时，框架将变量设置为字符串的长度（以字符为单位）， (包括放置在缓冲区中的终止 NULL 字符) 。 如果计数文件名不存在，框架会将变量设置为零。

返回值

如果操作成功，RetrieveCountedFileName 将返回S_OK。 否则，方法可能会返回以下值之一：

返回代码 说明
E_POINTER pdwCountedFileNameLength 指针为 NULL。
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER) 计数的文件名无效。
E_NOT_SUFFICIENT_BUFFER pCountedFileName 指向的缓冲区太小。

此方法可能会在 Winerror.h 中返回其他值之一。

注解

计数文件名是一个字符串，除了终止 NULL 之外，还可以包含嵌入的 NULL ('\0') 个字符。 若要获取没有嵌入 NULL 字符的名称字符串，驱动程序可以调用 IWDFFile：：RetrieveFileName。

通常，驱动程序使用以下步骤调用 RetrieveCountedFileName 两次：

  1. 驱动程序调用将 pCountedFileName 参数设置为 NULL 的 RetrieveCountedFileName，以获取所需的缓冲区长度。
  2. 驱动程序分配所需大小的缓冲区。
  3. 驱动程序再次调用 RetrieveCountedFileName 以获取文件名字符串。

示例

下面的代码示例从驱动程序的 IQueueCallbackCreate：：OnCreateFile 回调函数接收的 IWDFFile 接口获取 IWDFFile2 接口。 该示例调用 RetrieveCountedFileName 两次;一次获取文件名的长度，一次用于检索文件名字符串。

VOID
STDMETHODCALLTYPE
CMyQueue::OnCreateFile(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in IWDFFile*  pWdfFileObject
    )
 ...
    IWDFFile2*  pWdfFileObject2 = NULL;
    WCHAR*  countedFileName = NULL;
    DWORD  countedFileNameCch = 0;
    HRESULT  hr = S_OK;
 
    //
    // Obtain IWDFFile2 interface from IWDFFile.
    //
    hr = pWdfFileObject->QueryInterface(IID_PPV_ARGS(&pWdfFileObject2));
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    //
    // Get length of counted filename.
    //
    hr = pWdfFileObject2->RetrieveCountedFileName(NULL,
                                                  &countedFileNameCch);
    if (!SUCCEEDED(hr))
    {
        goto Done;
    }
    if (countedFileNameCch != 0)
    {
        //
        // Allocate a buffer.
        //
        countedFileName = new WCHAR[countedFileNameCch];
        if (countedFileName == NULL)
        {
            hr = E_OUTOFMEMORY;
            goto Done;
        }
        //
        // Get counted file name.
        //
        hr = pWdfFileObject2->RetrieveCountedFileName(countedFileName, 
                                                      &countedFileNameCch);
        if (!SUCCEEDED(hr))
        {
            goto Done;
        }
    }
    ...

要求

要求 值
结束支持 在 UMDF 2.0 及更高版本中不可用。
目标平台 桌面
最低 UMDF 版本 1.9
标头 wudfddi.h (包括 Wudfddi.h)
DLL WUDFx.dll

另请参阅