IMAPITable::SetCollapseState
The IMAPITable::SetCollapseState
method rebuilds the current expanded or collapsed state of a categorized table
using data that was saved by a prior call to the IMAPITable::GetCollapseState method.
Quick Info
See IMAPITable
: IUnknown.
HRESULT SetCollapseState(
|
ULONG ulFlags, |
|
|
ULONG cbCollapseState, |
|
|
LPBYTE pbCollapseState, |
|
|
BOOKMARK FAR * lpbkLocation |
|
|
) |
|
Parameters
ulFlags
Reserved;
must be zero.
cbCollapseState
[in] Count of
bytes in the structure pointed to by the pbCollapseState parameter.
pbCollapseState
[in] Pointer
to the structures containing the data needed to rebuild the table view.
lpbkLocation
[out] Pointer
to a bookmark identifying the row in the table at which the collapsed or
expanded state should be rebuilt. This bookmark and the instance key passed in
the lpbInstanceKey parameter in the call to IMAPITable::GetCollapseState identify the same row.
Return Values
S_OK
The state of
the categorized table was successfully rebuilt.
MAPI_E_BUSY
Another
operation is in progress that prevents the operation from starting. Either the
operation in progress should be allowed to complete or it should be stopped.
MAPI_E_UNABLE_TO_COMPLETE
The table
could not finish rebuilding the collapsed or expanded view.
Remarks
The IMAPITable::SetCollapseState
method reestablishes the expanded or collapsed state of the table view. SetCollapseState
and GetCollapseState work together as follows:
1. When the state of a categorized table is about
to change, IMAPITable::GetCollapseState is called to save all of the
data pertaining to the state prior to the change.
2. To restore the view of the table to its saved
state, SetCollapseState is called. The data saved by GetCollapseState
is passed to SetCollapseState. SetCollapseState is able to use
that data to restore the state.
3. SetCollapseState returns as an output
parameter a bookmark that identifies the same row as the instance key passed as
input to GetCollapseState.
For more
information about categorized tables, see Sorting and Categorization.
Notes to Implementers
You are
responsible for verifying that the sort order and restrictions are exactly the
same as they were at the time of the GetCollapseState call. If a change
has been made, ideally SetCollapseState should not be called because the
results can be unpredictable. This can happen if, for example, a client calls GetCollapseState
and then SortTable to change the sort key before calling SetCollapseState.
To be safe, check that the saved data is still valid before proceeding with the
restoration.
Notes to Callers
To call SetCollapseState,
you must have previously called GetCollapseState. The sort order
establishing the categories should be the same for both methods. If the sort
orders differ, the results of the SetCollapseState operation are
unpredictable.
See Also