RPC_INTERFACE_TEMPLATEW 结构 (rpcdce.h)

  • 项目

RPC_INTERFACE_TEMPLATE 结构定义 RPC 接口组服务器接口。

语法

typedef struct {
  unsigned long      Version;
  RPC_IF_HANDLE      IfSpec;
  UUID               *MgrTypeUuid;
  RPC_MGR_EPV        *MgrEpv;
  unsigned int       Flags;
  unsigned int       MaxCalls;
  unsigned int       MaxRpcSize;
  RPC_IF_CALLBACK_FN *IfCallback;
  UUID_VECTOR        *UuidVector;
  RPC_WSTR           Annotation;
  void               *SecurityDescriptor;
} RPC_INTERFACE_TEMPLATEW, *PRPC_INTERFACE_TEMPLATEW;

成员

Version

此字段是保留的，必须设置为 0。

IfSpec

MIDL 生成的结构，用于定义要注册的接口。

MgrTypeUuid

指向要与 MgrEpv 关联的 UUID 的指针。 NULL 或 nil UUID 将 IfSpec 注册到 nil UUID。

MgrEpv

指向 RPC_MGR_EPV 结构的指针，该结构包含管理器例程的入口点向量 (EPV) 。 如果 为 NULL，则使用 MIDL 生成的默认 EPV。

Flags

标志。 有关标志值的列表，请参阅 接口注册标志。 接口组接口始终被视为 自动侦听。

MaxCalls

服务器可在此接口上接受的最大并发远程过程调用请求数。 RPC 运行时库将尽最大努力确保服务器不允许的并发调用请求数不超过 MaxCalls 中指定的调用数。 但是，实际数字可能大于 MaxCalls ，并且可能因每个协议序列而异。

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

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

MaxRpcSize

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

IfCallback

指向RPC_INTERFACE_GROUP_IDLE_CALLBACK_FN安全回调函数 的 指针，或 NULL 表示无回调。 每个已注册的接口可以具有不同的回调函数。

UuidVector

指向要注册到 RPC 终结点映射器的服务器提供的对象 UUID 矢量的指针。 服务器应用程序构造此向量。 NULL 表示没有要注册的对象 UUID 。

Annotation

指向应用于添加到本地终结点映射数据库的每个跨积元素的字符串注释的指针。 字符串长度最多为 64 个字符，包括 null 终止字符。 如果没有批注字符串，请指定 null 值或以 null 结尾的字符串 (“\0”) 。

注释字符串仅由应用程序用于信息。 RPC 不使用此字符串来确定客户端与哪个服务器实例通信，也不用于枚举终结点映射数据库中的元素。

SecurityDescriptor

描述哪些客户端有权访问接口的可选安全描述符。

注解

为了注册接口，服务器提供以下信息：

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

所有接口组接口都被视为 自动侦听。 一旦激活接口组，运行时就会开始侦听调用。 对 RpcServerListen 和 RpcMgmtStopServerListening 的调用不会影响接口，也不会对 IfSpec 设置为 NULL 的 RpcServerUnregisterIf 的调用。

在 IfCallback 中指定安全回调函数允许服务器应用程序基于单个客户端限制对其接口的访问。 也就是说，默认情况下，安全性是可选的;即使服务器调用了 RpcServerRegisterAuthInfo，服务器运行时也会调度不安全的调用。 如果服务器只想接受经过身份验证的客户端，接口回调函数必须调用 RpcBindingInqAuthClient、 RpcGetAuthorizationContextForClient 或 RpcServerInqCallAttributes 来检索安全级别，或尝试使用 RpcImpersonateClient 模拟客户端。 它还可以在 Flags 中指定RPC_IF_ALLOW_SECURE_ONLY标志来拒绝未经身份验证的调用。

当服务器应用程序在 IfCallback 中为其接口 () 指定安全回调函数时，RPC 运行时会自动拒绝对该接口没有身份验证信息的调用。 此外，运行时还会记录每个客户端使用的接口。 当客户端向在当前通信会话期间未使用的接口发出 RPC 时，RPC 运行时库会调用接口的安全回调函数。 在 Flags 中指定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。

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

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

注意

rpcdce.h 标头将RPC_INTERFACE_TEMPLATE定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 Windows 8 [仅限桌面应用]
最低受支持的服务器 Windows Server 2012 [仅限桌面应用]
标头 rpcdce.h (包括 Rpc.h)

另请参阅

RPC_INTERFACE_GROUP_IDLE_CALLBACK_FN

RpcServerInqBindings

RpcServerInterfaceGroupActivate

RpcServerInterfaceGroupClose

RpcServerInterfaceGroupCreate

RpcServerInterfaceGroupDeactivate