rpcServerRegisterIf2 函数 (rpcdce.h)

项目
08/25/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

指向要与 MgrEpv 参数关联的 UUID 类型的指针。指定 null 参数值 (或 nil UUID) 将 IfSpec 注册到 nil 类型 UUID。

MgrEpv

管理器例程的入口点矢量 (EPV) 。若要使用 MIDL 生成的默认 EPV，请指定 null 值。有关详细信息，请参阅 RPC_MGR_EPV。

Flags

标志。有关标志值的列表，请参阅接口注册标志。

MaxCalls

服务器可以在 自动侦听 接口上接受的最大并发远程过程调用请求数。 MaxCalls 参数仅适用于自动侦听接口，在非自动侦听接口上将被忽略。 RPC 运行时库将尽最大努力确保服务器不允许的并发调用请求数不超过 MaxCalls 中指定的调用数。实际数字可能更大，并且可能因每个协议序列而异。

其他接口上的调用受 RpcServerListen 函数调用中指定的进程范围 MaxCalls 参数的值控制。

如果不考虑并发调用数，则可以使用 RPC_C_LISTEN_MAX_CALLS_DEFAULT 指定默认值，从而略微提高服务器端性能。这样做可以缓解 RPC 运行时环境强制实施不必要的限制。

MaxRpcSize

传入数据块的最大大小（以字节为单位）。此参数可用于帮助防止恶意拒绝服务攻击。如果远程过程调用的数据块大于 MaxRpcSize，则 RPC 运行时库会拒绝该调用，并向客户端发送RPC_S_ACCESS_DENIED错误。为此参数指定 (无符号 int) –1 的值将删除传入数据块的大小限制。此参数对通过 ncalrpc 协议进行的调用没有影响。

IfCallbackFn

安全回调函数，或 NULL 表示无回调。每个已注册的接口可以具有不同的回调函数。请参阅“备注”。

返回值

成功后返回RPC_S_OK。

注意有关有效错误代码的列表，请参阅 RPC 返回值。

注解

RpcServerRegisterIf2 函数的参数和效果扩展了 RpcServerRegisterIf 函数的参数和效果。区别在于能够注册 自动侦听 接口和指定安全回调函数。

服务器应用程序代码调用 RpcServerRegisterIf2 来注册接口。为了注册接口，服务器提供以下信息：

接口规范
接口规范是 MIDL 编译器生成的数据结构。
管理器类型 UUID 和管理器 EPV
管理器类型 UUID 和管理器 EPV 确定服务器从客户端接收远程过程调用请求时执行哪个管理器例程。对于服务器提供的接口的每个实现，它必须注册单独的管理器 EPV。

请注意，指定非 nil 管理器类型 UUID 时，服务器还必须调用 RpcObjectSetType 来注册此非 nil 类型的对象。

指定RPC_IF_AUTOLISTEN标志会将接口标记为 自动侦听 接口。注册接口后，运行时将立即开始侦听调用，并在取消注册接口时停止侦听。对此接口调用 RpcServerUnregisterIf 将等待此接口上所有挂起的调用完成。调用 RpcServerListen 和 RpcMgmtStopServerListening 函数不会影响接口，也不会对 IfSpec 设置为 NULL 值的 RpcServerUnregisterIf 函数的调用。这允许 DLL 注册 RPC 接口或将其从注册表中删除，而无需更改main应用程序的 RPC 状态。

指定安全回调函数允许服务器应用程序基于单个客户端限制对其接口的访问。也就是说，默认情况下，安全性是可选的;即使服务器调用了 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仅在 Windows XP 和更高版本的 Windows 上拒绝 null 会话调用。

有关回调函数的签名，请参阅 RPC_IF_CALLBACK_FN。

如果允许客户端调用此接口中的方法，则回调函数应返回RPC_S_OK。任何其他返回代码都将导致客户端接收异常RPC_S_ACCESS_DENIED。

在某些情况下，RPC 运行时可能会对每个客户端、每个接口多次调用安全回调函数。请确保回调函数可以处理这种可能性。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	rpcdce.h (包括 Rpc.h)
Library	Rpcrt4.lib
DLL	Rpcrt4.dll