E2kRestriction

## E2kRestriction E2kRestriction — Search criteria |

## Synopsis

    struct              E2kRestriction;

    E2kRestriction *    e2k_restriction_and                 (gint nrns,
                                                             E2kRestriction **rns,
                                                             gboolean unref);
    E2kRestriction *    e2k_restriction_andv                (E2kRestriction *rn,
                                                             ...);
    E2kRestriction *    e2k_restriction_or                  (gint nrns,
                                                             E2kRestriction **rns,
                                                             gboolean unref);
    E2kRestriction *    e2k_restriction_orv                 (E2kRestriction *rn,
                                                             ...);
    E2kRestriction *    e2k_restriction_not                 (E2kRestriction *rn,
                                                             gboolean unref);
    enum                E2kRestrictionFuzzyLevel;
    #define             E2K_FL_MATCH_TYPE                   (fl)
    E2kRestriction *    e2k_restriction_content             (const gchar *propname,
                                                             E2kRestrictionFuzzyLevel fuzzy_level,
                                                             const gchar *value);
    enum                E2kRestrictionRelop;
    E2kRestriction *    e2k_restriction_prop_bool           (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             gboolean value);
    E2kRestriction *    e2k_restriction_prop_int            (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             gint value);
    E2kRestriction *    e2k_restriction_prop_date           (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             const gchar *value);
    E2kRestriction *    e2k_restriction_prop_string         (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             const gchar *value);
    E2kRestriction *    e2k_restriction_prop_binary         (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             gconstpointer data,
                                                             gint len);
    E2kRestriction *    e2k_restriction_compare             (const gchar *propname1,
                                                             E2kRestrictionRelop relop,
                                                             const gchar *propname2);
    enum                E2kRestrictionBitop;
    E2kRestriction *    e2k_restriction_bitmask             (const gchar *propname,
                                                             E2kRestrictionBitop bitop,
                                                             guint32 mask);
    E2kRestriction *    e2k_restriction_size                (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             guint32 size);
    E2kRestriction *    e2k_restriction_exist               (const gchar *propname);
    E2kRestriction *    e2k_restriction_sub                 (const gchar *subtable,
                                                             E2kRestriction *rn,
                                                             gboolean unref);

    void                e2k_restriction_ref                 (E2kRestriction *rn);
    void                e2k_restriction_unref               (E2kRestriction *rn);

    gchar *             e2k_restriction_to_sql              (E2kRestriction *rn);

## Description

## Details

### struct E2kRestriction

    struct E2kRestriction {
    };

### e2k_restriction_and ()

    E2kRestriction *    e2k_restriction_and                 (gint nrns,
                                                             E2kRestriction **rns,
                                                             gboolean unref);

Creates a new restriction which is true if all of the restrictions in `rns` are true.

If `unref` is `TRUE`, then `e2k_restriction_and()` is essentially stealing the caller's references on the restrictions. If it is `FALSE`, then `e2k_restriction_and()` will acquire its own references to each of the restrictions.

`nrns` : | length of `rns`
`rns` : | an array of E2kRestriction
`unref` : | whether or not to unref the restrictions when it is done
Returns : | the new restriction

### e2k_restriction_andv ()

    E2kRestriction *    e2k_restriction_andv                (E2kRestriction *rn,
                                                             ...);

Creates a new restriction which is true if all of the passed-in restrictions are true. `e2k_restriction_andv()` steals the caller's reference on each of the passed-in restrictions.

`rn` : | an E2kRestriction
`...` : | a `NULL`-terminated list of additional E2kRestrictions
Returns : | the new restriction

### e2k_restriction_or ()

    E2kRestriction *    e2k_restriction_or                  (gint nrns,
                                                             E2kRestriction **rns,
                                                             gboolean unref);

Creates a new restriction which is true if any of the restrictions in `rns` are true.

`nrns` : | length of `rns`
`rns` : | an array of E2kRestriction
`unref` : | see `e2k_restriction_and()`
Returns : | the new restriction

### e2k_restriction_orv ()

    E2kRestriction *    e2k_restriction_orv                 (E2kRestriction *rn,
                                                             ...);

Creates a new restriction which is true if any of the passed-in restrictions are true. `e2k_restriction_orv()` steals the caller's reference on each of the passed-in restrictions.

