Rejestrowanie interfejsów

W tej sekcji przedstawiono szczegółową dyskusję na temat procesu rejestrowania interfejsu RPC.

Informacje w tej sekcji przedstawiono w następujących tematach:

• funkcje rejestracji interfejsu
• Entry-Point Wektory
• Manager EPVs
• zarejestrowanie pojedynczej implementacji interfejsu
• Rejestrowanie wielu implementacji interfejsu
• Zasady wywoływania rutyn menedżera
• wysyłanie zdalnego wywołania procedury do Server-Manager Program
• dostarczanie własnej funkcji Object-Inquiry

Funkcje rejestracji interfejsu

Serwery rejestrują swoje interfejsy, wywołując funkcję RpcServerRegisterIf. Złożone programy serwerowe często obsługują więcej niż jeden interfejs. Aplikacje serwera muszą wywoływać tę funkcję raz dla każdego obsługiwanego interfejsu.

Ponadto serwery mogą obsługiwać wiele wersji tego samego interfejsu, z których każda ma własną implementację funkcji interfejsu. Jeśli program serwera to robi, musi podać zestaw punktów wejścia. Punkt wejścia jest procedurą menedżera, która wysyła wywołania dla wersji interfejsu. Dla każdej wersji interfejsu musi istnieć jeden punkt wejścia. Grupa punktów wejścia jest nazywana wektorem punktu wejścia. Aby uzyskać szczegółowe informacje, zobacz Entry-Point Vectors.

Oprócz standardowej funkcji RpcServerRegisterIfrPC obsługuje również inne funkcje rejestracji interfejsu. Funkcja RpcServerRegisterIf2 rozszerza możliwości RpcServerRegisterIf, umożliwiając określenie zestawu flag rejestracji (zobacz flagi rejestracji interfejsu), maksymalna liczba współbieżnych żądań wywołań procedur zdalnych, które serwer może zaakceptować, oraz maksymalny rozmiar w bajtach przychodzących bloków danych.

Biblioteka RPC zawiera również funkcję o nazwie RpcServerRegisterIfEx. Podobnie jak funkcja RpcServerRegisterIf, ta funkcja rejestruje interfejs. Program serwera może również użyć tej funkcji, aby określić zestaw flag rejestracji (zobacz flagi rejestracji interfejsu), maksymalną liczbę równoczesnych żądań wywołania zdalnej procedury, które serwer może zaakceptować oraz funkcję zwrotną zabezpieczeń.

Funkcje RpcServerRegisterIf, RpcServerRegisterIfExi RpcServerRegisterIf2 ustawiają wartości w tabeli rejestru interfejsu wewnętrznego. Ta tabela służy do mapowania identyfikatorów UUID interfejsu i identyfikatorów UUID obiektów do menedżera protokołu EPV. Menedżer EPV to tablica wskaźników funkcji, która zawiera dokładnie jeden wskaźnik funkcji dla każdego prototypu funkcji w interfejsie określonym w pliku IDL.

Aby uzyskać informacje na temat dostarczania wielu EPV w celu udostępnienia wielu implementacji interfejsu, zobacz Implementacje wielu interfejsów.

Biblioteka uruchomieniowa używa tabeli rejestru interfejsu (ustawianej poprzez wywołanie funkcji RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2) i tabeli rejestru obiektów (ustawianej poprzez wywołanie funkcji RpcObjectSetType) do mapowania interfejsów i identyfikatorów UUID obiektu na wskaźnik funkcji.

Jeśli program serwera ma usunąć interfejs z rejestru bibliotek czasu wykonywania RPC, wywołaj funkcję RpcServerUnregisterIf. Po usunięciu interfejsu z rejestru biblioteka uruchomieniowa RPC nie będzie już akceptować nowych wywołań dla tego interfejsu.

Wektory punktu wejścia

Wektor wejścia menedżera (EPV) to tablica wskaźników funkcji wskazująca implementacje funkcji określonych w pliku IDL. Liczba elementów w tablicy odpowiada liczbie funkcji określonych w pliku IDL. RPC obsługuje wiele wektorów punktów wejścia reprezentujących wiele implementacji funkcji określonych w interfejsie.

Kompilator MIDL automatycznie generuje typ danych menedżera EPV do wykorzystania przy konstruowaniu menedżerów EPV. Typ danych ma nazwę if-name**_SERVER_EPV**, gdzie if-name określa identyfikator interfejsu w pliku IDL.

