The ComplexPing (Opnum 2) method is invoked to create or modify a ping set, to ping a ping set, or to perform a combination of these operations in one invocation.

 [idempotent] error_status_t ComplexPing(
   [in] handle_t hRpc,
   [in, out] SETID* pSetId,
   [in] unsigned short SequenceNum,
   [in] unsigned short cAddToSet,
   [in] unsigned short cDelFromSet,
   [in, unique, size_is(cAddToSet)] 
     OID AddToSet[],
   [in, unique, size_is(cDelFromSet)] 
     OID DelFromSet[],
   [out] unsigned short* pPingBackoffFactor
 );

hRpc: This MUST specify an RPC binding handle as specified in [MS-RPCE] section 3.2.2.3.1.

pSetId: This MUST specify the SETID of the ping set to ping. If the SETID specified by the client is zero, the object resolver MUST return the SETID of a new ping set containing the OIDs specified in AddToSet. If the SETID specified by the client is not zero, the object exporter MUST not change the SETID.

SequenceNum: This MUST specify a sequence number shared between the client and the object resolver.

cAddToSet: This MUST specify the number of OIDs in the AddToSet array.

cDelFromSet: This MUST specify the number of OIDs in the DelFromSet array.

AddToSet: This MUST specify an array of OIDs to add to the set.

DelFromSet: This MUST specify an array of OIDs to remove from the set.

pPingBackoffFactor: This MUST contain a hint to reduce ping load on the server. Servers MAY set the hint to an implementation-specific value. Clients MAY choose to treat this as zero always.<55>

When processing this call:

• The object resolver MAY compare the client's credentials against a set of implementation-specific permissions.<56> If the permissions do not allow access to the client credentials, the object resolver MUST return ERROR_ACCESS_DENIED (as specified in [MS-ERREF] section 2.2).

• If the client specifies a nonzero SETID, the object resolver MUST look up the SETID entry for the SETID. If the entry is not found, the object resolver MUST return OR_INVALID_SET (as specified in [MS-ERREF] section 2.2).

• If the entry is found, and if it has a sequence number greater than that specified by the client, the object resolver MUST take no further action and return success.

• Otherwise, the object resolver MUST do the following:

  • For each OID in the AddToSet list:

    • It MUST look up the OID in the OID list in the SETID entry.

    • If not found:

      • It MUST look up the OID entry in the OID table. If found:

        • It MUST increment the reference count in the OID entry.

        • It MUST add the OID to the OID list in the SETID entry.

      • If the OID entry is not found, it MUST return OR_INVALID_OID ([MS-ERREF] section 2.2).

  • For each OID in the DelFromSet list:

    • It MUST look up the OID in the OID list in the SETID entry.

    • If found:

      • It MUST look up the OID entry in the OID table. If found:

        • It MUST decrement the reference count in the OID entry.

      • If the OID entry is not found, it MUST proceed to the following step.

      • It MUST remove the OID from the OID list in the SETID entry.

  • It MUST reset the ping timer in the SETID entry.

  • It MUST set the sequence number to the value specified by the client.

• If the client specifies a NULL SETID, it MUST add a new SETID entry as follows:

  • It MUST allocate a SETID.

  • It MUST set the sequence number to the value specified by the client.

  • For each OID in the AddToSet list, it MUST do the following:

    • It MUST look up the OID entry. If the entry is found:

      • It MUST increment the reference count in the OID entry.

      • It MUST add the OID to the OID list in the SETID entry.

  • It MUST start the ping set timer. It MUST initialize the timer, as specified in section 3.1.2.2.

  • It MUST return the SETID to the client.