3.1.4.12 NspiCompareMIds (Opnum 10)

  • Article

The NspiCompareMIds method compares the position in an address book container of two objects identified by MId and returns the value of the comparison.

 long NspiCompareMIds(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD Reserved,
   [in] STAT* pStat,
   [in] DWORD MId1,
   [in] DWORD MId2,
   [out] long* plResult
 );

hRpc:  An RPC context handle as specified in section 2.3.9.

Reserved: A DWORD value reserved for future use. Ignored by the server.

pStat: pStat: A reference to a STAT block describing a logical position in a specific address book container.

MId1: A DWORD value containing a MId.

MId2: A DWORD value containing a MId.

plResult: A DWORD value. On return, it contains the result of the comparison.

Return Values: The server returns a long value specifying the return status of the method.

Exceptions Thrown

No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

Server Processing Rules

Upon receiving this message, the server MUST process the data from the message subject to the following constraints:

  1. If the CodePage field of the input parameter pStat contains the value CP_WINUNICODE, the server MUST return one of the return values documented in section 2.2.2.  No further constraints are applied to server processing of this method; in this case server behavior is undefined.  Note especially that there is no constraint on the data the server returns in any output parameter other than the return value, nor is there any constraint on how or if the server changes its state.

  2. The server MAY make additional validations as described in Security (section 5). If the server chooses to limit the visibility of data based on these validations, the server MUST proceed as if that data did not exist in the address book. See the product behavior note cited in section 5.1 for more information.

  3. If the server is unable to locate the address book container specified by the ContainerID field in the input parameter pStat, the server MUST return the return value InvalidBookmark.

  4. If the server returns any return value other than Success, the protocol does not constrain the value in the return parameter plResult.

  5. If the server is unable to locate the objects specified by the input parameters MId1 or MId2 in the table specified by the ContainerID field of the input parameter pStat, the server MUST return the return value GeneralFailure.

  6. If the position of the object specified by MId1 comes before the position of the object specified by MId2 in the table specified by the field ContainerID of the input parameter pStat, the server MUST return a value less than 0 in the output parameter plResult.

  7. If the position of the object specified by MId1 comes after the position of the object specified by MId2 in the table specified by the field ContainerID of the input parameter pStat, the server MUST return a value greater than 0 in the output parameter plResult.

  8. If the position of the object specified by MId1 is the same as the position of the object specified by MId2 in the table specified by the field ContainerID of the input parameter pStat (that is, they specify the same object), the server MUST return a value of 0 in the output parameter plResult.

  9. If no other return values have been specified by these constraints, the server MUST return the return value Success.