mu/src/mu-msg-iter.h

/*
** Copyright (C) 2008-2010 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
**
** This program is free software; you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation; either version 3 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program; if not, write to the Free Software Foundation,
** Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
**
*/

#ifndef __MU_MSG_ITER_H__
#define __MU_MSG_ITER_H__

#include <glib.h>
#include <mu-msg.h>

G_BEGIN_DECLS


/**
 * MuMsgIter is a structure to iterate over the results of a
 * query. You can iterate only in one-direction, and you can do it
 * only once.
 * 
 */

struct _MuMsgIter;
typedef struct _MuMsgIter MuMsgIter;

/**
 * get the next message (which you got from
 * e.g. mu_query_run)
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return TRUE if it succeeded, FALSE otherwise (e.g., because there
 * are no more messages in the query result)
 */
gboolean         mu_msg_iter_next              (MuMsgIter *iter);


/**
 * does this iterator point past the end of the list?
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return TRUE if the iter points past end of the list, FALSE
 * otherwise
 */
gboolean         mu_msg_iter_is_done (MuMsgIter *iter);


/**
 * destroy the sequence of messages; ie. /all/ of them
 * 
 * @param msg a valid MuMsgIter message or NULL
 */
void		 mu_msg_iter_destroy           (MuMsgIter *iter);


/**
 * get the corresponding MuMsg for this iter; this requires the actual
 * message file to be present at the expected place in the maildir in
 * the file system. Note, it's faster to use the database fields (the
 * various mu_msg_iter_get_... functions), so MuMsg should use only
 * when information is needed that is not provided from the iter).
 * 
 * @param iter a valid MuMsgIter instance 
 * @param err which receives error info or NULL. err is only filled
 * when the function returns NULL
 * 
 * @return a MuMsg instance, or NULL in case of error. Use
 * mu_msg_unref when the instance is no longer needed
 */
MuMsg* mu_msg_iter_get_msg (MuMsgIter *iter, GError **err)
        G_GNUC_MALLOC G_GNUC_WARN_UNUSED_RESULT;



/**
 * get the document id for the current message
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the docid or (unsigned int)-1 in case of error
 */
unsigned int     mu_msg_iter_get_docid         (MuMsgIter *iter);



/**
 * get the index for this iterator (ie. somewhere between [0..n-1],
 * with being the number of matches, and increasing 1 for each
 * iter_next)
 * 
 * @param iter a valid MuMsgIter 
 * 
 * @return the index or (unsigned int)-1 in case of error

 */
unsigned int      mu_msg_iter_get_index        (MuMsgIter *iter);


/**
 * get the full path of the message file
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the path, or NULL in case of error
 */
const char*      mu_msg_iter_get_path          (MuMsgIter *iter);


/**
 * get the maildir of the message - e.g., a message file 
 * /home/user/Maildir/foo/bar/cur/abc123 would have maildir
 *   "/foo/bar"
 * 
 * @param iter a valid MuMsgIter iterator
 *  * @return the path, or NULL in case of error
 */
const char*      mu_msg_iter_get_maildir (MuMsgIter *iter);



/**
 * get the msgid of the message
 *  
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the msgid or NULL in case of error
 */
const char*      mu_msg_iter_get_msgid (MuMsgIter *iter);



/**
 * get the size of the message in Kb
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the size, or 0 in case of error
 */
size_t           mu_msg_iter_get_size          (MuMsgIter *iter);  

/**
 * get the timestamp (ctime) of the message file
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the size, or 0 in case of error
 */
time_t           mu_msg_iter_get_timestamp     (MuMsgIter *iter);  

/**
 * get the sent time of the message
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the time, or 0 in case of error
 */
time_t           mu_msg_iter_get_date          (MuMsgIter *iter);  

/**
 * get the message sender(s) of the message
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the time, or 0 in case of error
 */
const char*      mu_msg_iter_get_from          (MuMsgIter *iter);

/**
 * get the message recipient (To:) of the message
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the To-recipient(s), or NULL in case of error
 */
const char*      mu_msg_iter_get_to            (MuMsgIter *iter);


/**
 * get the 'carbon-copy' recipient(s) (Cc:) of the message
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the Cc-recipient(s), or NULL in case of error
 */
const char*      mu_msg_iter_get_cc            (MuMsgIter *iter);


/**
 * get the 'blind carbon-copy' message recipient(s) (Bcc:) of the
 * message
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the Bcc-recipient(s), or NULL in case of error
 */
const char*      mu_msg_iter_get_bcc            (MuMsgIter *iter);

/**
 * get the subject of the message
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the subject, or NULL in case of error
 */
const char*      mu_msg_iter_get_subject       (MuMsgIter *iter);

/**
 * get the message flags 
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the message flags, or MU_MSG_FLAG_UNKNOWN
 */
MuMsgFlags       mu_msg_iter_get_flags         (MuMsgIter *iter);


/**
 * get the message priority 
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the message priority, or MU_MSG_PRIO_NONE
 */
MuMsgPrio    mu_msg_iter_get_prio      (MuMsgIter *iter);



/**
 * get the references (References: and Reply-To:) as a comma-separated
 * string, with the last one pointing at the parent
 * 
 * @param iter a valid MuMsgIter iterator
 * 
 * @return the message references, or NULL in case of error or if
 * there is none
 */
const char* mu_msg_iter_get_refs (MuMsgIter *iter);

/**
 * get some message field
 * 
 * @param iter a valid MuMsgIter iterator
 * @param field the string field to retrieve
 * 
 * @return the field value, or NULL
 */
const gchar*     mu_msg_iter_get_field         (MuMsgIter *iter, 
						MuMsgFieldId mfid);

/**
 * get some numeric message field
 * 
 * @param iter a valid MuMsgIter iterator
 * @param field the numeric field to retrieve
 * 
 * @return the field value, or -1 in case of error
 */
gint64           mu_msg_iter_get_field_numeric     (MuMsgIter *iter, 
						    MuMsgFieldId mfid);
G_END_DECLS

#endif /*__MU_MSG_ITER_H__*/