Kompilator MIDL automatycznie tworzy i inicjuje domyślny menedżer EPV przy założeniu, że procedura menedżera o tej samej nazwie istnieje dla każdej procedury w interfejsie i jest określona w pliku IDL.

Gdy serwer oferuje wiele implementacji tego samego interfejsu, serwer musi utworzyć jeden dodatkowy menedżer EPV dla każdej implementacji. Każdy protokół EPV musi zawierać dokładnie jeden punkt wejścia (adres funkcji) dla każdej procedury zdefiniowanej w pliku IDL. Aplikacja serwera deklaruje i inicjuje jedną zmienną EPV menedżera typu if-name**_SERVER_EPV** dla każdej dodatkowej implementacji interfejsu. Aby zarejestrować EPV, wywołuje RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2 raz dla każdego typu obiektu, który obsługuje.

Gdy klient wykonuje zdalne wywołanie procedury do serwera, protokół EPV zawierający wskaźnik funkcji jest wybierany na podstawie identyfikatora UUID interfejsu i typu obiektu. Typ obiektu pochodzi z identyfikatora UUID obiektu przez funkcję object-inquiry lub mapowanie oparte na tabeli kontrolowane przez RpcObjectSetType.

Menedżer EPV

Domyślnie kompilator MIDL używa nazw procedur z pliku IDL interfejsu do generowania EPV zarządzającego, który kompilator umieszcza bezpośrednio w szkielecie serwera. Ten domyślny protokół EPV jest statycznie inicjowany przy użyciu nazw procedur zadeklarowanych w definicji interfejsu.

Aby zarejestrować menedżera przy użyciu domyślnego protokołu EPV, określ null jako wartość parametru MgrEpv w wywołaniu funkcji RpcServerRegisterIf, RpcServerRegisterIfExlub funkcji RpcServerRegisterIf 2. Jeśli rutynowe nazwy używane przez menedżera odpowiadają definicjom interfejsu, możesz zarejestrować tego menedżera przy użyciu domyślnego protokołu EPV interfejsu wygenerowanego przez kompilator MIDL. Menedżer można również zarejestrować przy użyciu protokołu EPV, który dostarcza aplikacja serwera.

Serwer może (a czasami musi) utworzyć i zarejestrować nie-null menedżera protokołu EPV dla interfejsu. Aby wybrać EPV dostarczony przez aplikację serwera, przekaż adres EPV, którego wartość została zadeklarowana przez serwer jako wartość parametru MgrEpv. Wartośćinnej niż null dla MgrEpv parametr zawsze zastępuje domyślny protokół EPV w wycinku serwera.

Kompilator MIDL automatycznie generuje typ danych menedżera EPV (RPC_MGR_EPV) dla aplikacji serwera do wykorzystania przy konstruowaniu menedżerów EPV. Menedżer EPV musi zawierać dokładnie jeden punkt wejścia (adres funkcji) dla każdej procedury zdefiniowanej w pliku IDL.

W następujących przypadkach serwer musi podaćo wartości null protokołu EPV:

• Gdy nazwy procedur menedżera różnią się od nazw procedur zadeklarowanych w definicji interfejsu
• Gdy serwer używa domyślnego protokołu EPV do rejestrowania innej implementacji interfejsu

Serwer deklaruje menedżera protokołu EPV, inicjując zmienną typu if-name**_SERVER_EPV** dla każdej implementacji interfejsu.

Rejestrowanie pojedynczej implementacji interfejsu

Gdy serwer oferuje tylko jedną implementację interfejsu, serwer wywołuje RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2 tylko raz. W standardowym przypadku serwer używa domyślnego menedżera protokołu EPV. (Wyjątek występuje, gdy menedżer używa rutynowych nazw, które różnią się od tych zadeklarowanych w interfejsie).

W przypadku przypadku standardowego należy podać następujące wartości dla wywołań RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2:

• Menedżer EPV

  Aby użyć domyślnego protokołu EPV, określ wartość null dla parametru MgrEpv.

• UUID typu menedżera

  W przypadku korzystania z domyślnego EPV, zarejestruj interfejs z UUID menedżera typu nil, podając wartość null lub zerowy UUID dla parametru MgrTypeUuid. W takim przypadku wszystkie wywołania zdalnych procedur, niezależnie od identyfikatora UUID obiektu w ich uchwycie powiązania, są kierowane do domyślnego EPV, zakładając, że nie zostały wykonane żadne wywołania RpcObjectSetType.

  Można również podać identyfikator UUID typu menedżera innego niż nil. W takim przypadku należy również wywołać procedurę RpcObjectSetType.

