Fungsi GetPointerFrameInfo (winuser.h)

Mendapatkan seluruh bingkai informasi untuk penunjuk yang ditentukan yang terkait dengan pesan saat ini.

Sintaks

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

Parameter

[in] pointerId

Pengidentifikasi penunjuk untuk mengambil informasi bingkai.

[in, out] pointerCount

Penunjuk ke variabel yang menentukan jumlah struktur dalam buffer tempat pointerInfo menunjuk. Jika GetPointerFrameInfo berhasil, pointerCount diperbarui dengan jumlah total pointer dalam bingkai.

[out] pointerInfo

Alamat array struktur POINTER_INFO untuk menerima informasi penunjuk. Parameter ini bisa NULL jika *pointerCount adalah nol.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Perangkat mode paralel dapat melaporkan input pointer dalam bingkai, yaitu, perangkat dapat melaporkan status dan posisi semua pointer dari perangkat tersebut dalam satu laporan input ke sistem. Idealnya, aplikasi harus melihat seluruh bingkai sebagai input tunggal kecuali persyaratan khusus aplikasi menentukan sebaliknya.

GetPointerFrameInfo mengambil seluruh bingkai input pointer yang terkait dengan pesan pointer. Gunakan GetPointerInfo untuk mengambil informasi untuk satu penunjuk yang terkait dengan pesan penunjuk.

Bingkai hanya berisi penunjuk yang saat ini dimiliki oleh jendela yang sama dengan penunjuk yang ditentukan.

Informasi yang dikembalikan oleh GetPointerFrameInfo dikaitkan dengan pesan pointer terbaru yang diambil oleh utas panggilan. Ketika pesan berikutnya diambil oleh utas panggilan, informasi yang terkait dengan pesan sebelumnya mungkin tidak lagi tersedia.

Jika aplikasi tidak memproses pesan input pointer secepat yang dihasilkan, beberapa pesan mungkin digabungkan ke dalam pesan WM_POINTERUPDATE . Gunakan GetPointerFrameInfoHistory untuk mengambil riwayat pesan dari pesan WM_POINTERUPDATE terbaru.

Setelah mengambil seluruh bingkai informasi, aplikasi kemudian dapat memanggil fungsi SkipPointerFrameMessages untuk melewati pesan pointer yang tersisa yang terkait dengan bingkai ini yang menunggu pengambilan. Ini menyimpan aplikasi overhead pengambilan dan pemrosesan pesan yang tersisa satu per satu. Namun, fungsi SkipPointerFrameMessages harus digunakan dengan hati-hati dan hanya ketika pemanggil dapat memastikan bahwa tidak ada entitas lain pada utas pemanggil yang mengharapkan untuk melihat pesan pointer yang tersisa satu per satu saat mereka diambil.

Perhatikan bahwa informasi yang diambil dikaitkan dengan bingkai penunjuk yang terakhir diambil oleh utas panggilan. Setelah utas panggilan mengambil pesan berikutnya, informasi yang terkait dengan bingkai penunjuk sebelumnya mungkin tidak lagi tersedia.

Jika bingkai penunjuk tidak berisi penunjuk tambahan selain penunjuk yang ditentukan, fungsi ini berhasil dan hanya mengembalikan informasi untuk penunjuk yang ditentukan.

Jika informasi yang terkait dengan bingkai penunjuk tidak lagi tersedia, fungsi ini gagal dengan kesalahan terakhir yang diatur ke ERROR_NO_DATA.

Jika utas panggilan tidak memiliki jendela (tempat input awalnya dikirim atau tempat pesan diteruskan) tempat pesan penunjuk dikirimkan, fungsi ini gagal dengan kesalahan terakhir yang diatur ke ERROR_ACCESS_DENIED.

Untuk aplikasi yang memiliki area klien dan non-klien, bingkai input dapat menyertakan data klien dan non-klien. Untuk membedakan antara data klien dan non-klien, Anda harus melakukan pengujian hit pada jendela target.

Kami merekomendasikan hal berikut jika Anda ingin memfilter data dari bingkai input:

• Untuk setiap pembaruan yang tidak menyertakan kontak pointer ( POINTER_FLAG_UPDATE tanpa POINTER_FLAG_INCONTACT), tekan pengujian untuk menentukan apakah input adalah klien atau non-klien.
• Untuk setiap kontak baru (POINTER_FLAG_DOWN), tekan uji untuk menentukan apakah input adalah klien atau non-klien dan lacak info ini.
• Untuk setiap pembaruan yang menyertakan kontak pointer ( POINTER_FLAG_UPDATE dengan POINTER_FLAG_INCONTACT), gunakan info pelacakan untuk menentukan apakah input adalah klien atau non-klien.
• Untuk setiap POINTER_FLAG_UP, gunakan info pelacakan untuk menentukan apakah input adalah klien atau non-klien lalu hapus pointer ini dari data pelacakan.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 8 [khusus aplikasi desktop]
Server minimum yang didukung	Windows Server 2012 [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (termasuk Windows.h)
Pustaka	User32.lib
DLL	User32.dll

Lihat juga

Fungsi

GetPointerFrameInfoHistory

GetPointerInfo

GetPointerInfoHistory