`rn` : | an E2kRestriction
`...` : | a `NULL`-terminated list of additional E2kRestrictions
Returns : | the new restriction

### e2k_restriction_not ()

    E2kRestriction *    e2k_restriction_not                 (E2kRestriction *rn,
                                                             gboolean unref);

Creates a new restriction which is true if `rn` is false.

`rn` : | an E2kRestriction
`unref` : | see `e2k_restriction_and()`
Returns : | the new restriction

### enum E2kRestrictionFuzzyLevel

    typedef enum {
    	E2K_FL_FULLSTRING     = 0x00000,
    	E2K_FL_SUBSTRING      = 0x00001,
    	E2K_FL_PREFIX         = 0x00002,
    	E2K_FL_SUFFIX         = 0x00003, /* Not a MAPI constant */

    	E2K_FL_IGNORECASE     = 0x10000,
    	E2K_FL_IGNORENONSPACE = 0x20000,
    	E2K_FL_LOOSE          = 0x40000
    } E2kRestrictionFuzzyLevel;

### E2K_FL_MATCH_TYPE()

    #define E2K_FL_MATCH_TYPE(fl) ((fl) & 0x3)

`fl` : |

### e2k_restriction_content ()

    E2kRestriction *    e2k_restriction_content             (const gchar *propname,
                                                             E2kRestrictionFuzzyLevel fuzzy_level,
                                                             const gchar *value);

Creates a new restriction that is true for objects where the indicated property's value matches `value` according to `fuzzy_level`.

For a WebDAV SEARCH, `fuzzy_level` should be `E2K_FL_FULLSTRING`, `E2K_FL_SUBSTRING`, `E2K_FL_PREFIX`, or `E2K_FL_SUFFIX`.

For a MAPI restriction, `fuzzy_level` may not be `E2K_FL_SUFFIX`, but may be ORed with any of the additional values `E2K_FL_IGNORECASE`, `E2K_FL_IGNORENONSPACE`, or `E2K_FL_LOOSE`.

To compare a property's sort order to another string, use `e2k_restriction_prop_string()`.

`propname` : | text property to compare against
`fuzzy_level` : | how to compare
`value` : | value to compare against
Returns : | the new restriction

### enum E2kRestrictionRelop

    typedef enum {
    	E2K_RELOP_LT = 0,
    	E2K_RELOP_LE = 1,
    	E2K_RELOP_GT = 2,
    	E2K_RELOP_GE = 3,
    	E2K_RELOP_EQ = 4,
    	E2K_RELOP_NE = 5,
    	E2K_RELOP_RE = 6,

    	E2K_RELOP_DL_MEMBER = 100
    } E2kRestrictionRelop;

### e2k_restriction_prop_bool ()

    E2kRestriction *    e2k_restriction_prop_bool           (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             gboolean value);

Creates a new restriction that is true for objects where the indicated property matches `relop` and `value`.

`propname` : | boolean property to compare against
`relop` : | `E2K_RELOP_EQ` or `E2K_RELOP_NE`
`value` : | `TRUE` or `FALSE`
Returns : | the new restriction

### e2k_restriction_prop_int ()

    E2kRestriction *    e2k_restriction_prop_int            (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             gint value);

Creates a new restriction that is true for objects where the indicated property matches `value` according to `relop`.

`propname` : | integer property to compare against
`relop` : | an E2kRestrictionRelop
`value` : | number to compare against
Returns : | the new restriction

### e2k_restriction_prop_date ()

    E2kRestriction *    e2k_restriction_prop_date           (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             const gchar *value);

Creates a new restriction that is true for objects where the indicated property matches `value` according to `relop`.

`propname` : | date/time property to compare against
`relop` : | an E2kRestrictionRelop
`value` : | date/time to compare against (as returned by `e2k_make_timestamp()`)
Returns : | the new restriction

### e2k_restriction_prop_string ()

    E2kRestriction *    e2k_restriction_prop_string         (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             const gchar *value);

Creates a new restriction that is true for objects where the indicated property matches `value` according to `relop`.

To do a substring match, use `e2k_restriction_content()`.

`propname` : | text property to compare against
`relop` : | an E2kRestrictionRelop
`value` : | text to compare against
Returns : | the new restriction

