Mendaftarkan Antarmuka
Bagian ini menyajikan diskusi terperinci tentang proses mendaftarkan antarmuka RPC.
Informasi di bagian ini disajikan dalam topik berikut:
- Fungsi Pendaftaran Antarmuka
- Vektor Titik Entri
- Manajer EPV
- Mendaftarkan Satu Implementasi Antarmuka
- Mendaftarkan Beberapa Implementasi Antarmuka
- Aturan untuk Rutinitas Manajer Pemanggilan
- Mengirimkan Panggilan Prosedur Jarak Jauh ke Rutinitas Server-Manager
- Menyediakan Fungsi Object-Inquiry Anda Sendiri
Fungsi Pendaftaran Antarmuka
Server mendaftarkan antarmuka mereka dengan memanggil fungsi RpcServerRegisterIf . Program server yang kompleks sering mendukung lebih dari satu antarmuka. Aplikasi server harus memanggil fungsi ini sekali untuk setiap antarmuka yang mereka dukung.
Selain itu, server dapat mendukung beberapa versi antarmuka yang sama, masing-masing dengan implementasi fungsi antarmukanya sendiri. Jika program server Anda melakukan ini, program ini harus menyediakan sekumpulan titik masuk. Titik masuk adalah rutinitas manajer yang mengirimkan panggilan untuk versi antarmuka. Harus ada satu titik masuk untuk setiap versi antarmuka. Grup titik masuk disebut vektor titik masuk. Untuk detailnya, lihat Vektor Titik Entri.
Selain fungsi standar RpcServerRegisterIf, RPC juga mendukung fungsi pendaftaran antarmuka lainnya. Fungsi RpcServerRegisterIf2 memperluas kemampuan RpcServerRegisterIf dengan memungkinkan Anda menentukan serangkaian bendera pendaftaran (lihat Bendera Pendaftaran Antarmuka), jumlah maksimum permintaan panggilan prosedur jarak jauh bersamaan yang dapat diterima server, dan ukuran maksimum dalam byte blok data masuk.
Pustaka RPC juga berisi fungsi yang disebut RpcServerRegisterIfEx. Seperti fungsi RpcServerRegisterIf , fungsi ini mendaftarkan antarmuka. Program server Anda juga dapat menggunakan fungsi ini untuk menentukan sekumpulan bendera pendaftaran (lihat Bendera Pendaftaran Antarmuka), jumlah maksimum permintaan panggilan prosedur jarak jauh bersamaan yang dapat diterima server, dan fungsi panggilan balik keamanan.
Fungsi RpcServerRegisterIf, RpcServerRegisterIfEx, dan RpcServerRegisterIf2 menetapkan nilai dalam tabel registri antarmuka internal. Tabel ini digunakan untuk memetakan antarmuka UUID dan UUID objek ke manajer EPV. Manajer EPV adalah array penunjuk fungsi yang berisi tepat satu penunjuk fungsi untuk setiap prototipe fungsi dalam antarmuka yang ditentukan dalam file IDL.
Untuk informasi tentang menyediakan beberapa EPV untuk menyediakan beberapa implementasi antarmuka, lihat Beberapa Implementasi Antarmuka.
Pustaka run-time menggunakan tabel registri antarmuka (diatur oleh panggilan ke fungsi RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2) dan tabel registri objek (diatur oleh panggilan ke fungsi RpcObjectSetType) untuk memetakan antarmuka dan UUID objek ke pointer fungsi.
Ketika Anda ingin program server Anda menghapus antarmuka dari registri pustaka run-time RPC, panggil fungsi RpcServerUnregisterIf . Setelah antarmuka dihapus dari registri, pustaka run-time RPC tidak akan lagi menerima panggilan baru untuk antarmuka tersebut.
Vektor titik masuk
Vektor titik entri manajer (EPV) adalah array penunjuk fungsi yang menunjuk ke implementasi fungsi yang ditentukan dalam file IDL. Jumlah elemen dalam array sesuai dengan jumlah fungsi yang ditentukan dalam file IDL. RPC mendukung beberapa vektor titik entri yang mewakili beberapa implementasi fungsi yang ditentukan dalam antarmuka.
Kompilator MIDL secara otomatis menghasilkan jenis data EPV manajer untuk digunakan dalam membangun EPV manajer. Jenis data diberi nama if-name**_SERVER_EPV**, di mana if-name menentukan pengidentifikasi antarmuka dalam file IDL.
Kompilator MIDL secara otomatis membuat dan menginisialisasi manajer default EPV dengan asumsi bahwa rutinitas manajer dengan nama yang sama ada untuk setiap prosedur dalam antarmuka dan ditentukan dalam file IDL.
Ketika server menawarkan beberapa implementasi antarmuka yang sama, server harus membuat satu EPV manajer tambahan untuk setiap implementasi. Setiap EPV harus berisi tepat satu titik entri (alamat fungsi) untuk setiap prosedur yang ditentukan dalam file IDL. Aplikasi server mendeklarasikan dan menginisialisasi satu variabel EPV manajer jenis if-name**_SERVER_EPV** untuk setiap implementasi tambahan antarmuka. Untuk mendaftarkan EPV, ia memanggil RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 sekali untuk setiap jenis objek yang didukungnya.
Ketika klien melakukan panggilan prosedur jarak jauh ke server, EPV yang berisi penunjuk fungsi dipilih berdasarkan antarmuka UUID dan jenis objek. Jenis objek berasal dari UUID objek oleh fungsi object-inquiry atau pemetaan berbasis tabel yang dikendalikan oleh RpcObjectSetType.
Manajer EPV
Secara default, pengkompilasi MIDL menggunakan nama prosedur dari file IDL antarmuka untuk menghasilkan manajer EPV, yang ditempat pengkompilasi langsung ke dalam stub server. EPV default ini secara statis diinisialisasi menggunakan nama prosedur yang dideklarasikan dalam definisi antarmuka.
Untuk mendaftarkan manajer menggunakan EPV default, tentukan NULL sebagai nilai parameter MgrEpv dalam panggilan ke fungsi RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 . Jika nama rutin yang digunakan oleh manajer sesuai dengan definisi antarmuka, Anda dapat mendaftarkan manajer ini menggunakan EPV default antarmuka yang dihasilkan oleh pengkompilasi MIDL. Anda juga dapat mendaftarkan manajer menggunakan EPV yang disediakan aplikasi server.
Server dapat (dan terkadang harus) membuat dan mendaftarkan EPV manajer non-null untuk antarmuka. Untuk memilih EPV yang disediakan aplikasi server, berikan alamat EPV yang nilainya telah dideklarasikan oleh server sebagai nilai MgrEpv parameter. Nilai non-null untuk MgrEpv parameter selalu menggantikan EPV default di stub server.
Kompilator MIDL secara otomatis menghasilkan jenis data EPV manajer (RPC_MGR_EPV) untuk digunakan aplikasi server dalam membangun EPV manajer. Manajer EPV harus berisi tepat satu titik masuk (alamat fungsi) untuk setiap prosedur yang ditentukan dalam file IDL.
Server harus menyediakan EPV non-null dalam kasus berikut:
- Ketika nama rutinitas manajer berbeda dari nama prosedur yang dideklarasikan dalam definisi antarmuka
- Ketika server menggunakan EPV default untuk mendaftarkan implementasi lain dari antarmuka
Server mendeklarasikan manajer EPV dengan menginisialisasi variabel jenis if-name**_SERVER_EPV** untuk setiap implementasi antarmuka.
Mendaftarkan Satu Implementasi Antarmuka
Ketika server hanya menawarkan satu implementasi antarmuka, server memanggil RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 hanya sekali. Dalam kasus standar, server menggunakan manajer default EPV. (Pengecualiannya adalah ketika manajer menggunakan nama rutin yang berbeda dari yang dideklarasikan dalam antarmuka.)
Untuk kasus standar, Anda menyediakan nilai berikut untuk panggilan ke RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2:
Manajer EPV
Untuk menggunakan EPV default, tentukan nilai null untuk parameter MgrEpv .
UUID jenis manajer
Saat menggunakan EPV default, daftarkan antarmuka dengan UUID jenis manajer nihil dengan menyediakan nilai null atau UUID nihil untuk parameter MgrTypeUuid . Dalam hal ini, semua panggilan prosedur jarak jauh, terlepas dari UUID objek dalam handel pengikatannya, dikirim ke EPV default, dengan asumsi tidak ada panggilan RpcObjectSetType yang telah dilakukan.
Anda juga dapat menyediakan UUID jenis manajer non-nihil. Dalam hal ini, Anda juga harus memanggil rutinitas RpcObjectSetType .
Mendaftarkan Beberapa Implementasi Antarmuka
Anda dapat menyediakan lebih dari satu implementasi prosedur jarak jauh yang ditentukan dalam file IDL. Aplikasi server memanggil RpcObjectSetType untuk memetakan UUID objek untuk mengetik UUID dan memanggil RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 untuk mengaitkan EPV manajer dengan jenis UUID. Ketika panggilan prosedur jarak jauh tiba dengan UUID objeknya, pustaka run-time server RPC memetakan UUID objek ke UUID jenis. Aplikasi server kemudian menggunakan jenis UUID dan antarmuka UUID untuk memilih manajer EPV.
Anda juga dapat menentukan fungsi Anda sendiri untuk menyelesaikan pemetaan dari UUID objek ke UUID jenis manajer. Anda menentukan fungsi pemetaan saat memanggil RpcObjectSetInqFn.
Untuk menawarkan beberapa implementasi antarmuka, server harus mendaftarkan setiap implementasi dengan memanggil RpcServerRegisterIf, RpcServerRegisterIfEx atau RpcServerRegisterIf2 secara terpisah. Untuk setiap implementasi yang didaftarkan server, server memasok parameter IfSpec yang sama, tetapi sepasang parameter MgrTypeUuid dan MgrEpv yang berbeda.
Dalam kasus beberapa manajer, gunakan RpcServerRegisterIf, RpcServerRegisterIfEx atau RpcServerRegisterIf2 sebagai berikut:
Manajer EPV
Untuk menawarkan beberapa implementasi antarmuka, server harus:
- Buat EPV manajer non-null untuk setiap implementasi tambahan.
- Tentukan nilai non-null untuk parameter MgrEpv di RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2.
Harap dicatat bahwa server juga dapat mendaftar dengan manajer default EPV.
UUID jenis manajer
Berikan UUID jenis manajer untuk setiap EPV antarmuka. UUID jenis nihil (atau nilai null ) untuk MgrTypeUuid parameter dapat ditentukan untuk salah satu EPV manajer. Setiap jenis UUID harus berbeda.
Aturan untuk Rutinitas Manajer Pemanggilan
Pustaka run-time RPC mengirimkan panggilan prosedur jarak jauh masuk ke manajer yang menawarkan antarmuka RPC yang diminta. Ketika beberapa manajer terdaftar untuk antarmuka, pustaka run-time RPC harus memilih salah satunya. Untuk memilih manajer, pustaka run-time RPC menggunakan UUID objek yang ditentukan oleh handel pengikatan panggilan.
Pustaka run-time menerapkan aturan berikut saat menginterpretasikan UUID objek dari panggilan prosedur jarak jauh:
UUID objek nihil
UUID objek nihil secara otomatis ditetapkan UUID jenis nihil (ilegal untuk menentukan UUID objek nihil dalam rutinitas RpcObjectSetType ). Oleh karena itu, panggilan prosedur jarak jauh yang handel pengikatannya berisi UUID objek nihil secara otomatis dikirim ke manajer yang terdaftar dengan UUID jenis nihil, jika ada.
UUID objek non-nihil
Pada prinsipnya, panggilan prosedur jarak jauh yang handel pengikatannya berisi UUID objek non-nihil harus diproses oleh manajer yang jenis UUID-nya cocok dengan jenis UUID objek. Namun, mengidentifikasi manajer yang benar mengharuskan server telah menentukan jenis UUID objek tersebut dengan memanggil rutinitas RpcObjectSetType .
Jika server gagal memanggil rutinitas RpcObjectSetType untuk UUID objek non-nihil, panggilan prosedur jarak jauh untuk UUID objek tersebut masuk ke EPV manajer yang melayani panggilan prosedur jarak jauh dengan UUID objek nihil (yaitu, UUID jenis nihil).
Panggilan prosedur jarak jauh dengan UUID objek non-nihil dalam handel pengikatan tidak dapat dijalankan jika server menetapkan UUID objek non-nihil jenis UUID dengan memanggil rutinitas RpcObjectSetType , tetapi tidak juga mendaftarkan manajer EPV untuk UUID jenis tersebut dengan memanggil RpcServerRegisterIf, RpcServerRegisterIfEx atau RpcServerRegisterIf2.
Tabel berikut ini meringkas tindakan yang digunakan pustaka run-time untuk memilih rutinitas manajer.
| UUID objek panggilan | Jenis set server untuk UUID objek? | Jenis EPV terdaftar server? | Tindakan pengiriman |
|---|---|---|---|
| Nihil | Tidak berlaku | Ya | Menggunakan manajer dengan UUID jenis nihil. |
| Nihil | Tidak berlaku | Tidak | Kesalahan (RPC_S_UNSUPPORTED_TYPE); menolak panggilan prosedur jarak jauh. |
| Non-nihil | Ya | Ya | Menggunakan manajer dengan UUID jenis yang sama. |
| Non-nihil | Tidak | Diabaikan | Menggunakan manajer dengan UUID jenis nihil. Jika tidak ada manajer dengan UUID jenis nihil, kesalahan (RPC_S_UNSUPPORTEDTYPE); menolak panggilan prosedur jarak jauh. |
| Non-nihil | Ya | Tidak | Kesalahan (RPC_S_UNSUPPORTEDTYPE); menolak panggilan prosedur jarak jauh. |
UUID objek panggilan adalah UUID objek yang ditemukan dalam handel pengikatan untuk panggilan prosedur jarak jauh.
Server mengatur jenis UUID objek dengan memanggil RpcObjectSetType untuk menentukan jenis UUID untuk objek.
Server mendaftarkan jenis untuk manajer EPV dengan memanggil RpcServerRegisterIf, RpcServerRegisterIfEx atau RpcServerRegisterIf2 menggunakan UUID jenis yang sama.
Catatan
UUID objek nihil selalu secara otomatis ditetapkan UUID jenis nihil. Adalah ilegal untuk menentukan UUID objek nihil dalam rutinitas RpcObjectSetType .
Mengirimkan Panggilan Prosedur Jarak Jauh ke Rutinitas Manajer Server
Tabel berikut menunjukkan langkah-langkah yang diperlukan pustaka run-time RPC untuk mengirimkan panggilan prosedur jarak jauh ke rutinitas manajer server.
Kasus sederhana di mana server mendaftarkan manajer default EPV, dijelaskan dalam tabel berikut.
Tabel Registri Antarmuka
| Antarmuka UUID | UUID jenis manajer | Vektor titik masuk |
|---|---|---|
| uuid1 | Nihil | Default EPV |
Tabel Registri Objek
| UUID Objek | Tipe objek |
|---|---|
| Nihil | Nihil |
| (UUID objek lainnya) | Nihil |
Memetakan Handel Pengikatan ke Vektor Titik Entri (EPV)
| Antarmuka UUID (dari handel pengikatan klien) | UUID objek (dari handel pengikatan klien) | Jenis objek (dari tabel registri objek) | Manajer EPV (dari tabel registri antarmuka) |
|---|---|---|---|
| uuid1 | Nihil | Nihil | Default EPV |
| Sama seperti di atas | uuidA | Nihil | Default EPV |
Langkah-langkah berikut menjelaskan tindakan yang dilakukan pustaka run-time server RPC, seperti yang ditunjukkan pada tabel sebelumnya, saat klien dengan antarmuka UUID uuid1 memanggilnya.
Server memanggil RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 untuk mengaitkan antarmuka yang ditawarkannya dengan UUID jenis manajer nihil dan dengan EPV manajer default yang dihasilkan MIDL. Panggilan ini menambahkan entri dalam tabel registri antarmuka. Antarmuka UUID terkandung dalam parameter IfSpec .
Secara default, tabel registri objek mengaitkan semua UUID objek dengan UUID jenis nihil. Dalam contoh ini, server tidak memanggil RpcObjectSetType.
Pustaka run-time server menerima kode prosedur jarak jauh yang berisi antarmuka UUID tempat panggilan berada dan UUID objek dari handel pengikatan panggilan.
Lihat entri referensi fungsi berikut untuk diskusi tentang bagaimana UUID objek diatur ke dalam handel pengikatan:
Menggunakan antarmuka UUID dari panggilan prosedur jarak jauh, pustaka run-time server menemukan antarmuka UUID tersebut dalam tabel registri antarmuka.
Jika server tidak mendaftarkan antarmuka menggunakan RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2, maka panggilan prosedur jarak jauh kembali ke pemanggil dengan kode status RPC_S_UNKNOWN_IF.
Menggunakan UUID objek dari handel pengikatan, pustaka run-time server menemukan UUID objek tersebut dalam tabel registri objek. Dalam contoh ini, semua UUID objek memetakan ke jenis objek nihil.
Pustaka run-time server menemukan jenis manajer nihil dalam tabel registri antarmuka.
Menggabungkan antarmuka UUID dan jenis nihil dalam tabel registri antarmuka diselesaikan ke EPV default, yang berisi rutinitas manajer server yang akan dijalankan untuk antarmuka UUID yang ditemukan dalam panggilan prosedur jarak jauh.
Asumsikan bahwa server menawarkan beberapa antarmuka dan beberapa implementasi dari setiap antarmuka, seperti yang dijelaskan dalam tabel berikut.
Tabel Registri Antarmuka
| Antarmuka UUID | UUID jenis manajer | Vektor titik masuk |
|---|---|---|
| uuid1 | Nihil | epv1 |
| uuid1 | uuid3 | epv4 |
| uuid2 | uuid4 | epv2 |
| uuid2 | uuid7 | epv3 |
Tabel Registri Objek
| UUID Objek | Tipe objek |
|---|---|
| uuidA | uuid3 |
| uuidB | uuid7 |
| uuidC | uuid7 |
| uuidD | uuid3 |
| uuidE | uuid3 |
| uuidF | uuid8 |
| Nihil | Nihil |
| (UUID lainnya) | Nihil |
Memetakan Handel Pengikatan ke Vektor Titik Entri
| Antarmuka UUID (dari handel pengikatan klien) | UUID objek (dari handel pengikatan klien) | Jenis objek (dari tabel registri objek) | Manajer EPV (dari tabel registri antarmuka) |
|---|---|---|---|
| uuid1 | Nihil | Nihil | epv1 |
| uuid1 | uuidA | uuid3 | epv4 |
| uuid1 | uuidD | uuid3 | epv4 |
| uuid1 | uuidE | uuid3 | epv4 |
| uuid2 | uuidB | uuid7 | epv3 |
| uuid2 | uuidC | uuid7 | epv3 |
Langkah-langkah berikut menjelaskan tindakan yang dilakukan pustaka run-time server, seperti yang ditunjukkan pada tabel sebelumnya saat klien dengan antarmuka UUID uuid2 dan uuidC UUID objek memanggilnya.
Server memanggil RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 untuk mengaitkan antarmuka yang ditawarkannya dengan EPV manajer yang berbeda. Entri dalam tabel registri antarmuka mencerminkan empat panggilan RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 untuk menawarkan dua antarmuka, dengan dua implementasi (EPV) untuk setiap antarmuka.
Server memanggil RpcObjectSetType untuk membuat jenis setiap objek yang ditawarkannya. Selain asosiasi default objek nihil ke jenis nihil, semua UUID objek lainnya tidak secara eksplisit ditemukan dalam tabel registri objek juga memetakan ke UUID jenis nihil.
Dalam contoh ini, server memanggil rutinitas RpcObjectSetType enam kali.
Pustaka run-time server menerima panggilan prosedur jarak jauh yang berisi antarmuka UUID tempat panggilan berada dan UUID objek dari handel pengikatan panggilan.
Menggunakan antarmuka UUID dari panggilan prosedur jarak jauh, pustaka run-time server menemukan antarmuka UUID dalam tabel registri antarmuka.
Menggunakan UUID objek uuidC dari handel pengikatan, pustaka run-time server menemukan UUID objek dalam tabel registri objek dan menemukan bahwa ia memetakan untuk mengetik uuid7.
Untuk menemukan jenis manajer, pustaka run-time server menggabungkan antarmuka UUID, uuid2, dan jenis uuid7 dalam tabel registri antarmuka. Ini diselesaikan ke epv3, yang berisi rutinitas manajer server yang akan dijalankan untuk panggilan prosedur jarak jauh.
Rutinitas dalam epv2 tidak akan pernah dijalankan karena server belum memanggil rutinitas RpcObjectSetType untuk menambahkan objek apa pun dengan UUID jenis uuid4 ke tabel registri objek.
Panggilan prosedur jarak jauh dengan antarmuka UUID uuid2 dan uuidF UUID objek kembali ke pemanggil dengan kode status RPC_S_UNKNOWN_MGR_TYPE karena server tidak memanggil RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 untuk mendaftarkan antarmuka dengan jenis manajer uuid8.
Nilai yang Dikembalikan
Fungsi ini mengembalikan salah satu nilai berikut.
| Nilai | Makna |
|---|---|
| RPC_S_OK | Berhasil |
| RPC_S_TYPE_ALREADY_REGISTERED | Ketik UUID yang sudah terdaftar |
Menyediakan fungsi penyelidikan objek Anda sendiri
Pertimbangkan server yang mengelola ribuan objek dari berbagai jenis. Setiap kali server dimulai, aplikasi server harus memanggil fungsi RpcObjectSetType untuk setiap objek, meskipun klien mungkin hanya merujuk ke beberapa di antaranya (atau membutuhkan waktu lama untuk merujuknya). Ribuan objek ini kemungkinan berada di disk, jadi mengambil jenisnya akan memakan waktu. Selain itu, tabel internal yang memetakan UUID objek ke UUID jenis manajer pada dasarnya akan menduplikasi pemetaan yang dipertahankan dengan objek itu sendiri.
Untuk kenyamanan, set fungsi RPC mencakup fungsi RpcObjectSetInqFn. Dengan fungsi ini, Anda menyediakan fungsi penyelidikan objek Anda sendiri.
Sebagai contoh, Anda dapat menyediakan fungsi penyelidikan objek Anda sendiri saat memetakan objek 100–199 untuk mengetik nomor 1, 200–299 untuk mengetik nomor 2, dan seterusnya. Fungsi pertanyaan objek juga dapat diperluas ke sistem file terdistribusi, di mana aplikasi server tidak memiliki daftar semua file (UUID objek) yang tersedia, atau ketika UUID objek memberi nama file dalam sistem file dan Anda tidak ingin memuat semua pemetaan antara UUID objek dan UUID jenis.
Topik terkait
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk