[MS-OXORULE]: Rules Protocol Specification

Transcription

1 [MS-OXORULE]: Rules Protocol Specification Intellectual Property Rights Notice for Protocol Documentation Copyrights. This protocol documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you may make copies of it in order to develop implementations of the protocols, and may distribute portions of it in your implementations of the protocols or your documentation as necessary to properly document the implementation. This permission also applies to any documents that are referenced in the protocol documentation. No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation. Patents. Microsoft has patents that may cover your implementations of the protocols. Neither this notice nor Microsoft's delivery of the documentation grants any licenses under those or any other Microsoft patents. However, the protocols may be covered by Microsoft s Open Specification Promise (available here: If you would prefer a written license, or if the protocols are not covered by the OSP, patent licenses are available by contacting protocol@microsoft.com. Trademarks. The names of companies and products contained in this documentation may be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than specifically described above, whether by implication, estoppel, or otherwise. Preliminary Documentation. This documentation is preliminary documentation for these protocols. Since the documentation may change between this preliminary version and the final version, there are risks in relying on preliminary documentation. To the extent that you incur additional development obligations or any other costs as a result of relying on this preliminary documentation, you do so at your own risk. 1 of 54

2 Tools. This protocol documentation is intended for use in conjunction with publicly available standard specifications and networking programming art, and assumes that the reader is either familiar with the aforementioned material or has immediate access to it. A protocol specification does not require the use of Microsoft programming tools or programming environments in order for a Licensee to develop an implementation. Licensees who have access to Microsoft programming tools and environments are free to take advantage of them. Revision Summary Author Date Version Comments Microsoft Corporation April 4, Initial Availability 2 of 54

3 Table of Contents 1 Introduction Glossary References Normative References Informative References Protocol Overview (Synopsis) Creating, Modifying and Deleting Rules Retrieving Rules from the Server Executing Client-side Rules Relationship to Other Protocols Prerequisites/Preconditions Applicability Statement Versioning and Capability Negotiation Vendor-Extensible Fields Standards Assignments Messages Transport Message Syntax RopModifyRules Format RopGetRulesTable Format RopUpdateDeferredActionMessages Format Extended Rules Message Syntax Rule Action Format Deferred Action Message (DAM) Syntax Deferred Error Message (DEM) Syntax Protocol Details Client Details Abstract Data Model Timers Initialization Higher-Layer Triggered Events Message Processing Events and Sequencing Rules Timer Events Other Local Events Server Details Abstract Data Model Timers Initialization Higher-Layer Triggered Events of 54

4 3.2.5 Message Processing Events and Sequencing Rules Timer Events Other Local Events Protocol Examples Adding a New Rule Client Request Buffer Server Responds to Client Request Displaying Rules to the User Client Request for a Rules Table Server Responds to Client Requests Deleting a Rule Client Request Buffer Server Responds to Client Request Security Security Considerations for Implementers Index of Security Parameters Appendix A: Microsoft Office and Microsoft Exchange Behavior Index of 54

5 1 Introduction Rules are sets of conditions and associated actions that enable a user to automatically organize, categorize and act on messages as the messages are delivered to a folder. This document specifies the Rules Protocol: The format in which a client can add, modify or delete rules on a folder The format in which a client can retrieve rules set on a folder Details that allow the server and the client to evaluate and execute rules 1.1 Glossary The following terms are defined in [MS-OXGLOS]: address book binary large object (BLOB) Boolean contents table entry ID FAI contents table FAI message folder folder associated information (FAI) folder ID (FID) GUID handle little-endian message message ID (MID) message object named property property property ID property tag remote operation (ROP) 5 of 54

6 ROP request ROP response rule store special folder table Unicode The following data types are defined in [MS-DTYP]: BYTE DWORD WORD ULONG The following terms are specific to this document: action: A discrete operation that is executed on an incoming message when all conditions in the same rule are TRUE. A rule contains one or more actions. client-side rule: A rule that has at least one action that cannot be executed by the server and must be executed by the client. condition: A logical expression comparing one or more properties in all incoming messages against a set of clauses. This logical expression can evaluate to TRUE or FALSE. COUNT: A data type that is either a 2-byte WORD or a 4-byte DWORD, depending on the context where this data type is referenced: within a given buffer, COUNT is always 2 bytes or always 4 bytes, never a mix of the two. Deferred Action Message (DAM): A hidden message indicating to the client it needs to execute one or more rules on another (user-visible) message in the store. Deferred Error Message (DEM): A hidden message indicating to the client it needs to present the user with an error indicating a server-side rule failed to execute. Deferred Action Folder (DAF): A special folder where the server places all DAMs and DEMs to be acted on by the client; this folder is not visible to the user. extended rule: A rule that is added to, modified, and deleted from the server using a different mechanism than regular rules (standard rules), but is otherwise functionally identical to a standard rule. Content that applies only to extended rules is identified as such in the text of this document. 6 of 54

