E2kRestriction

## E2kRestriction E2kRestriction — Search criteria |

## Synopsis

    struct      E2kRestriction;

    E2kRestriction* e2k_restriction_and         (int nrns,
                                                 E2kRestriction **rns,
                                                 gboolean unref);
    E2kRestriction* e2k_restriction_andv        (E2kRestriction *rn,
                                                 ...);
    E2kRestriction* e2k_restriction_or          (int 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 char *propname,
                                                 E2kRestrictionFuzzyLevel fuzzy_level,
                                                 const char *value);
    enum        E2kRestrictionRelop;
    E2kRestriction* e2k_restriction_prop_bool   (const char *propname,
                                                 E2kRestrictionRelop relop,
                                                 gboolean value);
    E2kRestriction* e2k_restriction_prop_int    (const char *propname,
                                                 E2kRestrictionRelop relop,
                                                 int value);
    E2kRestriction* e2k_restriction_prop_date   (const char *propname,
                                                 E2kRestrictionRelop relop,
                                                 const char *value);
    E2kRestriction* e2k_restriction_prop_string (const char *propname,
                                                 E2kRestrictionRelop relop,
                                                 const char *value);
    E2kRestriction* e2k_restriction_prop_binary (const char *propname,
                                                 E2kRestrictionRelop relop,
                                                 gconstpointer data,
                                                 int len);
    E2kRestriction* e2k_restriction_compare     (const char *propname1,
                                                 E2kRestrictionRelop relop,
                                                 const char *propname2);
    enum        E2kRestrictionBitop;
    E2kRestriction* e2k_restriction_bitmask     (const char *propname,
                                                 E2kRestrictionBitop bitop,
                                                 guint32 mask);
    E2kRestriction* e2k_restriction_size        (const char *propname,
                                                 E2kRestrictionRelop relop,
                                                 guint32 size);
    E2kRestriction* e2k_restriction_exist       (const char *propname);
    E2kRestriction* e2k_restriction_sub         (const char *subtable,
                                                 E2kRestriction *rn,
                                                 gboolean unref);

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

    char*       e2k_restriction_to_sql          (E2kRestriction *rn);

## Description

## Details

### struct E2kRestriction

    struct E2kRestriction {
    };

This represents a MAPI SRestriction structure.

### e2k_restriction_and ()

    E2kRestriction* e2k_restriction_and         (int 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          (int 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;

This is used in content restrictions to determine how to compare the data. See `e2k_restriction_content()` for more information.

### E2K_FL_MATCH_TYPE()

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

This extracts just the “match type” part of the fuzzy level. (`E2K_FL_FULLSTRING`, `E2K_FL_SUBSTRING`, or `E2K_FL_PREFIX`)

`fl` : | an E2kRestrictionFuzzyLevel
Returns : | the “match type” part of `fl`

### e2k_restriction_content ()

    E2kRestriction* e2k_restriction_content     (const char *propname,
                                                 E2kRestrictionFuzzyLevel fuzzy_level,
                                                 const char *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;

This is used in property restrictions to determine how to compare the data:

`E2K_RELOP_LT` | property value is less than given value
`E2K_RELOP_LE` | property value is less than or equal to given value
`E2K_RELOP_GT` | property value is greater than given value
`E2K_RELOP_GE` | property value is greater than or equal to given value
`E2K_RELOP_EQ` | property value is equal to given value
`E2K_RELOP_NE` | property value is not equal to given value
`E2K_RELOP_RE` | property value matches the given regular expression
`E2K_RELOP_DL_MEMBER` | property value names a member of the given distribution list

### e2k_restriction_prop_bool ()

    E2kRestriction* e2k_restriction_prop_bool   (const char *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 char *propname,
                                                 E2kRestrictionRelop relop,
                                                 int 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 char *propname,
                                                 E2kRestrictionRelop relop,
                                                 const char *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 char *propname,
                                                 E2kRestrictionRelop relop,
                                                 const char *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 char *propname,
                                                 E2kRestrictionRelop relop,
                                                 gconstpointer data,
                                                 int 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 char *propname1,
                                                 E2kRestrictionRelop relop,
                                                 const char *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;

This is used in bitmask restrictions to determine how to compare the data to the mask:

`E2K_BMR_EQZ` | property value logically ANDed with mask equals 0
`E2K_BMR_NEZ` | property value logically ANDed with mask does not equal 0

### e2k_restriction_bitmask ()

    E2kRestriction* e2k_restriction_bitmask     (const char *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 char *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 char *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 char *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 ()

    char*       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.