Rejestrowanie wielu implementacji interfejsu

Można podać więcej niż jedną implementację procedur zdalnych określonych w pliku IDL. Aplikacja serwera wywołuje RpcObjectSetType, aby powiązać identyfikatory UUID obiektów z identyfikatorami UUID typu i wywołuje RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2, aby skojarzyć menedżerów EPV z typem UUID. Kiedy nadejdzie zdalne wywołanie procedury z identyfikatorem UUID obiektu, biblioteka uruchomieniowa serwera RPC mapuje identyfikator UUID obiektu na typ UUID. Następnie aplikacja serwera używa typu UUID i UUID interfejsu do wybrania menedżera EPV.

Możesz również określić swoją funkcję, aby rozwiązać mapowanie z UUID obiektu na UUID typu menedżera. Należy określić funkcję mapowania podczas wywoływania RpcObjectSetInqFn.

Aby zapewnić wiele implementacji interfejsu, serwer musi zarejestrować każdą implementację, wywołując RpcServerRegisterIf, RpcServerRegisterIfEx lub RpcServerRegisterIf2 oddzielnie. Dla każdej implementacji serwer rejestruje się, dostarczając ten sam parametr IfSpec, ale różne pary parametrów MgrTypeUuid i MgrEpv.

W przypadku wielu menedżerów użyj RpcServerRegisterIf, RpcServerRegisterIfEx lub RpcServerRegisterIf2 w następujący sposób:

• Menedżer EPV

  Aby zapewnić wiele implementacji interfejsu, serwer musi:

  • Utwórz protokół EPV o wartości innej niżnull menedżera dla każdej dodatkowej implementacji.
  • Określ wartość null inną niż dla MgrEpv parametru w RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2.

  Należy pamiętać, że serwer może również zarejestrować się w domyślnym menedżerze protokołu EPV.

• UUID typu menedżera

  Podaj identyfikator UUID typu menedżera dla każdego protokołu EPV interfejsu. UUID typu zerowego (lub wartość null) dla parametru MgrTypeUuid można określić dla jednego z EPV menedżera. Każdy typ UUID musi być inny.

Reguły wywoływania rutyn menedżera

Środowisko wykonawcze RPC kieruje przychodzące zdalne wywołanie procedury do menedżera, który oferuje żądany interfejs RPC. Po zarejestrowaniu wielu menedżerów dla interfejsu biblioteka czasu wykonywania RPC musi wybrać jedną z nich. Aby wybrać menedżera, biblioteka czasu wykonywania RPC używa identyfikatora UUID obiektu określonego przez uchwyt powiązania wywołania.

Biblioteka czasu wykonywania stosuje następujące reguły podczas interpretowania identyfikatora UUID obiektu wywołania procedury zdalnej:

• Identyfikatory UUID obiektu Nil

  Identyfikator UUID obiektu zerowego jest automatycznie przydzielany identyfikator UUID typu zerowego (niedozwolone jest określenie identyfikatora UUID obiektu zerowego w procedurze RpcObjectSetType). W związku z tym zdalne wywołanie procedury, którego uchwyt powiązania zawiera identyfikator UUID obiektu zerowego, jest automatycznie wysyłany do menedżera zarejestrowanego przy użyciu identyfikatora UUID typu nil, jeśli istnieje.

• Identyfikatory UUID obiektów niebędących nullem

  W zasadzie zdalne wywołanie procedury, którego uchwyt powiązania zawiera identyfikator UUID obiektu innego niż zero, powinno być przetwarzane przez menedżera, którego identyfikator UUID typu odpowiada typowi identyfikatora UUID obiektu. Jednak zidentyfikowanie prawidłowego menedżera wymaga, aby serwer określił typ UUID tego obiektu przez wywołanie procedury RpcObjectSetType.

  Jeśli serwer nie może wywołać RpcObjectSetType procedury dla identyfikatora UUID obiektu innego niż zero, zdalne wywołanie procedury dla tego obiektu UUID przechodzi do menedżera EPV, który obsługuje zdalne wywołania procedury z zerowym identyfikatorem UUID obiektu (czyli zerowym typem UUID).

  Wywołania procedur zdalnych z niepustym identyfikatorem UUID obiektu w uchwycie powiązania nie mogą być wykonane, jeśli serwer przypisał temu identyfikatorowi UUID obiektu niepustego typu UUID przez wywołanie procedury RpcObjectSetType, ale nie zarejestrował również menedżera EPV dla tego typu UUID, wywołując RpcServerRegisterIf, RpcServerRegisterIfEx lub RpcServerRegisterIf2.

