Fungsi RpcServerRegisterIfEx (rpcdce.h)

Artikel
03/15/2023

Fungsi RpcServerRegisterIfEx mendaftarkan antarmuka dengan pustaka run-time RPC.

Sintaks

RPC_STATUS RpcServerRegisterIfEx(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  RPC_IF_CALLBACK_FN *IfCallback
);

Parameter

IfSpec

Struktur yang dihasilkan MIDL menunjukkan antarmuka untuk mendaftar.

MgrTypeUuid

Arahkan ke UUID jenis untuk dikaitkan dengan parameter MgrEpv . Menentukan nilai parameter null (atau UUID nihil) mendaftarkan IfSpec dengan UUID jenis nil.

MgrEpv

Vektor titik masuk (EPV) rutin manajer. Untuk menggunakan EPV default yang dihasilkan MIDL, tentukan nilai null . Untuk informasi lebih lanjut, silakan lihat RPC_MGR_EPV.

Flags

Bendera. Untuk daftar nilai bendera, lihat Bendera Pendaftaran Antarmuka.

MaxCalls

Jumlah maksimum permintaan panggilan prosedur jarak jauh bersamaan yang dapat diterima server pada antarmuka mendengarkan otomatis. Parameter MaxCalls hanya berlaku pada antarmuka mendengarkan otomatis, dan diabaikan pada antarmuka yang tidak mendengarkan secara otomatis. Pustaka run-time RPC berusaha sebaik mungkin untuk memastikan server tidak mengizinkan permintaan panggilan yang lebih bersamaan daripada jumlah panggilan yang ditentukan dalam MaxCalls. Jumlah aktual bisa lebih besar dan dapat bervariasi untuk setiap urutan protokol.

Panggilan pada antarmuka lain diatur oleh nilai parameter MaxCalls di seluruh proses yang ditentukan dalam panggilan fungsi RpcServerListen .

Jika jumlah panggilan bersamaan tidak menjadi perhatian, Anda dapat mencapai performa sisi server yang sedikit lebih baik dengan menentukan nilai default menggunakan RPC_C_LISTEN_MAX_CALLS_DEFAULT. Melakukannya akan meringankan lingkungan run-time RPC agar tidak memberlakukan pembatasan yang tidak perlu.

IfCallback

Fungsi panggilan balik keamanan, atau NULL tanpa panggilan balik. Setiap antarmuka terdaftar dapat memiliki fungsi panggilan balik yang berbeda. Lihat Keterangan untuk detail selengkapnya.

Nilai kembali

Mengembalikan RPC_S_OK setelah berhasil.

Catatan Untuk daftar kode kesalahan yang valid, lihat Nilai Pengembalian RPC.

Keterangan

Parameter dan efek rpcServerRegisterIfEx subsume RpcServerRegisterIf. Perbedaannya adalah kemampuan untuk mendaftarkan antarmuka mendengarkan otomatis dan menentukan fungsi panggilan balik keamanan.

Kode aplikasi server memanggil RpcServerRegisterIfEx untuk mendaftarkan antarmuka. Untuk mendaftarkan antarmuka, server menyediakan informasi berikut:

Spesifikasi antarmuka
Spesifikasi antarmuka adalah struktur data yang dihasilkan kompilator MIDL.
UUID jenis manajer dan manajer EPV
UUID jenis manajer dan manajer EPV menentukan rutinitas manajer mana yang dijalankan ketika server menerima permintaan panggilan prosedur jarak jauh dari klien. Untuk setiap implementasi antarmuka yang ditawarkan oleh server, antarmuka harus mendaftarkan EPV manajer terpisah.

Perhatikan bahwa saat menentukan UUID jenis manajer non-nihil, server juga harus memanggil RpcObjectSetType untuk mendaftarkan objek dari jenis non-nihil ini.

Menentukan bendera RPC_IF_AUTOLISTEN menandai antarmuka sebagai antarmuka mendengarkan otomatis. Run time mulai mendengarkan panggilan segera setelah antarmuka terdaftar, dan berhenti mendengarkan saat antarmuka tidak terdaftar. Panggilan ke RpcServerUnregisterIf untuk antarmuka ini akan menunggu penyelesaian semua panggilan yang tertunda pada antarmuka ini. Panggilan ke RpcServerListen dan RpcMgmtStopServerListening tidak akan memengaruhi antarmuka, juga tidak akan memanggil RpcServerUnregisterIf dengan IfSpec == NULL. Ini memungkinkan DLL untuk mendaftarkan antarmuka RPC atau menghapusnya dari registri tanpa mengubah status RPC aplikasi utama.

Menentukan fungsi panggilan balik keamanan memungkinkan aplikasi server membatasi akses ke antarmukanya berdasarkan per klien. Ingat bahwa, secara default, keamanan bersifat opsional; run time server akan mengirimkan panggilan yang tidak aman meskipun server telah memanggil RpcServerRegisterAuthInfo. Jika server hanya ingin menerima klien yang diautentikasi, fungsi panggilan balik antarmuka harus memanggil fungsi RpcBindingInqAuthClient atau RpcGetAuthorizationContextForClient untuk mengambil tingkat keamanan, atau mencoba meniru klien dengan RpcImpersonateClient. Ini juga dapat menentukan bendera RPC_IF_ALLOW_SECURE_ONLY di bendera antarmuka.

Ketika aplikasi server menentukan fungsi panggilan balik keamanan untuk antarmukanya, run time RPC secara otomatis menolak panggilan yang tidak dialokasikan ke antarmuka tersebut. Selain itu, run-time merekam antarmuka yang telah digunakan setiap klien. Ketika klien membuat RPC ke antarmuka yang belum digunakan selama sesi komunikasi saat ini, pustaka run-time RPC akan memanggil fungsi panggilan balik keamanan antarmuka. Menentukan bendera RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH akan mencegah penolakan otomatis terhadap klien yang tidak diaauthenticated.

Untuk tanda tangan untuk fungsi panggilan balik, lihat RPC_IF_CALLBACK_FN.

Fungsi panggilan balik harus mengembalikan RPC_S_OK jika klien diizinkan untuk memanggil metode di antarmuka ini. Kode pengembalian lainnya akan menyebabkan klien menerima pengecualian RPC_S_ACCESS_DENIED.

Dalam beberapa kasus, run time RPC dapat memanggil fungsi panggilan balik keamanan lebih dari sekali per klien–per antarmuka. Pastikan fungsi panggilan balik Anda dapat menangani kemungkinan ini.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	rpcdce.h (termasuk Rpc.h)
Pustaka	Rpcrt4.lib
DLL	Rpcrt4.dll