E2kRule

## E2kRule E2kRule — Exchange server-side rules |

## Synopsis

                E2kRule;
                E2kRules;
    enum        E2kRuleState;

    E2kRules*   e2k_rules_from_binary           (GByteArray *rules_data);
    GByteArray* e2k_rules_to_binary             (E2kRules *rules);
    xmlDoc*     e2k_rules_to_xml                (E2kRules *rules);
    void        e2k_rules_free                  (E2kRules *rules);
    void        e2k_rule_free                   (E2kRule *rule);

                E2kRuleProp;
    void        e2k_rule_prop_set               (E2kRuleProp *prop,
                                                 const char *propname);
                E2kPropValue;
    void        e2k_rule_append_proptag         (GByteArray *ba,
                                                 E2kRuleProp *prop);
    gboolean    e2k_rule_extract_proptag        (guint8 **ptr,
                                                 int *len,
                                                 E2kRuleProp *prop);
    void        e2k_rule_append_propvalue       (GByteArray *ba,
                                                 E2kPropValue *pv);
    gboolean    e2k_rule_extract_propvalue      (guint8 **ptr,
                                                 int *len,
                                                 E2kPropValue *pv);
    void        e2k_rule_free_propvalue         (E2kPropValue *pv);

    void        e2k_rule_write_uint32           (guint8 *ptr,
                                                 guint32 val);
    void        e2k_rule_append_uint32          (GByteArray *ba,
                                                 guint32 val);
    guint32     e2k_rule_read_uint32            (guint8 *ptr);
    gboolean    e2k_rule_extract_uint32         (guint8 **ptr,
                                                 int *len,
                                                 guint32 *val);
    void        e2k_rule_write_uint16           (guint8 *ptr,
                                                 guint16 val);
    void        e2k_rule_append_uint16          (GByteArray *ba,
                                                 guint16 val);
    guint16     e2k_rule_read_uint16            (guint8 *ptr);
    gboolean    e2k_rule_extract_uint16         (guint8 **ptr,
                                                 int *len,
                                                 guint16 *val);
    void        e2k_rule_append_byte            (GByteArray *ba,
                                                 guint8 val);
    gboolean    e2k_rule_extract_byte           (guint8 **ptr,
                                                 int *len,
                                                 guint8 *val);
    void        e2k_rule_append_string          (GByteArray *ba,
                                                 const char *str);
    gboolean    e2k_rule_extract_string         (guint8 **ptr,
                                                 int *len,
                                                 char **str);
    void        e2k_rule_append_unicode         (GByteArray *ba,
                                                 const char *str);
    gboolean    e2k_rule_extract_unicode        (guint8 **ptr,
                                                 int *len,
                                                 char **str);
    void        e2k_rule_append_binary          (GByteArray *ba,
                                                 GByteArray *data);
    gboolean    e2k_rule_extract_binary         (guint8 **ptr,
                                                 int *len,
                                                 GByteArray **data);

## Description

e2k-rule contains functions for handling Exchange server-side rules.

### Note

This code is not heavily tested. It is possible that some of the information in this file about how server-side rules work is wrong.

## Details

### E2kRule

    typedef struct {
    	char           *name;
    	guint32         sequence;
    	guint32         state;
    	guint32         user_flags;
    	guint32         level;
    	guint32         condition_lcid;
    	E2kRestriction *condition;
    	GPtrArray      *actions;
    	char           *provider;
    	GByteArray     *provider_data;
    } E2kRule;

A single server-side rule.

char *`name`; | Name of the rule (UTF-8)
guint32 `sequence`; | The rule's sequence number. Lower sequence numbers are evaluated first. There may be gaps in rule numbering in a folder.
guint32 `state`; | A combination of E2kRuleState values
guint32 `user_flags`; | Always 0?
guint32 `level`; | Always 0?
guint32 `condition_lcid`; | Locale ID for `condition`. (Not clear what effect this has.)
E2kRestriction *`condition`; | the condition that causes `actions` to be triggered
GPtrArray *`actions`; | an array of E2kAction to take if `condition` is met
char *`provider`; | the rule provider that created this rule
GByteArray *`provider_data`; | provider-specific data.

### E2kRules

    typedef struct {
    	guint8     version;
    	guint32    codepage;
    	GPtrArray *rules;
    } E2kRules;

The complete list of rules for a folder.

guint8 `version`; | Always 2?
guint32 `codepage`; | A Windows codepage. Always 1252 in my rules, though the strings seem to actually be Unicode-encoded rather than cp-1252...
GPtrArray *`rules`; | an array of E2kRule.

### enum E2kRuleState

    typedef enum {
    	E2K_RULE_STATE_DISABLED          = 0x00,
    	E2K_RULE_STATE_ENABLED           = 0x01,
    	E2K_RULE_STATE_ERROR             = 0x02,
    	E2K_RULE_STATE_ONLY_WHEN_OOF     = 0x04,
    	E2K_RULE_STATE_KEEP_OOF_HISTORY  = 0x08,
    	E2K_RULE_STATE_EXIT_LEVEL        = 0x10,

    	E2K_RULE_STATE_CLEAR_OOF_HISTORY = 0x80000000
    } E2kRuleState;

