3.1.4.1.8 NspiQueryRows (Opnum 3)

  • Article

The NspiQueryRows method returns to the client a number of rows from a specified table. Although the protocol places no boundary or requirements on the minimum number of rows the server returns, implementations SHOULD return as many rows as possible to improve usability of the 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.2.10.

dwFlags: A DWORD [MS-DTYP] value that contains 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 that describes 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 server.

dwETableCount: A DWORD value that contains 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, as specified in section 3.1.4.4.2.

Count: A DWORD value that contains 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 that 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 whether 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 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 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.

  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:

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

    • 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 ([MS-OXOABK] section 2.2.2.3), PidTagObjectType ([MS-OXOABK] section 2.2.3.10), PidTagDisplayType ([MS-OXOABK] section 2.2.3.11), PidTagDisplayName ([MS-OXOABK] section 2.2.3.1) with the property type PtypString8, as specified in [MS-OXCDATA] section 2.11.1, PidTagPrimaryTelephoneNumber ([MS-OXOCNTC] section 2.2.1.4.5) with the property type PtypString8, PidTagDepartmentName ([MS-OXOABK] section 2.2.4.6) with the property type PtypString8, PidTagOfficeLocation ([MS-OXOABK] section 2.2.4.5) 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. The client MUST NOT specify the value 0 for the input parameter Count if the input parameter lpETable is not NULL.

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

  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 Delta field).

  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 NspiGetProps method, as specified in section 3.1.4.1.7, using the following parameters:

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

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

    • The NspiQueryRows input parameter pStat is used as the NspiGetProps parameter pStat The CurrentRec field is set to the Minimal Entry ID of the row being returned.

    • The list of proptags the server constructs as specified by constraint 6 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 return the value "Success" and place a PropertyRowSet_r with rows according to the input parameter "Count" in the output parameter ppRows, in which the property type fields of the property are all set to 0x0000000A (PtypErrorCode).

  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 NspiUpdateStat method with the following parameters:

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

    • The value 0 is used as NspiUpdateStat parameter Reserved.

    • The NspiQueryRows output parameter pStat (as modified by the prior constraints) is used as the NSPIUpdateStat parameter pStat. The number of rows returned in the NspiQueryRows output parameter ppRows is added to the Delta field.

    • The value NULL is used as the NspiUpdateStat parameter plDelta.

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