RpcServerInterfaceGroupCreateW function (rpcdce.h)
The RpcServerInterfaceGroupCreate function creates an RPC server interface group for the server application. This interface group fully specifies the interfaces, endpoints, and idle properties of an RPC server application. Once created, an interface group can be activated and deactivated as the application requires.
Syntax
RPC_STATUS RpcServerInterfaceGroupCreateW(
[in] RPC_INTERFACE_TEMPLATEW *Interfaces,
[in] unsigned long NumIfs,
[in] RPC_ENDPOINT_TEMPLATEW *Endpoints,
[in] unsigned long NumEndpoints,
[in] unsigned long IdlePeriod,
[in] RPC_INTERFACE_GROUP_IDLE_CALLBACK_FN IdleCallbackFn,
[in] void *IdleCallbackContext,
[out] PRPC_INTERFACE_GROUP IfGroup
);
Parameters
[in] Interfaces
A pointer to an array of RPC_INTERFACE_TEMPLATE structures that define the interfaces exposed by the interface group.
[in] NumIfs
The number of elements in Interfaces.
[in] Endpoints
A pointer to an array of RPC_ENDPOINT_TEMPLATE structures that define the endpoints used by the interface group.
[in] NumEndpoints
The number of elements in Endpoints.
[in] IdlePeriod
The length of time in seconds after the interface group becomes idle that the RPC runtime should wait before invoking the idle callback. 0 means the callback is invoked immediately. INFINITE means the server application does not care about the interface group’s idle state.
[in] IdleCallbackFn
A RPC_INTERFACE_GROUP_IDLE_CALLBACK_FN callback that the RPC runtime will invoke once the interface group is idle for the length of time given in IdlePeriod. Can be NULL only if IdlePeriod is INFINITE.
[in] IdleCallbackContext
A user-defined pointer to be passed to the idle callback in IdleCallbackFn.
[out] IfGroup
If successful, a pointer to an RPC_INTERFACE_GROUP buffer that receives the handle to the newly created interface group. If this function fails, IfGroup is undefined.
Return value
| Value | Meaning |
|---|---|
|
The call succeeded. |
Remarks
A server application can optionally be notified when an interface group becomes idle. Though any application can take advantage of this functionality, it is targeted towards service developers who would like to enable their service to idle stop.
IdlePeriod prevents the RPC runtime from producing a large number of notifications if the idle state rapidly changes, and in the case of triggered services, helps the service avoid needlessly starting and stopping. Developers should consider the cost of service initialization and shutdown, the expected frequency with which new activity will occur, and the cost of keeping the service sitting idle when selecting this value. A low idle period will cause the service to frequently start and stop as new client activity takes place, whereas a high idle period will cause the service to consume resources without performing meaningful work.
Interfaces in an interface group can only be called over endpoints of the same group. Interfaces that are not part of an interface group cannot be called over endpoints that are part of a group.
RPC server activity is not always visible to the server application. In some cases, simply having a client with an open connection to the server may keep it active even if no calls have been dispatched for a long period of time. Server applications must not rely on any correlation between the RPC runtime declaring that the group is idle and the time since the last call was dispatched.
Note
The rpcdce.h header defines RpcServerInterfaceGroupCreate as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
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 |
See also
RpcServerInterfaceGroupActivate