RpcServerListen function (rpcdce.h)
The RpcServerListen function signals the RPC run-time library to listen for remote procedure calls. This function will not affect auto-listen interfaces; use RpcServerRegisterIfEx if you need that functionality.
Syntax
RPC_STATUS RpcServerListen(
unsigned int MinimumCallThreads,
unsigned int MaxCalls,
unsigned int DontWait
);
Parameters
MinimumCallThreads
Hint to the RPC run time that specifies the minimum number of call threads that should be created and maintained in the given server. This value is only a hint and is interpreted differently in different versions of Windows. In Windows XP, this value is the number of previously created threads in each thread pool that the RPC run time creates. An application should specify one for this parameter, and defer thread creation decisions to the RPC run time.
MaxCalls
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
Flag controlling the return from RpcServerListen. A value of nonzero indicates that RpcServerListen should return immediately after completing function processing. A value of zero indicates that RpcServerListen should not return until the RpcMgmtStopServerListening function has been called and all remote calls have completed.
Return value
| Value | Meaning |
|---|---|
|
The call succeeded. |
|
The server is already listening. |
|
There are no protocol sequences registered. |
|
The maximum calls value is too small. |
Remarks
A server calls RpcServerListen when the server is ready to process remote procedure calls. RPC allows a server to simultaneously process multiple calls. The MaxCalls parameter recommends the maximum number of concurrent remote procedure calls the server should execute.
The MaxCalls value should not be zero, and should be larger than MinimumCallThreads. Values larger than 0x7FFFFFFF are set to 0x7FFFFFFF without notice.
Windows XP/2000: Setting the MaxCalls parameter to RPC_C_LISTEN_MAX_CALLS_DEFAULT removes the limit on concurrent remote procedure calls, rather than setting it to the constant-defined value of 1234. Removing the limit on maximum concurrent calls allows as many concurrent remote procedure calls as the computer can handle. This behavior enables increased efficiency in the RPC run time.
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 RpcMgmtStopServerListening.
- 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.
When the DontWait parameter has a nonzero value, RpcServerListen returns to the server immediately after processing all the instructions associated with the function. You can use the RpcMgmtWaitServerListen function to perform the wait operation usually associated with RpcServerListen.
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 |