Функция RpcServerRegisterIfEx (rpcdce.h)

Статья
03/15/2023

Функция RpcServerRegisterIfEx регистрирует интерфейс в библиотеке времени выполнения RPC.

Синтаксис

RPC_STATUS RpcServerRegisterIfEx(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  RPC_IF_CALLBACK_FN *IfCallback
);

Параметры

IfSpec

Структура, созданная ПО MIDL, указывающая интерфейс для регистрации.

MgrTypeUuid

Указатель на тип UUID для связи с параметром MgrEpv . Если указать значение параметра NULL (или nil UUID), ifSpec регистрируется с UUID типа nil.

MgrEpv

Вектор точки входа (EPV) подпрограмм диспетчера. Чтобы использовать EPV по умолчанию, сгенерированный MIDL, укажите значение NULL . Дополнительные сведения см. в разделе RPC_MGR_EPV.

Flags

Флаги. Список значений флагов см. в разделе Флаги регистрации интерфейса.

MaxCalls

Максимальное количество одновременных запросов на вызовы удаленных процедур, которые сервер может принимать в интерфейсе автоматического прослушивания. Параметры MaxCalls применимы только к интерфейсу автоматического прослушивания и игнорируются в интерфейсах, которые не поддерживают автоматическое прослушивание. Библиотека времени выполнения RPC делает все возможное, чтобы сервер не разрешал больше одновременных вызовов, чем количество вызовов, указанное в MaxCalls. Фактическое число может быть больше и может отличаться для каждой последовательности протокола.

Вызовы в других интерфейсах управляются значением параметра MaxCalls для всего процесса, указанного в вызове функции RpcServerListen .

Если количество одновременных вызовов не является проблемой, можно немного повысить производительность на стороне сервера, указав значение по умолчанию с помощью RPC_C_LISTEN_MAX_CALLS_DEFAULT. Это освобождает среду выполнения RPC от применения ненужных ограничений.

IfCallback

Функция обратного вызова безопасности или ЗНАЧЕНИЕ NULL для отсутствия обратного вызова. Каждый зарегистрированный интерфейс может иметь другую функцию обратного вызова. Дополнительные сведения см. в разделе Примечания.

Возвращаемое значение

Возвращает RPC_S_OK при успешном выполнении.

Примечание Список допустимых кодов ошибок см. в разделе Возвращаемые значения RPC.

Параметры и эффекты RpcServerRegisterIfEx подразделяют параметры RpcServerRegisterIf. Разница заключается в возможности зарегистрировать интерфейс автоматического прослушивания и указать функцию обратного вызова безопасности.

Код серверного приложения вызывает RpcServerRegisterIfEx для регистрации интерфейса. Чтобы зарегистрировать интерфейс, сервер предоставляет следующие сведения:

Спецификация интерфейса
Спецификация интерфейса — это структура данных, которую создает компилятор MIDL.
Тип диспетчера UUID и EPV диспетчера
Тип диспетчера UUID и EPV диспетчера определяют, какая подпрограмма диспетчера выполняется, когда сервер получает запрос на удаленный вызов процедуры от клиента. Для каждой реализации интерфейса, предлагаемого сервером, необходимо зарегистрировать отдельный EPV диспетчера.

Обратите внимание, что при указании типа UUID, отличного от nil, сервер также должен вызвать RpcObjectSetType для регистрации объектов этого типа, отличного от nil.

При указании флагов RPC_IF_AUTOLISTEN интерфейс помечается как интерфейс автоматического прослушивания. Время выполнения начинает прослушивать вызовы сразу после регистрации интерфейса и прекращает прослушивание при отмене регистрации интерфейса. Вызов RpcServerUnregisterIf для этого интерфейса будет ожидать завершения всех ожидающих вызовов в этом интерфейсе. Вызовы RpcServerListen и RpcMgmtStopServerListening не повлияют на интерфейс и не будут вызывать RpcServerUnregisterIf с IfSpec == NULL. Это позволяет библиотеке DLL регистрировать интерфейсы RPC или удалять их из реестра, не изменяя состояние RPC приложения main.

Указание функции обратного вызова безопасности позволяет серверным приложениям ограничивать доступ к своим интерфейсам для каждого клиента. Помните, что по умолчанию безопасность является необязательной; время выполнения сервера будет отправлять незащищенные вызовы, даже если сервер вызвал RpcServerRegisterAuthInfo. Если сервер хочет принимать только клиенты, прошедшие проверку подлинности, функция обратного вызова интерфейса должна вызвать функцию RpcBindingInqAuthClient или RpcGetAuthorizationContextForClient для получения уровня безопасности или попытаться олицетворять клиент с помощью RpcImpersonateClient. Он также может указать флаг RPC_IF_ALLOW_SECURE_ONLY в флагах интерфейса.

Когда серверное приложение указывает функцию обратного вызова безопасности для своих интерфейсов, время выполнения RPC автоматически отклоняет вызовы этого интерфейса без проверки подлинности. Кроме того, во время выполнения записываются интерфейсы, используемые каждым клиентом. Когда клиент отправляет RPC в интерфейс, который он не использовал во время текущего сеанса связи, библиотека времени выполнения RPC вызывает функцию обратного вызова безопасности интерфейса. Указание RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH флага предотвратит автоматическое отклонение клиентов без проверки подлинности.

Сигнатуру функции обратного вызова см. в разделе RPC_IF_CALLBACK_FN.

Функция обратного вызова должна возвращать RPC_S_OK, если клиенту разрешено вызывать методы в этом интерфейсе. Любой другой код возврата приведет к тому, что клиент получит RPC_S_ACCESS_DENIED исключения.

В некоторых случаях время выполнения RPC может вызывать функцию обратного вызова безопасности несколько раз для каждого клиента на интерфейс. Убедитесь, что функция обратного вызова может справиться с этой возможностью.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	rpcdce.h (включая Rpc.h)
Библиотека	Rpcrt4.lib
DLL	Rpcrt4.dll