IMAPITable::ExpandRow

The IMAPITable::ExpandRow method expands a collapsed table category, adding the leaf rows belonging to the category to the table view.

Quick Info

See IMAPITable : IUnknown.

HRESULT ExpandRow(
  ULONG cbInstanceKey,   
  LPBYTE pbInstanceKey,  
  ULONG ulRowCount,      
  ULONG ulFlags,         
  LPSRowSet FAR * lppRows,   
  ULONG FAR * lpulMoreRows  
);

Parameters

cbInstanceKey: [in] Count of bytes in the PR_INSTANCE_KEY property pointed to by the pbInstanceKey parameter.
pbInstanceKey: [in] Pointer to the PR_INSTANCE_KEY property that identifies the heading row for the category.
ulRowCount: [in] Maximum number of leaf rows to add to the table view.
ulFlags: Reserved; must be zero.
lppRows: [out] Pointer to an SRowSet structure holding the leaf rows that have been inserted into the table view as a result of the expansion. These rows are inserted after the heading row identified by the pbInstanceKey parameter. The lppRows parameter can be NULL if the ulRowCount parameter is zero.
lpulMoreRows: [out] Pointer to the total number of rows that were added to the table view.

Return Values

S_OK: The category was expanded successfully.
MAPI_E_NOT_FOUND: The row identified by the pbInstanceKey parameter does not exist.

Remarks

The IMAPITable::ExpandRow method expands a collapsed table category, adding the leaf rows that belong to the category to the table view. A limit to the number of rows to be included in the expanded category can be specified in the ulRowCount parameter. When ulRowCount is set to a value greater than zero and one or more rows are returned in the row set pointed to by lppRows, the position of the bookmark BOOKMARK_CURRENT is moved to the row immediately following the last row in the row set.

When ulRowCount is set to zero, requesting that zero leaf rows be added to the category, or zero rows are returned because there are no leaf rows in the category, the position of BOOKMARK_CURRENT is set to the row following the row identified by pbInstanceKey.

Notes to Implementers

Do not generate notifications on rows that are added to a table view due to category expansion.

Notes to Callers

The number of rows in the row set pointed to by the lppRows parameter might not equal the number of rows that were actually added to the table, the entire set of leaf rows for the category. Errors can occur, such as insufficient memory, or the number of rows in the category exceeding the number specified in ulRowCount parameter. In either case, BOOKMARK_CURRENT will be positioned at the last row returned. To immediately retrieve the rest of the rows in the category, call IMAPITable::QueryRows.

Do not expect to receive a table notification when a category changes its state. You can maintain a local cache of rows that can be updated with every ExpandRow or CollapseRow call.

For more information about categorized tables, see Sorting and Categorization.