February 14, 1995Defined in Rule.Def
Inherits from RuleQualifier
Class LocalRuleQualifier is the most common subclass of class RuleQualifier. You'll use local rule qualifier objects often while writing rules. Qualifiers describe conditions that rules must meet before they are allowed to perform their actions.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Instantiate: often Subclass: rarely Call its methods: rarely
Class LocalRuleQualifier overrides the two important methods it inherits from class RuleQualifier, QualifyRule and ComputeRuleText. You probably won't ever call QualifyRule yourself, since the system calls it from InvokeRule as part of the process of triggering a rule. You might subclass LocalRuleQualifier, though, if you want to define a new qualifier type.
Class LocalRuleQualifier defines the following methods:
| Method | Description |
|---|---|
| QualifyRule | Check to see if the rule meets its qualifier |
| ComputeRuleText | Create a text description for the rule, using the qualifier |
| SetEntity | If the qualifierObject is an entity, set it to be the new entity (only for qualifySender and qualifyCaller rules) |
Class LocalRuleQualifier defines the following attributes:
| Field | Type | Description |
|---|---|---|
| QualifierObject | Object | provides an interface to the qualifierObject field |
| QualifierData | Unsigned | provides an interface to the qualifierData field |
Class LocalRuleQualifier defines the following fields:
| Field | Type | Description |
|---|---|---|
| qualifierType | Unsigned | Predefined qualifier type |
| qualifierObject | Object | The object or condition to match |
| qualifierData | Unsigned | Additional data to use while qualifying rule |
The qualifier object usually specifies the condition or object to meet or match. The qualifier type describes how the rule's trigger data is to be compared to the qualifier object. The system defines several qualifier types which are handled by the QualifyRule method. The section on Qualifier Types later in this chapter lists the predefined qualifier types.
Here's an example of a rule with its qualifier:
Instance Rule 17;
ruleFlags: 0x40400000;
ruleTemplate: nilObject;
ruleTrigger: iNewCardInOutboxTrigger;
description: (Text 18);
ruleAction: (LocalRuleAction 19);
ruleQualifier: (LocalRuleQualifier 20);
End Instance;
Instance Text 18;
text: 'Send everything in the out box as soon \
as it contains an urgent message.';
End Instance;
Instance LocalRuleAction 19;
actionType: 7; // actionDoOperation
actionObject: iOutBoxStack;
actionData: operation_AddToSendQueue;
End Instance;
Instance LocalRuleQualifier 20;
qualifierType: 2; // qualifyMailAttribute
qualifierObject: (MailAttribute 'urgent' 3651);
qualifierData: 0;
End Instance;
This qualifier is of type qualifyMailAttribute. The trigger data, passed along from the initial PostTrigger call, would be the card that's just been placed in the outbox. The qualifier object is the mail attribute of interest to the rule. If the new card has its "urgent" attribute set, this rule qualifies and its action will be performed.
This section describes all the qualifier types handled by QualifyRule. If you need a different qualifier type, you should subclass LocalRuleQualifier and override QualifyRule.
#define qualifyAll 0
Use this qualifier type for rules that should always qualify. You could also use nilObject as a qualifier object for a rule that should always qualify.
#define qualifySender 1
Use this qualifier type for rules that should take effect when the trigger object is a card that's been send by a particular sender. The rule will qualify if the trigger object's sender is the same correspondent as the qualifier object; that is, if IsSameNamedCorrespondent returns true. The rule will also qualify if the qualifier object is a group list of which the sender is a member.
#define qualifyMailAttribute 2
Use this qualifier type if your rule should check a mail attribute of a message. Mail attributes should qualify themselves. QualifyRule will pass along the call to the mail attribute, like this:
qualified = QualifyRule(qualObject, triggerData, rule);
Mail attributes implement a QualifyRule method. The qualObject parameter is the mail attribute to be checked and the triggerData is the telecard to check.
#define qualifyMatchViewable 3
Use this qualifier type for rules that should take effect when the trigger object contains a particular viewable. The qualifier object should be the viewable to match. For example, you could use this qualifier type for rules that act only on objects with an appropriate stamp.
#define qualifyMatchText 4
Use this qualifier type for rules that should take effect when the trigger object contains a certain text run. The qualifier object should be the text object containing the text to match.
#define qualifyCaller 5
Use this qualifier type for rules that should take effect when the trigger object is the same as the qualifier object. QualifyRule will check by comparing the DirectIDs of the objects.
#define qualifyConnected 6
Use this qualifier type for rules that should take effect when a particular communication method is connected. The qualifier object should be a communication stream object. The rule qualifies if the stream is connected.
#define qualifyStackCount 7
Use this qualifier type for rules that should take effect when the number of objects in a particular list is greater than a specified number. The qualifier object should be an object of a class that inherits from HasCount. (It should at least be of a class that implements a Count method.) The qualifier data is the threshhold number.
operation QualifyRule(contextObject: Object; rule: Object):
Boolean
Call: rarely
Override: rarely
The systems calls QualifyRule in the process of deciding if a rule's action should take place. See the chapter on class Rule for the details on exactly how the system calls this method.
QualifyRule handles the qualifier types listed earlier in this chapter. If you need a qualifier type not already handled, subclass RuleQualifier and override its QualifyRule method. You'll only rarely subclass LocalRuleQualifier and override QualifyRule.
Here's how the system will call QualifyRule:
qualified = QualifyRule(qualifier, triggerData, rule);
The triggerData parameter (referred to in the method declaration as "contextObject") is usually the original triggerData parameter from the initial PostTrigger call. The rule parameter is the rule to qualify.