Poniższa tabela zawiera podsumowanie działań stosowanych przez bibliotekę wykonawczą do wyboru procedury zarządcy.

Identyfikator UUID obiektu wywołania to identyfikator UUID obiektu znaleziony w dojściu powiązania dla zdalnego wywołania procedury.

Serwer ustawia typ UUID obiektu przez wywołanie RpcObjectSetType, aby określić typ UUID dla obiektu.

Serwer rejestruje typ dla menedżera EPV, wywołując RpcServerRegisterIf, RpcServerRegisterIfEx lub RpcServerRegisterIf2, używając tego samego typu UUID.

Wysyłanie zdalnego wywołania procedury do funkcji menedżera serwera

W poniższych tabelach przedstawiono kroki wykonywane przez bibliotekę czasu wykonywania RPC w celu przesłania zdalnego wywołania procedury do rutyny zarządzającej serwerem.

Prosty przypadek, w którym serwer rejestruje domyślny menedżer EPV, jest opisany w poniższych tabelach.

Tabela Rejestru Interfejsów

tabela rejestru obiektów

Mapowanie uchwytu powiązania do Wektora Punktu Wejścia (EPV)

W poniższych krokach opisano działania, które wykonuje biblioteka uruchomieniowa serwera RPC, jak pokazano na poprzednich tabelach, gdy klient z interfejsem UUID uuid1 nawiązuje połączenie.

1. Serwer wywołuje RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2, aby skojarzyć interfejs, który oferuje, z identyfikatorem UUID menedżera typu 'nil' oraz z domyślnym menedżerem EPV wygenerowanym przez MIDL. To wywołanie dodaje wpis w tabeli rejestru interfejsów. Identyfikator UUID interfejsu znajduje się w IfSpec parametru.

2. Domyślnie tabela rejestru obiektów kojarzy wszystkie identyfikatory UUID obiektów z identyfikatorem UUID typu nil. W tym przykładzie serwer nie wywołuje RpcObjectSetType.

3. Biblioteka środowiska wykonawczego serwera otrzymuje kod procedury zdalnej, który zawiera identyfikator UUID interfejsu przypisanego do wywołania oraz identyfikator UUID obiektu z uchwytu powiązania wywołania.

   Zapoznaj się z poniższymi wpisami referencyjnymi dla funkcji, aby dowiedzieć się, jak identyfikator UUID obiektu jest ustawiany w uchwycie wiązania.

   • RpcNsBindingImportBegin
   • RpcNsBindingLookupBegin
   • RpcBindingFromStringBinding
   • RpcBindingSetObject

4. Korzystając z identyfikatora UUID interfejsu z wywołania procedury zdalnej, biblioteka czasu wykonywania serwera lokalizuje ten identyfikator UUID interfejsu w tabeli rejestru interfejsu.

   Jeśli serwer nie zarejestrował interfejsu przy użyciu RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2, wywołanie procedury zdalnej powraca do obiektu wywołującego z kodem stanu RPC_S_UNKNOWN_IF.

5. Korzystając z identyfikatora UUID obiektu z uchwytu powiązania, biblioteka czasu wykonywania serwera lokalizuje ten identyfikator UUID obiektu w tabeli rejestru obiektów. W tym przykładzie wszystkie identyfikatory UUID obiektu są mapowane na typ obiektu nil.

6. Biblioteka czasu wykonywania serwera lokalizuje typ menedżera nil w tabeli rejestru interfejsów.

7. Połączenie identyfikatora UUID interfejsu i typu nil w tabeli rejestru interfejsu rozpoznawane jest jako domyślny EPV, zawierający procedury zarządzania serwerem, które mają być wykonane dla identyfikatora UUID interfejsu odnalezionego w zdalnym wywołaniu procedury.

Załóżmy, że serwer oferuje wiele interfejsów i wiele implementacji każdego interfejsu, zgodnie z opisem w poniższych tabelach.

Tabela rejestru interfejsu

Tabela rejestru obiektów

Mapowanie dojścia powiązania na wektor punktu wejścia

Poniższe kroki opisują działania podejmowane przez bibliotekę uruchomieniową serwera, jak pokazano w poprzednich tabelach, gdy klient z interfejsem UUID uuid2 i identyfikatorem UUID obiektu uuidC go wywołuje.

