共用方式為

IWDFFile2：：RetrieveCountedFileName 方法 (wudfddi.h)

  • 發行項

警告

UMDF 2 是最新版的 UMDF，並取代 UMDF 1。 所有新的UMDF驅動程式都應該使用UMDF 2撰寫。 未將新功能新增至 UMDF 1，且較新版本的 #D960AB00ACA324E23BD9B8460942A5346 上，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。 否則，方法可能會傳回下列其中一個值：

傳回碼 Description
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

另請參閱