struktur RPC_INTERFACE_TEMPLATEW (rpcdce.h)
Struktur RPC_INTERFACE_TEMPLATE mendefinisikan antarmuka server grup antarmuka RPC.
Sintaks
typedef struct {
unsigned long Version;
RPC_IF_HANDLE IfSpec;
UUID *MgrTypeUuid;
RPC_MGR_EPV *MgrEpv;
unsigned int Flags;
unsigned int MaxCalls;
unsigned int MaxRpcSize;
RPC_IF_CALLBACK_FN *IfCallback;
UUID_VECTOR *UuidVector;
RPC_WSTR Annotation;
void *SecurityDescriptor;
} RPC_INTERFACE_TEMPLATEW, *PRPC_INTERFACE_TEMPLATEW;
Anggota
Version
Bidang ini dicadangkan dan harus diatur ke 0.
IfSpec
Struktur yang dihasilkan MIDL yang mendefinisikan antarmuka untuk mendaftar.
MgrTypeUuid
Arahkan ke UUID untuk dikaitkan dengan MgrEpv. NULL atau UUID nihil mendaftarkan IfSpec dengan UUID nihil.
MgrEpv
Penunjuk ke struktur RPC_MGR_EPV yang berisi vektor titik masuk (EPV) rutin manajer. Jika NULL, EPV default yang dihasilkan MIDL digunakan.
Flags
Bendera. Untuk daftar nilai bendera, lihat Bendera Pendaftaran Antarmuka. Antarmuka grup antarmuka selalu diperlakukan sebagai mendengarkan otomatis.
MaxCalls
Jumlah maksimum permintaan panggilan prosedur jarak jauh bersamaan yang dapat diterima server pada antarmuka ini. Pustaka run-time RPC berupaya sebaik mungkin untuk memastikan server tidak mengizinkan permintaan panggilan yang lebih bersamaan daripada jumlah panggilan yang ditentukan di MaxCalls. Namun, jumlah aktual dapat lebih besar dari MaxCalls dan dapat bervariasi untuk setiap urutan protokol.
Panggilan pada antarmuka lain diatur oleh nilai parameter MaxCalls di seluruh proses yang ditentukan dalam RpcServerListen.
Jika jumlah panggilan bersamaan tidak menjadi perhatian, performa sisi server yang sedikit lebih baik dapat dicapai dengan menentukan nilai default menggunakan RPC_C_LISTEN_MAX_CALLS_DEFAULT. Melakukannya meringankan lingkungan run-time RPC dari memberlakukan pembatasan yang tidak perlu.
MaxRpcSize
Ukuran maksimum, dalam byte, dari blok data masuk. MaxRpcSize 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 di MaxRpcSize menghapus batas ukuran blok data masuk. Parameter ini tidak berpengaruh pada panggilan yang dilakukan melalui protokol ncalrpc .
IfCallback
Penunjuk ke fungsi panggilan balik keamanan RPC_INTERFACE_GROUP_IDLE_CALLBACK_FN , atau NULL tanpa panggilan balik. Setiap antarmuka terdaftar dapat memiliki fungsi panggilan balik yang berbeda.
UuidVector
Arahkan ke vektor UUID objek yang ditawarkan oleh server untuk didaftarkan ke pemeta titik akhir RPC. Aplikasi server membangun vektor ini. NULL menunjukkan tidak ada UUID objek untuk didaftarkan.
Annotation
Penunjuk ke komentar string karakter yang diterapkan ke setiap elemen lintas produk yang ditambahkan ke database peta titik akhir lokal. Panjang string dapat mencapai 64 karakter, termasuk karakter penghentian null. Tentukan nilai null atau string null-terminated ("\0") jika tidak ada string anotasi.
String anotasi hanya digunakan oleh aplikasi untuk informasi. RPC tidak menggunakan string ini untuk menentukan instans server mana yang dikomunikasikan klien dengan atau untuk menghitung elemen dalam database peta titik akhir.
SecurityDescriptor
Deskriptor keamanan opsional yang menjelaskan klien mana yang memiliki hak untuk mengakses antarmuka.
Keterangan
Untuk mendaftarkan antarmuka, server menyediakan informasi berikut:
- Spesifikasi antarmuka Spesifikasi antarmuka adalah struktur data yang dihasilkan kompilator MIDL.
- Jenis manajer UUID dan manajer EPV Jenis manajer UUID 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 manajer EPV terpisah. Perhatikan bahwa saat menentukan UUID jenis manajer non-nihil, server juga harus memanggil RpcObjectSetType untuk mendaftarkan objek dari jenis non-nihil ini.
Semua antarmuka grup antarmuka diperlakukan sebagai mendengarkan otomatis. Runtime mulai mendengarkan panggilan segera setelah grup antarmuka diaktifkan. Panggilan ke RpcServerListen dan RpcMgmtStopServerListening tidak memengaruhi antarmuka, juga tidak melakukan panggilan ke RpcServerUnregisterIf dengan IfSpec diatur ke NULL.
Menentukan fungsi panggilan balik keamanan di IfCallback memungkinkan aplikasi server membatasi akses ke antarmukanya secara individual. Artinya, secara default, keamanan bersifat opsional; run-time server akan mengirimkan panggilan yang tidak aman bahkan jika server telah memanggil RpcServerRegisterAuthInfo. Jika server hanya ingin menerima klien yang diautentikasi, fungsi panggilan balik antarmuka harus memanggil RpcBindingInqAuthClient, RpcGetAuthorizationContextForClient, atau RpcServerInqCallAttributes untuk mengambil tingkat keamanan, atau mencoba meniru klien dengan RpcImpersonateClient. Ini juga dapat menentukan bendera RPC_IF_ALLOW_SECURE_ONLY di Bendera untuk menolak panggilan yang tidak diaauthenticated.
Ketika aplikasi server menentukan fungsi panggilan balik keamanan untuk antarmukanya di IfCallback, 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 RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH dalam Bendera akan mencegah penolakan otomatis terhadap klien yang tidak diaauthenticated. Perhatikan bahwa panggilan pada 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 di IfCallback 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. Fungsi panggilan balik harus dapat menangani kemungkinan ini.
Catatan
Header rpcdce.h mendefinisikan RPC_INTERFACE_TEMPLATE sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows 8 [khusus aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2012 [hanya aplikasi desktop] |
| Header | rpcdce.h (termasuk Rpc.h) |
Lihat juga
RPC_INTERFACE_GROUP_IDLE_CALLBACK_FN