| Platform SDK: MAPI |
There are many types of restrictions, some that focus on specific columns. All table implementations are expected to support restrictions on the columns in the current column set. However, to add value, table implementers can also support restrictions based on object properties that are not currently in the table view.
Some restrictions can be combined using a restriction that performs a logical AND, OR, or NOT operation. For example, most property restrictions must be joined with exist restrictions using AND restrictions. There are a few exceptions, such as when the property used in the property restriction is the PR_ANR property or when it is a required column in a table. A client building restrictions to limit its view should use exist restrictions with its property restrictions because MAPI does not specify how service providers should evaluate property restrictions when a property does not exist. It is reasonable and recommended that service providers fail the restriction, but there are no requirements.
A restriction is defined using the SRestriction data structure which contains a union of more specialized restriction structures and an indicator of the type of structure included in the union.
Each of the specialized restriction structures in the union represents a different type of restriction. The types of restrictions and their associated data structures are:
| Type of restriction | Associated data structure | Description |
|---|---|---|
| Compare property | SComparePropsRestriction | Compares two properties of the same type. |
| AND | SAndRestriction | Performs a logical AND operation on two or more restrictions. |
| OR | SOrRestriction | Performs a logical OR operation on two or more restrictions. |
| NOT | SNotRestriction | Performs a logical NOT operation on two or more restrictions. |
| Content | SContentRestriction | Locates specified data. |
| Property | SPropertyRestriction | Specifies a particular property value as criteria for matching. Can be used, for example, to search for a particular type of attachment. |
| Bitmask | SBitMaskRestriction | Applies a bitmask to a PT_LONG property, typically to determine if particular flags are set. |
| Size | SSizeRestriction | Tests the size of a property using standard relational operators. |
| Exist | SExistRestriction | Tests whether or not an object has a value for a property. |
| Subobject | SSubRestriction | Used for searching through subobjects, or objects that cannot be accessed with an entry identifier (recipients and attachments). Can be used, for example, to look for messages for a particular recipient. |
| Comment | SCommentRestriction | Associates an object with a set of named properties. |
Some restrictions use regular expressions, and MAPI supports a limited form of regular expression notation in the style that is used in the grep utility. For a discussion of MAPI's use of regular expressions, see Regular Expressions.
The comment restriction is used by clients that save restrictions on disk to keep application-specific information with the restriction. For example, a client saving the name of a named property used in a property restriction can do so with a comment restriction. Saving the name is not possible in a property restriction; the SPropertyRestriction data structure holds only the property tag. Comment restrictions are ignored by Restrict in that they have no effect on the rows returned by QueryRows after a Restrict call has been made.