Edit

Making the Server Available on the Network

  • Article

Before a server application can accept remote procedure calls, it must be available on the network. To do this, the server indicates to the RPC Run time that it is willing to accept calls on one or more protocol sequences. Choosing the protocol sequences a server application supports is an important decision; different protocol sequences have very different capabilities. Servers that expect calls to be received locally should use ncalrpc. Servers that accept remote calls should use ncacn_ip_tcp. Servers should not verify that the protocol sequence on which they receive calls is the protocol sequence on which they expect to receive calls. See Be Wary of Other RPC Endpoints Running in the Same Process in Best RPC Programming Practices for more information.

The following example uses ncacn_ip_tcp.

Most server programs use all protocol sequences available on the network. To do this, they invoke the RpcServerUseProtseq function, as shown in the following code fragment:

RPC_STATUS status;
status = RpcServerUseAllProtseq(
    L"ncacn_ip_tcp",
    RPC_C_PROTSEQ_MAX_REQS_DEFAULT,    // Protseq dependent parameter
    NULL);                             // Always specify NULL here.

The first parameter to the RpcServerUseProtseq function is the protocol sequence. The second parameter is dependent on the protocol sequence. As illustrated in the code fragment, most server programs set this parameter to RPC_C_PROTSEQ_MAX_REQS_DEFAULT. This value sets the RPC library to use the default value. The third parameter is a security descriptor and should not be used in applications. For more information, see Security.

You can also use the RpcServerUseAllProtseqs, RpcServerUseProtseqEx, RpcServerUseProtseqEp, or RpcServerUseProtseqEpEx functions.

After a server application selects at least one protocol sequence, servers that use dynamic endpoints must create binding information for each protocol sequence it uses. The server stores the binding information in a binding vector that it can then export to the endpoint mapper service.

Use the RpcServerInqBindings function to obtain a binding vector for the server application, as shown in the following example:

RPC_STATUS status;
RPC_BINDING_VECTOR *rpcBindingVector;
 
status = RpcServerInqBindings(&rpcBindingVector);

The only parameter passed to the RpcServerInqBindings function is a pointer to a pointer to an RPC_BINDING_VECTOR structure. The RPC run-time library dynamically allocates an array of binding vectors and stores the address of the array in the parameter variable (in this case, rpcBindingVector). Each server application is responsible for freeing this binding vector using the RpcBindingVectorFree function once it has finished using it (for example, after it has passed it to the appropriate functions).