3.1.4.1.10 NspiGetMatches (Opnum 5)

  • Article

The NspiGetMatches method returns an Explicit Table. The rows in the table are chosen based on two possible criteria: a restriction applied to an address book container or the values of a property on a single object that hold references to other objects.

 long NspiGetMatches(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD Reserved1,
   [in, out] STAT* pStat,
   [in, unique] PropertyTagArray_r* pReserved,
   [in] DWORD Reserved2,
   [in, unique] Restriction_r* Filter,
   [in, unique] PropertyName_r* lpPropName,
   [in] DWORD ulRequested,
   [out] PropertyTagArray_r** ppOutMIds,
   [in, unique] PropertyTagArray_r* pPropTags,
   [out] PropertyRowSet_r** ppRows
 );

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

Reserved1: A DWORD [MS-DTYP] value reserved for future use.

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

pReserved: A PropertyTagArray_r reserved for future use.

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

Filter: The value NULL or an Restriction_r value. Holds a logical restriction to apply to the rows in the address book container specified in the pStat parameter.

lpPropName: The value NULL or a PropertyName_r value. Holds the property to be opened as a restricted address book container.

ulRequested: A DWORD value. Contains the maximum number of rows to return in a restricted address book container.

ppOutMIds: A PropertyTagArray_r value. On return, it holds a list of Minimal Entry IDs that comprise a restricted address book container.

pPropTags: The value NULL or a reference to a PropertyTagArray_r value. Contains list of the proptags of the columns that client wants to be returned for each row returned.

ppRows: A reference to a PropertyRowSet_r value. Contains the address book container rows the server returns in response to the request.

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 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 input parameter Filter contains any value other than NULL and 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 input parameter Reserved1 contains any value other than 0, 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.

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

  5. 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.

  6. If the input SortType field of the input parameter pStat is SortTypeDisplayName or SortTypePhoneticDisplayName and 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".

  7. If the input parameter Filter is not NULL, the server constructs an Explicit Table as follows:

    • If the input parameter Filter is not NULL, it specifies a restriction, as specified in [MS-OXCDATA].

    • If the server will not support the call because the search is too complex, the server MUST return the value "TooComplex". The Exchange Server NSPI Protocol does not prescribe what constitutes a search that is too complex.

    • If the server will support the filter, it identifies the rows in the table specified in the input parameter pStat for which the filter is true. The Minimal IDs of these rows are inserted into the Explicit Table, maintaining their order from the originating table.

  8. If the input parameter Filter is NULL, the server constructs an Explicit Table as follows:

    • The Minimal Entry ID of the object the server is to read values from is specified in the CurrentRec field of the input parameter pStat. The server MUST ignore any values of the Delta and ContainerID fields while locating the object. That is, the server MUST NOT enforce any restrictions that the object specified by CurrentRec is actually in any particular address book container. Note that this is an exceptional use of the pStat parameter for position, not conforming to the semantic meaning of this field in all other NSPI methods.

    • If the input parameter lpPropName is not NULL, it specifies the property the server is to read the values of. If the input parameter lpPropName is NULL, the server is to read the values of the property specified as a proptag value in the ContainerID field of the input parameter pStat. Note, this is an exceptional use of this field, not conforming to the semantic meaning of this field in all other NSPI methods.

  9. The server locates the object specified by the client, subject to these restraints. If the server is unable to locate the object, the server MUST return the value "GeneralFailure".

  10. If the SortType field of the input parameter pStat has the value SortTypeDisplayName_W and the server does not support modifying the value of the property specified by the client on the object specified by the client, the server MUST return the value "NotSupported".

  11. If the server is unable to locate objects in the address book based on values of the property specified by the client on the object specified by the client, the server MUST return the value "NotSupported". Note that this constraint is intended to apply in the case where the server is categorically unable to locate specific objects based on the value of the property, not the case where the property has no values.

  12. The server reads the values of the property specified by the client. For each value read, the server tries to locate a specific object in the address book corresponding to this value. If a specific object is located, the Minimal ID of the object is inserted into the Explicit Table.

  13. The server MUST sort the rows in Explicit Table by the Unicode representation of the value of the PidTagDisplayName property, as specified in section 3.1.4.3).

  14. If the server returns "Success", the server MUST set the ContainerID field of the output parameter pStat to be equal to the CurrentRec field of the input parameter pStat. The server MUST NOT modify any other fields in this parameter.

  15. If the number of rows in the constructed Explicit Table is greater than the input parameter ulRequested, the server MUST return the value "TableTooBig".

  16. If the server will not support the call because the Explicit Table is larger than the server will allow, the server MUST return the value "TableTooBig". The Exchange Server NSPI Protocol does not prescribe what constitutes a table that is too large.

  17. If the input parameter proptags is not NULL, the client is requesting the server to return a PropertyRowSet_r. Subject to the prior constraints, the server MUST construct a PropertyRowSet_r to return to the client in the output parameter ppRows. This PropertyRowSet_r MUST be exactly the same PropertyRowSet_r that would be returned in the ppRows parameter of a call to the NspiQueryRows method with the following parameters:

    • The NspiGetMatches parameter hRpc is used as the NspiQueryRows parameter hRpc.

    • The value "fEphID" is used as the NspiQueryRows parameter dwFlags.

    • The NspiGetMatches output parameter pStat (as modified by the prior constraints) is used as the NspiQueryRows parameter pStat.

    • The number of Minimal Entry IDs in the constructed Explicit Table is used as the NspiQueryRows parameter dwETableCount.

    • The constructed Explicit Table is used as the NspiQueryRows parameter lpETable. These Minimal Entry IDs are expressed as a simple array of DWORD values rather than as a PropertyTagArray_r value.

    • The number of Minimal Entry IDs in the constructed Explicit Table is used as the NspiQueryRows parameter Count.

    • The NspiGetMatches parameter proptags is used as the NspiQueryRows parameter proptags.

      Note that the server MUST NOT modify the return value of the NspiGetMatches method output parameter pStat in any way in the process of constructing the output PropertyRowSet_r. The server MUST return the constructed PropertyRowSet_r in the output parameter ppRows.

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