RpcServerRegisterIfEx  4.QB_QU

The RpcServerRegisterIfEx function registers an interface with the RPC run-time library.

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

#include <rpc.h>

RPC_STATUS RPC_ENTRY RpcServerRegisterIfEx(

Parameters

IfSpec

Specifies a MIDL-generated data structure indicating the interface to register.

MgrTypeUuid

Points to a type UUID to associate with the MgrEpv argument. Specifying a null argument value (or a nil UUID) registers IfSpec with a nil type UUID.

MgrEpv

Specifies the manager routines  entry-point vector (EPV). To use the MIDL-generated default EPV, specify a null value.

Flags

The following flags are defined:

MaxCalls

Specifies the maximum number of concurrent remote procedure call requests the server can accept. The RPC run-time library guarantees that the server can accept at least this number of concurrent call requests. The actual number can be greater and can vary for each protocol sequence. Use RPC_C_PROTSEQ_MAX_REQS_DEFAULT to specify the default value.

IfCallback

Specifies a security callback function, or NULL for no callback. Each registered interface can have a different callback function. See Remarks for more details.

Remarks

The parameters and effects of RpcServerRegisterIfEx subsume those of RpcServerRegisterIf. The difference is the ability to register an auto-listen interface and to specify a security callback function.

The server application code calls the RpcServerRegisterIfEx routine to register an interface. To register an interface, the server provides the following information:

    Interface specification.

The interface specification is a data structure that the MIDL compiler generates.

    Manager type UUID and manager EPV

The manager type UUID and the manager EPV determine which manager routine executes when a server receives a remote procedure call request from a client. For each implementation of an interface offered by a server, it must register a separate manager EPV.

Note that when specifying a non-nil manager type UUID, the server must also call the RpcObjectSetType routine to register objects of this non-nil type.

Specifying the RPC_IF_AUTOLISTEN flags marks the interface as an auto-listen interface. The runtime begins listening for calls as soon as the interface is registered, and stops listening when the interface is unregistered. A call to RpcServerUnregisterIf for this interface will wait for the completion of all pending calls on this interface. Calls to RpcServerListen and RpcServerStopServerListening will not affect the interface, nor will a call to RpcServerUnregisterIf with IfSpec == NULL. This allows a DLL to register and unregister RPC interfaces without changing the main application s RPC state.

Specifying a security callback function allows the server application to restrict access to its interfaces on a per-client basis. Remember that, by default, security is optional; the server runtime will dispatch unsecured calls even if the server has called RpcServerRegisterAuthInfo. If the server wants to accept only authenticated clients, each server stub must call RpcServerInqAuthClient to retrieve the security level, or attempt to impersonate the client with RpcImpersonateClient.

When a server app specifies a security callback function for its interface(s), the RPC runtime automatically rejects unauthenticated calls to that interface. In addition, the runtime records the interfaces that each client has used. When a client makes an RPC to a heretofore unused interface, the RPC runtime will call the interface s security callback function.

The signature for the callback function is as follows:

typedef RPC_STATUS

RPC_IF_CALLBACK_FN (

    IN RPC_IF_ID * Interface,

    IN void * Context

    ) ;

Interface contains the UUID and version of the interface in question.

Context is a server binding handle representing the client. The callback function may pass this handle to RpcImpersonateClient or RpcBindingServerToClient to gain information about the client.

The callback function should return RPC_S_OK if the client is allowed to call methods in this interface. Any other return code will cause the client to receive the exception RPC_S_ACCESS_DENIED.

In some cases the RPC runtime may call the security callback function more than once per client per interface. Be sure your callback function can handle this possibility.

See Also