RpcServerRegisterIf3 function (rpcdce.h)

Article
10/13/2021

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

Syntax

RPC_STATUS RpcServerRegisterIf3(
  [in]           RPC_IF_HANDLE      IfSpec,
  [in, optional] UUID               *MgrTypeUuid,
  [in, optional] RPC_MGR_EPV        *MgrEpv,
  [in]           unsigned int       Flags,
  [in]           unsigned int       MaxCalls,
  [in]           unsigned int       MaxRpcSize,
  [in, optional] RPC_IF_CALLBACK_FN *IfCallback,
  [in, optional] void               *SecurityDescriptor
);

Parameters

[in] IfSpec

MIDL-generated structure indicating the interface to register.

[in, optional] MgrTypeUuid

Pointer to a type UUID to associate with the MgrEpv parameter. Specifying a null parameter value (or a nil UUID) registers IfSpec with a nil-type UUID.

[in, optional] MgrEpv

Manager routines' entry-point vector (EPV). To use the MIDL-generated default EPV, specify a null value. For more information, please see RPC_MGR_EPV.

[in] Flags

Flags. For a list of flag values, see Interface Registration Flags.

[in] MaxCalls

Maximum number of concurrent remote procedure call requests the server can accept on an auto-listen interface. The MaxCalls parameter is only applicable on an auto-listen interface, and is ignored on interfaces that are not auto-listen. The RPC run-time library makes its best effort to ensure the server does not allow more concurrent call requests than the number of calls specified in MaxCalls. The actual number can be greater and can vary for each protocol sequence.

Calls on other interfaces are governed by the value of the process-wide MaxCalls parameter specified in the RpcServerListen function call.

If the number of concurrent calls is not a concern, you can achieve slightly better server-side performance by specifying the default value using RPC_C_LISTEN_MAX_CALLS_DEFAULT. Doing so relieves the RPC run-time environment from enforcing an unnecessary restriction.

[in] MaxRpcSize

Maximum size of incoming data blocks, in bytes. This parameter may be used to help prevent malicious denial-of-service attacks. If the data block of a remote procedure call is larger than MaxRpcSize, the RPC run-time library rejects the call and sends an RPC_S_ACCESS_DENIED error to the client. Specifying a value of (unsigned int) –1 for this parameter removes the limit on the size of incoming data blocks. This parameter has no effect on calls made over the ncalrpc protocol.

[in, optional] IfCallback

Security-callback function, or NULL for no callback. Each registered interface can have a different callback function. See the Remarks on RpcServerRegisterIf2.

[in, optional] SecurityDescriptor

Security descriptor for accessing the RPC interface. Each registered interface can have a different security descriptor.

Return value

Returns RPC_S_OK upon success.

Note For a list of valid error codes, see RPC Return Values.

Remarks

The parameters and effects of the RpcServerRegisterIf3 function extend those of the RpcServerRegisterIf2 function. The difference is the ability to specify a security descriptor for controlling access to the registered RPC interface.

If both SecurityDescriptor and IfCallbackFn are specified, the security descriptor in SecurityDescriptor will be checked first and the callback in IfCallbackFn will be called after the access check against the security descriptor passes.

When calling RpcServerRegisterIf3 with SecurityDescriptor set to NULL, or calling RpcServerRegisterIf, RpcServerRegisterIf2, or RpcServerRegisterIfEx to register an interface, a default security descriptor will be used. The default security descriptor will not allow access from any AppContainer process to the interface if the RPC server is not an AppContainer process. The default security descriptor will not allow access from any process in other AppContainer processes to the interface if the RPC server is an AppContainer process. The default security descriptor will allow access from normal processes including Low integrity processes.

Requirements

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