Fungsi GetPointerFrameTouchInfo (winuser.h)

Mendapatkan seluruh bingkai informasi berbasis sentuhan untuk pointer yang ditentukan (jenis PT_TOUCH) yang terkait dengan pesan saat ini.

Sintaks

BOOL GetPointerFrameTouchInfo(
  [in]      UINT32             pointerId,
  [in, out] UINT32             *pointerCount,
  [out]     POINTER_TOUCH_INFO *touchInfo
);

Parameter

[in] pointerId

Pengidentifikasi pointer untuk mengambil informasi bingkai.

[in, out] pointerCount

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

[out] touchInfo

Alamat array struktur POINTER_TOUCH_INFO untuk menerima informasi penunjuk. Parameter ini dapat berupa 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.

GetPointerFrameTouchInfo mengambil seluruh bingkai input pointer yang terkait dengan pesan pointer (jenis PT_TOUCH). Gunakan GetPointerTouchInfo 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 GetPointerFrameTouchInfo dikaitkan dengan pesan penunjuk 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 GetPointerFrameTouchInfoHistory 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 pointer 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 pesan penunjuk dikirimkan, fungsi ini gagal dengan kesalahan terakhir yang diatur ke ERROR_ACCESS_DENIED.

Jika penunjuk yang ditentukan bukan berjenis PT_TOUCH, fungsi ini gagal dengan kesalahan terakhir yang diatur ke ERROR_DATATYPE_MISMATCH.

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 (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll
Set API	ext-ms-win-rtcore-ntuser-wmpointer-l1-1-0 (diperkenalkan dalam Windows 10, versi 10.0.14393)

Lihat juga

Fungsi

GetPointerFrameTouchInfoHistory

GetPointerTouchInfo

GetPointerTouchInfoHistory