IObjectExporter::ComplexPing

[idempotent] error_status_t ComplexPing
    (
    [in]  handle_t        hRpc,
    [in]  SETID          *pSetId,
    [in]  unsigned short  SequenceNum,
    [in]  unsigned short  SetPingPeriod,
    [in]  unsigned short  SetNumPingsToTimeout,
    [out] unsigned short *pReqSetPingPeriod,
    [out] unsigned short *pReqSetNumPingsToTimeout,
    [in]  unsigned short  cAddToSet,
    [in]  unsigned short  cDelFromSet,
    [in,  unique, size_is(cAddToSet)]   GUID AddToSet[],
    [in,  unique, size_is(cDelFromSet)] GUID DelFromSet[]
    );

Ping a ping set. Optionally, add and / or remove some OIDs from the set. Optionally, adjust the ping timing parameters associated with the set. After a set is defined, a SimplePing will mark the entire contents of the set as active. After a set is defined, SimplePing should be used to ping the set. ComplexPing need only be used to adjust the contents of the set (or the time-out).

Ping set IDs (SETIDs) are allocated unilaterally by a client Object Exporter. The client Object Exporter then communicates with the server Object Exporter to add (and later remove) OIDs from the ping set. Clients must ensure the SETIDs pinged at a given server are unique over all of that server's clients. Thus, the client must only use SETIDs that it knows not to be in use as SETIDs by other clients on that server. (In practice, clients allocate SETIDs as globally unique). A client may use as many sets as it likes, though using fewer sets is more efficient.

Each OID owned by a server Object Exporter may be placed in zero or more ping sets by the various clients of the OID. The client owner of each such set will set a ping period and a ping time-out count for the set, thus determining an overall time-out period for the set as the product of these two values. The time-out period is implicitly applied to each OID contained in the set and to future OIDs that might add be added to it. The server Object Exporter is responsible for ensuring that an OID that it owns does not expire until at least a period of time t has elapsed without that OID being pinged, where t is the maximum time-out period over all the sets which presently contain the given OID, or, if OID is not presently in any such sets but was previously, t is the time-out period for the last set from which OID was removed at the instant that that removal was done;15. otherwise, OID has never been in a set, and t is a default value (TBD).

Clients are responsible for pinging servers often enough to ensure that they do not expire given the possibility of network delays, lost packets, and so on. If a client only requires access to a given object for what it would consider less than a time-out period for the object (that is, it receives and release the object in that period of time), then unless it is certain it has not itself passed the object to another client it must be sure to nevertheless ping the object (a ComplexPing that both adds and removes the OID will suffice). This ensures that an object will not expire as it is passed through a chain of calls from one client to another.

An OID is said to be pinged when a set into which it was previously added and presently still resides is pinged with either a SimplePing or a ComplexPing, or when it is newly added to a set with ComplexPing. Note that these rules imply that a ComplexPing that removes an OID from a set still counts as a ping on that OID.

In addition to pinging the set SETID, this call sets the time-out period of the set as the product of a newly-specified ping period and a newly-specified "ping count to expiration;" these values take effect immediately. Ping periods are specified in tenths of a second, yielding a maximum allowable ping period of about 1 hr 50 min. Adjustment of the time-out period of the set is considered to happen before the addition of any new OIDs to the set, which is in turn considered to happen before the removal of any OIDs from the set. Thus, an OID that is added and removed in a single call no longer resides in the set, but is considered to have been pinged, and will have as its time-out at least the time-out period specified in that ComplexPing call.

On exit, the server may request that the client adjust the time-out period; that is, ask it to specify a different time-out period in subsequent calls to ComplexPing. This capability can be used to reduce traffic in busy servers or over slow links. The server indicates its desire through the values it returns through the variables pReqSetPingPeriod and pReqSetNumPingsToTimeOut. If the server seeks no change, it simply returns the corresponding values passed by the client; if it wishes a longer time-out period, it indicates larger values for one or both of these variables; if it wishes a smaller period, it indicates smaller values. When indicating a larger value, the server must start immediately acting on that larger value by adjusting the time-out period of the set. However, when indicating a smaller value, it must consider its request as purely advice to the client, and not take any action: if the client wishes to oblige, it will do so in a subsequent call to ComplexPing by specifying an appropriate time-out period.

Argument

Type

Description

hRpc	handle_t	An RPC binding handle used to make the request.
pSetId	SETID	The SETID being manipulated.
SequenceNum	USHORT	The sequence number allows the object exporter to detect duplicate packets. Since the call is idempotent, it is possible for duplicates to get executed and for calls to arrive out of order when one ping is delayed.
SetPingPeriod	USHORT	This parameter is going away.
SetNumPings ToTimeOut	USHORT	This parameter is going away.
pReqSetPing Period	USHORT*	This parameter is changing. The server uses pReqSetPingPeriod to request a new ping period. If the requested period is shorter then the current period, the server must continue to use the current period until the client calls back. When the client calls back the old requested period will only be used if the client specifies it as the new SetPingPeriod. If the requested period is longer then the current period, the server must immediately begin using the new period. However, if the client doesn't accept it, the next call will contain the old, shorter period.
pReqSetNum PingsToTimeOut	USHORT*	This parameter is changing. The server uses pReqSetNumPingsToTimeout to request a new number of pings. If the number of pings is less then the current number of pings, the server must continue to use the current number of pings until the client calls back. When the client calls back the old requested period will only be used if the client specifies it as the new SetNumPingsToTimeout. If the requested number of pings is larger then the current number of pings, the server must immediately begin using the new number of pings. However, if the client doesn't accept it, the next call will contain the old, smaller number of pings.
cAddToSet	USHORT	The size of the array AddToSet.
cDelFromSet	USHORT	The size of the array DelFromSet.
AddToSet	OID[]	The list of OIDs which are to be added to this set. Adding an OID to a set in which it already exists is permitted; such an action, as would be expected, is considered to ping the OID.
DelFromSet	OID[]	The list of OIDs which are to be removed from this set. Removal counts as a ping. An IPID removed from a set will expire after the number of ping periods has expired without any pings (not the number of ping periods -1). If an ID is added and removed from a set in the same ComplexPing, the ID is considered to have been deleted.

Return Value

Meaning

S_OK	Success. The set was pinged, and so forth.
RPC_E_INVALID _OBJECT	Indicates that some OID was not recognized. There is no recovery action for this error; it is informational only.
RPC_E_ACCESS _DENIED
RPC_E_OUT_OF _ORDER	Returned when a call is received with a sequence number which is less then the last sequence number executed successfully.
E_OUTOFMEMORY	There was not enough memory to service the call. The caller may retry adding OIDs to the set on the next ping.
E_UNEXPECTED	An unspecified error occurred. It is not known whether the ping or any of the other actions were done or not.
Security related errors	TBD