7 Out of Office rule: A rule that has the ST_ONLY_WHEN_OOF bit set in the PidTagRuleState property. rule provider: A client application that created and maintains a specific rule. The application identifies itself using a unique, well-known string saved as a property on the rule. Rule FAI Message: An FAI message stored in the Inbox Special Folder where the client can store extra rule-related information that is opaque to the server. server-side rule: A rule for which all actions are executed by the server. standard rule: A rule that is not an extended rule. MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as described in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT. 1.2 References Normative References [MS-DTYP] Microsoft Corporation, "Windows Data Types", March 2007, [MS-OXCDATA] Microsoft Corporation, "Data Structures Protocol Specification", April [MS-OXCFOLD] Microsoft Corporation, "Folder Object Protocol Specification", April [MS-OXCMSG] Microsoft Corporation, "Message and Attachment Object Protocol Specification", April [MS-OXCPRPT] Microsoft Corporation, "Property and Stream Object Protocol Specification", April [MS-OXCROPS] Microsoft Corporation, "Remote Operations (ROP) List and Encoding Protocol Specification", April [MS-OXCSTOR] Microsoft Corporation, "Store Object Protocol Specification", April [MS-OXCTABL] Microsoft Corporation, "Table Object Protocol Specification", April [MS-OXGLOS] Microsoft Corporation, "Office Exchange Protocols Master Glossary", April [MS-OXOSFLD] Microsoft Corporation, "Special Folders Protocol Specification", April of 54

