e2k-restriction

e2k-restriction — Search criteria

Synopsis




struct      E2kRestriction;
enum        E2kRestrictionType;
enum        E2kRestrictionRelop;
enum        E2kRestrictionBitop;
enum        E2kRestrictionFuzzyLevel;
#define     E2K_FL_MATCH_TYPE               (fl)

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);
E2kRestriction* e2k_restriction_content     (const char *propname,
                                             E2kRestrictionFuzzyLevel fuzzy_level,
                                             const char *value);
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);
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);
gboolean    e2k_restriction_extract         (guint8 **data,
                                             int *len,
                                             E2kRestriction **rn);
void        e2k_restriction_append          (GByteArray *ba,
                                             E2kRestriction *rn);

Description

Details

struct E2kRestriction

struct E2kRestriction {

	E2kRestrictionType type;
	int ref_count;

	union {
		struct {
			guint            nrns;
			E2kRestriction **rns;
		} and;

		struct {
			guint            nrns;
			E2kRestriction **rns;
		} or;

		struct {
			E2kRestriction *rn;
		} not;

		struct {
			E2kRestrictionFuzzyLevel fuzzy_level;
			E2kPropValue             pv;
		} content;

		struct {
			E2kRestrictionRelop  relop;
			E2kPropValue         pv;
		} property;

		struct {
			E2kRestrictionRelop  relop;
			E2kRuleProp          prop1;
			E2kRuleProp          prop2;
		} compare;

		struct {
			E2kRestrictionBitop  bitop;
			E2kRuleProp          prop;
			guint32              mask;
		} bitmask;

		struct {
			E2kRestrictionRelop  relop;
			E2kRuleProp          prop;
			guint32              size;
		} size;

		struct {
			E2kRuleProp prop;
		} exist;

		struct {
			E2kRuleProp     subtable;
			E2kRestriction *rn;
		} sub;

		struct {
			guint32         nprops;
			E2kRestriction *rn;
			E2kPropValue   *props;
		} comment;
	} res;
};

This represents a MAPI SRestriction structure.


enum E2kRestrictionType

typedef enum {
	E2K_RESTRICTION_AND		= 0,
	E2K_RESTRICTION_OR		= 1,
	E2K_RESTRICTION_NOT		= 2,
	E2K_RESTRICTION_CONTENT		= 3,
	E2K_RESTRICTION_PROPERTY	= 4,
	E2K_RESTRICTION_COMPAREPROPS	= 5,
	E2K_RESTRICTION_BITMASK		= 6,
	E2K_RESTRICTION_SIZE		= 7,
	E2K_RESTRICTION_EXIST		= 8,
	E2K_RESTRICTION_SUBRESTRICTION	= 9,
	E2K_RESTRICTION_COMMENT		= 10
} E2kRestrictionType;

This indicates the type of restriction. See the descriptions of the various constructors below for more information.


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_LTproperty value is less than given value
E2K_RELOP_LEproperty value is less than or equal to given value
E2K_RELOP_GTproperty value is greater than given value
E2K_RELOP_GEproperty value is greater than or equal to given value
E2K_RELOP_EQproperty value is equal to given value
E2K_RELOP_NEproperty value is not equal to given value
E2K_RELOP_REproperty value matches the given regular expression
E2K_RELOP_DL_MEMBERproperty value names a member of the given distribution list

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_EQZproperty value logically ANDed with mask equals 0
E2K_BMR_NEZproperty value logically ANDed with mask does not equal 0

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_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

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

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

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.

e2k_restriction_extract ()

gboolean    e2k_restriction_extract         (guint8 **data,
                                             int *len,
                                             E2kRestriction **rn);

Attempts to extract a restriction from *data, which contains a binary-encoded restriction from a server-side rule.

On success, *rn will contain the extracted restriction, *data will be advanced past the end of the restriction data, and *len will be decremented accordingly.

data : pointer to data pointer
len : pointer to data length
rn : pointer to variable to store the extracted restriction in
Returns : success or failure

e2k_restriction_append ()

void        e2k_restriction_append          (GByteArray *ba,
                                             E2kRestriction *rn);

Appends rn to ba as part of a server-side rule.

ba : a buffer into which a server-side rule is being constructed
rn : the restriction to append to ba