Creating a Rule

To create a rule, you must create at least one Action object. You can also create an optional Condition object for the rule. When a message arrives that satisfies the Rule's condition, the actions are applied (rules without a condition apply to all messages). Once you have created the Action and Condition objects, you create a Rules object and bind it to a folder using a CDO Folder object. Once bound, the Rules object contains any rules for the folder as a collection of Rule objects. You then can create a new Rule object, and add it to the Rules collection. The steps of creating actions, conditions, and creating the new Rule object are listed in the following sections.

Creating an Action

To create an action, perform the following steps:

1. Create an instance of the Action COM class.
2. Assign a value to the IAction::ActionType property. These actions include:

3. Assign a value to the IAction::Arg property. The data type of the property varies to match the requirements of the ActionType property. For example, if the ActionType is ACTION_FORWARD, the Arg property is a VARIANT SAFEARRAY of BSTR values (VT_ARRAY|VT_BSTR in C++, or simply an Array of String in Visual Basic) containing one or more addresses.

Creating a Condition

Conditions range from simple requirements, such as messages marked with specific importance levels, to complex expressions, with multiple logical conditions. When creating complex conditions, it's probably best to work from the bottom up. Use the following guidelines when creating a condition:

When the condition depends on text in the message Subject or Body field

Use a ContentCondition object to create the condition. Perform the following steps:

1. Create an instance of the ContentCondition COM class. This object will represent the condition for the rule.
2. Create an instance of the PropVal COM class. This object will contain information about the property and values used when evaluating the rule.
3. Set the IPropVal::Tag property to the CDO CdoPR_BODY or CdoPR_SUBJECT tag. This holds the MAPI entry ID for these MAPI properties to which to check for a particular value.
4. Set the IPropVal::Value to the string to check for in the PR_BODY or PR_SUBJECT properties.
5. Set the IContentCondition::Value property to the IPropVal object reference (interface) on the PropVal object created in step 2.
6. Set the IContentCondition::PropertyType property to the same CDO tag (CdoPR_BODY or CdoPR_SUBJECT for example) used when configuring the PropVal object in step 4.
7. Set the IContentCondition::Operator property to the appropriate string operator. To search the string for a particular substring, you could set it to SUBSTRING.

When the condition depends upon the value of a message property

Use an instance of the PropertyCondition COM class for the condition. There are over 400 CDO property tags (that are used to access MAPI properties) to choose from. The following table lists many common tags.

To create such a condition, perform the following steps:

1. Create an instance of the PropVal COM class.
2. Set the IPropVal::Tag property to the appropriate CDO property tag.
3. Set the IPropVal::Value property to an appropriate value. This value should match the type as defined by the MAPI property specified in the Tag property. For example, if the Tag is set to CdoPR_MESSAGE_TO_ME, the Value should be a Boolean.
4. Create an instance of the PropertyCondition COM class.
5. Set the IPropertyCondition::Value property to the IPropVal object reference on the PropVal object created in step 1.
6. Set the IPropertyCondition::PropertyTag property to the same CDO tag used when configuring the PropVal object in step 3.
7. Set the IPropertyCondition::Operator property to the appropriate relational operator. For example, use REL_EQ to test for equality between the specified property and the specified value.

When the condition depends upon the comparison of two message properties.

Use an instance of the ComparePropsCondition COM class. Perform the following steps:

1. Create an instance of the ComparePropsCondition COM class.
2. Set the IComparePropsCondition::PropertyTag1 property to a CDO property tag. This will be the first tag to which to compare the other.
3. Set the IComparePropsCondition::PropertyTag2 property to another CDO property tag. This will be the second property to which to compare the other.
4. Set the IComparePropsCondition::Operator property to the appropriate relational operator. For example, to check if two properties are equal, use the value REL_EQ.

When the condition depends upon the presence or absence of one or more binary digits (bits) in a message property

Use an instance of the BitmaskCondition COM class. Perform the following steps:

1. Create an instance of the BitmaskCondition COM class.
2. Set the IBitmaskCondition::Value property to the value with which the property value is masked.
3. Set the IBitmaskCondition::PropertyTag to the CDO property tag for the property to mask.
4. Set the IBitmaskCondition::Operator property to the appropriate bit-mask operator, one of B_NEZ, or B_EQZ. With B_NEZ, the condition is true if the property value with the mask applied as a logical "AND" is not equal to zero. With B_EQZ, the condition is true if the masked value is zero.

When the condition depends upon the size of a message property

Use an instance of the SizeCondition COM class. Perform the following steps:

1. Create an instance of the SizeCondition COM class.
2. Set the ISizeCondition::PropertyTag property to the CDO property tag value for the MAPI property to check.
3. Set the ISizeCondition::Operator property to the appropriate relational operator. For example, REL_LE is used to check whether a property is less than a certain size.
4. Set the ISizeCondition::Size property to the value to which to compare the property specified with the PropertyTag property.

When the condition depends upon a particular address in the From, To, CC, or Bcc field, or the presence of an attachment

Use an instance of the SubCondition COM class. Perform the following steps:

1. Create an instance of the PropVal COM class.
2. Set the IPropVal::Tag property to the CDO property tag that identifies the MAPI property to check. For example, to check the sender's email address, set the Tag property to CdoPR_SENDER_EMAIL_ADDRESS.
3. Set the IPropVal::Value property to the address for which to check. This should be a recipient URL, such as LDAP://Server/cn=User,cn=Recipients,ou=OrgUnit,o=Org.
4. Create an instance of the PropertyCondition COM class.
5. Set the IPropertyCondition::Value property to the IPropVal object reference on the PropVal object create in step 1.
6. Set the IPropertyCondition::PropertyTag property to the same CDO tag used when configuring the PropVal object in step 2.
7. Set the IPropertyCondition::Operator property to either REL_EQ or REL_NE. REL_EQ tests for equality, and REL_NE tests for inequality.
8. Create an instance of the SubCondition COM class.
9. Set the ISubCondition::Condition property to the IPropertyCondition object reference on the SubCondition object created in step 4.
10. Set the ISubCondition::Operator property to either MSG_RECIP or MSG_ATTCH. MSG_RECIP checks for message recipients and MSG_ATTCH checks for message attachments.

When you want to check for the existence of properties

Use an instance of the ExistsCondition COM class. Perform the following steps:

1. Create an instance of the ExistsCondition COM class.
2. Set the IExistsCondition::PropertyTag property to a CDO tag that identifies the MAPI property to check for.

When you want to logically join two conditions

Use an instance of the LogicalCondition COM class. Perform the following steps:

1. Create the subordinate condition or conditions to join.
2. Create an instance of the LogicalCondition COM class.
3. Use the ILogicalCondition::Add method to add the condition objects to the logical condition.
4. Set the ILogicalCondition::Operator property to the appropriate logical operator, such as L_AND, L_OR, or L_NOT.

Creating the Rule

Once you have created the Action and Condition objects, you can proceed to create the Rule object. Perform the following steps:

1. Create an instance of the Rules COM class.
2. Bind the object to a particular CDO Folder object.
3. Create an instance of the Rule COM class.
4. Set the IRule::Condition property to the top-level condition object you have created.
5. Add references to your Action objects to the IRule::Actions collection. Use the IActions::Add method.
6. Add the reference to the Rule object to the Rules object using the IRules::Add method.

For an example of creating complete rules, see the examples in the Rule COM component and Rule COM class portions of the reference.