8 [MS-OXPROPS] Microsoft Corporation, "Office Exchange Protocols Master Property List Specification", April [MS-OXWOOF] Microsoft Corporation, "Out of Office (OOF) Web Service Protocol Specification", April [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997, Informative References None. 1.3 Protocol Overview (Synopsis) The Rules Protocol specifies the client/server interaction that allows a messaging system to implement automatic message processing ( message rules). This protocol documents a specific mechanism through which the server and the client can implement a flexible message processing system; since mail delivery is a complex operation, the server and the client may implement their own additional processing that is not covered by this protocol. Rules are sets of conditions and associated actions that enable a user to automatically organize, categorize and act on messages as the messages are delivered to a folder. Rules can be set on any server folder (either public or private folders) <1>. Rule evaluation is triggered when messages are delivered in a user s mailbox or when messages are first saved to a public folder. The conditions in a rule are evaluated against the properties of the incoming message. If the conditions evaluate to TRUE, the rule actions are executed either by the server or by the client. If all actions in a rule can be executed by the server, the rule is said to be a server-side rule. If any action cannot be executed by the server (for example, the server doesn t have access to user s personal store, therefore it has to defer to the client any action moving messages to a personal store), the rule must be executed by the client and it is said to be a client-side rule. Server-side rules are handled entirely by the messaging server, independent of the state of the messaging client. Client-side rules do not execute until the mail client connects to the particular store on the server. For each message that needs to be acted on by the client as a result of a client-side rule, the server will create a message called Deferred Action Message (DAM) in a special folder called the Deferred Action Folder (DAF) as specified in [MS- OXOSFLD]. All (enabled) rules in a folder are evaluated in sequential order, one by one, until all rules in the rules table for the particular folder have been evaluated. If a particular rule s conditions are met, its associated set of actions is executed. If a rule is an exit level rule (according to a flag in the rule state property) and the rule condition is met, then the evaluation of subsequent 8 of 54

9 rules is cancelled. Otherwise, evaluation of the next rule continues even if a rule action moves the message, in which case the remaining rules continue to run against the moved message. If the rule action is to copy or move a message to a (server) folder, the server will verify the existence of the destination folder. If the destination folder also has rules (this is not common <1>), the server will evaluate the destination folder rules against the moved message after evaluating the remaining rules in the original folder. If the destination folder does not exist, the server will create a Deferred Error Message (DEM) in the DAF and the client will display the appropriate error when it processes the DEM. When a folder is deleted, all rules set on that folder are also deleted. This protocol specifies two slightly different types of rules: standard rules, which are more commonly used, and extended rules, which provide greater storage capacity but, for performance reasons, the server may choose to limit their usage. The way the two types of rules are created and modified differs, but they are processed identically by the server and by the client. The following sub-sections describe the main components covered in this protocol Creating, Modifying and Deleting Rules Standard rules are created, modified and deleted using the ROPs specified in section using the underlying [MS-OXCROPS] protocol. Extended rules are created, modified, and deleted using an FAI message representation as specified in section using the underlying [MS-OXCMSG] protocol Retrieving Rules from the Server The messaging client can retrieve the standard rules in a folder in the form of a Table Object using the underlying ROP transport (see [MS-OXCROPS]) in the format specified in section Each row in the returned Table Object contains data representing one rule. The conditions, actions and other rule properties are returned as properties in the corresponding Table Row as specified in section To obtain a list of extended rules in a folder, the client can retrieve the FAI contents table for that folder. Extended rules are FAI messages identified by the value of their PidTagMessageClass property, as specified in section Executing Client-side Rules When a rule cannot be executed entirely by the server, the client will need to complete the rule execution. The Rule Protocol specifies how this is achieved via Deferred Actions (section ). 9 of 54

10 1.4 Relationship to Other Protocols The [MS-OXORULE] protocol specification relies on an understanding of how to work with folders, messages and tables (for more detail see [MS-OXCMSG], [MS-OXCSTOR] and [MS-OXCTABL]). The specification also relies on understanding how ROPs defined in this protocol are transmitted to the server using the underlying transport (see [MS-OXCROPS]). Extended rules use message objects specified in [MS-OXCMSG] as an underlying transport. 1.5 Prerequisites/Preconditions This protocol specification assumes the messaging client has previously logged on to the messaging server (see [MS-OXCROPS]) and has acquired a handle to the folder it needs to set/retrieve the rules to/from (see [MS-OXCFOLD]). This document also relies on the use of the underlying ROP transport protocol specified in [MS-OXCROPS]. 1.6 Applicability Statement The [MS-OXORULE] protocol can be used to build automatic workflows for messages that are delivered by the server into a message folder. 1.7 Versioning and Capability Negotiation None. 1.8 Vendor-Extensible Fields A third party application can create its own set of rules by using its own custom string as the value of PidTagRuleProvider property (specified in section ). There is no centralized authority that ensures uniqueness of Rule Provider strings across different client applications. 1.9 Standards Assignments None. 10 of 54

11 2 Messages 2.1 Transport The standard rules (sections 2.2.1, 2.2.2, and 2.2.3) are built using the ROP protocol specified in [MS-OXCROPS]. The extended rules portion of the protocol (section 2.2.4) is built using the messages protocol specified in [MS-OXCMSG]. The ROP request and ROP response buffers specified by this protocol are sent to and received from the server respectively using the underlying protocol specified by [MS- OXCROPS]. 2.2 Message Syntax Standard rules are the most common and typical way of specifying rules for a folder. Sections 2.2.1, and specify the ROP requests specific to the [MS-OXORULE] protocol. The syntax of these requests and responses is documented in [MS-OXCROPS], as specified in each section below. Before sending any of these requests to the server, the client MUST have successfully logged onto the server using RopLogon, and have a valid LoginIndex as specified in [MS- OXCROPS]. Also, the higher layers issuing the messages specified in this section MUST have opened handles to the messaging objects used as parameters in the ROP requests (as specified in each section). Unless otherwise noted, sizes in this section are expressed in BYTES. Unless otherwise noted, the fields specified in this section are packed in buffers in the order they appear in this document, without any padding in little endian format RopModifyRules Format The messaging client sends the RopModifyRules request to create, modify or delete rules in a folder. The syntax of the RopModifyRules request and response buffers are specified in the [MS- OXCROPS] protocol. This section specifies the syntax and semantics of various fields that are not fully specified in the Remote Operations (ROP) List and Encoding Protocol (see [MS- OXCROPS]) Request Buffer InputHandleIndex The input handle for this operation is a folder object handle representing the folder for which rules are to be modified. 11 of 54

12 ModifyRulesFlag This is a 8-bit field with a structure specified by the following table: X X X X X X X R R: (bitmask 0x01)If this bit is set, the rules in this request are to replace existing rules in the folder; in this case, all subsequent RuleData structures MUST have ROW_ADD as the value of their RuleDataFlag field. If this bit is not set, the rules specified in this request represent changes (delete, modify, add) to the rules already existing in this folder. X: Unused. This bit MUST be set to 0 by the protocol client and ignored by the protocol server RulesCount This is a WORD field whose value MUST be the number of RuleData structures present in the ROP request RulesData Array This is an array of RuleData structures that use the format specified in section Response Buffer InputHandleIndex The input handle in the response buffer MUST be the same as the input handle in the request buffer for this operation ReturnValue The ReturnValue is a 32-bit unsigned integer value that indicates the result of the operation. To indicate success, the server MUST return 0x For a list of common error return values, see [MS-OXCDATA] RuleData Structure The RopModifyRules request buffer MUST contain exactly RulesCount number of RuleData buffers, as specified in [MS-OXCROPS]. The following table specifies the format of the RuleData structures in the RopModifyRules request buffer of 54

13 RuleDataFlags PropertyValueCount PropertyValue1 (variable) PropertyValue1 (continued) PropertyValueN (variable) RuleDataFlags (1 byte): MUST be set to one of the values specified in section PropertyValueCount (2 bytes): The count of properties that are defined in this structure. This field MUST be greater than zero and MUST be followed by exactly PropertyValueCount PropertyBuffer structures. PropertyValue1 (variable length structure): PropertyValue structure containing one property tag and its associated value. The Property Tag used in this buffer MUST be among the ones specified in section The format of the PropertyValue structure is specified in [MS-OXCDATA]. PropertyValueN (variable length structure): Last of PropertyValueCount PropertyValue structures RuleDataFlags The RuleDataFlags field in the RuleData structure MUST have one of the following values: Name Value Description ROW_ADD 0x01 Adds the data in the rule buffer to the rule set as a new rule. ROW_MODIFY 0x02 Modifies the existing rule identified by the value of PidTagRuleId property. ROW_REMOVE 0x04 Removes from the rule set the rule that has the same value of the PidTagRuleId property PropertyValue Structure This section specifies the allowed set of property tags that MUST be used in the PropertyValue structure. When deleting a rule, the only property the protocol client MUST pass is PidTagRuleId and SHOULD NOT pass in any other property. The protocol server MUST ignore properties other than PidTagRuleId. When adding a rule, the client MUST NOT pass in PidTagRuleId, it MUST pass in PidTagRuleCondition, PidTagRuleActions and 13 of 54

14 PidTagRuleProvider, and SHOULD <2> pass in the rest of the properties specified in this section. When modifying a rule, the client MUST pass in PidTagRuleId and SHOULD pass in the rest of the properties that need to be modified. The protocol server MUST ignore properties that are not specified in this section. Refer to [MS-OXPROPS] and [MS-OXCDATA] for more specification details about properties, property types, and the buffer format of the PropertyBuffer structure PidTagRuleId An 64-bit unsigned integer value containing a unique identifier the messaging server generates for each rule when the rule is first created. The client MUST NOT specify this property when creating a new rule but MUST specify it when modifying or deleting a rule PidTagRuleSequence A ULONG value used to determine the order in which rules are evaluated and executed. Rules are evaluated in sequence according to the increasing order of this value. The evaluation order for rules that have the same value in the PidTagRuleSequence property is undefined PidTagRuleState A ULONG value interpreted as a bitmask combination of flags that specify the state of the rule. The value of PidTagRuleState is defined in the following table: X P E S C L E L H I O F E R E N X X X X X X X X X X X X X X X X X X X X X X X X EN (ST_ENABLED, bit mask 0x ): The rule is enabled for execution. If this flag is not set, the server MUST skip this rule when evaluating rules. ER (ST_ERROR, bit mask 0x ): The server has encountered an error processing the rule. OF (ST_ONLY_WHEN_OOF, bit mask 0x ): The rule is executed only when the user sets the Out of Office state on the mailbox (see [MS-OXWOOF]. This flag MUST NOT be set in a Public Folder Rule. For details on this flag, see section 3.2 HI (ST_KEEP_OOF_HIST, bit mask 0x ): For details, see Out of Office Rule Processing in section 3.2. This flag MUST NOT be set in a Public Folder Rule. EL (ST_EXIT_LEVEL, bit mask 0x ): Rule evaluation will terminate after executing this rule, except for evaluation of Out of Office rules. 14 of 54

15 SCL (ST_SKIP_IF_SCL_IS_SAFE, bit mask 0x ): Evaluation of this rule will be skipped if the delivered message s PidTagContentFilterSCL property has a value of 0xFFFFFFFF PE (ST_RULE_PARSE_ERROR, bit mask 0x ): The server has encountered an error parsing the rule data provided by the client X: Unused by this protocol. This bit MUST NOT be modified by the protocol client <3> Note on the interaction between ST_ONLY_WHEN_OOF and ST_EXIT_LEVEL flags: When the Out of Office state is set on the mailbox (as specified in [MS-OXWOOF]), and a rule condition evaluates to TRUE, and: Or, the rule has the ST_EXIT_LEVEL flag set and does not have ST_ONLY_WHEN_OOF flag set, then the server MUST NOT evaluate subsequent rules that do not have ST_ONLY_WHEN_OOF flag set, and MUST evaluate subsequent rules that have ST_ONLY_WHEN_OOF flag set. the rule has both the ST_EXIT_LEVEL and ST_ONLY_WHEN_OOF flags set, then the server MUST NOT evaluate any subsequent rules PidTagRuleName A string property that is the user-readable name of the rule PidTagRuleProvider A string property identifying the client application that owns the rule. The client MUST specify this property when adding or modifying a rule. Rules that are stored on folders are associated with the application that owns the rules using a rule provider string. Each client application SHOULD only add, modify or delete rules that it is responsible for. A messaging client can define its own rule provider string, provided the value of the string is not the same as the rule provider string being used by another messaging client that could be setting rules on the same folder <4> PidTagRuleLevel This property is not used; if setting this property, the client MUST pass in 0x PidTagRuleUserFlags A LONG property set by the client for the exclusive use of the client. The server MUST preserve this value if it was set by the client, but MUST ignore it during rule evaluation and processing PidTagRuleProviderData 15 of 54

16 An opaque binary property that the client sets for the exclusive use of the client. The server MUST preserve this value if it was set by the client but MUST ignore its contents during rule evaluation and processing PidTagRuleCondition The condition used when evaluating the rule. The condition is expressed as a Restriction (as specified in [MS-OXCDATA]) and the PropertyValue buffer contains the Restriction structure packaged as specified in [MS-OXCDATA] (using 2-byte sized COUNT values) PidTagRuleActions The set of actions associated with the rule. Its structure is specified in section 2.2.5, using a 2- byte sized COUNT value RopGetRulesTable Format The syntax of the RopGetRulesTable request and response buffers are specified in the [MS- OXCROPS] protocol. The RopGetRulesTable remote operation (ROP) creates a table object through which the client can access the standard rules in a folder using table operations as specified in the [MS- OXCTABL] protocol. The table returned by the server MUST contain all standard rules associated with a given folder. Each row in the table MUST represent one rule. The properties in each row are the properties set when the rule was created or modified. This section specifies the syntax and semantics of various fields that are not fully specified in the [MS-OXCROPS] protocol Request Buffer InputHandleIndex The input handle for this operation is a folder object handle representing the folder for which rules are to be retrieved TableFlags This is an 8-bit field as specified below X U X X X X X X U (bit mask 0x40): Set if the client is requesting that string values in the table to be returned as Unicode strings. 16 of 54

17 X: Unused. This bit MUST be set to 0 by the client and ignored by the server Response Buffer InputHandleIndex The input handle in the response buffer MUST be the same as the input handle in the request buffer for this operation ReturnValue The ReturnValue is a 32-bit unsigned integer value that indicates the result of the operation. To indicate success, the server MUST return 0x For a list of common error return values, see [MS-OXCDATA] RopUpdateDeferredActionMessages Format The format of the RopUpdateDeferredActionMessages request and response buffers are specified in the [MS-OXCROPS] protocol. When the server generates DAMs for a message, the server MUST set the value of PidTagHasDAMs property on the message to TRUE. During download, the EntryId identifying a message in the messaging system can change, for example when the client downloads the message into a store different than the server store. In such cases, as detailed in section , the messaging client MUST send the server a RopUpdateDeferredActionMessages request with the appropriate information on the message EntryId change as soon as the message s EntryId has been updated on the client. This section specifies the syntax and semantics of various fields that are not fully specified in the [MS-OXCROPS] protocol Request Buffer InputHandleIndex The input handle for this operation is a logon object handle ServerEntryIdSize WORD value representing the length, in bytes, of the ServerEntryId field ServerEntryId Byte array representing the EntryId of the message on the server for which the DAM has been generated. The length of this byte array is specified by the ServerEntryIdSize field ClientEntryIdSize WORD value representing the length, in bytes, of the ClientEntryId field 17 of 54

18 ClientEntryId Byte array representing the EntryId of the message downloaded by the client to which the DAM will now apply. The length of this byte array is specified by the ClientEntryIdSize field Response Buffer InputHandleIndex The input handle in the response buffer MUST be the same as the input handle in the request buffer for this operation ReturnValue The ReturnValue is a 32-bit unsigned integer value that indicates the result of the operation. To indicate success, the server MUST return 0x For a list of common error return values, see [MS-OXCDATA] Extended Rules Message Syntax The standard rules protocol has one major limitation as a consequence of using the ROP layer as the underlying transport there is an inherent size limitation of 32kb per ROP package. To work around this limitation, extended rules were created. Extended rules are built using the [MS-OXCMSG] protocol. An extended rule is defined as an FAI message in a folder that MUST have the value of the PidTagMessageClass property set to IPM.ExtendedRule.Message. This FAI message also has a set of rule-related properties set on it, as specified below. To create, modify or delete an Extended Rule, the application MUST create, modify or delete the underling FAI message. Extended rules use a different set of properties than RopModifyRules. However, these properties map to properties for RopModifyRules; and except where noted, their formats are identical and the same syntactic restrictions and semantic meanings of values apply as the respective property defined in section Properties of an Extended Rule The following properties have a particular meaning when set on FAI messages representing an extended rule. The application can store additional meta-data in any other property on the FAI message. The server MUST ignore any properties not explicitly listed here when evaluating extended rules PidTagRuleMsgName This string property SHOULD be set on the FAI message. This property has the same semantics as PidTagRuleName defined in section PidTagMessageClass 18 of 54

19 This string property MUST be set on the FAI message, and MUST have a value of IPM.ExtendedRule.Message PidTagRuleMsgSequence This unsigned LONG property MUST be set on the FAI message. This property has the same semantics as PidTagRuleSequence defined in section PidTagRuleMsgState This unsigned LONG property MUST be set on the FAI message. This property has the same semantics and flag meanings as PidTagRuleState defined in section PidTagRuleMsgUserFlags This unsigned LONG property MAY be set on the FAI message. This property has the same semantics as PidTagRuleUserFlags defined in section PidTagRuleMsgLevel This unsigned LONG property SHOULD be set on the FAI message. This property has the same semantics as PidTagRuleLevel defined in section PidTagRuleMsgProvider This string property MUST be set on the FAI message. This property has the same semantics as PidTagRuleProvider defined in section PidTagRuleMsgProviderData This binary property MAY be set on the FAI message. This property has the same syntax and semantics as PidTagRuleProviderData defined in section PidTagExtendedRuleMsgActions This binary property MUST be set on the FAI message. This property serves the same purpose as PidTagRuleActions, however it contains additional information about the named properties used. All string values contained in any part of the action buffer used to contain actions MUST be in Unicode format. The format of this property is defined in section PidTagExtendedRuleMsgCondition This binary property MUST be set on the FAI message. This property serves the same purpose as PidTagRuleCondition, however it contains additional information about the named properties used. All string values contained in any part of this condition property value MUST be in Unicode format. The format of this property is defined in section If the PidTagExtendedRuleSizeLimit property is set on the logon object (as specified in [MS- OXCSTOR]), the client SHOULD keep the size of the PidTagExtendedRuleMsgCondition under the value specified by the PidTagExtendedRuleSizeLimit property; conversely, the 19 of 54

20 server SHOULD return an error if the client does attempt to set a binary property that is too large Extended Rule Actions Format An extended rule s PidTagExtendedRuleMsgActions property contains additional information about the version of the rule and the named properties stored in the rule action, as well as information about the actions to be performed by this rule. The format of the binary property is specified in the following table: NamedPropertyInformation (variable) RuleVersion RuleActionsBuffer (variable) NamedPropertyInformation (variable length structure): Specifies information about named properties used in this action as specified in section RuleVersion (ULONG): Specifies the extended rules version format. This document defines version 1, and thus this value MUST be set to 0x RuleActionsBuffer (variable length structure): A structure containing the actions to be executed when this rule condition evaluates to true. The format of this structure is defined in section 2.2.5, using a 4-byte COUNT value (see Section 1.1 for a definition of COUNT) Extended Rule Condition Format Similar to extended rule actions, extended rule conditions contain information about any named properties contained inside of them. The format of the PidTagExtendedRuleMsgCondition binary property is specified in the following table NamedPropertyInformation (variable) RuleRestriction (variable) NamedPropertyInformation (variable length structure): Specifies information about named properties used in this condition as specified in section of 54

21 RuleRestriction (variable length structure): A structure containing the condition to be evaluated, represented as a Restriction structure. The format of this Restriction structure is defined in [MS-OXCDATA], using a 4-byte COUNT value Named Property Information Format The named property information format provides context to any named property tags which are present in the structure it precedes. For every distinct (unique) named property used in the structure it precedes, the Named Property Information structure MUST contain one PropId NamedProperty pair. Each PropId field is a Property ID that MUST have a value of 0x8000 or greater and uniquely identifies the named property within an extended rule. The format of the Named Property Information structure is specified in the following table NoOfNamedProps PropId-1 PropId-N NamedPropertiesSize NamedProperty (variable) NamedProperty-N (variable) NoOfNamedProps (WORD): Specifies the number of named property mappings that are packed in this buffer. If no named properties are used in the structure that follows the Named Property Information buffer, the value of this field MUST be 0x0000. PropId-1 (WORD): the first PropId field PropId-N (WORD): the last (NoOfNamedProps) PropId field NamedPropertiesSize (DWORD): The total size, in bytes, of the following fields. Only present if NoOfNamedProps is greater than zero. NamedProperty (variable length structure): Specifies the first PropertyName structure, whose format is specified in [MS-OXCDATA]. NamedProperty-N (variable length structure): Specifies the last (NoOfNamedProps) PropertyName structures. Note that if there are no named properties to be listed, the Named Property Information reduces to a two byte WORD value of 0x of 54

22 2.2.5 Rule Action Format The Rule Action data buffer MUST have one or more blocks of action block binary data to specify various actions of the rule, as specified in the following table. The COUNT data type MUST be either a 2-byte WORD or a 4-byte DWORD, depending on the context where this section is referenced: within a given buffer, COUNT is always 2 bytes or always 4 bytes, never a mix of the two. Unless explicitly specified, any document referring to this section MUST assume a 2-byte size for the COUNT data type NoOfActions (2-byte COUNT or 4-byte COUNT) ActionBlock-1 (variable) ActionBlock-N (variable) NoOfActions (COUNT): Specifies the number of ActionBlocks that are packed in this buffer. This number MUST be greater than zero. ActionBlock-1 (variable length structure): Specifies an action, see section ActionBlock-N (variable length structure): Specifies an action (the last of the NoOfActions ActionBlock fields). 22 of 54

23 Action Block Buffer Format The format of action data block buffer is specified the following table: ActionLength (2-byte COUNT or 4-byte COUNT) ActionType ActionFlavor (continued) ActionFlags (continued) ActionFlavor ActionFlags ActionData (variable) ActionLength (COUNT): MUST be the cumulative length (in BYTES) of the subsequent fields in this ActionBlock. ActionType (BYTE): Specifies the types of action (see table below) ActionFlavor (DWORD): MUST be used in conjunction with specific ActionTypes that support it, and MUST be zero otherwise (see below) ActionFlags (DWORD): Client-defined flags. ActionData (variable length binary): Specifies action data based on the ActionType. For more details see section Action Types The ActionType field MUST have one of the following values: Rule action types Name Value Description OP_MOVE 0x01 Moves the message to a folder. MUST NOT be used in a Public Folder Rule. OP_COPY 0x02 Copies the message to a folder. MUST NOT be used in a Public Folder Rule. OP_REPLY 0x03 Replies to the message. OP_OOF_REPLY 0x04 Sends an Out of Office (OOF) reply to the message. 23 of 54

24 Name Value Description OP_DEFER_ACTION 0x05 Used for actions that cannot be executed by the server (like playing a sound). MUST NOT be used in a Public Folder Rule. OP_BOUNCE 0x06 Rejects the message back to the sender. OP_FORWARD 0x07 Forwards the message to a recipient address. OP_DELEGATE 0x08 Assigns the message to another recipient. OP_TAG 0x09 Adds or changes a property on the message. OP_DELETE 0x0A Deletes the message. OP_MARK_AS_READ 0x0B Sets the MSGFLAG_READ in the PidTagMessageFlags property on the message (see [MS-OXPROPS]) Action Flavors The only action types that currently support an Action Flavor are OP_REPLY, OP_OOF_REPLY and OP_FORWARD. The value of ActionFlavor MUST be 0x if ActionType is not one of these values. If ActionType is OP_FORWARD, ActionFlavor MUST be a combination of the bitwise flags specified in the following table X X X X X A T N C P R X X X X X X X X X X X X X X X X X X X X X X X X PR (bit mask 0x ): Preserves the sender information and indicates that the message was auto-forwarded. Can be combined with the NC ActionFlavor flag. NC (bit mask 0x ): Forwards the message without making any changes to the message. Can be combined with PR ActionFlavor flag AT (bit mask 0x ): Makes the message an attachment to the forwarded message. This value MUST NOT be combined with other ActionFlavor flags. X: Unused. This bit MUST be set to 0 by the client and ignored by the server. 24 of 54

25 If ActionType is OP_REPLY or OP_OOF_REPLY, ActionFlavor MUST have one of the values specified in the following table (a value of 0x indicates standard reply behavior): X X X X X X S T N S X X X X X X X X X X X X X X X X X X X X X X X X NS: Do not send the message to the message sender (the reply template MUST contain recipients in this case). ST: Server will use a fixed, server-defined text in the reply message and ignore the text in the reply template Action Data Buffer Format The ActionData buffer is different for each ActionType and MUST use the appropriate format specified in this section OP_MOVE and OP_COPY Action Data Buffer Format A Move/Copy action is used to move or copy an incoming message to a specified folder in the destination store. The following table specifies the ActionData buffer used in an action of type OP_MOVE or OP_COPY FolderInThisStore StoreEIDSize StoreEID (variable) StoreEID (continued) FolderEIDSize FolderEID (continued) FolderEID (variable) FolderInThisStore (BYTE): MUST be either 0x01 if the folder whose Entry ID is FolderEID is in the protocol server store, or 0x00 if the folder is in a different store (for example, a local store the server cannot access). StoreEIDSize (WORD): The size of the StoreEID byte array StoreEID (BYTE array): The binary buffer specifies the destination store EntryId. FolderEIDSize (WORD): The size of the FolderEID byte array. 25 of 54

26 FolderEID (BYTE array): The binary buffer specifies the destination folder's EntryId. Furthermore, if the value of the FolderInThisStore field is 0x01, the FolderEID BYTE array MUST have the following structure: Type Type (BYTE): MUST be set to 0x01 FolderID ID Padding FolderID (8-byte unsigned integer): MUST be set to the FID of the destination folder ID (8-byte unsigned integer): MUST be set to 0x Padding (unsigned LONG): MUST be set to 0x OP_REPLY and OP_OOF_REPLY Action Data Buffer Format The following table specifies the Reply/OOF Reply ActionData buffer format ReplyTemplateFID ReplyTemplateMID ReplyTemplateGUID 26 of 54

27 ReplyTemplateFID: The reply template 8-byte FID (see below) ReplyTemplateMID: The reply template 8-byte MID (see below) ReplyTemplateGUID: The reply template GUID (see below) Before creating a rule that has an OP_REPLY or OP_OOF_REPLY ActionType, the client MUST first create a Reply Template FAI message in the same folder as the rule. (For details on creating and manipulating FAI messages, see [MS-OXCMSG].) The following steps specify how to create a Reply Template: 1. Create a new FAI message in the folder. 2. Set the value of the PidTagMessageClass property to a string that has the prefix IPM.Note.Rules.ReplyTemplate. (for OP_REPLY) or IPM.Note.Rules.OOFTemplate. (for OP_OOF_REPLY) 3. Set the value of the PidTagReplyTemplateId property with a newly generated GUID 4. Set the value of PidTagSubject property, the text of the message and other message properties as desired. 5. Save the newly created message 6. Get the value of the MID and FID from the saved message For more details about creating and working with FAI messages, see [MS-OXCFOLD] and [MS-OXCMSG]. The ReplyTemplateGUID field in the reply ActionData buffer is the value of the GUID generated by the client at step 3 above, which is also stored on the reply template message as the value of the PidTagReplyTemplateId property. The ReplyTemplateGUID field MUST be unique in the folder - no two reply templates can share the same GUID OP_DEFER_ACTION Action Data Buffer Format If one or more actions for a specific rule cannot be executed on the server, the rule MUST be a client-side rule, whose ActionType MUST be OP_DEFER_ACTION. Execution of the rule is postponed until the client is available. The messaging client encodes the rule information as a client-dependent data structure designating the action to be performed. The format is client implementation dependent and contains enough information to allow the client to perform the client-side operation when requested. The size of the buffer is obtained by reading the ActionLength value in the ActionBlock containing an OP_DEFER_ACTION ActionType. 27 of 54

28 If the action type is OP_DEFER_ACTION, the ActionData buffer is completely under the control of the messaging client that created the rule. This binary buffer MUST be treated as an opaque binary large object (BLOB) by the server. When a message that satisfies the rule condition is received, the server creates a DAM and places the entire content of the ActionBlock as a property on the DAM for the client to execute (see section ) OP_FORWARD and OP_DELEGATE Action Data Buffer Format The following table specifies the ActionData buffer format that MUST be used with the OP_FORWARD and OP_DELEGATE action types RecipientCount (2-byte COUNT or 4-byte COUNT) RecipientBlock-1 (variable) RecipientBlock-N (variable) RecipientCount (COUNT): Specifies the number of recipient blocks. This number MUST be greater than zero. RecipientBlock-1 (variable length binary): Specifies recipient information (see table below) RecipientBlock-N (variable length binary): Last of RecipientCount RecipientBlocks The following table specifies the RecipientBlock data buffer Reserved NoOfProperties (continued) NoOfProperties (2-byte COUNT or 4-byte COUNT) PropertyValue 1 (variable) Reserved (BYTE): MUST be set to 0x01. PropertyValue N (variable) 28 of 54

29 NoOfProperties (COUNT): Specifies the number of properties in the block. This number MUST be greater than zero. PropertyValue 1 (variable length structure): Specifies the first PropertyValue structure. PropertyValue N(variable length structure): Last of NoOfProperties PropertyValue structures For details about parsing the PropertyValue structure, see [MS-OXCDATA]. The client MUST at a minimum specify values for the PidTagDisplayName, PidTag Address, and PidTagRecipientType properties in the forward/delegate ActionData buffer OP_BOUNCE Action Data Buffer Format The following table shows the Bounce ActionData buffer format BounceCode BounceCode (DWORD): Specifies a bounce code as specified below. The BounceCode field MUST have one of the following values: Values Description 0x D The message was refused because it was too large. 0x F 0x The message was refused because it cannot be displayed to the user The message delivery was denied for other reasons OP_TAG Action Data Buffer Format An OP_TAG Action Data Buffer is a PropertyValue structure, packaged as specified in [MS- OXCDATA] OP_DELETE or OP_MARK_AS_READ Data Buffer Format The incoming messages are deleted <5> or marked as read according to the ActionType itself. These actions have no ActionData buffer Deferred Action Message (DAM) Syntax A Deferred Action Message MUST be created by the server to indicate to the client that it must further process a client-side rule action. This process is specified in section of this document. 29 of 54

30 In addition to properties required on any message (as specified in [MS-OXCMSG]), the following properties are specific to a DAM PidTagMessageClass The value of this string property MUST be set to IPC.Microsoft Exchange 4.0.Deferred Action PidTagDAMBackPatched The value of this Boolean property MUST be set to FALSE when the DAM is generated; it MUST be set to TRUE if the DAM was updated by the server as a result of a RopUpdateDeferredActionMessages request PidTagDAMOriginalEntryId The value of this binary property MUST be set to the EntryId of the delivered (target) message which the client has to process PidTagRuleProvider The value of this string property MUST be set to the same value as the PidTagRuleProvider property on the rule(s) that have generated the DAM PidTagRuleFolderEntryId The value of this binary property MUST be set to the EntryId of the folder where the rule that triggered the generation of this DAM is stored PidTagClientActions The value of this binary property is a binary buffer specifying the actions the client must take on the message. The buffer MUST be packed according to the Rule Action Buffer format specified in section The server MUST place in this property the relevant actions as they were set by the client when the rule was created or changed using RopModifyRules. Note that the server can combine actions from different rules into one DAM, in which case the rule actions will be concatenated in the DAM s PidTagClientActions using the proper action syntax specified in section PidTagRuleId The value of this binary property is a binary buffer obtained by concatenating the PidTagRuleId values (8-bytes each) from all the rules that contributed actions in the PidTagClientActions property. The length of this binary property MUST be a multiple of 8 bytes. 30 of 54

31 2.2.7 Deferred Error Message (DEM) Syntax A Deferred Error Message SHOULD be created by the server when an error is encountered while executing a rule. This process is specified in section of this document. In addition to properties required on any message (as specified in [MS-OXCMSG]), the following properties are specific to a DEM PidTagMessageClass The value of this string property MUST be set to IPC.Microsoft Exchange 4.0.Deferred Error PidTagRuleError The value of this unsigned LONG property MUST be set to one of the following values, indicating the cause of the error encountered during the execution of the rule: 0x : generic error that doesn t fall into any of the other categories 0x : error opening the rules folder 0x : error delivering the message 0x : error while parsing the rule format 0x : error processing the rule 0x : error moving or copying the message to the destination folder 0x : permission error moving or copying the message to the destination folder 0x : error creating the Deferred Action Message 0x : error sending as another user 0x A: error retrieving the reply template 0x B: generic error while executing the rule on the server 0x C: error processing rule due to mailbox quotas 0x D: error processing the message due to the large number of recipients 0x E: error copying or moving a message due to folder quotas PidTagRuleActionType The value of this unsigned LONG property MUST be set to the ActionType (see Rule Action Types in section ) of the action in the rule that failed, or 0x if the failure is not specific to an action. Related property: PidTagRuleActionNumber. 31 of 54