Flags for a rule.

`E2K_RULE_STATE_DISABLED` | Rule is disabled (cannot be used with any other flags).
`E2K_RULE_STATE_ENABLED` | Rule is enabled
`E2K_RULE_STATE_ERROR` | ?
`E2K_RULE_STATE_ONLY_WHEN_OOF` | Rule only runs when user is Out of Office
`E2K_RULE_STATE_KEEP_OOF_HISTORY` | ? (presumably means "only trigger this rule once per user")
`E2K_RULE_STATE_EXIT_LEVEL` | Skip further rule processing
`E2K_RULE_STATE_CLEAR_OOF_HISTORY` | ?

### e2k_rules_from_binary ()

    E2kRules*   e2k_rules_from_binary           (GByteArray *rules_data);

Extract rules from `rules_data` and returns them in an E2kRules structure.

`rules_data` : | binary-encoded rules data
Returns : | the rules, or `NULL` on error.

### e2k_rules_to_binary ()

    GByteArray* e2k_rules_to_binary             (E2kRules *rules);

Encodes `rules` into binary form

`rules` : | an E2kRules structure
Returns : | the binary-encoded rules

### e2k_rules_to_xml ()

    xmlDoc*     e2k_rules_to_xml                (E2kRules *rules);

Encodes `rules` into an XML format like that used by the evolution filter code.

`rules` : | an E2kRules
Returns : | the XML rules

### e2k_rules_free ()

    void        e2k_rules_free                  (E2kRules *rules);

Frees `rules` and the rules it contains

`rules` : | an E2kRules structure

### e2k_rule_free ()

    void        e2k_rule_free                   (E2kRule *rule);

Frees `rule`

`rule` : | an E2kRule

### E2kRuleProp

    typedef struct {
    	const char *name;
    	guint32     proptag;
    } E2kRuleProp;

A combination of a WebDAV property name and its corresponding MAPI proptag, so that different parts of the code can use which representation is more convenient.

const char *`name`; | the property name
guint32 `proptag`; | the MAPI proptag (or 0 if `name` is not in the MAPI proptag namespace)

### e2k_rule_prop_set ()

    void        e2k_rule_prop_set               (E2kRuleProp *prop,
                                                 const char *propname);

This is a convenience function to set both the `name` and `proptag` fields of `prop`.

`prop` : | an E2kRuleProp
`propname` : | a MAPI property name

### E2kPropValue

    typedef struct {
    	E2kRuleProp  prop;
    	E2kPropType  type;
    	gpointer     value;
    } E2kPropValue;

A property/value pair.

E2kRuleProp `prop`; | the property
E2kPropType `type`; | the type of `value`
gpointer `value`; | the value

### e2k_rule_append_proptag ()

    void        e2k_rule_append_proptag         (GByteArray *ba,
                                                 E2kRuleProp *prop);

Appends a representation of `prop` to the rule in `ba`

`ba` : | a byte array containing a binary rule
`prop` : | an E2kRuleProp

### e2k_rule_extract_proptag ()

    gboolean    e2k_rule_extract_proptag        (guint8 **ptr,
                                                 int *len,
                                                 E2kRuleProp *prop);

Reads a proptag from the rule at **`ptr` into *`prop` and updates *`ptr` and *`len` accordingly.

`ptr` : | pointer to a pointer into a binary rule
`len` : | pointer to the remaining length of *`ptr`
`prop` : | poitner to an E2kRuleProp
Returns : | success or failure

### e2k_rule_append_propvalue ()

    void        e2k_rule_append_propvalue       (GByteArray *ba,
                                                 E2kPropValue *pv);

Appends a representation of `pv` (the proptag and its value) to the rule in `ba`

`ba` : | a byte array containing a binary rule
`pv` : | an E2kPropValue

### e2k_rule_extract_propvalue ()

    gboolean    e2k_rule_extract_propvalue      (guint8 **ptr,
                                                 int *len,
                                                 E2kPropValue *pv);

Reads a representation of an E2kPropValue from the rule at **`ptr` into *`pv` and updates *`ptr` and *`len` accordingly.

`ptr` : | pointer to a pointer into a binary rule
`len` : | pointer to the remaining length of *`ptr`
`pv` : | pointer to an E2kPropValue
Returns : | success or failure

### e2k_rule_free_propvalue ()

    void        e2k_rule_free_propvalue         (E2kPropValue *pv);

Frees `pv`

`pv` : | an E2kPropValue

### e2k_rule_write_uint32 ()

    void        e2k_rule_write_uint32           (guint8 *ptr,
                                                 guint32 val);

Writes `val` into the rule at `ptr`

`ptr` : | pointer into a binary rule
`val` : | a uint32 value

### e2k_rule_append_uint32 ()

    void        e2k_rule_append_uint32          (GByteArray *ba,
                                                 guint32 val);

