From 4b578ad52b06ae220b932e30a4a8ae2a2915289b Mon Sep 17 00:00:00 2001 From: "Dirk-Jan C. Binnema" Date: Fri, 8 Jan 2010 20:52:50 +0200 Subject: [PATCH] * mu-msg-fields: document public functions --- src/mu-msg-fields.c | 6 +-- src/mu-msg-fields.h | 122 ++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 121 insertions(+), 7 deletions(-) diff --git a/src/mu-msg-fields.c b/src/mu-msg-fields.c index f53e4f4a..2449a8f4 100644 --- a/src/mu-msg-fields.c +++ b/src/mu-msg-fields.c @@ -21,9 +21,9 @@ #include "mu-msg-fields.h" enum _FieldFlags { - FLAG_XAPIAN = 1 << 1, /* field stored as a string the in xapian db*/ - FLAG_GMIME = 1 << 2, /* field retrieved by reading msg with gmime */ - FLAG_XAPIAN_INDEX = 1 << 3 /* field is indexed in xapian */ + FLAG_XAPIAN = 1 << 1, /* field stored as a string in xapian db */ + FLAG_GMIME = 1 << 2, /* field retrieved by through gmime */ + FLAG_XAPIAN_INDEX = 1 << 3 /* field is indexed in xapian */ }; typedef enum _FieldFlags FieldFlags; diff --git a/src/mu-msg-fields.h b/src/mu-msg-fields.h index 8e325017..7df84ebe 100644 --- a/src/mu-msg-fields.h +++ b/src/mu-msg-fields.h @@ -61,28 +61,142 @@ enum _MuMsgFieldType { typedef enum _MuMsgFieldType MuMsgFieldType; static const guint MU_MSG_FIELD_TYPE_NONE = MU_MSG_FIELD_TYPE_NUM + 1; - typedef void (*MuMsgFieldForEachFunc) (const MuMsgField *field, gconstpointer data); + +/** + * iterator over all possible message fields + * + * @param func a function called for each field + * @param data a user data pointer passed the callback function + */ void mu_msg_field_foreach (MuMsgFieldForEachFunc func, gconstpointer data); +/** + * get the name of the field -- this a name that can be use in queries, + * ie. 'subject:foo', with 'subject' being the name + * + * @param field a MuMsgField + * + * @return the name of the field as a constant string, or + * NULL if the field is unknown + */ const char* mu_msg_field_name (const MuMsgField *field) G_GNUC_CONST; + +/** + * get the shortcut of the field -- this a shortcut that can be use in + * queries, ie. 's:foo', with 's' meaning 'subject' being the name + * + * @param field a MuMsgField + * + * @return the shortcut of the field as a constant string, or + * NULL if the field is unknown + */ const char* mu_msg_field_shortcut (const MuMsgField *field) G_GNUC_CONST; + +/** + * get the xapian prefix of the field -- that is, the prefix used in + * the Xapian database to identify the field + * + * @param field a MuMsgField + * + * @return the xapian prefix of the field as a constant string, or + * NULL if the field is unknown + */ const char* mu_msg_field_xapian_prefix (const MuMsgField *field) G_GNUC_PURE; +/** + * get the numerical ID of the field + * + * @param field a MuMsgField + * + * @return an id, or MU_MSG_FIELD_TYPE_NONE if the field is not known + */ MuMsgFieldId mu_msg_field_id (const MuMsgField *field) G_GNUC_CONST; + + +/** + * get the type of the field (string, size, time etc.) + * + * @param field a MuMsgField + * + * @return the type of the field (a #MuMsgFieldType), or + * MU_MSG_FIELD_TYPE_NONE if it is not found + */ MuMsgFieldType mu_msg_field_type (const MuMsgField *field) G_GNUC_CONST; -gboolean mu_msg_field_is_numeric (const MuMsgField *field) G_GNUC_CONST; +/** + * is the field numeric (has type MU_MSG_FIELD_TYPE_(BYTESIZE|TIME_T|INT))? + * + * @param field a MuMsgField + * + * @return TRUE if the field is numeric, FALSE otherwise + */ +gboolean mu_msg_field_is_numeric (const MuMsgField *field) G_GNUC_CONST; + +/** + * is the field Xapian-enabled? That is, should this field be stored + * (as a string) in the Xapian database? + * + * @param field a MuMsgField + * + * @return TRUE if the field is Xapian-enabled, FALSE otherwise + */ gboolean mu_msg_field_is_xapian_enabled (const MuMsgField *field) G_GNUC_PURE; -gboolean mu_msg_field_is_gmime_enabled (const MuMsgField *field) G_GNUC_PURE; + + +/** + * is the field Xapian-indexable? That is, should this field be + * indexed in the in the Xapian database, so we can use the all the + * phrasing, stemming etc. magic + * + * @param field a MuMsgField + * + * @return TRUE if the field is Xapian-enabled, FALSE otherwise + */ gboolean mu_msg_field_is_xapian_indexable (const MuMsgField *field) G_GNUC_PURE; + +/** + * is the field gmime-enabled? That is, can be field be retrieved + * using GMime? + * + * @param field a MuMsgField + * + * @return TRUE if the field is Gmime-enabled, FALSE otherwise + */ +gboolean mu_msg_field_is_gmime_enabled (const MuMsgField *field) G_GNUC_PURE; + + +/** + * get the corresponding MuMsgField for a name (as in mu_msg_field_name) + * + * @param str a name + * + * @return a MuMsgField, or NULL if it could not be found + */ const MuMsgField* mu_msg_field_from_name (const char* str) G_GNUC_PURE; + + +/** + * get the corresponding MuMsgField for a shortcut (as in mu_msg_field_shortcut) + * + * @param kar a shortcut character + * + * @return a MuMsgField, or NULL if it could not be found + */ const MuMsgField* mu_msg_field_from_shortcut (char kar) G_GNUC_CONST; -const MuMsgField* mu_msg_field_from_id (MuMsgFieldId) G_GNUC_CONST; + +/** + * get the corresponding MuMsgField for an id (as in mu_msg_field_id) + * + * @param id an id + * + * @return a MuMsgField, or NULL if it could not be found + */ +const MuMsgField* mu_msg_field_from_id (MuMsgFieldId id) G_GNUC_CONST; G_END_DECLS