Fungsi RpcServerRegisterIf2 (rpcdce.h)

Artikel
08/25/2023

Fungsi RpcServerRegisterIf2 mendaftarkan antarmuka dengan pustaka run-time RPC.

Sintaks

RPC_STATUS RpcServerRegisterIf2(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  unsigned int       MaxRpcSize,
  RPC_IF_CALLBACK_FN *IfCallbackFn
);

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.

MaxRpcSize

Ukuran maksimum blok data masuk, dalam byte. Parameter ini dapat digunakan untuk membantu mencegah serangan penolakan layanan berbahaya. Jika blok data panggilan prosedur jarak jauh lebih besar dari MaxRpcSize, pustaka run-time RPC menolak panggilan dan mengirim kesalahan RPC_S_ACCESS_DENIED ke klien. Menentukan nilai (int tidak ditandatangani) –1 untuk parameter ini akan menghapus batas ukuran blok data masuk. Parameter ini tidak berpengaruh pada panggilan yang dilakukan melalui protokol ncalrpc .

IfCallbackFn

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

Mengembalikan nilai

Mengembalikan RPC_S_OK setelah berhasil.

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

Keterangan

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

Kode aplikasi server memanggil RpcServerRegisterIf2 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 menunggu penyelesaian semua panggilan yang tertunda pada antarmuka ini. Panggilan ke fungsi RpcServerListen dan RpcMgmtStopServerListening tidak memengaruhi antarmuka, juga tidak melakukan panggilan ke fungsi RpcServerUnregisterIf dengan IfSpec diatur ke nilai 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 secara individual. Artinya, secara default, keamanan bersifat opsional; run-time server akan mengirimkan panggilan yang tidak aman meskipun server telah memanggil fungsi RpcServerRegisterAuthInfo . Jika server hanya ingin menerima klien yang diautentikasi, fungsi panggilan balik antarmuka harus memanggil fungsi RpcBindingInqAuthClient, RpcGetAuthorizationContextForClient, atau RpcServerInqCallAttributes untuk mengambil tingkat keamanan, atau mencoba meniru klien dengan fungsi RpcImpersonateClient . Ini juga dapat menentukan bendera RPC_IF_ALLOW_SECURE_ONLY di bendera antarmuka untuk menolak panggilan yang tidak diaauthenticated.

Ketika aplikasi server menentukan fungsi panggilan balik keamanan untuk antarmukanya, run time RPC secara otomatis menolak panggilan tanpa informasi autentikasi 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 memanggil fungsi panggilan balik keamanan antarmuka. Menentukan bendera RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH akan mencegah penolakan otomatis terhadap klien yang tidak diaauthenticated. Perhatikan bahwa panggilan pada apa yang disebut sesi keamanan NULL dapat memiliki informasi autentikasi, meskipun mereka berasal dari klien anonim. Dengan demikian keberadaan panggilan balik saja tidak cukup untuk mencegah klien anonim terhubung. Baik fungsi panggilan balik keamanan harus memeriksanya, atau bendera RPC_IF_ALLOW_SECURE_ONLY harus digunakan. RPC_IF_ALLOW_SECURE_ONLY menolak panggilan sesi null hanya pada Windows XP dan versi Windows yang lebih baru.

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 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	rpcdce.h (termasuk Rpc.h)
Pustaka	Rpcrt4.lib
DLL	Rpcrt4.dll