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 to 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.
See Also