Contents Index Topic Contents
	Previous Topic: IABTable::QueryPosition Next Topic: IABTable::QuerySortOrder

IABTable::QueryRows

HRESULT QueryRows(
    LONG lRowCount,
    ULONG ulFlags,
    LPSRowSet FAR * lppRows
);

Gets rows of data from a table.

• Returns one of the following values:

  S_OK	The rows were successfully returned.
  MAPI_E_BUSY	Another operation is in progress that prevents the row retrieval operation from starting. Either the operation in progress should be allowed to complete, or it should be stopped.
  MAPI_E_INVALID_PARAMETER	The lRowCount parameter is set to zero.

lRowCount

Number of rows requested. If positive, rows are read starting at the current position and reading forward. If negative, the cursor position moves backward the indicated number of rows, then reads in forward order.

ulFlags

Flags specifying advancement of the cursor operation. TBL_NOADVANCE prevents the cursor from advancing. Default is that the cursor will advance past the last returned row.

lppRows

Returned SRowSet structure. This buffer must be freed by the caller according to the rules specified in the following comments.

The cRows member in the SRowSet structure returned in lppRows indicates the number of rows returned. If zero rows are returned, there are no more rows to return.

Freeing of the SRowSet structure returned by QueryRows is unusual in that each row must be freed independently; the rows are not allocated with AllocateMore. Memory used for the properties held in the SRow structures that make up the SRowSet in the lppRows parameter and for the rgPropVals members of the ADRENTRY structure is separately allocated for each row, and memory for each row must be separately freed by a call to MAPIFreeBuffer. The SRowSet structure itself must also be freed. Thus, to free all the memory returned for 10 rows requires 11 calls to FreeBuffer. This process might seem complex, but freeing memory for each row separately enables implementations to free different rows at different times. However, when a call to QueryRows returns zero, indicating the beginning or end of the table, only the SRowSet structure itself needs to be freed.

Back to top

---

 Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.