Mendaftarkan Antarmuka
Bagian ini menyajikan diskusi terperinci tentang proses pendaftaran antarmuka RPC.
Informasi di bagian ini disajikan dalam topik berikut:
- Fungsi Pendaftaran Antarmuka
- Entry-Point Vektor
- Manajer EPV
- Mendaftarkan Implementasi Tunggal Antarmuka
- Mendaftarkan Beberapa Implementasi Antarmuka
- Aturan untuk Menjalankan Rutinitas Manajer
- Mengirimkan Panggilan Prosedur Jarak Jauh ke Rutin Server-Manager
- Menyediakan Fungsi Object-Inquiry Anda Sendiri
Fungsi Pendaftaran Antarmuka
Server mendaftarkan antarmuka mereka dengan memanggil fungsi RpcServerRegisterIf. Program server 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 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 Entry-Point Vektor.
Selain fungsi standar RpcServerRegisterIf, RPC juga mendukung fungsi pendaftaran antarmuka lainnya. FungsiRpcServerRegisterIf2 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 fungsiRpcServerRegisterIf, fungsi ini mendaftarkan antarmuka. Program server Anda juga dapat menggunakan fungsi ini untuk menentukan serangkaian 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 melalui panggilan ke fungsi RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2) dan tabel registri objek (diatur melalui panggilan ke fungsi RpcObjectSetType) untuk memetakan antarmuka dan UUID objek ke penunjuk fungsi.
Saat 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 masuk 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 EPV manajer default 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 diturunkan dari UUID objek melalui fungsi penyelidikan objek atau pemetaan yang didorong tabel yang dikontrol oleh RpcObjectSetType.
Manajer EPV
Pada pengaturan awal, kompilator MIDL menggunakan nama prosedur dari berkas IDL antarmuka untuk menghasilkan manajer EPV, dan menempatkannya langsung ke dalam rangka server. EPV default ini diinisialisasi secara statis 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 manajernull non- untuk antarmuka. Untuk memilih EPV yang disediakan aplikasi server, berikan alamat EPV yang nilainya telah dideklarasikan oleh server sebagai nilai MgrEpv parameter. Nilainull non- untuk MgrEpv parameter selalu mengambil alih 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 EPVnull non- 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 nil dengan menyediakan nilai null atau UUID nihil untuk MgrTypeUuid parameter. Dalam hal ini, semua panggilan prosedur jarak jauh, terlepas dari UUID objek dalam pengikatnya, dikirim ke EPV default, dengan asumsi tidak ada panggilan RpcObjectSetType yang telah dilakukan.
Anda juga dapat menyediakan UUID jenis manajer non-nil. 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 ke UUID tipe dan memanggil RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 untuk mengaitkan EPV pengelola dengan UUID tipe. Ketika panggilan prosedur jarak jauh tiba dengan UUID objeknya, perpustakaan waktu proses dari server RPC memetakan UUID objek ke UUID jenis. Aplikasi server kemudian menggunakan UUID jenis 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 menyediakan ifSpec yang sama parameter, tetapi sepasang MgrTypeUuid dan MgrEpv parameter.
Dalam kasus beberapa manajer, gunakan RpcServerRegisterIf, RpcServerRegisterIfEx atau RpcServerRegisterIf2 sebagai berikut:
Manajer EPV
Untuk menawarkan beberapa implementasi antarmuka, server harus:
- Buat EPV manajernull non- untuk setiap implementasi tambahan.
- Tentukan nilainull non- untuk MgrEpv parameter di RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2.
Perlu dicatat bahwa server dapat juga mendaftar dengan manajer default EPV.
UUID jenis manajer
Berikan UUID tipe manajer untuk setiap EPV pada antarmuka. UUID jenis nihil (atau nilai null) untuk MgrTypeUuid parameter dapat ditentukan untuk salah satu EPV manajer. Setiap jenis UUID harus berbeda.
Aturan untuk Memanggil Rutinitas Manajer
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 handle pengikatan panggilan.
Pustaka run-time menerapkan aturan berikut saat menginterpretasikan UUID objek dari panggilan prosedur jarak jauh:
UUID objek nihil
UUID objek kosong secara otomatis ditetapkan sebagai UUID tipe kosong (tidak sah menetapkan UUID objek kosong dalam rutin RpcObjectSetType). Oleh karena itu, panggilan prosedur jarak jauh yang handle pengikatnya berisi UUID objek kosong secara otomatis dikirim ke manajer yang terdaftar dengan UUID tipe kosong, jika ada.
UUID objek bukan kosong
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 RpcObjectSetType rutin untuk UUID objek non-nihil, panggilan prosedur jarak jauh untuk UUID objek tersebut masuk ke EPV manajer yang layanan prosedur jarak jauh memanggil dengan UUID objek nihil (yaitu, UUID jenis nihil).
Panggilan prosedur jarak jauh dengan UUID objek tidak-null dalam handle pengikatan tidak dapat dijalankan jika server menetapkan tipe UUID ke UUID objek tidak-null dengan memanggil fungsi RpcObjectSetType, tetapi juga tidak mendaftarkan pengelola EPV untuk tipe UUID 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 konfigurasi server untuk UUID objek? | Apakah server memiliki jenis EPV terdaftar? | Tindakan pengiriman |
|---|---|---|---|
| Nihil | Tidak berlaku | Ya | Menggunakan manajer dengan UUID tipe nil. |
| Nol | Tidak berlaku | Tidak | Kesalahan (RPC_S_UNSUPPORTED_TYPE); menolak panggilan prosedur jarak jauh. |
| Non-nihil | Ya | Ya | Menggunakan manajer dengan tipe UUID yang sama. |
| Non-nihil | Tidak | Diabaikan | Menggunakan manajer dengan UUID jenis null. Jika tidak ada manajer dengan UUID tipe nol, terjadi kesalahan (RPC_S_UNSUPPORTEDTYPE); menolak panggilan prosedur jarak jauh. |
| Non-nihil | Ya | Tidak | Kesalahan (RPC_S_UNSUPPORTEDTYPE); memblokir panggilan prosedur jarak jauh. |
UUID objek dari panggilan adalah UUID objek yang ditemukan dalam pegangan pengikatan untuk prosedur panggilan 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.
Nota
UUID objek null selalu secara otomatis diberikan tipe UUID null. Hal ini ilegal untuk menentukan UUID objek nihil dalam rutinitas RpcObjectSetType.
Mengirimkan Panggilan Prosedur Jarak Jauh ke Rutinitas Server-manager
Tabel berikut menunjukkan langkah-langkah yang diambil oleh perpustakaan run-time RPC untuk mendispatch panggilan prosedur jarak jauh ke rutin pengelola 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 | Kosong | Default EPV |
Tabel Registri Objek
| UUID Objek | Jenis objek |
|---|---|
| Kosong | Kosong |
| (UUID objek lainnya) | Nol |
Memetakan Handel Pengikatan ke Vektor Titik Masuk (EPV)
| Antarmuka UUID (dari handle pengikatan klien) | UUID objek (dari pegangan pengikatan klien) | Jenis objek (dari tabel registri objek) | Manajer EPV (dari tabel registri antarmuka) |
|---|---|---|---|
| uuid1 | Kosong | Kosong | Bawaan EPV |
| Sama seperti di atas | uuidA | Nol | Default EPV |
Langkah-langkah berikut menjelaskan tindakan yang diambil oleh pustaka runtime server RPC, seperti yang ditunjukkan dalam tabel sebelumnya, ketika seorang klien dengan antarmuka UUID uuid1 memanggilnya.
Server memanggil RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 untuk mengaitkan antarmuka yang ditawarkannya dengan UUID jenis manajer nil dan dengan EPV manajer default yang dihasilkan MIDL. Panggilan ini menambahkan entri dalam tabel registri antarmuka. Antarmuka UUID terkandung dalam IfSpec parameter.
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 UUID antarmuka yang terkait dengan panggilan dan UUID objek dari handle 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 handle pengikatan, pustaka run-time server menemukan UUID objek tersebut dalam tabel registri objek-objek. Dalam contoh ini, semua UUID objek memetakan ke tipe objek 'nil'.
Pustaka run-time server menemukan jenis manajer nil dalam tabel registri antarmuka.
Menggabungkan UUID antarmuka dan tipe null dalam tabel registri antarmuka akan ditetapkan ke EPV default, yang berisi rutinitas manajer server yang akan dijalankan untuk UUID antarmuka yang ditemukan dalam panggilan prosedur jarak jauh.
Asumsikan bahwa server menawarkan beberapa antarmuka dan beberapa implementasi setiap antarmuka, seperti yang dijelaskan dalam tabel berikut.
Tabel Registri Antarmuka
| Antarmuka UUID | UUID jenis manajer | Vektor titik masuk |
|---|---|---|
| uuid1 | Nol | epv1 |
| uuid1 | uuid3 | epv4 |
| uuid2 | uuid4 | epv2 |
| uuid2 | uuid7 | epv3 |
Tabel Registri Objek
| UUID Objek | Jenis objek |
|---|---|
| uuidA | uuid3 |
| uuidB | uuid7 |
| uuidC | uuid7 |
| uuidD | uuid3 |
| uuidE | uuid3 |
| uuidF | uuid8 |
| Nihil | Nol |
| (Sebuah UUID lainnya) | Nol |
Memetakan Pegangan Pengikatan ke Vektor Titik Masuk
| Antarmuka UUID (dari tangkai pengikatan klien) | UUID objek (dari handle pengikatan klien) | Jenis objek (dari tabel registri objek) | Manajer EPV (dari tabel registri antarmuka) |
|---|---|---|---|
| uuid1 | Tidak ada | Kosong | 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 oleh pustaka run-time server, seperti yang ditunjukkan dalam tabel sebelumnya ketika klien dengan UUID antarmuka uuid2 dan UUID objek uuidC 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 memanggilRpcObjectSetType untuk membuat jenis setiap objek yang ditawarkannya. Selain asosiasi bawaan objek kosong ke tipe kosong, semua UUID objek lainnya yang tidak secara eksplisit ditemukan dalam tabel registri objek juga dipetakan ke UUID tipe kosong.
Dalam contoh ini, server memanggil rutinitas RpcObjectSetType enam kali.
Perpustakaan run-time server menerima panggilan prosedur jarak jauh yang berisi UUID antarmuka yang dimiliki panggilan tersebut dan UUID objek dari handle 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 pada handle pengikatan, pustaka waktu run server menemukan UUID objek dalam tabel registri objek dan menemukan bahwa ia dipetakan ke tipe uuid7.
Untuk menentukan tipe manajer, pustaka run-time server menggabungkan UUID antarmuka, uuid2, dan tipe uuid7 dalam tabel registri antarmuka. Ini ditetapkan sebagai 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 RpcObjectSetType rutin untuk menambahkan objek apa pun dengan UUID jenis uuid4 ke tabel registri objek.
Panggilan prosedur jarak jauh dengan antarmuka UUID uuid2 dan UUID objek uuidF kembali ke pemanggil dengan kode status RPC_S_UNKNOWN_MGR_TYPE karena server tidak memanggil RpcServerRegisterIf, RpcServerRegisterIfEx, atau RpcServerRegisterIf2 untuk mendaftarkan antarmuka dengan tipe manajer uuid8.
Mengembalikan Nilai
Fungsi ini mengembalikan salah satu nilai berikut.
| Nilai | Arti |
|---|---|
| RPC_S_OK | Keberhasilan |
| Tipe RPC sudah terdaftar | 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 dari mereka (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 ketika Anda memetakan objek 100–199 ke tipe nomor 1, 200–299 ke tipe nomor 2, dan sebagainya. 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