IMAPITable::Restrict (Compact 7)
3/12/2014
This method applies a filter to a table, reducing the row set to only those rows that match the specified criteria.
Note
This method is supported for contents tables only.
Syntax
HRESULT Restrict (
LPSRestriction lpRestriction,
ULONG ulFlags
);
Parameters
- lpRestriction
[in] Pointer to a reference to an SRestriction structure, which contains members that define the filter conditions. Cannot be NULL.
- ulFlags
[in] Ignored.
Return Value
The following table shows the possible return values.
| Term | Description |
|---|---|
S_OK |
The method succeeded. |
MAPI_E_BUSY |
Another operation is in progress that prevents the restriction operation from starting. Either the operation in progress must be allowed to complete or it must be stopped. |
MAPI_E_TOO_COMPLEX |
The table cannot perform the operation because the particular filter that the lpRestriction parameter points to is too complicated. |
E_FAIL |
The operation failed due to an unspecified error. |
E_INVALIDARG |
The operation failed because one or more of the arguments is not valid. |
E_OUTOFMEMORY |
The operation failed because it needs more memory resources. |
E_UNEXPECTED |
The operation failed due to an unexpected error. |
Remarks
The Restrict method establishes a restriction, or filter, on a table. If a previous restriction exists, this method discards it and applies the new restriction. When you apply a restriction, it has no effect on the underlying data of a table; the restriction simply alters the view by limiting the rows that the IMAPITable interface retrieves to rows containing data that satisfy the restriction.
You can apply several different types of restrictions, each of which is 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 Embedded Compact Messaging requires the restriction type, specified by the rt member of SRestriction, to be RES_PROPERTY, RES_AND, or RES_OR. RELOP_RE comparisons are not supported on RES_PROPERTY restrictions.
This method discards all bookmarks for a table and BOOKMARK_CURRENT, the current cursor position, is set to the beginning of the table.
Do not attempt to impose a property restriction on a property that is not in the table's column set. If you are unsure whether a property is supported in a table, combine the property restriction with an RES_EXIST restriction type to check for the existence of the property before you attempt to impose the property restriction.
Do not expect to receive a table result on a row that was filtered from a table due to a restriction.
Requirements
Header |
mapidefs.h |
Library |
cemapi.lib |