RpcServerUseProtseqIfEx 函数 (rpcdce.h)

  • 项目

RpcServerUseProtseqIfEx 函数告知 RPC 运行时库将指定的协议序列与接口规范中的终结点结合使用，以接收远程过程调用。

语法

RPC_STATUS RpcServerUseProtseqIfEx(
  RPC_CSTR      Protseq,
  unsigned int  MaxCalls,
  RPC_IF_HANDLE IfSpec,
  void          *SecurityDescriptor,
  PRPC_POLICY   Policy
);

参数

Protseq

指向要注册到 RPC 运行时库的协议序列的字符串标识符的指针。

MaxCalls

ncacn_ip_tcp协议序列的积压工作队列长度。 所有其他协议序列都忽略此参数。 使用 RPC_C_PROTSEQ_MAX_REQS_DEFAULT 指定默认值。 请参阅“备注”。

IfSpec

接口包含终结点信息，用于为 Protseq 参数中指定的协议序列创建绑定。

SecurityDescriptor

指向为安全子系统提供的可选参数的指针。 仅用于 ncacn_np 和 ncalrpc 协议序列。 所有其他协议序列都忽略此参数。 不建议在终结点上使用安全描述符来确保服务器的安全。 此参数不显示在此 API 的 DCE 规范中。

Policy

指向 RPC_POLICY 结构的指针，该结构包含用于限制动态端口的端口分配的标志，并允许多宿主计算机选择性地绑定到网络接口卡。

返回值

值 含义
RPC_S_OK
 调用成功。
RPC_S_PROTSEQ_NOT_FOUND
 IDL 文件中未指定此协议序列的终结点。
RPC_S_PROTSEQ_NOT_SUPPORTED
 此主机上不支持协议序列。
RPC_S_INVALID_RPC_PROTSEQ
 协议序列无效。
RPC_S_INVALID_ENDPOINT_FORMAT
 终结点格式无效。
RPC_S_OUT_OF_MEMORY
 系统内存不足。
RPC_S_INVALID_SECURITY_DESC
 安全描述符无效。
 
注意 有关有效错误代码的列表，请参阅 RPC 返回值。
 

注解

RpcServerUseProtseqIfEx 的参数和效果扩展了 RpcServerUseProtseqIf 的参数和效果。 区别在于 Policy 参数，它允许限制动态端口的端口分配，并允许多宿主计算机选择性地绑定到网络接口卡。

将 RPC_POLICY 结构的 NICFlags 字段设置为 0 会使此扩展 API 在功能上等效于原始 RpcServerUseProtseqIf，服务器将根据系统注册表中的设置绑定到 NIC。 有关注册表设置如何定义可用的 Internet 和 Intranet 端口的信息，请参阅 为端口分配和选择性绑定配置注册表。

注意 “ 策略” 字段中的标志设置仅在 使用ncacn_ip_tcp 或 ncadg_ip_udp 协议序列时有效;对于所有其他协议序列，RPC 运行时会忽略这些值。
 
服务器应用程序调用 RpcServerUseProtseqIfEx 以向 RPC 运行时库注册一个协议序列。 对于每个协议序列注册，例程包括 IDL 文件中提供的终结点地址信息。

若要接收远程过程调用请求，服务器必须向 RPC 运行时库注册至少一个协议序列。 服务器应用程序可以多次调用此例程来注册其他协议序列。

对于服务器注册的每个协议序列，RPC 运行时库会创建一个或多个终结点，服务器通过这些终结点接收远程过程调用请求。 RPC 运行时库为每个协议序列创建不同的终结点。 但是，进程中的每个接口都可以通过任何终结点进行访问。 有关详细信息，请参阅编写安全 RPC 客户端或服务器。

对于 MaxCalls，应用程序提供的值只是一个提示。 RPC 运行时或 Windows 套接字提供程序可能会重写 值。 例如，在 Windows XP 或 Windows 2000 专业版上，该值限制为 5。 忽略大于 5 的值，改用 5。 在 Windows Server 2003 和 Windows 2000 Server 上，将遵循该值。

应用程序必须小心地在 MaxCalls 中传递合理的值。 服务器、高级服务器或数据中心服务器上的较大值可能会导致使用大量非分页池内存。 使用过小的值也是不利的，因为如果积压队列用尽，则可能会导致 TCP RST 从服务器满足 TCP SYN 数据包。 应用程序开发人员在确定 MaxCalls 的正确值时，应平衡内存占用量和可伸缩性要求。

将计算机配置为使用选择性绑定时，成功返回并不保证服务器已为计算机上存在的所有网络接口创建终结点。 RPC 运行时可能无法侦听某些网络接口，具体取决于选择性绑定设置。 此外，如果接口尚未收到使用 DHCP 的 IP 地址，则 RPC 服务器在分配 DHCP 地址之前不会侦听网络接口。 成功返回意味着服务器正在侦听至少一个网络接口;可以通过调用 RpcServerInqBindings 函数来获取可接收远程过程调用的绑定句柄的完整列表。

若要从 IDL 文件注册所有协议序列，服务器将调用 RpcServerUseAllProtseqsIfEx。 有关详细信息，请参阅 服务器端绑定。 有关 Microsoft RPC 支持的协议序列的列表，请参阅 字符串绑定。

要求

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

另请参阅

RpcServerUseAllProtseqsEx

RpcServerUseAllProtseqsIfEx

RpcServerUseProtseqEpEx

RpcServerUseProtseqEx

编写安全 RPC 客户端或服务器