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

Статья
03/15/2023

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

Синтаксис

RPC_STATUS RpcServerRegisterIf2(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  unsigned int       MaxRpcSize,
  RPC_IF_CALLBACK_FN *IfCallbackFn
);

Параметры

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 от применения ненужных ограничений.

MaxRpcSize

Максимальный размер блоков входящих данных в байтах. Этот параметр можно использовать для предотвращения вредоносных атак типа "отказ в обслуживании". Если блок данных удаленного вызова процедуры больше MaxRpcSize, библиотека времени выполнения RPC отклоняет вызов и отправляет клиенту ошибку RPC_S_ACCESS_DENIED. При указании значения (unsigned int) –1 для этого параметра удаляется ограничение на размер входящих блоков данных. Этот параметр не влияет на вызовы, выполненные по протоколу ncalrpc .

IfCallbackFn

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

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

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

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

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

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

Спецификация интерфейса
Спецификация интерфейса — это структура данных, которую создает компилятор 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 или RpcServerInqCallAttributes для получения уровня безопасности или попытаться олицетворение клиента с помощью функции RpcImpersonateClient . Он также может указать флаг RPC_IF_ALLOW_SECURE_ONLY в флагах интерфейса для отклонения вызовов без проверки подлинности.

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

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

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

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

Требования

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