共用方式為

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. 驅動程式會呼叫 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;
        }
    }
    ...

要求

要求 價值
終止支援 UMDF 2.0 和更新版本中無法使用。
目標平臺 桌面
最低 UMDF 版本 1.9
標頭 wudfddi.h （包括 Wudfddi.h）
DLL WUDFx.dll

另請參閱