/**
* url_free_tags - Free a list of tags
* @param tags List of tags
+ *
+ * Tags are stored as a singly-linked list.
+ * Free all the strings and the list, itself.
*/
static void url_free_tags(struct UriTag *tags)
{
return false;
}
+/**
+ * free_tag_list - Free a list of tags
+ * @param tag_list List of tags
+ *
+ * Take a nm_hdrtag struct (a singly-linked list) and free the attached strings
+ * and the list itself.
+ */
static void free_tag_list(struct NmHdrTag **tag_list)
{
struct NmHdrTag *tmp = NULL;
*tag_list = 0;
}
+/**
+ * free_hdrdata - Free header data attached to an email
+ * @param data Header data
+ *
+ * Each email can have an attached nm_hdrdata struct, which contains things
+ * like the tags (labels). This function frees all the resources and the
+ * nm_hdrdata struct itself.
+ */
static void free_hdrdata(struct NmHdrData *data)
{
if (!data)
FREE(&data);
}
+/**
+ * free_ctxdata - Free data attached to the context
+ * @param data A mailbox CONTEXT
+ *
+ * The nm_ctxdata struct stores global NotMuch data, such as the connection to
+ * the database. This function will close the database, free the resources and
+ * the struct itself.
+ */
static void free_ctxdata(struct NmCtxData *data)
{
if (!data)
FREE(&data);
}
+/**
+ * new_ctxdata - Create a new nm_ctxdata object from a query
+ * @param uri NotMuch query string
+ * @return a new nm_ctxdata struct
+ *
+ * A new nm_ctxdata struct is created, then the query is parsed and saved
+ * within it. This should be freed using free_ctxdata().
+ */
static struct NmCtxData *new_ctxdata(char *uri)
{
struct NmCtxData *data = NULL;
return data;
}
+/**
+ * init_context - Add NotMuch data to the Context
+ * @param ctx A mailbox CONTEXT
+ * @return
+ * * 0 Success
+ * * -1 Error: Bad format
+ *
+ * Create a new nm_ctxdata struct and add it CONTEXT::data.
+ * NotMuch-specific data will be stored in this struct.
+ * This struct can be freed using free_hdrdata().
+ */
static int init_context(struct Context *ctx)
{
if (!ctx || (ctx->magic != MUTT_NOTMUCH))
return -1;
}
+/**
+ * db_trans_begin - Start a NotMuch database transaction
+ * @param data Header data
+ * @return
+ * * < 0 = error
+ * * 1 = new transaction started
+ * * 0 = already within transaction
+ */
static int db_trans_begin(struct NmCtxData *data)
{
if (!data || !data->db)
return 0;
}
+/**
+ * is_longrun - Is NotMuch in the middle of a long-running transaction
+ * @param data Header data
+ * @return true if it is
+ */
static int is_longrun(struct NmCtxData *data)
{
return data && data->longrun;
}
+/**
+ * get_database_mtime - Get the database modification time
+ * @param[in] data Struct holding database info
+ * @param[out] mtime Save the modification time
+ * @return
+ * * 0 Success (result in mtime)
+ * * -1 Error
+ *
+ * Get the "mtime" (modification time) of the database file.
+ * This is the time of the last update.
+ */
static int get_database_mtime(struct NmCtxData *data, time_t *mtime)
{
char path[_POSIX_PATH_MAX];
}
}
+/**
+ * nm2mutt_message_id - converts notmuch message Id to mutt message Id
+ * @param id NotMuch ID to convert
+ * @return Mutt message ID
+ *
+ * Caller must free the Mutt Message ID
+ */
static char *nm2mutt_message_id(const char *id)
{
size_t sz;
FREE(&newpath);
}
+/**
+ * append_replies - add all the replies to a given messages into the display
+ *
+ * Careful, this calls itself recursively to make sure we get everything.
+ */
static void append_replies(struct Context *ctx, notmuch_query_t *q,
notmuch_message_t *top, int dedup)
{
}
}
+/**
+ * append_thread - add each top level reply in the thread
+ *
+ * add each top level reply in the thread, and then add each reply to the top
+ * level replies
+ */
static void append_thread(struct Context *ctx, notmuch_query_t *q,
notmuch_thread_t *thread, int dedup)
{
return 0;
}
+/**
+ * update_header_flags - Update the header flags
+ *
+ * TODO: extract parsing of string to separate function, join
+ * update_header_tags and update_header_flags, which are given an array of
+ * tags.
+ */
static int update_header_flags(struct Context *ctx, struct Header *hdr, const char *tags)
{
char *tag = NULL, *end = NULL, *p = NULL;
void nm_query_window_forward(void)
{
if (NotmuchQueryWindowCurrentPosition != 0)
- NotmuchQueryWindowCurrentPosition -= 1;
+ NotmuchQueryWindowCurrentPosition--;
mutt_debug(2, "nm_query_window_forward (%d)\n", NotmuchQueryWindowCurrentPosition);
}
*/
void nm_query_window_backward(void)
{
- NotmuchQueryWindowCurrentPosition += 1;
+ NotmuchQueryWindowCurrentPosition++;
mutt_debug(2, "nm_query_window_backward (%d)\n", NotmuchQueryWindowCurrentPosition);
}
return rc;
}
+/**
+ * nm_get_all_tags - Fill a list with all notmuch tags
+ *
+ * If tag_list is NULL, just count the tags.
+ */
int nm_get_all_tags(struct Context *ctx, char **tag_list, int *tag_count)
{
struct NmCtxData *data = get_ctxdata(ctx);
}
+/**
+ * nm_open_mailbox - Open a notmuch virtual mailbox
+ * @param ctx A mailbox CONTEXT
+ * @return
+ * * 0 Success
+ * * -1 Error
+ */
+
static int nm_open_mailbox(struct Context *ctx)
{
notmuch_query_t *q = NULL;
return rc;
}
+/**
+ * nm_close_mailbox - Close a notmuch virtual mailbox
+ * @param ctx A mailbox CONTEXT
+ * @return
+ * * 0 Success
+ * * -1 Error
+ */
static int nm_close_mailbox(struct Context *ctx)
{
if (!ctx || (ctx->magic != MUTT_NOTMUCH))
return 0;
}
+/**
+ * nm_check_mailbox - Check a notmuch mailbox for new mail
+ * @param ctx A mailbox CONTEXT
+ * @param index_hint Remeber our place in the index
+ * @return
+ * * -1 Error
+ * * 0 QWQ
+ * * #MUTT_NEW_MAIL - new mail has arrived
+ * * #MUTT_REOPENED - mailbox closed and reopened
+ * * #MUTT_FLAGS - QWQ
+ */
static int nm_check_mailbox(struct Context *ctx, int *index_hint)
{
struct NmCtxData *data = get_ctxdata(ctx);
/* message already exists, merge flags */
h->active = true;
- /* check to see if the message has moved to a different
- * subdirectory. If so, update the associated filename.
+ /* Check to see if the message has moved to a different subdirectory.
+ * If so, update the associated filename.
*/
new = get_message_last_filename(m);
header_get_fullpath(h, old, sizeof(old));
new_flags ? MUTT_FLAGS : 0;
}
+/**
+ * nm_sync_mailbox - Sync a notmuch mailbox
+ * @param ctx A mailbox CONTEXT
+ * @param index_hint Remember our place in the index
+ */
static int nm_sync_mailbox(struct Context *ctx, int *index_hint)
{
struct NmCtxData *data = get_ctxdata(ctx);
return rc;
}
+/**
+ * nm_open_message - Open a message from a notmuch mailbox
+ * @param ctx A mailbox CONTEXT
+ * @param msg Message to open
+ * @param msgno Index of message to open
+ * @return
+ * * 0 Success
+ * * 1 Error
+ */
static int nm_open_message(struct Context *ctx, struct Message *msg, int msgno)
{
if (!ctx || !msg)
return !msg->fp;
}
+/**
+ * nm_close_message - Close a message
+ * @param ctx A mailbox CONTEXT
+ * @param msg Message to close
+ * @return
+ * * 0 Success
+ * * 1 Error
+ */
static int nm_close_message(struct Context *ctx, struct Message *msg)
{
if (!msg)
*/
struct SbEntry
{
- char box[STRING]; /**< formatted mailbox name */
- struct Buffy *buffy;
- bool is_hidden;
+ char box[STRING]; /**< formatted mailbox name */
+ struct Buffy *buffy; /**< Mailbox this represents */
+ bool is_hidden; /**< Don't show, e.g. $sidebar_new_mail_only */
};
static int EntryCount = 0;
static int EntryLen = 0;
static struct SbEntry **Entries = NULL;
-static int TopIndex = -1; /* First mailbox visible in sidebar */
-static int OpnIndex = -1; /* Current (open) mailbox */
-static int HilIndex = -1; /* Highlighted mailbox */
-static int BotIndex = -1; /* Last mailbox visible in sidebar */
+static int TopIndex = -1; /**< First mailbox visible in sidebar */
+static int OpnIndex = -1; /**< Current (open) mailbox */
+static int HilIndex = -1; /**< Highlighted mailbox */
+static int BotIndex = -1; /**< Last mailbox visible in sidebar */
/**
* enum DivType - Source of the sidebar divider character
*/
enum DivType
{
- SB_DIV_USER,
- SB_DIV_ASCII,
- SB_DIV_UTF8
+ SB_DIV_USER, /**< User configured using $sidebar_divider_char */
+ SB_DIV_ASCII, /**< An ASCII vertical bar (pipe) */
+ SB_DIV_UTF8 /**< A unicode line-drawing character */
};
/**
*/
enum SidebarSrc
{
- SB_SRC_INCOMING,
- SB_SRC_VIRT,
+ SB_SRC_INCOMING, /**< Display real mailboxes */
+ SB_SRC_VIRT, /**< Display virtual mailboxes */
} sidebar_source = SB_SRC_INCOMING;
/**
* cb_format_str - Create the string to show in the sidebar
- * @param dest Buffer in which to save string
- * @param destlen Buffer length
- * @param col Starting column, UNUSED
- * @param cols Maximum columns, UNUSED
- * @param op printf-like operator, e.g. 'B'
- * @param src printf-like format string
- * @param prefix Field formatting string, UNUSED
- * @param ifstring If condition is met, display this string
- * @param elsestring Otherwise, display this string
- * @param data Pointer to our sidebar_entry
- * @param flags Format flags, e.g. MUTT_FORMAT_OPTIONAL
+ * @param[out] dest Buffer in which to save string
+ * @param[in] destlen Buffer length
+ * @param[in] col Starting column, UNUSED
+ * @param[in] cols Maximum columns, UNUSED
+ * @param[in] op printf-like operator, e.g. 'B'
+ * @param[in] src printf-like format string
+ * @param[in] prefix Field formatting string, UNUSED
+ * @param[in] ifstring If condition is met, display this string
+ * @param[in] elsestring Otherwise, display this string
+ * @param[in] data Pointer to our sidebar_entry
+ * @param[in] flags Format flags, e.g. MUTT_FORMAT_OPTIONAL
* @return src (unchanged)
*
* cb_format_str is a callback function for mutt_expando_format. It understands
/**
* make_sidebar_entry - Turn mailbox data into a sidebar string
- * @param buf Buffer in which to save string
- * @param buflen Buffer length
- * @param width Desired width in screen cells
- * @param box Mailbox name
- * @param sbe Mailbox object
+ * @param[out] buf Buffer in which to save string
+ * @param[in] buflen Buffer length
+ * @param[in] width Desired width in screen cells
+ * @param[in] box Mailbox name
+ * @param[in] sbe Mailbox object
*
* Take all the relevant mailbox data and the desired screen width and then get
* mutt_expando_format to do the actual work. mutt_expando_format will callback to
*
* For each SbEntry in the Entries array, check whether we should display it.
* This is determined by several criteria. If the Buffy:
- * is the currently open mailbox
- * is the currently highlighted mailbox
- * has unread messages
- * has flagged messages
- * is whitelisted
+ * * is the currently open mailbox
+ * * is the currently highlighted mailbox
+ * * has unread messages
+ * * has flagged messages
+ * * is whitelisted
*/
static void update_entries_visibility(void)
{
* @param num_rows Height of the Sidebar
* @param num_cols Width of the Sidebar
* @return
- * * 0: Empty string
- * * n: Character occupies n screen columns
+ * * 0: Empty string
+ * * n: Character occupies n screen columns
*
* Draw a divider using characters from the config option "sidebar_divider_char".
* This can be an ASCII or Unicode character.
}
/**
- * draw_sidebar - Write out a list of mailboxes, on the left
+ * draw_sidebar - Write out a list of mailboxes, in a panel
* @param num_rows Height of the Sidebar
* @param num_cols Width of the Sidebar
* @param div_width Width in screen characters taken by the divider