Edit

Share via

RpcServerUseAllProtseqsEx function (rpcdce.h)

  • Article

The RpcServerUseAllProtseqsEx function tells the RPC run-time library to use all supported protocol sequences for receiving remote procedure calls.

Syntax

RPC_STATUS RpcServerUseAllProtseqsEx(
  unsigned int MaxCalls,
  void         *SecurityDescriptor,
  PRPC_POLICY  Policy
);

Parameters

MaxCalls

Backlog queue length for the ncacn_ip_tcp protocol sequence. All other protocol sequences ignore this parameter. Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value. See Remarks.

SecurityDescriptor

Pointer to an optional parameter provided for the security subsystem. Used only for ncacn_np and ncalrpc protocol sequences. All other protocol sequences ignore this parameter. Using a security descriptor on the endpoint in order to make a server secure is not recommended. This parameter does not appear in the DCE specification for this API.

Policy

Pointer to the RPC_POLICY structure, which allows you to override the default policies for dynamic port allocation and binding to network interface cards (NICs) on multihomed computers (computers with multiple network cards).

Return value

Value Meaning
RPC_S_OK
 The call succeeded.
RPC_S_NO_PROTSEQS
 There are no supported protocol sequences.
RPC_S_OUT_OF_MEMORY
 Sufficient memory is not available.
RPC_S_INVALID_SECURITY_DESC
 The security descriptor is invalid.
 
Note  For a list of valid error codes, see RPC Return Values.
 

Remarks

Note  Listening on all supported protocol sequences is not recommended, because it causes the server to listen on all protocol sequences, including non-mainstream protocol sequences. It is recommended that servers listen on mainstream protocol sequences only.
 
The parameters and effects of RpcServerUseAllProtseqsEx subsume those of RpcServerUseAllProtseqs. The difference is the Policy parameter, which allows you to restrict port allocation for dynamic ports and allows multihomed machines to selectively bind to specified NICs.

Setting the NICFlags field of the RPC_POLICY structure to zero makes this extended API functionally equivalent to the original RpcServerUseAllProtseqs, and the server will bind to NICs based on the settings in the system registry. For information on how the registry settings define the available Internet and intranet ports, see Configuring the Registry for Port Allocations and Selective Binding.

Note  The flag settings in the Policy field are effective only when the ncacn_ip_tcp or ncadg_ip_udp protocol sequence is in use. For all other protocol sequences, the RPC run-time ignores these values.
 
A server application calls RpcServerUseAllProtseqsEx to register all supported protocol sequences with the RPC run-time library. To receive remote procedure calls, a server must register at least one protocol sequence with the RPC run-time library.

For each protocol sequence registered by a server, the RPC run-time library creates one or more endpoints through which the server receives remote procedure call requests. The RPC run-time library creates different endpoints for each protocol sequence. The endpoint name is generated by the RPC run time or the operating system. For example, for ncacn_ip_tcp, the port number is dynamically determined by the RPC run time, depending on availability and registry settings.

Note  Using the RpcServerUseAllProtseqsEx function does not cause the server to listen on the following protocol sequences:
 
Note  To listen on any of those protocol sequences, each sequence must be selected individually.
 
For MaxCalls, the value provided by the application is only a hint. The RPC run time or the Windows Sockets provider may override the value. For example, on Windows XP or Windows 2000 Professional, the value is limited to 5. Values greater than 5 are ignored and 5 is used instead. On Windows Server 2003 and Windows 2000 Server, the value will be honored.

Applications must be careful to pass reasonable values in MaxCalls. Large values on Server, Advanced Server, or Datacenter Server can cause a large amount of non-paged pool memory to be used. Using too small a value is also unfavorable, as it may result in TCP SYN packets being met by TCP RST from the server if the backlog queue gets exhausted. An application developer should balance memory footprint versus scalability requirements when determining the proper value for MaxCalls.

When the computer is configured to use selective binding, successful return does not guarantee that the server has created endpoints for all the network interfaces present on the computer. The RPC run-time may not listen on some network interfaces depending on the selective binding settings. In addition, if an interface has not yet received an IP address using DHCP, the RPC server does not listen on the network interface until a DHCP address is assigned to it. A successful return implies that the server is listening on at least one network interface; the full list of the binding handles over which remote procedure calls can be received can be obtained with a call to the RpcServerInqBindings function.

To selectively register protocol sequences, a server calls RpcServerUseProtseqEx, RpcServerUseProtseqIfEx, or RpcServerUseProtseqEpEx. See Server-Side Binding for a description of the routines that a server will typically call after registering protocol sequences.

Requirements

Requirement Value
Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header rpcdce.h (include Rpc.h)
Library Rpcrt4.lib
DLL Rpcrt4.dll

See also

Configuring the Registry for Port Allocations and Selective Binding

RpcServerUseAllProtseqsIfEx

RpcServerUseProtseqEpEx

RpcServerUseProtseqEx

RpcServerUseProtseqIfEx