3.1.4.9 NspiSeekEntries (Opnum 4)

  • Article

The NspiSeekEntries method searches for and sets the logical position in a specific table to the first entry greater than or equal to a specified value. Optionally, it might also return information about rows in the table.

 long NspiSeekEntries(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD Reserved,
   [in, out] STAT* pStat,
   [in] PropertyValue_r* pTarget,
   [in, unique] PropertyTagArray_r* lpETable,
   [in, unique] PropertyTagArray_r* pPropTags,
   [out] PropertyRowSet_r** ppRows
 );

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: A pointer to a STAT block describing a logical position in a specific address book container. This parameter is used to both specify input parameters from the client and return values from the NSPI server.

pTarget: A PropertyValue_r value holding the value that is being sought.

lpETable: The value NULL or a PropertyTagArray_r value. It holds a list of Mids that comprises 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 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. If the input parameter lpETable is not NULL and does not contain an Explicit Table both containing a restriction of the table specified by the input parameter pStat and sorted as specified by the SortType field of the input parameter pStat, 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.

  3. If the input parameter Reserved contains any value other than 0, 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.

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

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

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

  7. If the input parameter lpETable is NULL, the server MUST use the table specified by the input parameter pStat when constructing the return parameter ppRows.

  8. If the input parameter lpETable contains an Explicit Table, the server MUST use that table when constructing the return parameter ppRows.

  9. If the server does not support the SortTypePhoneticDisplayName and the SortType field of the input parameter pStat has the value SortTypePhoneticDisplayName, the server MUST return the value GeneralFailure.

  10. If the SortType field in the input parameter pStat has any value other than SortTypeDisplayName or SortTypePhoneticDisplayName, the server MUST return the value GeneralFailure.

  11. If the SortType field in the input parameter pStat is SortTypeDisplayName and the property specified in the input parameter pTarget is anything other than PidTagDisplayName (with either the Property Type PtypString8 or PtypString), the server MUST return the value GeneralFailure.

  12. If the SortType field in the input parameter pStat is SortTypePhoneticDisplayName and the property specified in the input parameter pTarget is anything other than PidTagAddressBookPhoneticDisplayName (with either the Property Type PtypString8 or PtypString), the server MUST return the value GeneralFailure.

  13. The server MUST locate the first row in the specified table that has a value equal to or greater than the value specified in the input parameter pTarget. If no such row exists, the server MUST return the value NotFound.

  14. If a qualifying row was found, the server MUST update the position information in the parameter pStat.

    1. The server MUST set CurrentRec field of the parameter pStat to the MId of the qualifying row.

    2. If the server is using the table specified by the input parameter lpETable, the server MUST set the NumPos field of the parameter pStat to the accurate numeric position of the qualifying row in the table.

    3. If the server is using the table specified by the input parameter pStat, the server MUST set the NumPos field of the parameter pStat to the approximate numeric position of the qualifying row in the table.

    4. The TotalRecs field of the parameter pStat MUST be set to the accurate number of records in the table used.

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

  15. If the input parameter pPropTags is not NULL, the client is requesting the server to return an PropertyRowSet_r. Subject to the prior constraints, the server MUST construct an 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:

    1. The NspiSeekEntries parameter hRpc is used as the NspiQueryRows parameter hRpc.

    2. The value fEphID is used as the NspiQueryRows parameter dwFlag.

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

    4. If the NspiSeekEntries input parameter lpETable is NULL, the value 0 is used as the NspiQueryRows parameter dwETableCount, and the value NULL is used as the NspiQueryRows parameter lpETable.

    5. If the NspiSeekEntries input parameter lpETable is not NULL, the server constructs an explicit table from the table specified by lpETable by copying rows in order from lpETable to the new explicit table. The server begins copying from the row specified by the NumPos field of the pStat parameter (as modified by the prior constraints), and continues until all remaining rows are added to the new table. The number of rows in this new table is used as the NspiQueryRows parameter dwETableCount, and the new table is used as the NspiQueryRows lpETable parameter.

    6. The list of MIds in the input parameter lpETable starting with the qualifying row is used as the NspiQueryRows parameter lpETable. These MIds are expressed as a simple array of DWORD values rather than as a PropertyTagArray_r value. Note that the qualifying row is included in this list, and that the order of the MIds from the input parameter lpETable is preserved in this list.

    7. If the NspiSeekEntries input parameter lpETable is NULL, the server MUST choose a value for the NspiQueryRows parameter Count. The NSPI Protocol does not prescribe any particular algorithm. The server MUST use a value greater than 0.

    8. If the NspiSeekEntries input parameter lpETable is not NULL, the value used for the NspiQueryRows parameter dwETableCount is used for the NspiQueryRows parameter Count.

    9. The NspiSeekEntries parameter pPropTags is used as the NspiQueryRows parameter pPropTags.

      Note that the server MUST NOT modify the return value of the NspiSeekEntry output parameter pStat in any way in the process of constructing the output PropertyRowSet_r.

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