### e2k_restriction_prop_binary ()

    E2kRestriction *    e2k_restriction_prop_binary         (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             gconstpointer data,
                                                             gint len);

Creates a new restriction that is true for objects where the indicated property matches `value` according to `relop`.

`propname` : | binary property to compare against
`relop` : | `E2K_RELOP_EQ` or `E2K_RELOP_NE`
`data` : | data to compare against
`len` : | length of `data`
Returns : | the new restriction

### e2k_restriction_compare ()

    E2kRestriction *    e2k_restriction_compare             (const gchar *propname1,
                                                             E2kRestrictionRelop relop,
                                                             const gchar *propname2);

Creates a new restriction which is true for objects where `propname1` and `propname2` have the relationship described by `relop`.

`propname1` : | first property
`relop` : | an E2kRestrictionRelop
`propname2` : | second property
Returns : | the new restriction

### enum E2kRestrictionBitop

    typedef enum {
    	E2K_BMR_EQZ = 0,
    	E2K_BMR_NEZ = 1
    } E2kRestrictionBitop;

### e2k_restriction_bitmask ()

    E2kRestriction *    e2k_restriction_bitmask             (const gchar *propname,
                                                             E2kRestrictionBitop bitop,
                                                             guint32 mask);

Creates a new restriction that is true for objects where the indicated bits of the value of `propname` either are or aren't zero, as indicated by `bitop`.

This cannot be used for WebDAV SEARCH restrictions.

`propname` : | integer property to compare
`bitop` : | an E2kRestrictionBitop
`mask` : | mask of bits to compare against
Returns : | the new restriction

### e2k_restriction_size ()

    E2kRestriction *    e2k_restriction_size                (const gchar *propname,
                                                             E2kRestrictionRelop relop,
                                                             guint32 size);

Creates a new restriction which is true for objects where the size of the value of `propname` matches `size` according to `relop`.

This cannot be used for WebDAV SEARCH restrictions.

You probably do not want to use this. The standard idiom for checking the size of a message is to use `e2k_restriction_prop_int()` on its `PR_MESSAGE_SIZE` property, not to use `e2k_restriction_size()` on its `PR_BODY`.

`propname` : | property to compare
`relop` : | an E2kRestrictionRelop
`size` : | the size to compare `propname` to
Returns : | the new restriction

### e2k_restriction_exist ()

    E2kRestriction *    e2k_restriction_exist               (const gchar *propname);

Creates a new restriction which is true for objects that have a `propname` property.

This cannot be used for WebDAV SEARCH restrictions.

`propname` : | property to check
Returns : | the new restriction

### e2k_restriction_sub ()

    E2kRestriction *    e2k_restriction_sub                 (const gchar *subtable,
                                                             E2kRestriction *rn,
                                                             gboolean unref);

Creates a new restriction that is true for objects where `rn` is true when applied to the value of `subtable` on that object.

`subtable` is generally `PR_MESSAGE_RECIPIENTS` (for finding messages whose recipients match a given restriction) or `PR_MESSAGE_ATTACHMENTS` (for finding messages whose attachments match a given restriction).

This cannot be used for WebDAV SEARCH restrictions.

`subtable` : | the WebDAV name of a MAPI property of type PT_OBJECT
`rn` : | the restriction to apply against the values of `subtable`
`unref` : | see `e2k_restriction_and()`
Returns : | the new restriction

### e2k_restriction_ref ()

    void                e2k_restriction_ref                 (E2kRestriction *rn);

Refs `rn`.

`rn` : | a restriction

### e2k_restriction_unref ()

    void                e2k_restriction_unref               (E2kRestriction *rn);

Unrefs `rn`. If there are no more references to `rn`, it is freed.

`rn` : | a restriction

### e2k_restriction_to_sql ()

    gchar *             e2k_restriction_to_sql              (E2kRestriction *rn);

Converts `rn` to an SQL WHERE clause to be used with the WebDAV SEARCH method. Note that certain restriction types cannot be used in SQL, as mentioned in their descriptions above.

If the restriction matches all objects, the return value will be the empty string. Otherwise it will start with "WHERE ".

`rn` : | a restriction
Returns : | the SQL WHERE clause, which the caller must free, or `NULL` if `rn` could not be converted to SQL.