Fungsi RpcServerSubscribeForNotification (rpcasync.h)
Fungsi RpcServerSubscribeForNotification berlangganan server untuk pemberitahuan RPC.
Sintaks
RPC_STATUS RpcServerSubscribeForNotification(
[in] RPC_BINDING_HANDLE Binding,
[in] RPC_NOTIFICATIONS Notification,
[in] RPC_NOTIFICATION_TYPES NotificationType,
[in] RPC_ASYNC_NOTIFICATION_INFO *NotificationInfo
);
Parameter
[in] Binding
RPC_BINDING_HANDLE struktur yang berisi handel pengikatan untuk panggilan saat ini. Jika fungsi ini dipanggil pada utas yang sama dengan yang telah dikirim RPC panggilan, parameter ini dapat diatur ke NULL; jika tidak, handel pengikatan eksplisit harus diteruskan dalam parameter ini.
[in] Notification
Kombinasi bitwise dari nilai enumerasi RPC_NOTIFICATIONS yang menentukan jenis pemberitahuan yang diminta dari RPC oleh server.
Windows Vista: Saat ini, hanya RpcNotificationClientDisconnect dan RpcNotificationCallCancel yang didukung. Jika ada nilai lain yang ditentukan untuk parameter ini, kode kesalahan RPC_S_CANNOT_SUPPORT dikembalikan.
[in] NotificationType
RPC_NOTIFICATION_TYPES nilai enumerasi yang menentukan metode di mana RPC akan memberi tahu server.
Windows Vista: RpcNotificationTypeNone tidak didukung. Jika nilai ini ditentukan, kode kesalahan RPC_S_INVALID_ARG dikembalikan.
[in] NotificationInfo
Arahkan ke serikat RPC_ASYNC_NOTIFICATION_INFO yang berisi informasi spesifik yang diperlukan rpc untuk menghubungi server untuk pemberitahuan. Data yang terkandung dalam serikat ini khusus untuk metode yang diteruskan ke parameter NotificationType .
Jika metode RpcNotificationTypeCallback ditentukan dalam NotificationTypes, anggota NotificationRoutine dari cabang serikat yang sesuai diatur ke handel pengikatan untuk panggilan sinkron dan handel asinkron untuk panggilan asinkron.
RPC membuat salinan parameter ini selama panggilan yang berhasil ke fungsi ini. Pemanggil dapat membebaskan atau memperbarui parameter ini saat API kembali.
Nilai kembali
Fungsi ini mengembalikan RPC_S_OK pada keberhasilan; jika tidak, kode kesalahan RPC_S_* dikembalikan.
Keterangan
Jika penelepon menentukan jenis pemberitahuan selain RpcNotificationTypeEvent, pemanggil dapat berlangganan pemberitahuan RpcNotificationClientDisconnect dan RpcNotificationCallCancel dengan satu panggilan. Untuk peristiwa, diperlukan dua panggilan terpisah ke API ini.
Aplikasi server harus berhenti berlangganan pemberitahuan sebelum panggilan RPC selesai. Jika panggilan RPC sinkron, itu selesai ketika server mengirim nilai yang dikembalikan ke RPC. Jika panggilan RPC asinkron, itu selesai ketika server memanggil RpcAsyncCompleteCall atau RpcAsyncAbortCall, atau melemparkan pengecualian dari rutinitas manajer. Jika server gagal berhenti berlangganan pemberitahuan perubahan status panggilan, hasilnya tidak terdefinisi, dan server mungkin mengalami crash di lain waktu. Perhatikan bahwa langganan hanya berlaku untuk satu panggilan RPC. Jika aplikasi server perlu memantau lebih dari satu panggilan, aplikasi perlu berlangganan untuk setiap panggilan secara khusus.
Aplikasi server dapat mengharapkan bahwa aplikasi tidak akan diberi sinyal untuk pemberitahuan yang belum berlangganan. Jika telah berlangganan untuk lebih dari satu pemberitahuan, setiap pemberitahuan dikomunikasikan ke metode penyelesaian jika metode penyelesaian yang dipilih mengizinkannya. Jika tidak mengizinkan komunikasi pemberitahuan, aplikasi server dapat memanggil API server RPC untuk menguji apakah klien telah membatalkan atau memutuskan sambungannya atau tidak. Tabel di bawah ini menunjukkan bagaimana jenis pemberitahuan (pembatalan panggilan atau pemutusan sambungan klien) dikomunikasikan ke setiap metode pemberitahuan:
| Metode Pemberitahuan | Jenis Peristiwa/Pemberitahuan |
|---|---|
| RpcNotificationTypeNone | Tidak diizinkan untuk langganan. |
| RpcNotificationTypeEvent | Jenis pemberitahuan tidak tersedia. |
| RpcNotificationTypeApc | Jenis pemberitahuan ditemukan dalam parameter Peristiwa fungsi APC. |
| RpcNotificationTypeIoc | Jenis pemberitahuan tidak tersedia. |
| RpcNotificationTypeCallback | Jenis pemberitahuan ditemukan di parameter Peristiwa fungsi panggilan balik. |
Perhatikan bahwa tabel tidak menyiratkan apakah penelepon dapat berlangganan pemberitahuan menggunakan metode pemberitahuan yang diberikan atau tidak; sebaliknya, itu hanya menyatakan informasi yang dapat diperoleh pemanggil ketika pemberitahuan diterima, seperti jenis pemberitahuan.
Pemanggil harus menyinkronkan antara RpcServerSubscribeForNotification dan RpcServerUnsubscribeForNotification pada handel pengikatan yang sama. Jika dipanggil secara bersamaan, hasilnya tidak terdefinisi dan dapat menimbulkan pemberitahuan yang hilang, pemberitahuan tambahan, jumlah pemberitahuan yang salah, crash proses, kerusakan data, dan kebocoran memori. Kekhawatiran yang sama berlaku untuk thread yang memanggil RpcServerSubscribeForNotification pada handel pengikatan yang sama.
Memanggil RpcServerSubscribeForNotification dan RpcServerUnsubscribeForNotification pada handel pengikatan yang sama aman untuk utas. Untuk pemberitahuan saat ini, RPC akan memberi tahu server tidak lebih dari sekali per panggilan.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows Vista, Windows XP dengan SP2 [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008, Windows Server 2003 dengan SP1 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | rpcasync.h (termasuk Rpc.h) |
| Pustaka | Rpcrt4.lib |
| DLL | Rpcrt4.dll |