IMAPITable::Restrict

Article
08/28/2006

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

Note This method is supported for contents tables only.

Syntax

HRESULT Restrict (
  LPSRestriction lpRestriction,
  ULONG ulFlags
);

Parameters

lpRestriction
[in] Reference to an SRestriction structure, which contains members that define the filter conditions; cannot be NULL.
ulFlags
[in] Ignored.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
Indicates success.
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

Restrict establishes a restriction, or filter, on a table. If there is a previous restriction, it is discarded and the new one is applied. Applying a restriction has no effect 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. The Restrict method in Windows Mobile Messaging requires the restriction type, specified by the rt member of SRestriction, to be RES_PROPERTY.

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 of whether a property is supported in a table, before attempting to impose the property restriction, combine the property restriction with an RES_EXIST restriction type to check for the existence of the property.

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

Requirements

Pocket PC: Pocket PC 2002 and later
Smartphone: Smartphone 2002 and later
OS Versions: Windows CE 3.0 and later
Header: mapidefs.h
Library: cemapi.lib