IMAPITable::Restrict

The IMAPITable::Restrict method applies a filter to a table, reducing the row set to only those rows matching the specified criteria.

Quick Info

See IMAPITable : IUnknown.

HRESULT Restrict(
  LPSRestriction lpRestriction,   
  ULONG ulFlags                   
);

Parameters

lpRestriction

[in] Pointer to an SRestriction structure defining the conditions of the filter. Passing NULL in the lpRestriction parameter removes the current filter.

ulFlags

[in] Bitmask of flags that controls the timing of the restriction operation. The following flags can be set:

TBL_ASYNC: Starts the operation asynchronously and returns before the operation completes.
TBL_BATCH: Defers evaluation of the filter until the data in the table is required.

Return Values

S_OK: The filter was successfully applied.
MAPI_E_BUSY: Another operation is in progress that prevents the restriction operation from starting. Either the operation in progress should be allowed to complete or it should be stopped.
MAPI_E_TOO_COMPLEX: The table cannot perform the operation because the particular filter pointed to by the lpRestriction parameter is too complicated.

Remarks

The IMAPITable::Restrict method establishes a restriction, or filter, on a table. If there is a previous restriction, it is discarded and the new one applied. Applying a restriction has no affect on the underlying data of a table; it simply alters the view by limiting the rows that can be retrieved to rows containing data that satisfy the restriction.

There are several different types of restrictions, each described with a different structure. The SRestriction structure contains two members: a value that indicates the type of restriction and the specific structure applicable for that type.

Notifications for table rows that are hidden from view by calls to Restrict are never generated.

A property restriction on a multivalued property works like a restriction on a single-valued property. A multivalued property to be used in a property restriction must have the MVI_FLAG flag set. If it doesn't have this flag set, it is treated as a totally ordered tuple. A comparison of two multivalued columns compares the column elements in order, reporting the relation of the columns at the first inequality. Equality is returned only if the columns compared contain the same values in the same order. If one column has fewer values than the other, the reported relation is that of a null value to the other value.

For more information about restrictions, see About Restrictions.

Notes to Callers

To discard the current restriction without creating a new one, pass NULL in lpRestriction.

If another asynchronous table call is in progress, causing Restrict to return MAPI_E_BUSY, you can call IMAPITable::Abort to stop the call.

Restrict operates synchronously unless you set one of the flags. If you set the TBL_BATCH flag, Restrict postpones the evaluation of the restriction unless you request the data. If the TBL_ASYNC flag is set, Restrict operates asynchronously, potentially returning before the completion of the operation.

All bookmarks for a table are discarded when a call to Restrict is made, and BOOKMARK_CURRENT, the current cursor position, is set to the beginning of the table.

If you attempt to impose a property restriction on a property that is not in the table's column set, the results are undefined. Whenever you are unsure as to whether a property is supported in a table, combine the property restriction with an exists restriction. The exists restriction checks for the existence of the property before attempting to impose the property restriction.

Do not expect to receive a table notification on a row that has been filtered from a table due to a restriction.