Export (0) Print
Expand All
Expand Minimize
This topic has not yet been rated - Rate this topic

RpcServerInterfaceGroupCreate function

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 RPC_ENTRY RpcServerInterfaceGroupCreate(
  _In_   RPC_INTERFACE_TEMPLATE *Interfaces,
  _In_   unsigned long NumIfs,
  _In_   RPC_ENDPOINT_TEMPLATE *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

Interfaces [in]

A pointer to an array of RPC_INTERFACE_TEMPLATE structures that define the interfaces exposed by the interface group.

NumIfs [in]

The number of elements in Interfaces.

Endpoints [in]

A pointer to an array of RPC_ENDPOINT_TEMPLATE structures that define the endpoints used by the interface group.

NumEndpoints [in]

The number of elements in Endpoints.

IdlePeriod [in]

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.

IdleCallbackFn [in]

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.

IdleCallbackContext [in]

A user-defined pointer to be passed to the idle callback in IdleCallbackFn.

IfGroup [out]

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

ValueMeaning
RPC_S_OK

The call succeeded.

 

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

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.

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Rpcdce.h (include Rpc.h)

Library

Rpcrt4.lib

DLL

Rpcrt4.dll

Unicode and ANSI names

RpcServerInterfaceGroupCreateW (Unicode) and RpcServerInterfaceGroupCreateA (ANSI)

See also

RpcServerInterfaceGroupActivate
RpcServerInterfaceGroupClose
RpcServerInterfaceGroupDeactivate
RpcServerInterfaceGroupInqBindings

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.