3.1.4.1.11 NspiResortRestriction (Opnum 6)

The NspiResortRestriction method applies a sort order to the objects in a restricted address book container.

 long NspiResortRestriction(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD Reserved,
   [in, out] STAT* pStat,
   [in] PropertyTagArray_r* pInMIds,
   [in, out] PropertyTagArray_r** ppOutMIds
 );

hRpc: An RPC context handle, as specified in section 2.2.10.

Reserved: A DWORD [MS-DTYP] value reserved for future use. Ignored by the server.

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

pInMIds: A PropertyTagArray_r value. It holds a list of Minimal Entry IDs that comprise a restricted address book container.

ppOutMIds: A PropertyTagArray_r value. The server MUST ignore this parameter in the request. On return, it holds a list of Minimal Entry IDs that comprise a restricted address book container.

Return Values: The server returns a long value that specifies 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 specified in section 2.2.1.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. If the SortType field of the input parameter pStat contains any value other than "SortTypeDisplayName" or "SortTypePhoneticDisplayName", the server MUST return one of the return values specified in section 2.2.1.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.

  3. If the server returns any return values other than "Success", the server MUST return a NULL for the output parameter ppOutMIds and MUST NOT modify the value of the parameter pStat

  4. The server MAY make additional validations as described in 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.

  5. If the SortType field in the input parameter pStat has any value other than SortTypeDisplayName, the server SHOULD<6> return the value "GeneralFailure".

  6. The server constructs an Explicit Table as follows:

    • The server locates all the objects specified in the Explicit Table specified by the input value pInMIds. The server MUST ignore any Minimal Entry IDs that do not specify an object.

    • For each such object located, a row is inserted into the constructed Explicit Table.

    • The server MUST sort the rows in the constructed explicit table by the property specified in the SortType field of the input parameter pStat.

  7. The server MUST return the constructed Explicit Table in the output parameter ppOutMIds.

  8. The server MUST update the output parameter pStat as follows:

    • The TotalRecs field is set to the number of objects in the constructed Explicit Table.

    • If the object specified by the CurrentRec field of the input parameter pStat is not in the constructed Explicit Table, the CurrentRec field of the output parameter pStat is set to the value MID_BEGINNING_OF_TABLE and the NumPos field of the output parameter pStat is set to the value 0.

    • The server MUST NOT modify any other fields of the output parameter pStat.

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