RpcServerInterfaceGroupDeactivate function (rpcdce.h)

Article
10/13/2021

The RpcServerInterfaceGroupDeactivate function tells the RPC runtime to attempt to close the given interface group, optionally aborting the operation if there is outstanding client activity.

Syntax

RPC_STATUS RpcServerInterfaceGroupDeactivate(
  [in] RPC_INTERFACE_GROUP IfGroup,
  [in] unsigned long       ForceDeactivation
);

Parameters

[in] IfGroup

A RPC_INTERFACE_GROUP from RpcServerInterfaceGroupCreate that defines the interface group to deactivate

[in] ForceDeactivation

If TRUE, the RPC runtime should ignore client activity and unconditionally deactivate the interface group. If FALSE, the operation should be aborted if new activity takes place.

Return value

Value	Meaning
RPC_S_OK	The call succeeded.
RPC_S_SERVER_TOO_BUSY	ForceDeactivation is FALSE and there is outstanding client activity.

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

Remarks

RpcServerInterfaceGroupDeactivate is used by server applications to unregister the interfaces and endpoints in an interface group. It does the bulk of the shutdown work that RPC server applications need to do. It performs the following operations:

Unregisters the endpoints and interfaces from the RPC endpoint mapper.
Unregisters the endpoints from the server runtime.
Unregisters the interfaces from the server runtime.
Tells the runtime to stop listening for calls if no other interfaces are present.

If ForceDeactivation is FALSE, RpcServerInterfaceGroupDeactivate will only deactivate the interface group if there is no outstanding client activity. If new activity arrives during the deactivation process, RPC_S_SERVER_TOO_BUSY is returned. In this case, the operation is rolled back and the interface group will continue to receive and dispatch calls.

If ForceDeactivation is TRUE, RpcServerInterfaceGroupDeactivate does not fail.

Service applications can call RpcServerInterfaceGroupDeactivate with ForceDeactivation set to FALSE from their idle callback function RpcServerInterfaceGroupCreate. When used in conjunction with RPC service start triggers, this enables them to safely idle stop without missing calls from potential clients.

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