共用方式為

GetPointerFrameInfoHistory 函式 (winuser.h)

  • 發行項

取得整個資訊框架， (包括與目前訊息相關聯之指定指標的聯合輸入框架) 。

語法

BOOL GetPointerFrameInfoHistory(
  [in]      UINT32       pointerId,
  [in, out] UINT32       *entriesCount,
  [in, out] UINT32       *pointerCount,
  [out]     POINTER_INFO *pointerInfo
);

參數

[in] pointerId

要擷取框架資訊的指標識別碼。

[in, out] entriesCount

變數的指標，指定 pointerInfo 指向之二維陣列中的資料列計數。 如果 GetPointerFrameInfoHistory 成功， entriesCount 會以歷程記錄中可用的畫面總數來更新。

[in, out] pointerCount

變數的指標，指定 pointerInfo 指向的二維陣列中的資料行計數。 如果 GetPointerFrameInfoHistory 成功， pointerCount 會以每個畫面格中的指標總數來更新。

[out] pointerInfo

要接收指標資訊 之POINTER_INFO 結構的二維陣列位址。 如果 *entriesCount 和 *pointerCount 都是零，這個參數可以是 Null。

此陣列會解譯為 POINTER_INFO[*entriesCount][*pointerCount] 。

傳回值

如果函式成功，則傳回值為非零。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

平行模式裝置可能會報告畫面格中的指標輸入，也就是說，它們可能會向系統報告來自該裝置的所有指標狀態和位置。 在理想情況下，除非應用程式特定需求另有規定，否則應用程式應該將整個框架視為單一輸入。

GetPointerFrameInfo所傳回的資訊與呼叫執行緒所擷取的最新指標訊息相關聯。 當呼叫執行緒擷取下一個訊息時，可能無法再使用與上一個訊息相關聯的資訊。

如果應用程式未盡可能快速地處理指標輸入訊息，某些訊息可能會聯合成 WM_POINTERUPDATE 訊息。 使用 GetPointerFrameInfoHistory 擷取訊息歷程記錄 (包括來自最近WM_POINTERUPDATE訊息的聯合輸入畫面格 ) 。

擷取整個資訊框架之後，應用程式就可以呼叫 SkipPointerFrameMessages 函式，以略過與此框架相關聯的剩餘指標訊息，這些訊息會暫止擷取。 這可節省應用程式擷取和處理其餘訊息的額外負荷。 不過， SkipPointerFrameMessages 函式應該小心使用，而且只有在呼叫端可以確定呼叫端執行緒上沒有其他實體預期在擷取時，才會看到其餘的指標訊息。

此框架只包含目前與指定指標相同的視窗擁有的指標。

擷取的資訊代表一個二維陣列，每個歷程記錄專案各有一個資料列，以及框架中每個指標的一個資料行。

擷取的資訊會以反向時間順序顯示，且傳回陣列的第一個資料列中最新的專案。 最新的專案與 GetPointerFrameInfo 函式所傳回的專案相同。

如果提供的緩衝區中的資料列計數不足，無法保存所有可用的記錄專案，此函式就會成功，且緩衝區包含最新的專案和包含可用專案總數的 *entriesCount 。

如果指標框架除了指定的指標之外沒有其他指標，則此函式會成功，並只傳回指定指標的資訊。

如果不再提供與指標框架相關聯的資訊，此函式會失敗，並將最後一個錯誤設定為 ERROR_NO_DATA。

如果呼叫執行緒沒有擁有視窗 (輸入最初傳遞的位置，或訊息已轉送至其中) 已傳遞指標訊息的位置，則此函式會失敗，並將最後一個錯誤設定為 ERROR_ACCESS_DENIED。

對於同時具有用戶端和非用戶端區域的應用程式，輸入框架可以同時包含用戶端和非用戶端資料。 若要區分用戶端和非用戶端資料，您必須在目標視窗上執行點擊測試。

如果您想要從輸入框架篩選資料，建議您執行下列動作：

  • 對於不包含指標連絡人的每個更新， (沒有POINTER_FLAG_INCONTACT) 的POINTER_FLAG_UPDATE，點擊測試來判斷輸入是否為用戶端或非用戶端。
  • 針對每個新的連絡人 (POINTER_FLAG_DOWN) ，點擊測試以判斷輸入是否為用戶端或非用戶端，並追蹤此資訊。
  • 對於每個包含指標連絡人的更新， (具有POINTER_FLAG_INCONTACT) 的POINTER_FLAG_UPDATE，請使用追蹤資訊來判斷輸入是用戶端還是非用戶端。
  • 針對每個 POINTER_FLAG_UP，請使用追蹤資訊來判斷輸入是用戶端還是非用戶端，然後清除追蹤資料的這個指標。

規格需求

   
最低支援的用戶端 Windows 8 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2012 [僅限傳統型應用程式]
目標平台 Windows
標頭 winuser.h (包括 Windows.h)
程式庫 User32.lib
Dll User32.dll
API 集合 ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0 (Windows 10 10.0.14393 版)

請參閱

函式

GetPointerFrameInfo

GetPointerInfo

GetPointerInfoHistory