## 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 gchar *propname);
                        E2kPropValue;
    void                e2k_rule_append_proptag             (GByteArray *ba,
                                                             E2kRuleProp *prop);
    gboolean            e2k_rule_extract_proptag            (guint8 **ptr,
                                                             gint *len,
                                                             E2kRuleProp *prop);
    void                e2k_rule_append_propvalue           (GByteArray *ba,
                                                             E2kPropValue *pv);
    gboolean            e2k_rule_extract_propvalue          (guint8 **ptr,
                                                             gint *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,
                                                             gint *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,
                                                             gint *len,
                                                             guint16 *val);
    void                e2k_rule_append_byte                (GByteArray *ba,
                                                             guint8 val);
    gboolean            e2k_rule_extract_byte               (guint8 **ptr,
                                                             gint *len,
                                                             guint8 *val);
    void                e2k_rule_append_string              (GByteArray *ba,
                                                             const gchar *str);
    gboolean            e2k_rule_extract_string             (guint8 **ptr,
                                                             gint *len,
                                                             gchar **str);
    void                e2k_rule_append_unicode             (GByteArray *ba,
                                                             const gchar *str);
    gboolean            e2k_rule_extract_unicode            (guint8 **ptr,
                                                             gint *len,
                                                             gchar **str);
    void                e2k_rule_append_binary              (GByteArray *ba,
                                                             GByteArray *data);
    gboolean            e2k_rule_extract_binary             (guint8 **ptr,
                                                             gint *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 {
    	gchar           *name;
    	guint32         sequence;
    	guint32         state;
    	guint32         user_flags;
    	guint32         level;
    	guint32         condition_lcid;
    	E2kRestriction *condition;
    	GPtrArray      *actions;
    	gchar           *provider;
    	GByteArray     *provider_data;
    } E2kRule;

### E2kRules

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

### 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;

### 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 gchar *name;
    	guint32     proptag;
    } E2kRuleProp;

### e2k_rule_prop_set ()

    void                e2k_rule_prop_set                   (E2kRuleProp *prop,
                                                             const gchar *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;

### 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,
                                                             gint *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,
                                                             gint *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,
                                                             gint *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,
                                                             gint *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,
                                                             gint *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 gchar *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,
                                                             gint *len,
                                                             gchar **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 gchar *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,
                                                             gint *len,
                                                             gchar **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,
                                                             gint *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