IMAPITable::ExpandRow

Article
06/01/2022

Applies to: Outlook 2013 | Outlook 2016

Expands a collapsed table category, adding the leaf or lower-level heading rows belonging to the category to the table view.

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

Parameters

cbInstanceKey

[in] The count of bytes in the PR_INSTANCE_KEY property pointed to by the pbInstanceKey parameter.

pbInstanceKey

[in] A pointer to the PR_INSTANCE_KEY (PidTagInstanceKey) property that identifies the heading row for the category.

ulRowCount

[in] The maximum number of rows to return in the lppRows parameter.

ulFlags

Reserved; must be zero.

lppRows

[out] A pointer to an SRowSet structure receiving the first (up to ulRowCount) 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] A pointer to the total number of rows that were added to the table view.

Return value

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 or lower-level heading rows that belong to the category to the table view. A limit to the number of rows to be returned in the lppRows parameter 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 or lower-level heading rows be added to the category, or zero rows are returned because there are no leaf or lower-level heading 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 or lower-level heading 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.

MFCMAPI reference

For MFCMAPI sample code, see the following table.

File	Function	Comment
ContentsTableListCtrl.cpp	CContentsTableListCtrl::DoExpandCollapse	MFCMAPI uses the IMAPITable::ExpandRow method to expand a collapsed table category.