IMAPITable::QueryRows

  • Article

4/8/2010

The QueryRows method returns one or more rows from a table, beginning at the current cursor position.

Syntax

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

Parameters

  • lRowCount
    [in] The number of rows you want; must be greater than zero (scrolling backward through a table is not supported). A maximum of 10 rows is returned per call.
  • ulFlags
    [in] Not used; must be zero.
  • lppRows
    [out] Reference to an SRowSet structure holding the table rows.

Return Value

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

  • S_OK
    Indicates success.
  • 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.

Remarks

The cRows member in the SRowSet structure pointed to by the lppRows parameter indicates the number of rows returned. If zero rows are returned, the cursor was already positioned at the end of the table.

The number of columns and their ordering are the same for each row. If a property does not exist for a row or there is an error reading a property, the SPropValue structure for the property in the row contains the following values:

  • PT_ERROR for the property type in the ulPropTag member.
  • MAPI_E_NOT_FOUND for the Value member.

Memory used for the SPropValue structures in the row set pointed to by the lppRows parameter must be separately allocated and freed for each row. Use FreeProws to free the property value structures and to free the row set. When a call to QueryRows returns zero, however, indicating the end of the table, only the SRowSet structure needs to be freed.

The rows that are returned and the order in which they are returned depend on whether or not successful calls have been made to IMAPITable::Restrict and IMAPITable::SortTable. Restrict filters rows from the view, causing QueryRows to return only the rows that match the criteria specified in the restriction. SortTable establishes a standardized or categorized sort order that affects the sequence of rows returned by QueryRows. The returned rows are in the order specified in the SSortOrderSet structure passed to SortTable.

The columns returned for each row and the order in which they are returned depend on whether or not a successful call has been made to IMAPITable::SetColumns. SetColumns establishes a column set, specifying the properties to be included in columns in the table and the order in which they should be included. If a SetColumns call has been made, the particular columns in each row and the order of those columns match the column set specified in the call. If no SetColumns call has been made, the table returns its default column set.

When the column set established in a call to SetColumns includes columns set to PR_NULL, the SPropValue array within the row set returned in lppRows contains empty slots.

If none of these calls has been made, QueryRows returns all of the requested rows in the table. Each row contains the default column set in default order.

Usually, you receive as many rows as you specified in the lRowCount parameter. However, when memory or implementation limits (10 rows maximum are returned) are an issue or when the operation reaches the end of the table prematurely, QueryRows returns fewer rows than requested.

If QueryRows returns MAPI_E_BUSY, retry the call to QueryRows when the asynchronous operation is complete.

When calling QueryRows, the timing of asynchronous notifications can potentially cause the row set that you get back from QueryRows not to accurately represent the underlying data. For example, a call to QueryRows to a folder's contents table following the deletion of a message but prior to the receipt of the corresponding notification causes the deleted row to be returned in the row set. Always wait for a notification to arrive before updating the user's view of the data.

Requirements

Header mapidefs.h
Library cemapi.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Pocket PC 2002 and later, Smartphone 2002 and later

See Also

Reference

ADRENTRY
FreeProws
IMAPIProp::GetProps
IMAPITable
IMAPITable::SetColumns
MAPIFreeBuffer
SRow
SRowSet

Other Resources

Messaging