Appends `val` to the rule in `ba`

`ba` : | a byte array containing a binary rule
`val` : | a uint32 value

### e2k_rule_read_uint32 ()

    guint32     e2k_rule_read_uint32            (guint8 *ptr);

Reads a uint32 value from the rule at `ptr`

`ptr` : | pointer into a binary rule
Returns : | the uint32 value

### e2k_rule_extract_uint32 ()

    gboolean    e2k_rule_extract_uint32         (guint8 **ptr,
                                                 int *len,
                                                 guint32 *val);

Reads a uint32 value from the rule at **`ptr` into *`val` and updates *`ptr` and *`len` accordingly.

`ptr` : | pointer to a pointer into a binary rule
`len` : | pointer to the remaining length of *`ptr`
`val` : | pointer to a uint32 value
Returns : | success or failure

### e2k_rule_write_uint16 ()

    void        e2k_rule_write_uint16           (guint8 *ptr,
                                                 guint16 val);

Writes `val` into the rule at `ptr`

`ptr` : | pointer into a binary rule
`val` : | a uint16 value

### e2k_rule_append_uint16 ()

    void        e2k_rule_append_uint16          (GByteArray *ba,
                                                 guint16 val);

Appends `val` to the rule in `ba`

`ba` : | a byte array containing a binary rule
`val` : | a uint16 value

### e2k_rule_read_uint16 ()

    guint16     e2k_rule_read_uint16            (guint8 *ptr);

Reads a uint16 value from the rule at `ptr`

`ptr` : | pointer into a binary rule
Returns : | the uint16 value

### e2k_rule_extract_uint16 ()

    gboolean    e2k_rule_extract_uint16         (guint8 **ptr,
                                                 int *len,
                                                 guint16 *val);

Reads a uint16 value from the rule at **`ptr` into *`val` and updates *`ptr` and *`len` accordingly.

`ptr` : | pointer to a pointer into a binary rule
`len` : | pointer to the remaining length of *`ptr`
`val` : | pointer to a uint16 value
Returns : | success or failure

### e2k_rule_append_byte ()

    void        e2k_rule_append_byte            (GByteArray *ba,
                                                 guint8 val);

Appends `val` to the rule in `ba`

`ba` : | a byte array containing a binary rule
`val` : | a byte value

### e2k_rule_extract_byte ()

    gboolean    e2k_rule_extract_byte           (guint8 **ptr,
                                                 int *len,
                                                 guint8 *val);

Reads a byte value from the rule at **`ptr` into *`val` and updates *`ptr` and *`len` accordingly.

`ptr` : | pointer to a pointer into a binary rule
`len` : | pointer to the remaining length of *`ptr`
`val` : | pointer to a byte value
Returns : | success or failure

### e2k_rule_append_string ()

    void        e2k_rule_append_string          (GByteArray *ba,
                                                 const char *str);

Appends `str` to the rule in `ba`

`ba` : | a byte array containing a binary rule
`str` : | a (Windows) locale-encoded string

### e2k_rule_extract_string ()

    gboolean    e2k_rule_extract_string         (guint8 **ptr,
                                                 int *len,
                                                 char **str);

Reads a (Windows) locale-encoded string from the rule at **`ptr` into *`str` and updates *`ptr` and *`len` accordingly.

`ptr` : | pointer to a pointer into a binary rule
`len` : | pointer to the remaining length of *`ptr`
`str` : | pointer to a string pointer
Returns : | success or failure

### e2k_rule_append_unicode ()

    void        e2k_rule_append_unicode         (GByteArray *ba,
                                                 const char *str);

Appends `str` to the rule in `ba`

`ba` : | a byte array containing a binary rule
`str` : | a UTF-8 string

### e2k_rule_extract_unicode ()

    gboolean    e2k_rule_extract_unicode        (guint8 **ptr,
                                                 int *len,
                                                 char **str);

Reads a Unicode-encoded string from the rule at **`ptr` into *`str` and updates *`ptr` and *`len` accordingly.

`ptr` : | pointer to a pointer into a binary rule
`len` : | pointer to the remaining length of *`ptr`
`str` : | pointer to a string pointer
Returns : | success or failure

### e2k_rule_append_binary ()

    void        e2k_rule_append_binary          (GByteArray *ba,
                                                 GByteArray *data);

Appends `data` (with a 2-byte length prefix) to the rule in `ba`

`ba` : | a byte array containing a binary rule
`data` : | binary data

### e2k_rule_extract_binary ()

    gboolean    e2k_rule_extract_binary         (guint8 **ptr,
                                                 int *len,
                                                 GByteArray **data);

Reads binary data (preceded by a 2-byte length) from the rule at **`ptr` into *`data` and updates *`ptr` and *`len` accordingly.

`ptr` : | pointer to a pointer into a binary rule
`len` : | pointer to the remaining length of *`ptr`
`data` : | pointer to a GByteArray
Returns : | success or failure

## See Also

E2kRestriction, E2kAction