RpcServerListen

The RpcServerListen function tells the RPC run-time library to listen for remote procedure calls. This function will not affect auto-listen interfaces. See RpcServerRegisterIfEx for more details.

This function is supported by both server platforms — Windows NT and Windows 95.

#include <rpc.h>
RPC_STATUS RPC_ENTRY RpcServerListen( 
  unsigned int  MinimumCallThreads,   
  unsigned int  MaxCalls,             
  unsigned int  DontWait              
);
 

Parameters

MinimumCallThreads

Specifies the minimum number of call threads.

MaxCalls

Specifies the recommended maximum number of concurrent remote procedure calls the server can execute. To allow efficient performance, the RPC run-time libraries interpret the MaxCalls parameter as a suggested limit rather than as an absolute upper bound.

Use RPC_C_LISTEN_MAX_CALLS_DEFAULT to specify the default value.

DontWait

Specifies a flag controlling the return from RpcServerListen. A value of non-zero indicates that RpcServerListen should return immediately after completing function processing. A value of zero indicates that RpcServerListen should not return until RpcMgmtStopServerListening has been called and all remote calls have completed.

Remarks

Note  The Microsoft RPC implementation of RpcServerListen includes two new, additional parameters that do not appear in the DCE specification: DontWait and MinimumCallThreads.

A server calls the RpcServerListen routine when the server is ready to process remote procedure calls. RPC allows a server to simultaneously process multiple calls. The MaxCalls argument recommends the maximum number of concurrent remote procedure calls the server should execute.

The MaxCalls value should be equal to or greater than the largest MaxCalls value specified to the routines RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf, RpcServerUseAllProtseqs, and RpcServerUseAllProtseqsIf.

A server application is responsible for concurrency control between the server manager routines because each routine executes in a separate thread.

When the DontWait parameter has a value of zero, the RPC run-time library continues listening for remote procedure calls (that is, the routine does not return to the server application) until one of the following events occurs:

• One of the server application's manager routines calls the RpcMgmtStopServerListening routine.
• A client calls a remote procedure provided by the server that directs the server to call RpcMgmtStopServerListening.
• A client calls RpcMgmtStopServerListening with a binding handle to the server.

Once it receives a stop-listening request, the RPC run-time library stops accepting new remote procedure calls for all registered interfaces. Executing calls are allowed to complete, including callbacks.

After all calls complete, the RpcServerListen routine returns to the caller.

When the DontWait parameter has a non-zero value, RpcServerListen returns to the server immediately after processing all the instructions associated with the function. You can use the RpcMgmtWaitServerListen routine to perform the "wait" operation usually associated with RpcServerListen.

Return Values

QuickInfo

  Windows NT: Yes
  Windows CE: Unsupported.
  Header: Declared in rpcdce.h.
  Import Library: Link with rpcrt4.lib.

See Also

RpcMgmtStopServerListening, RpcMgmtWaitServerListen, RpcServerRegisterIf, RpcServerRegisterIfEx, RpcServerUseAllProtseqs, RpcServerUseAllProtseqsIf, RpcServerUseProtseq, RpcServerUseProtseqEp, RpcServerUseProtseqIf