SPropertyRestriction
Applies to: Outlook 2013 | Outlook 2016
Describes a property restriction that is used to match a constant with the value of a property.
| Property | Value |
|---|---|
| Header file: |
Mapidefs.h |
typedef struct _SPropertyRestriction
{
ULONG relop;
ULONG ulPropTag;
LPSPropValue lpProp;
} SPropertyRestriction;
Members
relop
Relational operator that will be used in the search. Possible values are as follows:
RELOP_GE: The comparison is made based on a greater or equal first value.
RELOP_GT: The comparison is made based on a greater first value.
RELOP_LE: The comparison is made based on a lesser or equal first value.
RELOP_LT: The comparison is made based on a lesser first value.
RELOP_NE: The comparison is made based on unequal values.
RELOP_RE: The comparison is made based on LIKE (regular expression) values.
RELOP_EQ: The comparison is made based on equal values.
ulPropTag
Property tag identifying the property to be compared.
lpProp
Pointer to an SPropValue structure that contains the constant value that will be used in the comparison.
Remarks
There are two property tags in an SPropertyRestriction structure. One is in the ulPropTag member and the other is in the ulPropTag member of the SPropValue structure pointed to by lpProp. MAPI requires both the property identifier field and the property type field. The ulPropTag in SPropertyRestriction is the property to be matched, and the lpProp pointer of the SPropertyRestriction to the ulPropTag's type of the SPropValue indicates how the members value of the lpProp union are interpreted. The two property types must match, or else the error value MAPI_E_TOO_COMPLEX is returned when the restriction is used in a call to IMAPITable::Restrict or IMAPITable::FindRow.
The comparison order is (property value) (relational operator) (constant value).
When a property restriction is passed to IMAPITable::Restrict or IMAPITable::FindRow and the target property does not exist, the results of the restriction are undefined. By creating an AND restriction that joins the property restriction with an EXIST restriction, a caller can be guaranteed accurate results. Use an SExistRestriction structure to define the EXIST restriction and an SAndRestriction structure to define the AND restriction.
In the specific case of Exchange Server 2019, comparisons that are performed on the server exhibit a behavior such that absent properties are treated as if they were present and had a value that is less than the minimum possible data type value. In other words, if a MAPI object which lacks e.g. a PR_SENSITIVITY property and which is being tested with a SPropertyRestriction{RELOP_LT, PR_SENSITIVITY, {PR_SENSITIVITY, 0, {.l = INT_MIN}} structure, the comparison yields "true". (This is consistent with the the "is undefined" specifiation above.)
Multi-valued property tags can be used in property restrictions if the service provider implementing the table supports them. If supported, multi-valued property tags can be used anywhere single-valued property tags can be used.
Multi-valued property tags can be used in the following methods:
Important
A notable case when the two property tags won't match is if restricting on a multi-value property. In this case the following must be true.
If the property type of the ulPropTag of SPropertyRestriction contains the multi-value property type bit flag MV_FLAG (0x1000), the property type of the ulPropTag of SPropValue should match the former minus the MV_FLAG bit flag, that is, its inverse. > For example, to restrict using a multi-value custom string property such as a category with a property tag for the property 0x8012101f, that is, PROP_TAG(MV_FLAG|PT_UNICODE, 0x8012)), the corresponding SPropertyRestriction would appear as follows.
SPropertyRestriction.ulPropTag = 0x8012101f; // attempt to restrict a MultiValue property
SPropertyRestriction.lpProp->ulPropTag = 0x8012001f; // the lpszW member of the Value property is valid> SPropertyRestriction.lpProp.Value->lpszW = L"My Category";> Note that if the property type of the ulPropTag of SPropValue contains the MV_FLAG bit flag, the likely return is MAPI_E_TOO_COMPLEX.
For more information about the SPropertyRestriction structure, see About Restrictions.