Rule CoClass

The Rule COM class defines an object with properties that you can use to manage Exchange folder rules.

CLSID

40E6B495-0976-11D2-BC0F-00C04F8C92F7

ProgID

MSExchange.Rule

Type Library

Microsoft Exchange 5.5 Rule Type Library 1.0 (MSExchangeRule.dll)

Threading Model

Single-threaded apartment (STA)

Interfaces

The Rule class exposes the IRule dual interface.

Remarks

Rules are actions to take when certain conditions are met by items in an Exchange Folder, commonly one's Inbox folder. Each rule is made up of a condition or set of conditions that must be met for the given rule to execute on the item; when those conditions are met, the action of the rule is executed on the item. Rules fire in a sequence: rule 1's condition is tested and if satisfied, its associated action is then executed; rule 2's condition is then tested and if satisfied, its associated action is executed, and so on.

Each Rule object represents a single rule to apply to an item. The object model follows the rule definition outlined previously; each Rule object contains a condition (or set of conditions) and an action to take when the conditions are met. The Condition objects implement interfaces derived from the ICondition interface. The Action object contains the action to execute when the conditions are met.

Creating Conditions

Creating Actions

When creating an Action object, you specify the type of action to perform and arguments that identify where or how the action is to be performed. For example, if the action is to forward a message to another person, the action is ACTION_TYPE.ACTION_FORWARD and the argument is that person's recipient address. The IAction::ActionTypeproperty specifies the type, and the IAction::Arg contains the arguments for the action. The arguments depend upon the type of action.

Once you have the Action object created and configured, you add it to the Rule objects IRule::Actions collection using the IActions::Add method.

Rule Index and Sequence

Rules are evaluated in the order of their IRule::Sequence property. Rules are stored in the Rules collection by their IRule::Index property. The value of the first rule's Index property is 1, and the value of each subsequent rule's Index property in the collection is one more than the previous. However, the value of the first rule's Sequence property is not necessarily 1, and the value of each subsequent rule's Sequence property in the collection is not necessarily one more than the previous rule. The most that can be said is that the relative ordering of index and sequence are always the same. The following equation defines this relationship

Index A < Index B < Index C <=> Sequence A < Sequence B < Sequence C

You can reorder the sequence in which the rules are executed by reordering the objects in the collection. However, because the Sequence property must be kept in the proper order, this reordering is a two-step process. You must do the following:

1. Set each Rule object's IRule::NewIndexproperty to the desired new ordinal index in the collection.
2. Call IRules::UpdateIndices to actually update the indices. When this method executes, the ordinal indexes are re-assigned, and additionally, the IRule::Sequence properties are re-assigned to reflect the new sequence. You cannot update the Sequence property manually.

The following example reverses the sequence in which a collection of rules is executed for a particular folder.

NumRules = myRules.Count

For Each myRule in myRules
  myRule.NewIndex = NumRules
  NumRules = NumRules -1
Next

myRules.UpdateIndices

Example

The following example deletes messages marked low importance sent to account TestUser on Microsoft Exchange server SERVER.

const ACTION_DELETE    =  3
const CdoPR_IMPORTANCE = &H00170003
const IMPORTANCE_LOW   = 0
const REL_EQ           = 7

Set mySession   = CreateObject("MAPI.Session")
mySession.Logon   "","",false,true,true,true,"SERVER" & vbLF & "TestUser"
Set myRules     = CreateObject("MSExchange.Rules")
myRules.Folder  = mySession.Inbox

Set importPropVal      = CreateObject("MSExchange.PropertyValue")
importPropVal.Tag      = CdoPR_IMPORTANCE
importPropVal.Value    = IMPORTANCE_LOW

Set importPropCond         = CreateObject("MSExchange.PropertyCondition")
importPropCond.Value       = importPropVal
importPropCond.PropertyTag = CdoPR_IMPORTANCE
importPropCond.Operator    = REL_EQ

Set myAction = CreateObject("MSExchange.Action")
myAction.ActionType = ACTION_DELETE

Set myRule         = CreateObject("MSExchange.Rule")
myRule.Name        = "RuleExample"
myRule.Actions.Add   , myAction
myRule.Condition   = importPropCond

myRules.Add , myRule

myRules.Update
mySession.Logoff

Set mySession         = Nothing
Set myRules           = Nothing
Set importPropVal     = Nothing
Set importPropCond    = Nothing
Set myAction          = Nothing
Set myRule            = Nothing