1. Serwer wywołuje RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2, aby powiązać interfejsy, które oferuje, z różnymi menedżerami EPV. Wpisy w tabeli rejestru interfejsów odzwierciedlają cztery wywołania RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2, które oferują dwa interfejsy, z dwiema implementacjami (EPV) dla każdego interfejsu.

2. Serwer wywołuje RpcObjectSetType w celu ustalenia typu każdego obiektu, który oferuje. Oprócz domyślnego skojarzenia obiektu nil z typem zerowym wszystkie inne identyfikatory UUID obiektu nie odnalezione jawnie w tabeli rejestru obiektów są również mapowane na identyfikator UUID typu zerowego.

   W tym przykładzie serwer wywołuje RpcObjectSetType procedury sześć razy.

3. Biblioteka uruchomieniowa serwera odbiera zdalne wywołanie procedury, które zawiera identyfikator UUID interfejsu, do którego należy wywołanie, oraz identyfikator UUID obiektu z uchwytu powiązania wywołania.

4. Korzystając z identyfikatora UUID interfejsu z wywołania procedury zdalnej, biblioteka uruchomieniowa serwera lokalizuje identyfikator UUID interfejsu w tabeli rejestru interfejsów.

5. Korzystając z identyfikatora UUID obiektu uuidC z uchwytu powiązania, biblioteka środowiska wykonawczego serwera lokalizuje identyfikator UUID obiektu w tabeli rejestru obiektów i znajduje, że jest powiązany z typem uuid7.

6. Aby zlokalizować typ menedżera, biblioteka środowiska uruchomieniowego serwera łączy interfejs UUID, uuid2oraz typ uuid7 w tabeli rejestru interfejsów. Spowoduje to rozwiązanie problemu epv3, który zawiera procedurę menedżera serwera, która ma być wykonywana dla zdalnego wywołania procedury.

Procedury w epv2 nigdy nie będą wykonywane, ponieważ serwer nie nazwał procedury RpcObjectSetType, aby dodać wszelkie obiekty o typie UUID uuid4 do tabeli rejestru obiektów.

Zdalne wywołanie procedury z interfejsem UUID uuid2 i UUID obiektu UUID uuidF zwraca do obiektu wywołującego z kodem stanu RPC_S_UNKNOWN_MGR_TYPE, ponieważ serwer nie wywołał RpcServerRegisterIf, RpcServerRegisterIfExlub RpcServerRegisterIf2, aby zarejestrować interfejs o typie menedżera uuid8.

Zwracane wartości

Ta funkcja zwraca jedną z następujących wartości.

Dostarczanie własnej funkcji zapytań dotyczących obiektów

Rozważ serwer, który zarządza tysiącami obiektów wielu różnych typów. Za każdym razem, gdy serwer został uruchomiony, aplikacja serwera musiałaby wywołać funkcję RpcObjectSetType dla każdego obiektu, mimo że klienci mogą odwoływać się tylko do kilku z nich (lub przez długi czas odwoływać się do nich). Te tysiące obiektów może znajdować się na dysku, więc pobieranie ich typów byłoby czasochłonne. Ponadto wewnętrzna tabela, która mapuje identyfikator UUID obiektu na identyfikator UUID typu menedżera, zasadniczo zduplikuje mapowanie utrzymywane z samymi obiektami.

Dla wygody zestaw funkcji RPC zawiera funkcję RpcObjectSetInqFn. Dzięki tej funkcji dostarczasz własną funkcję zapytania o obiekt.

Na przykład, możesz dostarczyć własną funkcję zapytania dotyczącą obiektów, mapując obiekty od 100 do 199 na typ numer 1, od 200 do 299 na typ numer 2 itd. Funkcja zapytania obiektu może być również rozszerzona na rozproszony system plików, gdzie aplikacja serwera nie ma listy wszystkich dostępnych plików (identyfikatorów UUID obiektów) lub gdy identyfikatory UUID obiektów nazywają pliki w systemie plików i nie chcemy wstępnie załadować wszystkich mapowań między identyfikatorami UUID obiektów a identyfikatorami UUID typów.

Tematy pokrewne

RpcBindingFromStringBinding

RpcBindingSetObject

RpcNsBindingExport

RpcNsBindingImportBegin

RpcNsBindingLookupBegin

RpcObjectSetType

RpcServerRegisterIf

RpcServerRegisterIf2

RpcServerRegisterIfEx

RpcServerUnregisterIf

RpcServerUnregisterIfEx