IWDFFile2：：RetrieveCountedFileName 方法 （wudfddi.h）

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

语法

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

参数

[out] pCountedFileName

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

[in, out] pdwCountedFileNameLengthInChars

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

返回值

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

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

言论

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

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

1. 驱动程序调用 RetrieveCountedFileName，并将 pCountedFileName 参数设置为 NULL，以获取所需的缓冲区长度。
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;
        }
    }
    ...

要求

另请参阅

• IWDFFile2
• IWDFFile：：RetrieveFileName