3.1.4.8 NspiQueryRows (Opnum 3)

  • Article

The NspiQueryRows method returns to the client a number of rows from a specified table. The server MUST return no more rows than the number specified in the input parameter Count. Although the protocol places no further boundary or requirements on the minimum number of rows the server returns, implementations SHOULD return as many rows as possible subject to this maximum limit to improve usability of the NSPI server for clients.

 long NspiQueryRows(
   [in] NSPI_HANDLE hRpc,
   [in] DWORD dwFlags,
   [in, out] STAT* pStat,
   [in, range(0,100000)] DWORD dwETableCount,
   [in, unique, size_is(dwETableCount)] 
     DWORD* lpETable,
   [in] DWORD Count,
   [in, unique] PropertyTagArray_r* pPropTags,
   [out] PropertyRowSet_r** ppRows
 );

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

dwFlags:  A DWORD value, containing a set of bit flags. The server MUST ignore values other than the bit flags fEphID and fSkipObjects.

pStat: A pointer to a STAT block describing a logical position in a specific address book container. This parameter is used to specify both input parameters from the client and return values from the NSPI server.

dwETableCount: A DWORD value containing the number values in the input parameter lpETable. This value is limited to 100,000.

lpETable:  An array of DWORD values, representing an Explicit Table (see Explicit Tables (section 3.1.1.3.2)).

Count: A DWORD value containing the number of rows the client is requesting.

pPropTags: The value NULL or a reference to a PropertyTagArray_r value, containing a list of the proptags of the properties that client requires 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 NULL and the input parameter Count is 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.

  3. 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 output 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. See the product behavior note cited in section 5.1 for more information.

  5. If the input parameter lpETable is NULL 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.

  6. The server constructs a list of proptags for which it will return property values as follows:

    1. If the input parameter pPropTags is not NULL, the client is requesting the server return only those properties and their values in the output parameter ppRows. The server MUST use this list.

    2. If the input parameter pPropTags is NULL, the client is requesting that the server construct a list of proptags on its behalf. This server MUST use the following proptag list (using proptags defined in [MS-OXPROPS]), in this order:

       {PidTagAddressBookContainerId,
 PidTagObjectType,
 PidTagDisplayType,
 PidTagDisplayName with the Property Type PtypString8,
 PidTagPrimaryTelephoneNumber with the Property Type PtypString8,
 PidTagDepartmentName with the Property Type PtypString8,
 PidTagOfficeLocation with the Property Type PtypString8}

  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 is not NULL, it contains an Explicit Table. The server MUST use that table when constructing the return parameter ppRows.

  9. If there are any rows that satisfy the client's query, the server MUST return at least one row.

  10. The server MUST return as many rows as possible, up to the number value specified in the input parameter Count. The server MAY return fewer for any reason.

  11. The server MUST return rows in the order they exist in the table being used.

  12. If the server is using the table specified by the input parameter pStat, the server MUST process rows starting from the current position in the table specified in that parameter (including any values of the field Delta).

  13. If the server is using the table specified by the input parameter lpETable, the server MUST process rows starting from the beginning of the table.

  14. The server constructs a RowSet. Each row in the RowSet corresponds to a row in the table specified by input parameters. The rows in the RowSet are in a one-to-one order preserving correspondence with the rows in the table specified by input parameters. The Rows placed into the RowSet are exactly those Rows that would be returned to the client in the ppRows output parameter of the method NspiGetProps (see section 3.1.4.7) using the following parameters:

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

    2. The NspiQueryRows parameter dwFlags is used as the NspiGetProps parameter dwFlags.

    3. The NspiQueryRows parameter pStat is used as the NspiGetProps parameter pStat. The CurrentRec field is set to the Minimal Entry ID (MId) of the row being returned.

    4. The list of proptags the server constructs as specified by constraint 5 is used as the NspiGetProps parameter pPropTags.

      If a call to the NspiGetProps method with these parameters would return any value other than Success or ErrorsReturned, the server MUST return that error code as the return value for the NspiQueryRows method. Otherwise, the server MUST return the RowSet constructed in the output parameter ppRows.

  15. If the server has no rows that satisfy this query, the server MUST place an PropertyRpw_r Set with 0 rows in the output parameter ppRows. The server MUST return the return value Success.

  16. If the server is using the table specified by the input parameter pStat, the server MUST update the status of the table. This update MUST be exactly the same update that would occur via the method NspiUpdateStat with the following parameters:

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

    2. The value 0 is used as NspiUpdateStat parameter Reserved.

    3. The NspiQueryRows parameter pStat is used as the NspiGetProps parameter pStat. The number of rows returned in the NspiQueryRows output parameter ppRows is added to the Delta field.

    4. The value NULL is used as the NspiUpdateStat parameter lpDelta. The list of proptags the server constructs as specified by constraint 5 is used as the NspiGetProps parameter pPropTags.

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