Fungsi SHChangeNotifyRegister (shlobj_core.h)

Artikel
08/26/2023

Mendaftarkan jendela untuk menerima pemberitahuan dari sistem file atau Shell, jika sistem file mendukung pemberitahuan.

Sintaks

ULONG SHChangeNotifyRegister(
  [in] HWND                      hwnd,
       int                       fSources,
       LONG                      fEvents,
       UINT                      wMsg,
       int                       cEntries,
  [in] const SHChangeNotifyEntry *pshcne
);

Parameter

[in] hwnd

Jenis: HWND

Handel ke jendela yang menerima pesan perubahan atau pemberitahuan.

fSources

Jenis: int

Satu atau beberapa nilai berikut yang menunjukkan jenis peristiwa yang akan menerima pemberitahuan.

Catatan Dalam versi SDK yang lebih lama, bendera ini tidak didefinisikan dalam file header dan pelaksana harus menentukan nilai-nilai ini sendiri atau menggunakan nilai numeriknya secara langsung. Pada Windows Vista, bendera ini didefinisikan dalam Shlobj.h.

SHCNRF_InterruptLevel (0x0001)

Pemberitahuan tingkat interupsi dari sistem file.

SHCNRF_ShellLevel (0x0002)

Pemberitahuan tingkat shell dari shell.

SHCNRF_RecursiveInterrupt (0x1000)

Mengganggu peristiwa pada seluruh subtree. Bendera ini harus digabungkan dengan bendera SHCNRF_InterruptLevel . Saat menggunakan bendera ini, pemberitahuan juga harus dibuat rekursif dengan mengatur anggota fRecursive dari struktur SHChangeNotifyEntry yang sesuai yang direferensikan oleh pshcne ke TRUE. Penggunaan SHCNRF_RecursiveInterrupt pada tampilan tingkat tunggal—misalnya, PIDL yang relatif dan hanya berisi satu SHITEMID—akan memblokir pemberitahuan peristiwa pada tingkat tertinggi dan dengan demikian mencegah pembaruan anak yang rekursif. Dengan demikian, ikon yang diseret ke tingkat hierarki folder terendah mungkin gagal muncul dalam tampilan seperti yang diharapkan.

SHCNRF_NewDelivery (0x8000)

Pesan yang diterima menggunakan memori bersama. Panggil SHChangeNotification_Lock untuk mengakses data aktual. Panggil SHChangeNotification_Unlock untuk melepaskan memori setelah selesai.

Catatan Kami merekomendasikan bendera ini karena menyediakan metode pengiriman yang lebih kuat. Semua klien harus menentukan bendera ini.

fEvents

Jenis: LONG

Ubah peristiwa pemberitahuan untuk menerima pemberitahuan. Lihat bendera SHCNE yang tercantum di SHChangeNotify untuk nilai yang mungkin.

wMsg

Jenis: UINT

Pesan yang akan diposting ke prosedur jendela.

cEntries

Jenis: int

Jumlah entri dalam array pshcne .

[in] pshcne

Jenis: const SHChangeNotifyEntry*

Array struktur SHChangeNotifyEntry yang berisi pemberitahuan. Array ini harus selalu diatur ke satu saat memanggil SHChangeNotifyRegister atau SHChangeNotifyDeregister tidak akan berfungsi dengan baik.

Menampilkan nilai

Jenis: ULONG

Mengembalikan ID pendaftaran bilangan bulat positif. Mengembalikan 0 jika kehabisan memori atau sebagai respons terhadap parameter yang tidak valid.

Keterangan

Lihat Change Notify Watcher Sample di Windows Software Development Kit (SDK) untuk contoh lengkap yang menunjukkan penggunaan fungsi ini.

Ketika peristiwa pemberitahuan perubahan dinaikkan, pesan yang ditunjukkan oleh wMsg dikirimkan ke jendela yang ditentukan oleh parameter hwnd .

Jika SHCNRF_NewDelivery ditentukan, nilai wParam dan lParam dalam pesan harus diteruskan ke SHChangeNotification_Lock sebagai parameter hChange dan dwProcID masing-masing.
Jika SHCNRF_NewDelivery tidak ditentukan, wParam adalah penunjuk ke dua penunjuk PIDLIST_ABSOLUTE, dan lParam menentukan peristiwa. Dua pointer PIDLIST_ABSOLUTE dapat berupa NULL, tergantung pada peristiwa yang dikirim.

Ketika peristiwa sistem file yang relevan terjadi dan parameter hwnd bukan NULL, maka pesan yang ditunjukkan oleh wMsg diposting ke jendela yang ditentukan. Jika tidak, jika parameter pshcne bukan NULL, entri pemberitahuan tersebut digunakan.

Untuk alasan performa, beberapa pemberitahuan dapat digabungkan menjadi satu pemberitahuan. Misalnya, jika sejumlah besar pemberitahuan SHCNE_UPDATEITEM dihasilkan untuk file di folder yang sama, mereka dapat digabungkan ke dalam satu pemberitahuan SHCNE_UPDATEDIR .

Fungsi NTSHChangeNotifyRegister , yang tidak lagi tersedia pada Windows Vista, setara dengan SHChangeNotifyRegister dengan bendera SHCNRF_NewDelivery.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	shlobj_core.h (termasuk Shlobj.h)
Pustaka	Shell32.lib
DLL	Shell32.dll (versi 5.0 atau yang lebih baru)
Set API	ext-ms-win-shell-shell32-l1-2-1 (diperkenalkan dalam Windows 10, versi 10.0.10240)

Bagikan melalui