Lots of functions were already commented.
This commit re-formats the comments to be doxygen-compatible.
Despite the size of the commit, no code has changed.
#include "protos.h"
#include "url.h"
-/* mutt_account_match: compare account info (host/port/user) */
+/**
+ * mutt_account_match - compare account info (host/port/user)
+ */
int mutt_account_match(const struct Account *a1, const struct Account *a2)
{
const char *user = NONULL(Username);
return 1;
}
-/* mutt_account_fromurl: fill account with information from url. */
+/**
+ * mutt_account_fromurl - fill account with information from url
+ */
int mutt_account_fromurl(struct Account *account, struct CissUrl *url)
{
/* must be present */
return 0;
}
-/* mutt_account_tourl: fill URL with info from account. The URL information
- * is a set of pointers into account - don't free or edit account until
- * you've finished with url (make a copy of account if you need it for
- * a while). */
+/**
+ * mutt_account_tourl - fill URL with info from account
+ *
+ * The URL information is a set of pointers into account - don't free or edit
+ * account until you've finished with url (make a copy of account if you need
+ * it for a while).
+ */
void mutt_account_tourl(struct Account *account, struct CissUrl *url)
{
url->scheme = U_UNKNOWN;
url->pass = account->pass;
}
-/* mutt_account_getuser: retrieve username into Account, if necessary */
+/**
+ * mutt_account_getuser - retrieve username into Account, if necessary
+ */
int mutt_account_getuser(struct Account *account)
{
char prompt[SHORT_STRING];
return 0;
}
-/* mutt_account_getpass: fetch password into Account, if necessary */
+/**
+ * mutt_account_getpass - fetch password into Account, if necessary
+ */
int mutt_account_getpass(struct Account *account)
{
char prompt[SHORT_STRING];
}
-/*
+/**
+ * write_safe_address - Defang malicious email addresses
+ *
* if someone has an address like
* From: Michael `/bin/rm -f ~` Elkins <me@mutt.org>
* and the user creates an alias for this, Mutt could wind up executing
FREE(&s);
}
-/*
- * Sanity-check an alias name: Only characters which are non-special to both
- * the RFC 822 and the mutt configuration parser are permitted.
+/**
+ * check_alias_name - Sanity-check an alias name
+ *
+ * Only characters which are non-special to both the RFC 822 and the mutt
+ * configuration parser are permitted.
*/
int check_alias_name(const char *s, char *dest, size_t destlen)
{
return;
}
-/*
- * This routine looks to see if the user has an alias defined for the given
- * address.
+/**
+ * alias_reverse_lookup - Does the user have an alias for the given address
*/
struct Address *alias_reverse_lookup(struct Address *a)
{
}
}
-/* alias_complete() -- alias completion routine
+/**
+ * mutt_alias_complete - alias completion routine
*
* given a partial alias, this routine attempts to fill in the alias
* from the alias list as much as possible. if given empty search string
return false;
}
-/* returns true if the given address belongs to the user. */
+/**
+ * mutt_addr_is_user - Does the address belong to the user
+ * @return true if the given address belongs to the user
+ */
bool mutt_addr_is_user(struct Address *addr)
{
const char *fqdn = NULL;
}
-/* return 1 if require full screen redraw, 0 otherwise */
+/**
+ * mutt_compose_attachment - Create an attachment
+ * @return
+ * * 1 if require full screen redraw
+ * * 0 otherwise
+ */
int mutt_compose_attachment(struct Body *a)
{
char type[STRING];
}
}
-/* returns -1 on error, 0 or the return code from mutt_do_pager() on success */
+/**
+ * mutt_view_attachment - View an attachment
+ * @return
+ * * -1 on error
+ * * 0 or the return code from mutt_do_pager() on success
+ */
int mutt_view_attachment(FILE *fp, struct Body *a, int flag, struct Header *hdr,
struct AttachPtr **idx, short idxlen)
{
return rc;
}
-/* returns 1 on success, 0 on error */
+/**
+ * mutt_pipe_attachment - Pipe an attachment to a command
+ * @return
+ * * 1 on success
+ * * 0 on error
+ */
int mutt_pipe_attachment(FILE *fp, struct Body *b, const char *path, char *outfile)
{
pid_t thepid;
return safe_fopen(path, "w");
}
-/* returns 0 on success, -1 on error */
+/**
+ * mutt_save_attachment - Save an attachment
+ * @return
+ * * 0 on success
+ * * -1 on error
+ */
int mutt_save_attachment(FILE *fp, struct Body *m, char *path, int flags, struct Header *hdr)
{
if (!m)
return 0;
}
-/* returns 0 on success, -1 on error */
+/**
+ * mutt_decode_save_attachment - Decode, then save an attachment
+ * @return 0 on success, -1 on error
+ */
int mutt_decode_save_attachment(FILE *fp, struct Body *m, char *path, int displaying, int flags)
{
struct State s;
return ret;
}
-/* Ok, the difference between send and receive:
+/**
+ * mutt_print_attachment - Print out an attachment
+ *
+ * Ok, the difference between send and receive:
* recv: Body->filename is a suggested name, and Context|Header points
* to the attachment in mailbox which is encoded
* send: Body->filename points to the un-encoded file which contains the
static char OldLastDir[_POSIX_PATH_MAX] = "";
static char LastDir[_POSIX_PATH_MAX] = "";
-/* Frees up the memory allocated for the local-global variables. */
+/**
+ * destroy_state - Free the BrowserState
+ *
+ * Frees up the memory allocated for the local-global variables.
+ */
static void destroy_state(struct BrowserState *state)
{
for (int c = 0; c < state->entrylen; c++)
return ((BrowserSort & SORT_REVERSE) ? -r : r);
}
-/* Wild compare function that calls the others. It's useful
- * because it provides a way to tell "../" is always on the
- * top of the list, independently of the sort method.
+/**
+ * browser_compare - Sort the items in the browser
+ *
+ * Wild compare function that calls the others. It's useful because it provides
+ * a way to tell "../" is always on the top of the list, independently of the
+ * sort method.
*/
static int browser_compare(const void *a, const void *b)
{
}
}
-/* Call to qsort using browser_compare function. Some
- * specific sort methods are not used via NNTP.
+/**
+ * browser_sort - Sort the entries in the browser
+ *
+ * Call to qsort using browser_compare function.
+ * Some specific sort methods are not used via NNTP.
*/
static void browser_sort(struct BrowserState *state)
{
menu->data = state->entry;
}
-/* get list of all files/newsgroups with mask */
+/**
+ * examine_directory - get list of all files/newsgroups with mask
+ */
static int examine_directory(struct Menu *menu, struct BrowserState *state,
char *d, const char *prefix)
{
}
#endif
-/* get list of mailboxes/subscribed newsgroups */
+/**
+ * examine_mailboxes - Get list of mailboxes/subscribed newsgroups
+ */
static int examine_mailboxes(struct Menu *menu, struct BrowserState *state)
{
struct stat s;
}
#endif
-/*
- * This function takes a menu and a state and defines the current
- * entry that should be highlighted.
+/**
+ * browser_highlight_default - Decide which browser item should be highlighted
+ *
+ * This function takes a menu and a state and defines the current entry that
+ * should be highlighted.
*/
static void browser_highlight_default(struct BrowserState *state, struct Menu *menu)
{
return ff->tagged - ot;
}
-/* Public function
+/**
+ * mutt_browser_select_dir - Remember the last directory selected
*
- * This function helps the browser to know which directory has
- * been selected. It should be called anywhere a confirm hit is done
- * to open a new directory/file which is a maildir/mbox.
+ * This function helps the browser to know which directory has been selected.
+ * It should be called anywhere a confirm hit is done to open a new
+ * directory/file which is a maildir/mbox.
*
* We could check if the sort method is appropriate with this feature.
*/
#include "lib.h"
#include "myvar.h"
-/* creates and initializes a Buffer */
+/**
+ * mutt_buffer_new - creates and initializes a Buffer
+ */
struct Buffer *mutt_buffer_new(void)
{
struct Buffer *b = NULL;
return b;
}
-/* initialize a new Buffer */
+/**
+ * mutt_buffer_init - initialize a new Buffer
+ */
struct Buffer *mutt_buffer_init(struct Buffer *b)
{
memset(b, 0, sizeof(struct Buffer));
return b;
}
-/*
+/**
+ * mutt_buffer_from - Create Buffer from an existing Buffer
+ *
* Creates and initializes a Buffer*. If passed an existing Buffer*,
* just initializes. Frees anything already in the buffer. Copies in
* the seed string.
return len;
}
-/* dynamically grows a Buffer to accommodate s, in increments of 128 bytes.
- * Always one byte bigger than necessary for the null terminator, and
- * the buffer is always null-terminated */
+/**
+ * mutt_buffer_add - Add a string to a Buffer, expanding it if necessary
+ *
+ * dynamically grows a Buffer to accommodate s, in increments of 128 bytes.
+ * Always one byte bigger than necessary for the null terminator, and the
+ * buffer is always null-terminated
+ */
static void mutt_buffer_add(struct Buffer *buf, const char *s, size_t len)
{
if (!buf || !s)
static short BuffyCount = 0; /* how many boxes with new mail */
static short BuffyNotify = 0; /* # of unnotified new boxes */
-/* Find the last message in the file.
- * upon success return 0. If no message found - return -1 */
+/**
+ * fseek_last_message - Find the last message in the file
+ * @return 0 on success, -1 if no message found
+ */
static int fseek_last_message(FILE *f)
{
LOFF_T pos;
return -1;
}
-/* Return 1 if the last message is new */
+/**
+ * test_last_status_new - Is the last message new
+ * @return 1 if the last message is new
+ */
static int test_last_status_new(FILE *f)
{
struct Header *hdr = NULL;
BuffyNotify++;
}
-/* fetch buffy object for given path, if present */
+/**
+ * buffy_get - fetch buffy object for given path, if present
+ */
static struct Buffy *buffy_get(const char *path)
{
struct Buffy *cur = NULL;
return 0;
}
-/* Check all Incoming for new mail and total/new/flagged messages
+/**
+ * mutt_buffy_check - Check all Incoming for new mail
+ *
+ * Check all Incoming for new mail and total/new/flagged messages
* force: if true, ignore BuffyTimeout and check for new mail anyway
*/
int mutt_buffy_check(bool force)
Charset = safe_strdup("iso-8859-1");
}
-/* this first ties off any charset extension such as //TRANSLIT,
- canonicalizes the charset and re-adds the extension */
+/**
+ * mutt_canonical_charset - Canonicalise the charset of a string
+ *
+ * this first ties off any charset extension such as //TRANSLIT,
+ * canonicalizes the charset and re-adds the extension
+ */
void mutt_canonical_charset(char *dest, size_t dlen, const char *name)
{
char *p = NULL, *ext = NULL;
return strcpy(fcharset, "us-ascii");
}
-/*
+/**
+ * mutt_iconv_open - Set up iconv for conversions
+ *
* Like iconv_open, but canonicalises the charsets, applies charset-hooks,
* recanonicalises, and finally applies iconv-hooks. Parameter flags=0 skips
* charset-hooks, while MUTT_ICONV_HOOK_FROM applies them to fromcode. Callers
}
-/*
+/**
+ * mutt_iconv - Change the encoding of a string
+ *
* Like iconv, but keeps going even when the input is invalid
* If you're supplying inrepls, the source charset should be stateless;
* if you're supplying an outrepl, the target charset should be.
}
-/*
- * Convert a string
- * Used in rfc2047.c, rfc2231.c, crypt_gpgme.c, mutt_idna.c, and more.
- * Parameter flags is given as-is to mutt_iconv_open(). See there
- * for its meaning and usage policy.
+/**
+ * mutt_convert_string - Convert a string between encodings
+ *
+ * Parameter flags is given as-is to mutt_iconv_open().
+ * See there for its meaning and usage policy.
*/
int mutt_convert_string(char **ps, const char *from, const char *to, int flags)
{
iconv_t cd;
};
-/*
- * Parameter flags is given as-is to mutt_iconv_open(). See there for its
- * meaning and usage policy.
+/**
+ * fgetconv_open - Open a file and convert its encoding
+ *
+ * Parameter flags is given as-is to mutt_iconv_open().
+ * See there for its meaning and usage policy.
*/
FGETCONV *fgetconv_open(FILE *file, const char *from, const char *to, int flags)
{
} while (MoreArgs(s));
}
-/* usage: uncolor index pattern [pattern...]
- * unmono index pattern [pattern...]
+/**
+ * _mutt_parse_uncolor - Parse an 'uncolor' command
+ *
+ * usage:
+ * * uncolor index pattern [pattern...]
+ * * unmono index pattern [pattern...]
*/
static int _mutt_parse_uncolor(struct Buffer *buf, struct Buffer *s, unsigned long data,
struct Buffer *err, short parse_uncolor)
return attr;
}
-/* usage: color <object> <fg> <bg> [ <regexp> ]
- * mono <object> <attr> [ <regexp> ]
+/**
+ * _mutt_parse_color - Parse a "color" command
+ *
+ * usage: color OBJECT FG BG [ REGEXP ]
+ * mono OBJECT ATTR [ REGEXP ]
*/
static int _mutt_parse_color(struct Buffer *buf, struct Buffer *s, struct Buffer *err,
parser_callback_t callback, bool dry_run)
}
-/* the following code is shared between printing and piping */
+/**
+ * _mutt_pipe_message - Pipe message to a command
+ *
+ * The following code is shared between printing and piping.
+ */
static int _mutt_pipe_message(struct Header *h, char *cmd, int decode,
int print, int split, char *sep)
{
return (Sort != method ? 0 : -1); /* no need to resort if it's the same */
}
-/* invoke a command in a subshell */
+/**
+ * mutt_shell_escape - invoke a command in a subshell
+ */
void mutt_shell_escape(void)
{
char buf[LONG_STRING];
}
}
-/* enter a mutt command */
+/**
+ * mutt_enter_command - enter a mutt command
+ */
void mutt_enter_command(void)
{
struct Buffer err, token;
return 0;
}
-/* returns 0 if the copy/save was successful, or -1 on error/abort */
+/**
+ * mutt_save_message - Save an email
+ * @return
+ * * 0 if the copy/save was successful
+ * * -1 on error/abort
+ */
int mutt_save_message(struct Header *h, int delete, int decode, int decrypt)
{
int i, need_buffy_cleanup;
}
-/* The padding needed for each header is strlen() + max_width - strwidth().
+/**
+ * init_header_padding - Calculate how much padding the compose table will need
+ *
+ * The padding needed for each header is strlen() + max_width - strwidth().
*
- * calc_header_width_padding sets each entry in HeaderPadding to
- * strlen - width. Then, afterwards, we go through and add max_width
- * to each entry.
+ * calc_header_width_padding sets each entry in HeaderPadding to strlen -
+ * width. Then, afterwards, we go through and add max_width to each entry.
*/
static void init_header_padding(void)
{
return s;
}
-/*
- * compose_format_str()
+/**
+ * compose_format_str - Format strings like printf()
*
- * %a = total number of attachments
- * %h = hostname [option]
- * %l = approx. length of current message (in bytes)
- * %v = Mutt version
+ * * \%a Total number of attachments
+ * * \%h Hostname [option]
+ * * \%l Approx. length of current message (in bytes)
+ * * \%v Mutt version
*
* This function is similar to status_format_str(). Look at that function for
* help when modifying this function.
mutt_FormatString(buf, buflen, col, cols, p, compose_format_str, (unsigned long) menu, 0);
}
-/* return values:
- *
- * 1 message should be postponed
- * 0 normal exit
- * -1 abort message
+/**
+ * mutt_compose_menu - Allow the user to edit the message envelope
+ * @return
+ * * 1 Message should be postponed
+ * * 0 Normal exit
+ * * -1 Abort message
*/
int mutt_compose_menu(struct Header *msg, /* structure for new message */
char *fcc, /* where to save a copy of the message */
static int address_header_decode(char **str);
static int copy_delete_attach(struct Body *b, FILE *fpin, FILE *fpout, char *date);
-/* Ok, the only reason for not merging this with mutt_copy_header()
- * below is to avoid creating a Header structure in message_handler().
- * Also, this one will wrap headers much more aggressively than the other one.
+/**
+ * mutt_copy_hdr - Copy header from one file to another
+ *
+ * Ok, the only reason for not merging this with mutt_copy_header() below is to
+ * avoid creating a Header structure in message_handler(). Also, this one will
+ * wrap headers much more aggressively than the other one.
*/
int mutt_copy_hdr(FILE *in, FILE *out, LOFF_T off_start, LOFF_T off_end,
int flags, const char *prefix)
return 0;
}
-/* flags
- CH_DECODE RFC2047 header decoding
- CH_FROM retain the "From " message separator
- CH_FORCE_FROM give CH_FROM precedence over CH_WEED
- CH_MIME ignore MIME fields
- CH_NOLEN don't write Content-Length: and Lines:
- CH_NONEWLINE don't output a newline after the header
- CH_NOSTATUS ignore the Status: and X-Status:
- CH_PREFIX quote header with $indent_string
- CH_REORDER output header in order specified by `hdr_order'
- CH_TXTPLAIN generate text/plain MIME headers [hack alert.]
- CH_UPDATE write new Status: and X-Status:
- CH_UPDATE_LEN write new Content-Length: and Lines:
- CH_XMIT ignore Lines: and Content-Length:
- CH_WEED do header weeding
- CH_NOQFROM ignore ">From " line
- CH_UPDATE_IRT update the In-Reply-To: header
- CH_UPDATE_REFS update the References: header
- CH_VIRTUAL write virtual header lines too
-
- prefix
- string to use if CH_PREFIX is set
+/**
+ * mutt_copy_header - Copy email header
+ *
+ * flags:
+ * * #CH_DECODE RFC2047 header decoding
+ * * #CH_FROM retain the "From " message separator
+ * * #CH_FORCE_FROM give CH_FROM precedence over CH_WEED
+ * * #CH_MIME ignore MIME fields
+ * * #CH_NOLEN don't write Content-Length: and Lines:
+ * * #CH_NONEWLINE don't output a newline after the header
+ * * #CH_NOSTATUS ignore the Status: and X-Status:
+ * * #CH_PREFIX quote header with $indent_string
+ * * #CH_REORDER output header in order specified by `hdr_order'
+ * * #CH_TXTPLAIN generate text/plain MIME headers [hack alert.]
+ * * #CH_UPDATE write new Status: and X-Status:
+ * * #CH_UPDATE_LEN write new Content-Length: and Lines:
+ * * #CH_XMIT ignore Lines: and Content-Length:
+ * * #CH_WEED do header weeding
+ * * #CH_NOQFROM ignore ">From " line
+ * * #CH_UPDATE_IRT update the In-Reply-To: header
+ * * #CH_UPDATE_REFS update the References: header
+ * * #CH_VIRTUAL write virtual header lines too
+ *
+ * prefix
+ * * string to use if CH_PREFIX is set
*/
int mutt_copy_header(FILE *in, struct Header *h, FILE *out, int flags, const char *prefix)
{
return 0;
}
-/* Count the number of lines and bytes to be deleted in this body */
+/**
+ * count_delete_lines - Count lines to be deleted in this email body
+ *
+ * Count the number of lines and bytes to be deleted in this body
+ */
static int count_delete_lines(FILE *fp, struct Body *b, LOFF_T *length, size_t datelen)
{
int dellines = 0;
return dellines;
}
-/* make a copy of a message
+/**
+ * _mutt_copy_message - make a copy of a message
+ * @param fpout Where to write output
+ * @param fpin Where to get input
+ * @param hdr Header of message being copied
+ * @param body Structure of message being copied
+ * @param flags See below
+ * @param chflags Flags to mutt_copy_header()
*
- * fpout where to write output
- * fpin where to get input
- * hdr header of message being copied
- * body structure of message being copied
- * flags
- * MUTT_CM_NOHEADER don't copy header
- * MUTT_CM_PREFIX quote header and body
- * MUTT_CM_DECODE decode message body to text/plain
- * MUTT_CM_DISPLAY displaying output to the user
- * MUTT_CM_PRINTING printing the message
- * MUTT_CM_UPDATE update structures in memory after syncing
- * MUTT_CM_DECODE_PGP used for decoding PGP messages
- * MUTT_CM_CHARCONV perform character set conversion
- * chflags flags to mutt_copy_header()
+ * * #MUTT_CM_NOHEADER don't copy header
+ * * #MUTT_CM_PREFIX quote header and body
+ * * #MUTT_CM_DECODE decode message body to text/plain
+ * * #MUTT_CM_DISPLAY displaying output to the user
+ * * #MUTT_CM_PRINTING printing the message
+ * * #MUTT_CM_UPDATE update structures in memory after syncing
+ * * #MUTT_CM_DECODE_PGP used for decoding PGP messages
+ * * #MUTT_CM_CHARCONV perform character set conversion
*/
int _mutt_copy_message(FILE *fpout, FILE *fpin, struct Header *hdr,
struct Body *body, int flags, int chflags)
return rc;
}
-/* should be made to return -1 on fatal errors, and 1 on non-fatal errors
- * like partial decode, where it is worth displaying as much as possible */
+/**
+ * mutt_copy_message - Copy a message
+ *
+ * should be made to return -1 on fatal errors, and 1 on non-fatal errors
+ * like partial decode, where it is worth displaying as much as possible
+ */
int mutt_copy_message(FILE *fpout, struct Context *src, struct Header *hdr,
int flags, int chflags)
{
return r;
}
-/* appends a copy of the given message to a mailbox
- *
- * dest destination mailbox
- * fpin where to get input
- * src source mailbox
- * hdr message being copied
- * body structure of message being copied
- * flags mutt_copy_message() flags
- * chflags mutt_copy_header() flags
+/**
+ * _mutt_append_message - appends a copy of the given message to a mailbox
+ * @param dest destination mailbox
+ * @param fpin where to get input
+ * @param src source mailbox
+ * @param hdr message being copied
+ * @param body structure of message being copied
+ * @param flags mutt_copy_message() flags
+ * @param chflags mutt_copy_header() flags
+ * @return 0 on success, -1 on error
*/
static int _mutt_append_message(struct Context *dest, FILE *fpin,
struct Context *src, struct Header *hdr,
return r;
}
-/*
+/**
+ * copy_delete_attach - Copy a message, deleting marked attachments
+ * @return
+ * * 0 on success
+ * * -1 on failure
+ *
* This function copies a message body, while deleting _in_the_copy_
* any attachments which are marked for deletion.
* Nothing is changed in the original message -- this is left to the caller.
- *
- * The function will return 0 on success and -1 on failure.
*/
static int copy_delete_attach(struct Body *b, FILE *fpin, FILE *fpout, char *date)
{
return 0;
}
-/*
- * This function is the equivalent of mutt_write_address_list(),
- * but writes to a buffer instead of writing to a stream.
- * mutt_write_address_list could be re-used if we wouldn't store
- * all the decoded headers in a huge array, first.
+/**
+ * format_address_header - Write address headers to a buffer
+ *
+ * This function is the equivalent of mutt_write_address_list(), but writes to
+ * a buffer instead of writing to a stream. mutt_write_address_list could be
+ * re-used if we wouldn't store all the decoded headers in a huge array, first.
*
* XXX - fix that.
*/
refresh();
}
-/* Make sure that the next refresh does a full refresh. This could be
- optimized by not doing it at all if DISPLAY is set as this might
- indicate that a GUI based pinentry was used. Having an option to
- customize this is of course the Mutt way. */
+/**
+ * mutt_need_hard_redraw - Force a hard refresh
+ *
+ * Make sure that the next refresh does a full refresh. This could be
+ * optimized by not doing it at all if DISPLAY is set as this might indicate
+ * that a GUI based pinentry was used. Having an option to customize this is
+ * of course the Mutt way. */
void mutt_need_hard_redraw(void)
{
keypad(stdscr, true);
return def;
}
-/* this function is called when the user presses the abort key */
+/**
+ * mutt_query_exit - Ask the user if they want to leave Mutt
+ *
+ * This function is called when the user presses the abort key.
+ */
void mutt_query_exit(void)
{
mutt_flushinp();
return rv;
}
-/* Assumes the cursor has already been positioned within the
- * window.
+/**
+ * mutt_window_clrtoeol - Clear to the end of the line
+ *
+ * Assumes the cursor has already been positioned within the window.
*/
void mutt_window_clrtoeol(struct MuttWindow *win)
{
mutt_window_clrtoeol(win);
}
-/* Assumes the current position is inside the window.
- * Otherwise it will happily return negative or values outside
- * the window boundaries
+/**
+ * mutt_window_getyx - Get the cursor position in the window
+ *
+ * Assumes the current position is inside the window. Otherwise it will
+ * happily return negative or values outside the window boundaries
*/
void mutt_window_getyx(struct MuttWindow *win, int *y, int *x)
{
}
}
-/*
+/**
+ * mutt_push_macro_event - Add the character/operation to the macro buffer
+ *
* Adds the ch/op to the macro buffer.
* This should be used for macros, push, and exec commands only.
*/
}
}
-/* Normally, OP_END_COND should only be in the MacroEvent buffer.
- * km_error_key() (ab)uses OP_END_COND as a barrier in the unget
- * buffer, and calls this function to flush. */
+/**
+ * mutt_flush_unget_to_endcond - Clear entries from UngetKeyEvents
+ *
+ * Normally, OP_END_COND should only be in the MacroEvent buffer.
+ * km_error_key() (ab)uses OP_END_COND as a barrier in the unget buffer, and
+ * calls this function to flush.
+ */
void mutt_flush_unget_to_endcond(void)
{
while (UngetCount > 0)
}
#if (defined(USE_SLANG_CURSES) || defined(HAVE_CURS_SET))
-/* The argument can take 3 values:
- * -1: restore the value of the last call
- * 0: make the cursor invisible
- * 1: make the cursor visible
+/**
+ * mutt_curs_set - Set the cursor position
+ * @param cursor
+ * * -1: restore the value of the last call
+ * * 0: make the cursor invisible
+ * * 1: make the cursor visible
*/
void mutt_curs_set(int cursor)
{
return choice;
}
-/*
- * addwch would be provided by an up-to-date curses library
+/**
+ * mutt_addwch - addwch would be provided by an up-to-date curses library
*/
int mutt_addwch(wchar_t wc)
{
return addstr(buf);
}
-
-/*
- * This formats a string, a bit like
- * snprintf (dest, destlen, "%-*.*s", min_width, max_width, s),
- * except that the widths refer to the number of character cells
- * when printed.
+/**
+ * mutt_format_string - Format a string, like snprintf()
+ *
+ * This formats a string, a bit like snprintf (dest, destlen, "%-*.*s",
+ * min_width, max_width, s), except that the widths refer to the number of
+ * character cells when printed.
*/
void mutt_format_string(char *dest, size_t destlen, int min_width, int max_width,
int justify, char m_pad_char, const char *s, size_t n, int arboreal)
}
}
-/*
+/**
+ * format_s_x - Format a string like snprintf()
+ *
* This formats a string rather like
* snprintf (fmt, sizeof (fmt), "%%%ss", prefix);
* snprintf (dest, destlen, fmt, s);
format_s_x(dest, destlen, prefix, s, 1);
}
-/*
- * mutt_paddstr (n, s) is almost equivalent to
- * mutt_format_string (bigbuf, big, n, n, FMT_LEFT, ' ', s, big, 0), addstr (bigbuf)
+/**
+ * mutt_paddstr - Display a string on screen, padded if necessary
+ * @param n Final width of field
+ * @param s String to display
*/
void mutt_paddstr(int n, const char *s)
{
addch(' ');
}
-/* See how many bytes to copy from string so it's at most maxlen bytes
- * long and maxwid columns wide */
+/**
+ * mutt_wstr_trunc - Work out how to truncate a widechar string
+ * @param[in] src String to measute
+ * @param[in] maxlen Maximum length of string in bytes
+ * @param[in] maxwid Maximum width in screen columns
+ * @param[out] width Save the truncated screen column width
+ * @return number of bytes to use
+ *
+ * See how many bytes to copy from string so it's at most maxlen bytes long and
+ * maxwid columns wide
+ */
size_t mutt_wstr_trunc(const char *src, size_t maxlen, size_t maxwid, size_t *width)
{
wchar_t wc;
return -1;
}
-/* Return the index of the first new message, or failing that, the first
+/**
+ * ci_first_message - Get index of first new message
+ *
+ * Return the index of the first new message, or failing that, the first
* unread message.
*/
static int ci_first_message(void)
return 0;
}
-/* This should be in mx.c, but it only gets used here. */
+/**
+ * mx_toggle_write - Toggle the mailbox's readonly flag
+ *
+ * This should be in mx.c, but it only gets used here.
+ */
static int mx_toggle_write(struct Context *ctx)
{
if (!ctx)
}
-/* terminal status capability check. terminfo must have been initialized. */
+/**
+ * mutt_ts_capability - Check terminal capabilities
+ *
+ * terminal status capability check. terminfo must have been initialized.
+ */
bool mutt_ts_capability(void)
{
char *term = getenv("TERM");
menu->redraw = 0;
}
-/* This function handles the message index window as well as commands returned
+/**
+ * mutt_index_menu - Display a list of emails
+ *
+ * This function handles the message index window as well as commands returned
* from the pager (MENU_PAGER).
*/
int mutt_index_menu(void)
#include <string.h>
#include <time.h>
-/* returns the seconds east of UTC given `g' and its corresponding gmtime()
- representation */
+/**
+ * compute_tz - Calculate the number of seconds east of UTC
+ *
+ * returns the seconds east of UTC given `g' and its corresponding gmtime()
+ * representation
+ */
static time_t compute_tz(time_t g, struct tm *utc)
{
struct tm *lt = localtime(&g);
return t;
}
-/* Returns the local timezone in seconds east of UTC for the time t,
+/**
+ * mutt_local_tz - Calculate the local timezone in seconds east of UTC
+ *
+ * Returns the local timezone in seconds east of UTC for the time t,
* or for the current time if t is zero.
*/
time_t mutt_local_tz(time_t t)
#define TM_YEAR_MAX \
(1970 + (((((TIME_T_MAX - 59) / 60) - 59) / 60) - 23) / 24 / 366)
-/* converts struct tm to time_t, but does not take the local timezone into
- account unless ``local'' is nonzero */
+/**
+ * mutt_mktime - Convert `struct tm` to `time_t`
+ *
+ * converts struct tm to time_t, but does not take the local timezone into
+ * account unless ``local'' is nonzero
+ */
time_t mutt_mktime(struct tm *t, int local)
{
time_t g;
return g;
}
-/* Return 1 if month is February of leap year, else 0 */
+/**
+ * is_leap_year_feb - Is it a leap year
+ * @param tm Date to be tested
+ * @return true if it's a leap year
+ */
static int is_leap_year_feb(struct tm *tm)
{
if (tm->tm_mon == 1)
** This is used to protect indentations in tables.
**/
-/* reduce CDATA to ID */
+/**
+ * sgml_id_fputs - reduce CDATA to ID
+ */
static int sgml_id_fputs(const char *s, FILE *out)
{
char id;
addch('\n');
}
-/* args:
- * force override the $ask* vars (used for the ~h command)
+/**
+ * be_edit_header - Edit the message headers
+ * @param e Message headers
+ * @param force override the $ask* vars (used for the ~h command)
*/
static void be_edit_header(struct Envelope *e, int force)
{
return i;
}
-/*
+/**
+ * replace_part - Search and replace on a buffer
+ *
* Replace part of the wchar_t buffer, from FROM to CURPOS, by BUF.
*/
static void replace_part(struct EnterState *state, size_t from, char *buf)
#include "mutt_curses.h"
#include "protos.h"
-/* Invokes a command on a pipe and optionally connects its stdin and stdout
+/**
+ * mutt_create_filter_fd - Run a command on a pipe
+ *
+ * Invokes a command on a pipe and optionally connects its stdin and stdout
* to the specified handles.
*/
pid_t mutt_create_filter_fd(const char *cmd, FILE **in, FILE **out, FILE **err,
h->searched = false;
}
+/**
+ * mutt_thread_set_flag - Set a flag on an entire thread
+ */
void mutt_tag_set_flag(int flag, int bf)
{
for (int j = 0; j < Context->vcount; j++)
if (Context->hdrs[Context->v2r[j]]->tagged)
mutt_set_flag(Context, Context->hdrs[Context->v2r[j]], flag, bf);
}
+
int mutt_thread_set_flag(struct Header *hdr, int flag, int bf, int subthread)
{
struct MuttThread *start = NULL, *cur = hdr->thread;
help)
echo "#ifdef HELP_C"
echo "const char *HelpStrings[] = {"
- expr='s;^[^ ]* *\(.*\); N_(\1),;'
+ expr='s;^[^ ]* *\(.*\); N_(\1),;'
;;
*)
echo "enum {"
- expr='s;^\([^ ]*\).*; \1,;'
+ expr='s;^\([^ ]*\).*; \1,;'
;;
esac
for i in $*; do
*l = d - dest;
}
-/*
- * Decode an attachment encoded with quoted-printable.
+/**
+ * decode_quoted - Decode an attachment encoded with quoted-printable
*
- * Why doesn't this overflow any buffers? First, it's guaranteed
- * that the length of a line grows when you _en_-code it to
- * quoted-printable. That means that we always can store the
- * result in a buffer of at most the _same_ size.
+ * Why doesn't this overflow any buffers? First, it's guaranteed that the
+ * length of a line grows when you _en_-code it to quoted-printable. That
+ * means that we always can store the result in a buffer of at most the _same_
+ * size.
*
- * Now, we don't special-case if the line we read with fgets()
- * isn't terminated. We don't care about this, since STRING > 78,
- * so corrupted input will just be corrupted a bit more. That
- * implies that STRING+1 bytes are always sufficient to store the
- * result of qp_decode_line.
+ * Now, we don't special-case if the line we read with fgets() isn't
+ * terminated. We don't care about this, since STRING > 78, so corrupted input
+ * will just be corrupted a bit more. That implies that STRING+1 bytes are
+ * always sufficient to store the result of qp_decode_line.
*
- * Finally, at soft line breaks, some part of a multibyte character
- * may have been left over by convert_to_state(). This shouldn't
- * be more than 6 characters, so STRING + 7 should be sufficient
- * memory to store the decoded data.
+ * Finally, at soft line breaks, some part of a multibyte character may have
+ * been left over by convert_to_state(). This shouldn't be more than 6
+ * characters, so STRING + 7 should be sufficient memory to store the decoded
+ * data.
*
- * Just to make sure that I didn't make some off-by-one error
- * above, we just use STRING*2 for the target buffer's size.
+ * Just to make sure that I didn't make some off-by-one error above, we just
+ * use STRING*2 for the target buffer's size.
*/
static void decode_quoted(struct State *s, long len, int istext, iconv_t cd)
{
return 0;
}
-/* for compatibility with metamail */
+/**
+ * is_mmnoask - for compatibility with metamail
+ */
static int is_mmnoask(const char *buf)
{
char tmp[LONG_STRING], *p = NULL, *q = NULL;
return rc;
}
-/* handles message/rfc822 body parts */
+/**
+ * message_handler - handles message/rfc822 body parts
+ */
static int message_handler(struct Body *a, struct State *s)
{
struct stat st;
return rc;
}
-/* returns 1 if decoding the attachment will produce output */
+/**
+ * mutt_can_decode - Will decoding the attachment produce any output
+ * @return 1 if decoding the attachment will produce output
+ */
int mutt_can_decode(struct Body *a)
{
if (is_autoview(a))
iconv_close(cd);
}
-/* when generating format=flowed ($text_flowed is set) from format=fixed,
- * strip all trailing spaces to improve interoperability;
- * if $text_flowed is unset, simply verbatim copy input
+/**
+ * text_plain_handler - Display plain text
+ *
+ * when generating format=flowed ($text_flowed is set) from format=fixed, strip
+ * all trailing spaces to improve interoperability; if $text_flowed is unset,
+ * simply verbatim copy input
*/
static int text_plain_handler(struct Body *b, struct State *s)
{
return table;
}
-/* table hash table to update
- * key key to hash on
- * data data to associate with `key'
- * allow_dup if nonzero, duplicate keys are allowed in the table
+/**
+ * union_hash_insert - Insert into a hash table using a union as a key
+ * @param table Hash table to update
+ * @param key Key to hash on
+ * @param data Data to associate with `key'
+ * @return
+ * * -1 on error
+ * * >=0 on success, index into the hash table
*/
static int union_hash_insert(struct Hash *table, union HashKey key, void *data)
{
union_hash_delete(table, key, data, destroy);
}
-/* ptr pointer to the hash table to be freed
- * destroy() function to call to free the ->data member (optional)
+/**
+ * hash_destroy - Destroy a hash table
+ * @param ptr Pointer to the hash table to be freed
+ * @param destroy Function to call to free the ->data member (optional)
*/
void hash_destroy(struct Hash **ptr, void (*destroy)(void *))
{
return hcpath;
}
-/* This function transforms a header into a char so that it is useable by
+/**
+ * hcache_dump - Serialise a Header object
+ *
+ * This function transforms a header into a char so that it is useable by
* db_store.
*/
static void *hcache_dump(header_cache_t *h, struct Header *header, int *off,
return false;
}
-/* Search for a mailing list in the list of addresses pointed to by adr.
+/**
+ * check_for_mailing_list_addr - Check an address list for a mailing list
+ *
* If one is found, print the address of the list into buf, then return 1.
* Otherwise, simply return 0.
*/
return false;
}
-/* Return values:
- * 0: user is not in list
- * 1: user is unique recipient
- * 2: user is in the TO list
- * 3: user is in the CC list
- * 4: user is originator
- * 5: sent to a subscribed mailinglist
+/**
+ * user_is_recipient - Is the user a recipient of the message
+ * @return
+ * * 0 User is not in list
+ * * 1 User is unique recipient
+ * * 2 User is in the TO list
+ * * 3 User is in the CC list
+ * * 4 User is originator
+ * * 5 Sent to a subscribed mailinglist
*/
static int user_is_recipient(struct Header *h)
{
}
-/* %a = address of author
- * %A = reply-to address (if present; otherwise: address of author
- * %b = filename of the originating folder
- * %B = the list to which the letter was sent, or else the folder name (%b).
- * %c = size of message in bytes
- * %C = current message number
- * %d = date and time of message using $date_format and sender's timezone
- * %D = date and time of message using $date_format and local timezone
- * %e = current message number in thread
- * %E = number of messages in current thread
- * %f = entire from line
- * %F = like %n, unless from self
- * %g = message labels (e.g. notmuch tags)
- * %i = message-id
- * %I = initials of author
- * %K = the list to which the letter was sent (if any; otherwise: empty)
- * %l = number of lines in the message
- * %L = like %F, except `lists' are displayed first
- * %m = number of messages in the mailbox
- * %n = name of author
- * %N = score
- * %O = like %L, except using address instead of name
- * %P = progress indicator for builtin pager
- * %q = newsgroup name (if compiled with NNTP support)
- * %r = comma separated list of To: recipients
- * %R = comma separated list of Cc: recipients
- * %s = subject
- * %S = short message status (e.g., N/O/D/!/r/-)
- * %t = `to:' field (recipients)
- * %T = $to_chars
- * %u = user (login) name of author
- * %v = first name of author, unless from self
- * %W = where user is (organization)
- * %x = `x-comment-to:' field (if present and compiled with NNTP support)
- * %X = number of MIME attachments
- * %y = `x-label:' field (if present)
- * %Y = `x-label:' field (if present, tree unfolded, and != parent's x-label)
- * %zs = message status flags
- * %zc = message crypto flags
- * %zt = message tag flags
- * %Z = combined message flags
+/**
+ * hdr_format_str - Format a string, like printf()
+ *
+ * | Expando | Description
+ * |:--------|:-----------------------------------------------------------------
+ * | \%a | address of author
+ * | \%A | reply-to address (if present; otherwise: address of author
+ * | \%b | filename of the originating folder
+ * | \%B | the list to which the letter was sent, or else the folder name (%b).
+ * | \%c | size of message in bytes
+ * | \%C | current message number
+ * | \%d | date and time of message using $date_format and sender's timezone
+ * | \%D | date and time of message using $date_format and local timezone
+ * | \%e | current message number in thread
+ * | \%E | number of messages in current thread
+ * | \%f | entire from line
+ * | \%F | like %n, unless from self
+ * | \%g | message labels (e.g. notmuch tags)
+ * | \%i | message-id
+ * | \%I | initials of author
+ * | \%K | the list to which the letter was sent (if any; otherwise: empty)
+ * | \%l | number of lines in the message
+ * | \%L | like %F, except `lists' are displayed first
+ * | \%m | number of messages in the mailbox
+ * | \%n | name of author
+ * | \%N | score
+ * | \%O | like %L, except using address instead of name
+ * | \%P | progress indicator for builtin pager
+ * | \%q | newsgroup name (if compiled with NNTP support)
+ * | \%r | comma separated list of To: recipients
+ * | \%R | comma separated list of Cc: recipients
+ * | \%s | subject
+ * | \%S | short message status (e.g., N/O/D/!/r/-)
+ * | \%t | `to:' field (recipients)
+ * | \%T | $to_chars
+ * | \%u | user (login) name of author
+ * | \%v | first name of author, unless from self
+ * | \%W | where user is (organization)
+ * | \%x | `x-comment-to:' field (if present and compiled with NNTP support)
+ * | \%X | number of MIME attachments
+ * | \%y | `x-label:' field (if present)
+ * | \%Y | `x-label:' field (if present, tree unfolded, and != parent's x-label)
+ * | \%zs | message status flags
+ * | \%zc | message crypto flags
+ * | \%zt | message tag flags
+ * | \%Z | combined message flags
*/
static const char *hdr_format_str(char *dest, size_t destlen, size_t col, int cols,
char op, const char *src, const char *prefix,
elem->data = (void *) count;
}
-/*
- * add an X-Label: field.
+/**
+ * label_message - add an X-Label: field
*/
static int label_message(struct Context *ctx, struct Header *hdr, char *new)
{
}
}
-/* When removing dups, we want the created "blanks" to be right below the
+/**
+ * remove_history_dups - De-dupe the history
+ *
+ * When removing dups, we want the created "blanks" to be right below the
* resulting h->last position. See the comment section above 'struct History'.
*/
static void remove_history_dups(enum HistoryClass hclass, const char *s)
FREE(&h);
}
-/* Deletes all hooks of type ``type'', or all defined hooks if ``type'' is 0 */
+/**
+ * delete_hooks - Delete matching hooks
+ * @param type
+ * * Hook type to delete, e.g. #MUTT_SENDHOOK
+ * * Or, 0 to delete all hooks
+ */
static void delete_hooks(int type)
{
struct Hook *h = NULL;
{ NULL, NULL },
};
-/* imap_authenticate: Attempt to authenticate using either user-specified
- * authentication method if specified, or any. */
+/**
+ * imap_authenticate - Authenticate to an IMAP server
+ *
+ * Attempt to authenticate using either user-specified authentication method if
+ * specified, or any.
+ */
int imap_authenticate(struct ImapData *idata)
{
const struct ImapAuth *authenticator = NULL;
#include "options.h"
#include "protos.h"
-/* this is basically a stripped-down version of the cram-md5 method. */
+/**
+ * imap_auth_anon - Authenticate anonymously
+ *
+ * this is basically a stripped-down version of the cram-md5 method.
+ */
enum ImapAuthRes imap_auth_anon(struct ImapData *idata, const char *method)
{
int rc;
/* forward declarations */
static void hmac_md5(const char *password, char *challenge, unsigned char *response);
-/* imap_auth_cram_md5: AUTH=CRAM-MD5 support. */
+/**
+ * imap_auth_cram_md5 - imap_auth_cram_md5: AUTH=CRAM-MD5 support
+ */
enum ImapAuthRes imap_auth_cram_md5(struct ImapData *idata, const char *method)
{
char ibuf[LONG_STRING * 2], obuf[LONG_STRING];
return IMAP_AUTH_FAILURE;
}
-/* hmac_md5: produce CRAM-MD5 challenge response. */
+/**
+ * hmac_md5 - hmac_md5: produce CRAM-MD5 challenge response
+ */
static void hmac_md5(const char *password, char *challenge, unsigned char *response)
{
struct Md5Ctx ctx;
mutt_debug(2, "((%s:%d )(%s:%d))\n", buf_maj, err_maj, buf_min, err_min);
}
-/* imap_auth_gss: AUTH=GSSAPI support. */
+/**
+ * imap_auth_gss - GSS Authentication support
+ */
enum ImapAuthRes imap_auth_gss(struct ImapData *idata, const char *method)
{
gss_buffer_desc request_buf, send_token;
#include "options.h"
#include "protos.h"
-/* imap_auth_login: Plain LOGIN support */
+/**
+ * imap_auth_login - Plain LOGIN support
+ */
enum ImapAuthRes imap_auth_login(struct ImapData *idata, const char *method)
{
char q_user[SHORT_STRING], q_pass[SHORT_STRING];
#include "mutt_socket.h"
#include "protos.h"
-/* imap_auth_plain: SASL PLAIN support */
+/**
+ * imap_auth_plain - SASL PLAIN support
+ */
enum ImapAuthRes imap_auth_plain(struct ImapData *idata, const char *method)
{
int rc;
#include "options.h"
#include "protos.h"
-/* imap_auth_sasl: Default authenticator if available. */
+/**
+ * imap_auth_sasl - Default authenticator if available
+ */
enum ImapAuthRes imap_auth_sasl(struct ImapData *idata, const char *method)
{
sasl_conn_t *saslconn = NULL;
#include "options.h"
#include "protos.h"
-/* imap_add_folder:
- * add a folder name to the browser list, formatting it as necessary.
+/**
+ * imap_add_folder - Format and add an IMAP folder to the browser
*
* The folder parameter should already be 'unmunged' via
* imap_unmunge_mbox_name().
return rc == IMAP_CMD_OK ? 0 : -1;
}
-/* imap_browse: IMAP hook into the folder browser, fills out browser_state,
- * given a current folder to browse */
+/**
+ * imap_browse - IMAP hook into the folder browser
+ *
+ * Fill out browser_state, given a current folder to browse
+ */
int imap_browse(char *path, struct BrowserState *state)
{
struct ImapData *idata = NULL;
return -1;
}
-/* imap_mailbox_create: Prompt for a new mailbox name, and try to create it */
+/**
+ * imap_mailbox_create - Create a new IMAP mailbox
+ *
+ * Prompt for a new mailbox name, and try to create it
+ */
int imap_mailbox_create(const char *folder)
{
struct ImapData *idata = NULL;
return cmd;
}
-/* queues command. If the queue is full, attempts to drain it. */
+/**
+ * cmd_queue - Add a IMAP command to the queue
+ *
+ * If the queue is full, attempts to drain it.
+ */
static int cmd_queue(struct ImapData *idata, const char *cmdstr)
{
struct ImapCommand *cmd = NULL;
return 0;
}
-/* cmd_handle_fatal: when ImapData is in fatal state, do what we can */
+/**
+ * cmd_handle_fatal - When ImapData is in fatal state, do what we can
+ */
static void cmd_handle_fatal(struct ImapData *idata)
{
idata->status = IMAP_FATAL;
return (rc < 0) ? IMAP_CMD_BAD : 0;
}
-/* parse response line for tagged OK/NO/BAD */
+/**
+ * cmd_status - parse response line for tagged OK/NO/BAD
+ */
static int cmd_status(const char *s)
{
s = imap_next_word((char *) s);
return IMAP_CMD_BAD;
}
-/* cmd_parse_expunge: mark headers with new sequence ID and mark idata to
- * be reopened at our earliest convenience */
+/**
+ * cmd_parse_expunge - Parse expunge command
+ *
+ * cmd_parse_expunge: mark headers with new sequence ID and mark idata to be
+ * reopened at our earliest convenience
+ */
static void cmd_parse_expunge(struct ImapData *idata, const char *s)
{
unsigned int exp_msn;
idata->reopen |= IMAP_EXPUNGE_PENDING;
}
-/* cmd_parse_fetch: Load fetch response into ImapData. Currently only
- * handles unanticipated FETCH responses, and only FLAGS data. We get
- * these if another client has changed flags for a mailbox we've selected.
- * Of course, a lot of code here duplicates code in message.c. */
+/**
+ * cmd_parse_fetch - Load fetch response into ImapData
+ *
+ * Currently only handles unanticipated FETCH responses, and only FLAGS data.
+ * We get these if another client has changed flags for a mailbox we've
+ * selected. Of course, a lot of code here duplicates code in message.c.
+ */
static void cmd_parse_fetch(struct ImapData *idata, char *s)
{
unsigned int msn;
}
}
-/* cmd_parse_capabilities: set capability bits according to CAPABILITY
- * response */
+/**
+ * cmd_parse_capability - set capability bits according to CAPABILITY response
+ */
static void cmd_parse_capability(struct ImapData *idata, char *s)
{
int x;
FREE(&token.data);
}
-/* cmd_parse_myrights: set rights bits according to MYRIGHTS response */
+/**
+ * cmd_parse_myrights - Set rights bits according to MYRIGHTS response
+ */
static void cmd_parse_myrights(struct ImapData *idata, const char *s)
{
mutt_debug(2, "Handling MYRIGHTS\n");
}
}
-/* cmd_parse_search: store SEARCH response for later use */
+/**
+ * cmd_parse_search - store SEARCH response for later use
+ */
static void cmd_parse_search(struct ImapData *idata, const char *s)
{
unsigned int uid;
}
}
-/* first cut: just do buffy update. Later we may wish to cache all
- * mailbox information, even that not desired by buffy */
+/**
+ * cmd_parse_status - Parse status from server
+ *
+ * first cut: just do buffy update. Later we may wish to cache all mailbox
+ * information, even that not desired by buffy
+ */
static void cmd_parse_status(struct ImapData *idata, char *s)
{
char *mailbox = NULL;
}
}
-/* cmd_parse_enabled: record what the server has enabled */
+/**
+ * cmd_parse_enabled - Record what the server has enabled
+ */
static void cmd_parse_enabled(struct ImapData *idata, const char *s)
{
mutt_debug(2, "Handling ENABLED\n");
}
}
-/* cmd_handle_untagged: fallback parser for otherwise unhandled messages. */
+/**
+ * cmd_handle_untagged - fallback parser for otherwise unhandled messages
+ */
static int cmd_handle_untagged(struct ImapData *idata)
{
char *s = NULL;
return 0;
}
-/* imap_cmd_start: Given an IMAP command, send it to the server.
- * If cmdstr is NULL, sends queued commands. */
+/**
+ * imap_cmd_start - Given an IMAP command, send it to the server
+ *
+ * If cmdstr is NULL, sends queued commands.
+ */
int imap_cmd_start(struct ImapData *idata, const char *cmdstr)
{
return cmd_start(idata, cmdstr, 0);
}
-/* imap_cmd_step: Reads server responses from an IMAP command, detects
- * tagged completion response, handles untagged messages, can read
- * arbitrarily large strings (using malloc, so don't make it _too_
- * large!). */
+/**
+ * imap_cmd_step - Reads server responses from an IMAP command
+ *
+ * detects tagged completion response, handles untagged messages, can read
+ * arbitrarily large strings (using malloc, so don't make it _too_ large!).
+ */
int imap_cmd_step(struct ImapData *idata)
{
size_t len = 0;
return rc;
}
-/* imap_code: returns 1 if the command result was OK, or 0 if NO or BAD */
+/**
+ * imap_code - Was the command successful
+ * @return 1 if the command result was OK, or 0 if NO or BAD
+ */
int imap_code(const char *s)
{
return cmd_status(s) == IMAP_CMD_OK;
}
-/* imap_cmd_trailer: extra information after tagged command response if any */
+/**
+ * imap_cmd_trailer - Extra information after tagged command response if any
+ */
const char *imap_cmd_trailer(struct ImapData *idata)
{
static const char *notrailer = "";
return 0;
}
-/* imap_cmd_finish: Attempts to perform cleanup (eg fetch new mail if
- * detected, do expunge). Called automatically by imap_cmd_step, but
- * may be called at any time. Called by imap_check_mailbox just before
- * the index is refreshed, for instance. */
+/**
+ * imap_cmd_finish - Attempt to perform cleanup
+ *
+ * Attempts to perform cleanup (eg fetch new mail if detected, do expunge).
+ * Called automatically by imap_cmd_step(), but may be called at any time.
+ * Called by imap_check_mailbox() just before the index is refreshed, for
+ * instance.
+ */
void imap_cmd_finish(struct ImapData *idata)
{
if (idata->status == IMAP_FATAL)
idata->status = false;
}
-/* imap_cmd_idle: Enter the IDLE state. */
+/**
+ * imap_cmd_idle - Enter the IDLE state
+ */
int imap_cmd_idle(struct ImapData *idata)
{
int rc;
static void imap_set_flag(struct ImapData *idata, int aclbit, int flag,
const char *str, char *flags, size_t flsize);
-/* imap_access: Check permissions on an IMAP mailbox.
- * TODO: ACL checks. Right now we assume if it exists we can
- * mess with it. */
+/**
+ * imap_access - Check permissions on an IMAP mailbox
+ *
+ * TODO: ACL checks. Right now we assume if it exists we can mess with it.
+ */
int imap_access(const char *path)
{
struct ImapData *idata = NULL;
return 0;
}
-/* imap_logout_all: close all open connections. Quick and dirty until we can
- * make sure we've got all the context we need. */
+/**
+ * imap_logout_all - close all open connections
+ *
+ * Quick and dirty until we can make sure we've got all the context we need.
+ */
void imap_logout_all(void)
{
struct Connection *conn = NULL;
}
}
-/* imap_read_literal: read bytes bytes from server into file. Not explicitly
- * buffered, relies on FILE buffering. NOTE: strips \r from \r\n.
- * Apparently even literals use \r\n-terminated strings ?! */
+/**
+ * imap_read_literal - Read bytes bytes from server into file
+ *
+ * Not explicitly buffered, relies on FILE buffering. NOTE: strips `\r` from
+ * `\r\n`. Apparently even literals use `\r\n`-terminated strings ?!
+ */
int imap_read_literal(FILE *fp, struct ImapData *idata, long bytes, struct Progress *pbar)
{
char c;
return 0;
}
-/* imap_expunge_mailbox: Purge IMAP portion of expunged messages from the
- * context. Must not be done while something has a handle on any headers
- * (eg inside pager or editor). That is, check IMAP_REOPEN_ALLOW. */
+/**
+ * imap_expunge_mailbox - Purge messages from the server
+ *
+ * Purge IMAP portion of expunged messages from the context. Must not be done
+ * while something has a handle on any headers (eg inside pager or editor).
+ * That is, check IMAP_REOPEN_ALLOW.
+ */
void imap_expunge_mailbox(struct ImapData *idata)
{
struct Header *h = NULL;
mutt_sort_headers(idata->ctx, 1);
}
-/* imap_check_capabilities: make sure we can log in to this server. */
+/**
+ * imap_check_capabilities - Make sure we can log in to this server
+ */
static int imap_check_capabilities(struct ImapData *idata)
{
if (imap_exec(idata, "CAPABILITY", 0) != 0)
return 0;
}
-/* imap_conn_find: Find an open IMAP connection matching account, or open
- * a new one if none can be found. */
+/**
+ * imap_conn_find - Find an open IMAP connection
+ *
+ * Find an open IMAP connection matching account, or open a new one if none can
+ * be found.
+ */
struct ImapData *imap_conn_find(const struct Account *account, int flags)
{
struct Connection *conn = NULL;
memset(idata->cmds, 0, sizeof(struct ImapCommand) * idata->cmdslots);
}
-/* imap_get_flags: Make a simple list out of a FLAGS response.
- * return stream following FLAGS response */
+/**
+ * imap_get_flags - Make a simple list out of a FLAGS response
+ *
+ * return stream following FLAGS response
+ */
static char *imap_get_flags(struct List **hflags, char *s)
{
struct List *flags = NULL;
return 0;
}
-/* imap_logout: Gracefully log out of server. */
+/**
+ * imap_logout - Gracefully log out of server
+ */
void imap_logout(struct ImapData **idata)
{
/* we set status here to let imap_handle_untagged know we _expect_ to
safe_strcat(flags, flsize, str);
}
-/* imap_has_flag: do a caseless comparison of the flag against a flag list,
-* return true if found or flag list has '\*', false otherwise */
+/**
+ * imap_has_flag - Does the flag exist in the list
+ * @return boolean
+ *
+ * Do a caseless comparison of the flag against a flag list, return true if
+ * found or flag list has '\*'.
+ */
bool imap_has_flag(struct List *flag_list, const char *flag)
{
if (!flag_list)
return false;
}
-/* Note: headers must be in SORT_ORDER. See imap_exec_msgset for args.
+/**
+ * imap_make_msg_set - Make a message set
+ *
+ * Note: headers must be in SORT_ORDER. See imap_exec_msgset for args.
* Pos is an opaque pointer a la strtok. It should be 0 at first call. */
static int imap_make_msg_set(struct ImapData *idata, struct Buffer *buf,
int flag, bool changed, bool invert, int *pos)
return rc;
}
-/* returns 0 if mutt's flags match cached server flags */
+/**
+ * compare_flags - Compare local flags against the server
+ * @return 0 if mutt's flags match cached server flags
+ */
static bool compare_flags(struct Header *h)
{
struct ImapHeaderData *hd = (struct ImapHeaderData *) h->data;
return false;
}
-/* Update the IMAP server to reflect the flags a single message. */
+/**
+ * imap_sync_message - Update server to reflect the flags of a single message
+ */
int imap_sync_message(struct ImapData *idata, struct Header *hdr,
struct Buffer *cmd, int *err_continue)
{
return count;
}
-/* update the IMAP server to reflect message changes done within mutt.
- * Arguments
- * ctx: the current context
- * expunge: 0 or 1 - do expunge?
+/**
+ * imap_sync_mailbox - Sync all the changes to the server
+ * @param ctx the current context
+ * @param expunge 0 or 1 - do expunge?
+ * @return 0 on success, -1 on error
*/
int imap_sync_mailbox(struct Context *ctx, int expunge)
{
return rc;
}
-/* imap_close_mailbox: clean up IMAP data in Context */
+/**
+ * imap_close_mailbox - Clean up IMAP data in Context
+ */
int imap_close_mailbox(struct Context *ctx)
{
struct ImapData *idata = NULL;
return rc;
}
-/* split path into (idata,mailbox name) */
+/**
+ * imap_get_mailbox - split path into (idata,mailbox name)
+ */
static int imap_get_mailbox(const char *path, struct ImapData **hidata, char *buf, size_t blen)
{
struct ImapMbox mx;
return 0;
}
-/* check for new mail in any subscribed mailboxes. Given a list of mailboxes
- * rather than called once for each so that it can batch the commands and
- * save on round trips. Returns number of mailboxes with new mail. */
+/**
+ * imap_buffy_check - Check for new mail in subscribed folders
+ *
+ * Given a list of mailboxes rather than called once for each so that it can
+ * batch the commands and save on round trips. Returns number of mailboxes with
+ * new mail.
+ */
int imap_buffy_check(int force, int check_stats)
{
struct ImapData *idata = NULL;
return buffies;
}
-/* imap_status: returns count of messages in mailbox, or -1 on error.
+/**
+ * imap_status - Get the status of a mailbox
+ * @return
+ * * -1 on error
+ * * >=0 count of messages in mailbox
* if queue != 0, queue the command and expect it to have been run
* on the next call (for pipelining the postponed count) */
int imap_status(char *path, int queue)
return 0;
}
-/* return cached mailbox stats or NULL if create is 0 */
+/**
+ * imap_mboxcache_get - Open an hcache for a mailbox
+ *
+ * return cached mailbox stats or NULL if create is 0
+ */
struct ImapStatus *imap_mboxcache_get(struct ImapData *idata, const char *mbox, int create)
{
struct List *cur = NULL;
mutt_free_list(&idata->mboxcache);
}
-/* returns number of patterns in the search that should be done server-side
- * (eg are full-text) */
+/**
+ * do_search - Perform a search of messages
+ *
+ * returns number of patterns in the search that should be done server-side
+ * (eg are full-text)
+ */
static int do_search(const struct Pattern *search, int allpats)
{
int rc = 0;
return rc;
}
-/* convert mutt Pattern to IMAP SEARCH command containing only elements
+/**
+ * imap_compile_search - Convert Mutt pattern to IMAP search
+ *
+ * Convert mutt Pattern to IMAP SEARCH command containing only elements
* that require full-text search (mutt already has what it needs for most
- * match types, and does a better job (eg server doesn't support regexps). */
+ * match types, and does a better job (eg server doesn't support regexps).
+ */
static int imap_compile_search(struct Context *ctx, const struct Pattern *pat,
struct Buffer *buf)
{
return pos;
}
-/* look for IMAP URLs to complete from defined mailboxes. Could be extended
- * to complete over open connections and account/folder hooks too. */
+/**
+ * imap_complete_hosts - Look for completion matches for mailboxes
+ *
+ * look for IMAP URLs to complete from defined mailboxes. Could be extended to
+ * complete over open connections and account/folder hooks too.
+ */
static int imap_complete_hosts(char *dest, size_t len)
{
struct Buffy *mailbox = NULL;
return rc;
}
-/* imap_complete: given a partial IMAP folder path, return a string which
- * adds as much to the path as is unique */
+/**
+ * imap_complete - Try to complete an IMAP folder path
+ *
+ * Given a partial IMAP folder path, return a string which adds as much to the
+ * path as is unique
+ */
int imap_complete(char *dest, size_t dlen, char *path)
{
struct ImapData *idata = NULL;
return -1;
}
-/* imap_fast_trash: use server COPY command to copy deleted
- * messages to the trash folder.
- * Return codes:
- * -1: error
- * 0: success
- * 1: non-fatal error - try fetch/append */
+/**
+ * imap_fast_trash - Use server COPY command to copy deleted messages to trash
+ * @return
+ * * -1: error
+ * * 0: success
+ * * 1: non-fatal error - try fetch/append
+ */
int imap_fast_trash(struct Context *ctx, char *dest)
{
struct ImapData *idata = NULL;
return 0;
}
-/* msg_parse_flags: read a FLAGS token into an ImapHeader */
+/**
+ * msg_parse_flags - read a FLAGS token into an ImapHeader
+ */
static char *msg_parse_flags(struct ImapHeader *h, char *s)
{
struct ImapHeaderData *hd = h->data;
return 0;
}
-/* msg_fetch_header: import IMAP FETCH response into an ImapHeader.
- * Expects string beginning with * n FETCH.
- * Returns:
- * 0 on success
- * -1 if the string is not a fetch response
- * -2 if the string is a corrupt fetch response */
+/**
+ * msg_fetch_header -import IMAP FETCH response into an ImapHeader.
+ * @return
+ * * 0 Success
+ * * -1 String is not a fetch response
+ * * -2 String is a corrupt fetch response
+ *
+ * Expects string beginning with * n FETCH.
+ */
static int msg_fetch_header(struct Context *ctx, struct ImapHeader *h, char *buf, FILE *fp)
{
struct ImapData *idata = NULL;
idata->msn_index_size = new_size;
}
-/* Generates a more complicated sequence set after using the header cache,
+/**
+ * imap_generate_seqset - Generate a sequence set
+ *
+ * Generates a more complicated sequence set after using the header cache,
* in case there are missing MSNs in the middle.
*
* There is a suggested limit of 1000 bytes for an IMAP client request.
}
}
-/* imap_read_headers:
- * Changed to read many headers instead of just one. It will return the
- * msn of the last message read. It will return a value other than
- * msn_end if mail comes in while downloading headers (in theory).
+/**
+ * imap_read_headers - Read headers from the server
+ *
+ * Changed to read many headers instead of just one. It will return the msn of
+ * the last message read. It will return a value other than msn_end if mail
+ * comes in while downloading headers (in theory).
*/
int imap_read_headers(struct ImapData *idata, unsigned int msn_begin, unsigned int msn_end)
{
return -1;
}
-/* imap_copy_messages: use server COPY command to copy messages to another
- * folder.
- * Return codes:
- * -1: error
- * 0: success
- * 1: non-fatal error - try fetch/append */
+/**
+ * imap_copy_messages - Server COPY messages to another folder
+ * @return
+ * * -1 Error
+ * * 0 Success
+ * * 1 Non-fatal error - try fetch/append
+ */
int imap_copy_messages(struct Context *ctx, struct Header *h, char *dest, int delete)
{
struct ImapData *idata = NULL;
return 0;
}
-/* imap_add_keywords: concatenate custom IMAP tags to list, if they
- * appear in the folder flags list. Why wouldn't they? */
+/**
+ * imap_add_keywords - concatenate custom IMAP tags to list
+ *
+ * If the tags appear in the folder flags list. Why wouldn't they?
+ */
void imap_add_keywords(char *s, struct Header *h, struct List *mailbox_flags, size_t slen)
{
struct List *keywords = NULL;
}
}
-/* imap_free_header_data: free ImapHeader structure */
+/**
+ * imap_free_header_data - free ImapHeader structure
+ */
void imap_free_header_data(struct ImapHeaderData **data)
{
if (*data)
}
}
-/* imap_set_flags: fill out the message header according to the flags from
- * the server. Expects a flags line of the form "FLAGS (flag flag ...)" */
+/**
+ * imap_set_flags - fill the message header according to the server flags
+ *
+ * Expects a flags line of the form "FLAGS (flag flag ...)"
+ */
char *imap_set_flags(struct ImapData *idata, struct Header *h, char *s)
{
struct Context *ctx = idata->ctx;
'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '+', ',',
};
-/*
- * Convert the data (u7,u7len) from RFC 2060's UTF-7 to UTF-8.
- * The result is null-terminated and returned, and also stored
- * in (*u8,*u8len) if u8 or u8len is non-zero.
- * If input data is invalid, return 0 and don't store anything.
- * RFC 2060 obviously intends the encoding to be unique (see
- * point 5 in section 5.1.3), so we reject any non-canonical
- * form, such as &ACY- (instead of &-) or &AMA-&AMA- (instead
- * of &AMAAwA-).
+/**
+ * utf7_to_utf8 - Convert the data (u7,u7len) from RFC 2060's UTF-7 to UTF-8
+ *
+ * The result is null-terminated and returned, and also stored in (*u8,*u8len)
+ * if u8 or u8len is non-zero. If input data is invalid, return 0 and don't
+ * store anything. RFC 2060 obviously intends the encoding to be unique (see
+ * point 5 in section 5.1.3), so we reject any non-canonical form, such as
+ * &ACY- (instead of &-) or &AMA-&AMA- (instead of &AMAAwA-).
*/
static char *utf7_to_utf8(const char *u7, size_t u7len, char **u8, size_t *u8len)
{
return 0;
}
-/*
- * Convert the data (u8,u8len) from UTF-8 to RFC 2060's UTF-7.
- * The result is null-terminated and returned, and also stored
- * in (*u7,*u7len) if u7 or u7len is non-zero.
- * Unicode characters above U+FFFF are replaced by U+FFFE.
- * If input data is invalid, return 0 and don't store anything.
+/**
+ * utf8_to_utf7 - Convert the data (u8,u8len) from UTF-8 to RFC 2060's UTF-7
+ *
+ * The result is null-terminated and returned, and also stored in (*u7,*u7len)
+ * if u7 or u7len is non-zero. Unicode characters above U+FFFF are replaced by
+ * U+FFFE. If input data is invalid, return 0 and don't store anything.
*/
static char *utf8_to_utf7(const char *u8, size_t u8len, char **u7, size_t *u7len)
{
return rc;
}
-/* Public function
- *
- * Provided an imap mbox name and a delimiter, returns the mbox parent
- * name.
- *
- * Could be static with a prototype in imap_private.h, but could be useful
- * as a public function.
+/**
+ * imap_get_parent - Get an IMAP folder's parent
*/
void imap_get_parent(char *output, const char *mbox, size_t olen, char delim)
{
}
}
-/* Public function
+/**
+ * imap_get_parent_path - Get the path of the parent folder
+ *
* Provided an imap path, returns in output the parent directory if
* existent. Else returns the same path.
*/
imap_qualify_path(output, olen, &mx, mbox);
}
-/* Public function
+/**
+ * imap_clean_path - Cleans an IMAP path using imap_fix_path
*
- * Cleans an IMAP path using imap_fix_path. Does it in place.
+ * Does it in place.
*/
void imap_clean_path(char *path, size_t plen)
{
}
#endif
-/* imap_parse_path: given an IMAP mailbox name, return host, port
- * and a path IMAP servers will recognize.
- * mx.mbox is malloc'd, caller must free it */
+/**
+ * imap_parse_path - Parse an IMAP mailbox name into name,host,port
+ *
+ * Given an IMAP mailbox name, return host, port and a path IMAP servers will
+ * recognize. mx.mbox is malloc'd, caller must free it
+ */
int imap_parse_path(const char *path, struct ImapMbox *mx)
{
static unsigned short ImapPort = 0;
return 0;
}
-/* silly helper for mailbox name string comparisons, because of INBOX */
+/**
+ * imap_mxcmp - Compare mailbox names, giving priority to INBOX
+ *
+ * silly helper for mailbox name string comparisons, because of INBOX
+ */
int imap_mxcmp(const char *mx1, const char *mx2)
{
char *b1 = NULL;
return rc;
}
-/* imap_pretty_mailbox: called by mutt_pretty_mailbox to make IMAP paths
- * look nice. */
+/**
+ * imap_pretty_mailbox - Prettify an IMAP mailbox name
+ *
+ * Called by mutt_pretty_mailbox() to make IMAP paths look nice.
+ */
void imap_pretty_mailbox(char *path)
{
struct ImapMbox home, target;
/* -- library functions -- */
-/* imap_continue: display a message and ask the user if she wants to
- * go on. */
+/**
+ * imap_continue - display a message and ask the user if they want to go on
+ */
int imap_continue(const char *msg, const char *resp)
{
imap_error(msg, resp);
return mutt_yesorno(_("Continue?"), 0);
}
-/* imap_error: show an error and abort */
+/**
+ * imap_error - show an error and abort
+ */
void imap_error(const char *where, const char *msg)
{
mutt_error("%s [%s]\n", where, msg);
mutt_sleep(2);
}
-/* imap_new_idata: Allocate and initialise a new ImapData structure.
- * Returns NULL on failure (no mem) */
+/**
+ * imap_new_idata - Allocate and initialise a new ImapData structure
+ * @return NULL on failure (no mem)
+ */
struct ImapData *imap_new_idata(void)
{
struct ImapData *idata = safe_calloc(1, sizeof(struct ImapData));
return idata;
}
-/* imap_free_idata: Release and clear storage in an ImapData structure. */
+/**
+ * imap_free_idata - Release and clear storage in an ImapData structure
+ */
void imap_free_idata(struct ImapData **idata)
{
if (!idata)
FREE(idata);
}
-/*
- * Fix up the imap path. This is necessary because the rest of mutt
- * assumes a hierarchy delimiter of '/', which is not necessarily true
- * in IMAP. Additionally, the filesystem converts multiple hierarchy
- * delimiters into a single one, ie "///" is equal to "/". IMAP servers
- * are not required to do this.
+/**
+ * imap_fix_path - Fix up the imap path
+ *
+ * This is necessary because the rest of mutt assumes a hierarchy delimiter of
+ * '/', which is not necessarily true in IMAP. Additionally, the filesystem
+ * converts multiple hierarchy delimiters into a single one, ie "///" is equal
+ * to "/". IMAP servers are not required to do this.
* Moreover, IMAP servers may dislike the path ending with the delimiter.
*/
char *imap_fix_path(struct ImapData *idata, const char *mailbox, char *path, size_t plen)
*s = '\0';
}
-/* imap_get_literal_count: write number of bytes in an IMAP literal into
- * bytes, return 0 on success, -1 on failure. */
+/**
+ * imap_get_literal_count - write number of bytes in an IMAP literal into bytes
+ * @return 0 on success, -1 on failure
+ */
int imap_get_literal_count(const char *buf, long *bytes)
{
char *pc = NULL;
return 0;
}
-/* imap_get_qualifier: in a tagged response, skip tag and status for
- * the qualifier message. Used by imap_copy_message for TRYCREATE */
+/**
+ * imap_get_qualifier - Get the qualifier from a tagged reponse
+ *
+ * In a tagged response, skip tag and status for the qualifier message. Used by
+ * imap_copy_message for TRYCREATE
+ */
char *imap_get_qualifier(char *buf)
{
char *s = buf;
return s;
}
-/* imap_next_word: return index into string where next IMAP word begins */
+/**
+ * imap_next_word - return index into string where next IMAP word begins
+ */
char *imap_next_word(char *s)
{
int quoted = 0;
return s;
}
-/* imap_parse_date: date is of the form: DD-MMM-YYYY HH:MM:SS +ZZzz */
+/**
+ * imap_parse_date - Parse date of the form: DD-MMM-YYYY HH:MM:SS +ZZzz
+ */
time_t imap_parse_date(char *s)
{
struct tm t;
return (mutt_mktime(&t, 0) + tz);
}
-/* format date in IMAP style: DD-MMM-YYYY HH:MM:SS +ZZzz.
+/**
+ * imap_make_date - format date in IMAP style: DD-MMM-YYYY HH:MM:SS +ZZzz
+ *
* Caller should provide a buffer of IMAP_DATELEN bytes */
void imap_make_date(char *buf, time_t timestamp)
{
tm->tm_min, tm->tm_sec, (int) tz / 60, (int) abs((int) tz) % 60);
}
-/* imap_qualify_path: make an absolute IMAP folder target, given ImapMbox
- * and relative path. */
+/**
+ * imap_qualify_path - Make an absolute IMAP folder target
+ *
+ * given ImapMbox and relative path.
+ */
void imap_qualify_path(char *dest, size_t len, struct ImapMbox *mx, char *path)
{
struct CissUrl url;
}
-/* imap_quote_string: quote string according to IMAP rules:
- * surround string with quotes, escape " and \ with \ */
+/**
+ * imap_quote_string - quote string according to IMAP rules
+ *
+ * Surround string with quotes, escape " and \ with backslash
+ */
void imap_quote_string(char *dest, size_t dlen, const char *src)
{
static const char quote[] = "\"\\";
*pt = 0;
}
-/* imap_unquote_string: equally stupid unquoting routine */
+/**
+ * imap_unquote_string - equally stupid unquoting routine
+ */
void imap_unquote_string(char *s)
{
char *d = s;
}
-/*
- * Quoting and UTF-7 conversion
+/**
+ * imap_munge_mbox_name - Quoting and UTF-7 conversion
*/
void imap_munge_mbox_name(struct ImapData *idata, char *dest, size_t dlen, const char *src)
{
FREE(&buf);
}
-/* imap_wordcasecmp: find word a in word list b */
+/**
+ * imap_wordcasecmp - find word a in word list b
+ */
int imap_wordcasecmp(const char *a, const char *b)
{
char tmp[SHORT_STRING];
return rc;
}
-/* Allow/disallow re-opening a folder upon expunge. */
+/**
+ * imap_allow_reopen - Allow/disallow re-opening a folder upon expunge
+ */
void imap_allow_reopen(struct Context *ctx)
{
struct ImapData *idata = NULL;
/* not reached */
}
-/* given the variable ``s'', return the index into the rc_vars array which
- matches, or -1 if the variable is not found. */
+/**
+ * mutt_option_index - Find the index (in rc_vars) of a variable name
+ * @param s Variable name to search for
+ * @return -1 on error, >0 on success
+ */
int mutt_option_index(const char *s)
{
for (int i = 0; MuttVars[i].option; i++)
}
}
-/* clean up before quitting */
+/**
+ * mutt_free_opts - clean up before quitting
+ */
void mutt_free_opts(void)
{
for (int i = 0; MuttVars[i].option; i++)
return -1;
}
-/* always wise to do what someone else did before */
+/**
+ * _attachments_clean - always wise to do what someone else did before
+ */
static void _attachments_clean(void)
{
int i;
return 0;
}
-/* line command to execute
-
- token scratch buffer to be used by parser. caller should free
- token->data when finished. the reason for this variable is
- to avoid having to allocate and deallocate a lot of memory
- if we are parsing many lines. the caller can pass in the
- memory to use, which avoids having to create new space for
- every call to this function.
-
- err where to write error messages */
+/**
+ * mutt_parse_rc_line - Parse a line of user config
+ * @param line config line to read
+ * @param token scratch buffer to be used by parser
+ * @param err where to write error messages
+ *
+ * Caller should free token->data when finished. the reason for this variable
+ * is to avoid having to allocate and deallocate a lot of memory if we are
+ * parsing many lines. the caller can pass in the memory to use, which avoids
+ * having to create new space for every call to this function.
+ */
int mutt_parse_rc_line(/* const */ char *line, struct Buffer *token, struct Buffer *err)
{
int i, r = 0;
}
}
-/* helper function for completion. Changes the dest buffer if
- necessary/possible to aid completion.
- dest == completion result gets here.
- src == candidate for completion.
- try == user entered data for completion.
- len == length of dest buffer.
+/**
+ * candidate - helper function for completion
+ * @param dest Completion result gets here
+ * @param src Candidate for completion
+ * @param try User entered data for completion
+ * @param len Length of dest buffer
+ *
+ * Changes the dest buffer if necessary/possible to aid completion.
*/
static void candidate(char *dest, char *try, const char *src, int len)
{
#ifdef USE_NOTMUCH
-/* Fetch a list of all notmuch tags and insert them into the completion
- * machinery.
+/**
+ * complete_all_nm_tags - Pass a list of notmuch tags to the completion code
*/
static int complete_all_nm_tags(const char *pt)
{
return 0;
}
-/* Return the last instance of needle in the haystack, or NULL.
+/**
+ * rstrnstr - Find last instance of a substring
+ *
+ * Return the last instance of needle in the haystack, or NULL.
* Like strstr(), only backwards, and for a limited haystack length.
*/
static const char *rstrnstr(const char *haystack, size_t haystack_length, const char *needle)
return NULL;
}
-/* Complete the nearest "tag:"-prefixed string previous to pos. */
+/**
+ * mutt_nm_query_complete - Complete to the nearest notmuch tag
+ *
+ * Complete the nearest "tag:"-prefixed string previous to pos.
+ */
bool mutt_nm_query_complete(char *buffer, size_t len, int pos, int numtabs)
{
char *pt = buffer;
return true;
}
-/* Complete the nearest "+" or "-" -prefixed string previous to pos. */
+/**
+ * mutt_nm_tag_complete - Complete to the nearest notmuch tag
+ *
+ * Complete the nearest "+" or "-" -prefixed string previous to pos.
+ */
bool mutt_nm_tag_complete(char *buffer, size_t len, int pos, int numtabs)
{
if (!buffer)
return 1;
}
-/* Implement the -Q command line flag */
+/**
+ * mutt_query_variables - Implement the -Q command line flag
+ */
int mutt_query_variables(struct List *queries)
{
struct List *p = NULL;
return 0;
}
-/* dump out the value of all the variables we have */
+/**
+ * mutt_dump_variables - Print a list of all variables with their values
+ */
int mutt_dump_variables(int hide_sensitive)
{
char command[STRING];
return n;
}
-/*
- * This function parses the string <NNN> and uses the octal value as the key
+/**
+ * parse_keycode - Parse a numeric keycode
+ *
+ * This function parses the string `<NNN>` and uses the octal value as the key
* to bind.
*/
static int parse_keycode(const char *s)
return (max - len);
}
-/* insert a key sequence into the specified map. the map is sorted by ASCII
- * value (lowest to highest)
+/**
+ * km_bind_err - Set up a key binding
+ *
+ * Insert a key sequence into the specified map.
+ * The map is sorted by ASCII value (lowest to highest)
*/
int km_bind_err(char *s, int menu, int op, char *macro, char *descr, struct Buffer *err)
{
{
return km_bind_err(s, menu, op, NULL, NULL, err);
}
+
static int km_bindkey(char *s, int menu, int op)
{
return km_bindkey_err(s, menu, op, NULL);
return NULL;
}
-/* Parses s for <function> syntax and adds the whole sequence to
- * either the macro or unget buffer. This function is invoked by the next
- * two defines below.
+/**
+ * generic_tokenize_push_string - Parse and queue a 'push' command
+ *
+ * Parses s for `<function>` syntax and adds the whole sequence to either the
+ * macro or unget buffer. This function is invoked by the next two defines
+ * below.
*/
static void generic_tokenize_push_string(char *s, void (*generic_push)(int, int))
{
return OP_NULL;
}
-/* return values:
- * >0 function to execute
- * OP_NULL no function bound to key sequence
- * -1 error occurred while reading input
- * -2 a timeout or sigwinch occurred
+/**
+ * km_dokey - Determine what a keypress should do
+ * @return
+ * * >0 Function to execute
+ * * OP_NULL No function bound to key sequence
+ * * -1 Error occurred while reading input
+ * * -2 A timeout or sigwinch occurred
*/
int km_dokey(int menu)
{
{ 0, 0 },
};
-/* Look up Mutt's name for a key and find the ncurses extended name for it */
+/**
+ * find_ext_name - Find the curses name for a key
+ *
+ * Look up Mutt's name for a key and find the ncurses extended name for it
+ */
static const char *find_ext_name(const char *key)
{
for (int j = 0; ExtKeys[j].name; ++j)
}
#endif /* NCURSES_VERSION */
-/* Determine the keycodes for ncurses extended keys and fill in the KeyNames array.
+/**
+ * init_extended_keys - Initialise map of ncurses extended keys
+ *
+ * Determine the keycodes for ncurses extended keys and fill in the KeyNames array.
*
- * This function must be called *after* initscr(), or tigetstr() returns -1. This
- * creates a bit of a chicken-and-egg problem because km_init() is called prior to
- * start_curses(). This means that the default keybindings can't include any of the
- * extended keys because they won't be defined until later.
+ * This function must be called *after* initscr(), or tigetstr() returns -1.
+ * This creates a bit of a chicken-and-egg problem because km_init() is called
+ * prior to start_curses(). This means that the default keybindings can't
+ * include any of the extended keys because they won't be defined until later.
*/
void init_extended_keys(void)
{
return r;
}
-/* expects to see: <menu-string>,<menu-string>,... <key-string> */
+/**
+ * parse_keymap - Parse a user-config key binding
+ *
+ * Expects to see: <menu-string>,<menu-string>,... <key-string>
+ */
char *parse_keymap(int *menu, struct Buffer *s, int maxmenus, int *nummenus, struct Buffer *err)
{
struct Buffer buf;
return NULL;
}
-/* bind menu-name '<key_sequence>' function-name */
+/**
+ * mutt_parse_bind - Parse a 'bind' command
+ *
+ * bind menu-name `<key_sequence>` function-name
+ */
int mutt_parse_bind(struct Buffer *buf, struct Buffer *s, unsigned long data,
struct Buffer *err)
{
return r;
}
-/* macro <menu> <key> <macro> <description> */
+/**
+ * mutt_parse_macro - Parse a 'macro' command
+ *
+ * macro `<menu>` `<key>` `<macro>` `<description>`
+ */
int mutt_parse_macro(struct Buffer *buf, struct Buffer *s, unsigned long data,
struct Buffer *err)
{
return r;
}
-/* exec function-name */
+/**
+ * mutt_parse_exec - exec function-name
+ */
int mutt_parse_exec(struct Buffer *buf, struct Buffer *s, unsigned long data,
struct Buffer *err)
{
return 0;
}
-/*
- * prompts the user to enter a keystroke, and displays the octal value back
- * to the user.
+/**
+ * mutt_what_key - Ask the user to press a key
+ *
+ * Displays the octal value back to the user.
*/
void mutt_what_key(void)
{
safe_realloc(p, strlen(*p) + 1);
}
-/* convert all characters in the string to lowercase */
+/**
+ * mutt_strlower - convert all characters in the string to lowercase
+ */
char *mutt_strlower(char *s)
{
char *p = s;
}
-/*
- * This function is supposed to do nfs-safe renaming of files.
+/**
+ * safe_rename - NFS-safe renaming of files
*
* Warning: We don't check whether src and target are equal.
*/
}
-/* Create a temporary directory next to a file name */
+/**
+ * mkwrapdir - Create a temporary directory next to a file name
+ */
static int mkwrapdir(const char *path, char *newfile, size_t nflen, char *newdir, size_t ndlen)
{
const char *basename = NULL;
return 0;
}
-/* remove a directory and everything under it */
+/**
+ * mutt_rmtree - remove a directory and everything under it
+ */
int mutt_rmtree(const char *path)
{
DIR *dirp = NULL;
return fd;
}
-/* when opening files for writing, make sure the file doesn't already exist
- * to avoid race conditions.
+/**
+ * safe_fopen - Call fopen() safely
+ *
+ * when opening files for writing, make sure the file doesn't already exist to
+ * avoid race conditions.
*/
FILE *safe_fopen(const char *path, const char *mode)
{
return 0;
}
-/* Read a line from ``fp'' into the dynamically allocated ``s'',
- * increasing ``s'' if necessary. The ending "\n" or "\r\n" is removed.
- * If a line ends with "\", this char and the linefeed is removed,
- * and the next line is read too.
+/**
+ * mutt_read_line - Read a line from a file
+ *
+ * Read a line from ``fp'' into the dynamically allocated ``s'', increasing
+ * ``s'' if necessary. The ending "\n" or "\r\n" is removed. If a line ends
+ * with "\", this char and the linefeed is removed, and the next line is read
+ * too.
*/
char *mutt_read_line(char *s, size_t *size, FILE *fp, int *line, int flags)
{
return p;
}
-/* prepare a file name to survive the shell's quoting rules.
+/**
+ * mutt_quote_filename - Quote a filename to survive the shell's quoting rules
+ *
* From the Unix programming FAQ by way of Liviu.
*/
size_t mutt_quote_filename(char *d, size_t l, const char *f)
#define EMAIL_WSP " \t\r\n"
-/* skip over WSP as defined by RFC5322. This is used primarily for parsing
- * header fields. */
+/**
+ * skip_email_wsp - Skip over whitespace as defined by RFC5322
+ *
+ * This is used primarily for parsing header fields.
+ */
static inline char *skip_email_wsp(const char *s)
{
if (s)
#define MUTT_NEWS (1 << 5) /* -g and -G */
#endif
+/**
+ * main - Start NeoMutt
+ * @param argc Number of command line arguments
+ * @param argv List of command line arguments
+ * @param env Copy of the environment
+ * @return 0 on success, 1 on error
+ */
int main(int argc, char **argv, char **env)
{
char folder[_POSIX_PATH_MAX] = "";
LOFF_T length;
};
-/* parameters:
- * ctx - context to lock
- * excl - exclusive lock?
- * retry - should retry if unable to lock?
+/**
+ * mbox_lock_mailbox - Lock a mailbox
+ * @param ctx Context to lock
+ * @param excl Exclusive lock?
+ * @param retry Should retry if unable to lock?
*/
static int mbox_lock_mailbox(struct Context *ctx, int excl, int retry)
{
return 0;
}
-/* Note that this function is also called when new mail is appended to the
+/**
+ * mbox_parse_mailbox - Read a mailbox from disk
+ *
+ * Note that this function is also called when new mail is appended to the
* currently open folder, and NOT just when the mailbox is initially read.
*
- * NOTE: it is assumed that the mailbox being read has been locked before
- * this routine gets called. Strange things could happen if it's not!
+ * NOTE: it is assumed that the mailbox being read has been locked before this
+ * routine gets called. Strange things could happen if it's not!
*/
static int mbox_parse_mailbox(struct Context *ctx)
{
#undef PREV
-/* open a mbox or mmdf style mailbox */
+/**
+ * mbox_open_mailbox - open a mbox or mmdf style mailbox
+ */
static int mbox_open_mailbox(struct Context *ctx)
{
int rc;
return 0;
}
-/* return 1 if address lists are strictly identical */
+/**
+ * strict_addrcmp - Strictly compare two address list
+ * @return 1 if address lists are strictly identical
+ */
static int strict_addrcmp(const struct Address *a, const struct Address *b)
{
while (a && b)
return 1;
}
-/* return 1 if headers are strictly identical */
+/**
+ * mbox_strict_cmp_headers - Strictly compare message headers
+ * @return 1 if headers are strictly identical
+ */
int mbox_strict_cmp_headers(const struct Header *h1, const struct Header *h2)
{
if (h1 && h2)
/**
* mbox_has_new - Does the mailbox have new mail
* @param ctx Context
- * @return true if the mailbox has at least 1 new messages (not old)
- * false, otherwise
+ * @return
+ * * true if the mailbox has at least 1 new messages (not old)
+ * * false otherwise
*/
static bool mbox_has_new(struct Context *ctx)
{
return false;
}
-/* if mailbox has at least 1 new message, sets mtime > atime of mailbox
- * so buffy check reports new mail */
+/**
+ * mbox_reset_atime - Reset the access time on the mailbox file
+ *
+ * if mailbox has at least 1 new message, sets mtime > atime of mailbox so
+ * buffy check reports new mail
+ */
void mbox_reset_atime(struct Context *ctx, struct stat *st)
{
struct utimbuf utimebuf;
utime(ctx->path, &utimebuf);
}
-/* return values:
- * 0 success
- * -1 failure
+/**
+ * mbox_sync_mailbox - Sync a mailbox to disk
+ * @return
+ * * 0 Success
+ * * -1 Failure
*/
static int mbox_sync_mailbox(struct Context *ctx, int *index_hint)
{
return (size_t) -2;
}
-/*
- * For systems that don't have them, we provide here our own
- * implementations of wcrtomb(), mbrtowc(), iswprint() and wcwidth().
- * Instead of using the locale, as these functions normally would,
- * we use Mutt's Charset variable. We support 3 types of charset:
- * (1) For 8-bit charsets, wchar_t uses the same encoding as char.
- * (2) For UTF-8, wchar_t uses UCS.
- * (3) For stateless Japanese encodings, we use UCS and convert
- * via UTF-8 using iconv.
+/**
+ * wcrtomb_iconv - Convert wide characters to multibyte characters
+ *
+ * For systems that don't have them, we provide here our own implementations of
+ * wcrtomb(), mbrtowc(), iswprint() and wcwidth(). Instead of using the
+ * locale, as these functions normally would, we use Mutt's Charset variable.
+ * We support 3 types of charset:
+ * 1. For 8-bit charsets, wchar_t uses the same encoding as char.
+ * 2. For UTF-8, wchar_t uses UCS.
+ * 3. For stateless Japanese encodings, we use UCS and convert via UTF-8 using
+ * iconv.
* Unfortunately, we can't handle non-stateless encodings.
*/
static size_t wcrtomb_iconv(char *s, wchar_t wc, iconv_t cd)
return (0 <= wc && wc < 256) ? isupper(wc) : 0;
}
-/*
- * l10n for Japanese:
+/**
+ * wcwidth_ja - Calculate character widths for Japanese
+ *
+ * L10N for Japanese:
* Symbols, Greek and Cyrillic in JIS X 0208, Japanese Kanji
* Character Set, have a column width of 2.
*/
64-byte boundary. (RFC 1321, 3.1: Step 1) */
static const unsigned char fillbuf[64] = { 0x80, 0 /* , 0, 0, ... */ };
-/* Initialize structure containing state of computation.
- (RFC 1321, 3.3: Step 3) */
+/**
+ * md5_init_ctx - Initialise the MD5 computation
+ *
+ * (RFC 1321, 3.3: Step 3)
+ */
void md5_init_ctx(struct Md5Ctx *ctx)
{
ctx->A = 0x67452301;
ctx->buflen = 0;
}
-/* Copy the 4 byte value from v into the memory location pointed to by *cp,
- If your architecture allows unaligned access this is equivalent to
- * (md5_uint32 *) cp = v */
+/**
+ * set_uint32 - Write a 32 bit number
+ *
+ * Copy the 4 byte value from v into the memory location pointed to by *cp, If
+ * your architecture allows unaligned access this is equivalent to
+ * `*(md5_uint32*) cp = v`
+ */
static inline void set_uint32(char *cp, md5_uint32 v)
{
memcpy(cp, &v, sizeof(v));
}
-/* Put result from CTX in first 16 bytes following RESBUF. The result
- must be in little endian byte order. */
+/**
+ * md5_read_ctx - Read from the context into a buffer
+ *
+ * Put result from CTX in first 16 bytes following RESBUF.
+ * The result must be in little endian byte order.
+ */
void *md5_read_ctx(const struct Md5Ctx *ctx, void *resbuf)
{
char *r = resbuf;
return resbuf;
}
-/* Process the remaining bytes in the internal buffer and the usual
- prolog according to the standard and write the result to RESBUF. */
+/**
+ * md5_finish_ctx - Process the remaining bytes in the buffer
+ *
+ * Process the remaining bytes in the internal buffer and the usual prologue
+ * according to the standard and write the result to RESBUF.
+ */
void *md5_finish_ctx(struct Md5Ctx *ctx, void *resbuf)
{
/* Take yet unprocessed bytes into account. */
return md5_read_ctx(ctx, resbuf);
}
-/* Compute MD5 message digest for bytes read from STREAM. The
- resulting message digest number will be written into the 16 bytes
- beginning at RESBLOCK. */
+/**
+ * md5_stream - Compute MD5 message digest for bytes read from a file
+ *
+ * The resulting message digest number will be written into the 16 bytes
+ * beginning at RESBLOCK.
+ */
int md5_stream(FILE *stream, void *resblock)
{
struct Md5Ctx ctx;
return 0;
}
-/* Compute MD5 message digest for LEN bytes beginning at Buffer. The
- result is always in little endian byte order, so that a byte-wise
- output yields to the wanted ASCII representation of the message
- digest. */
+/**
+ * md5_buffer - Calculate the MD5 hash of a buffer
+ *
+ * Compute MD5 message digest for LEN bytes beginning at Buffer. The result is
+ * always in little endian byte order, so that a byte-wise output yields to the
+ * wanted ASCII representation of the message digest.
+ */
void *md5_buffer(const char *buffer, size_t len, void *resblock)
{
struct Md5Ctx ctx;
#define FH(b, c, d) (b ^ c ^ d)
#define FI(b, c, d) (c ^ (b | ~d))
-/* Process LEN bytes of Buffer, accumulating context into CTX.
- It is assumed that LEN % 64 == 0. */
+/**
+ * md5_process_block - Process a block with MD5
+ *
+ * Process LEN bytes of Buffer, accumulating context into CTX.
+ * It is assumed that LEN % 64 == 0.
+ */
void md5_process_block(const void *buffer, size_t len, struct Md5Ctx *ctx)
{
md5_uint32 correct_words[16];
mutt_error(_("You cannot scroll up farther."));
}
-/*
- * pageup: jumplen == -pagelen
- * pagedown: jumplen == pagelen
- * halfup: jumplen == -pagelen/2
- * halfdown: jumplen == pagelen/2
+/**
+ * menu_length_jump - Calculate the destination of a jump
+ *
+ * * pageup: jumplen == -pagelen
+ * * pagedown: jumplen == pagelen
+ * * halfup: jumplen == -pagelen/2
+ * * halfdown: jumplen == pagelen/2
*/
#define DIRECTION ((neg * 2) + 1)
static void menu_length_jump(struct Menu *menu, int jumplen)
fputc('\n', fp);
}
-/* XXX - we don't currently remove deleted messages from sequences we don't know. Should we? */
+/**
+ * mh_update_sequences - Update sequence numbers
+ *
+ * XXX we don't currently remove deleted messages from sequences we don't know.
+ * Should we?
+ */
static void mh_update_sequences(struct Context *ctx)
{
FILE *ofp = NULL, *nfp = NULL;
}
}
-/* maildir support */
+/**
+ * maildir_free_entry - Free a maildir object
+ */
static void maildir_free_entry(struct Maildir **md)
{
if (!md || !*md)
ctx->mtime = st.st_mtime;
}
-/*
+/**
+ * maildir_parse_stream - Parse a Maildir message
+ *
* Actually parse a maildir message. This may also be used to fill
* out a fake header structure generated by lazy maildir parsing.
*/
return h;
}
-/*
- * Actually parse a maildir message. This may also be used to fill
- * out a fake header structure generated by lazy maildir parsing.
+/**
+ * maildir_parse_message - Actually parse a maildir message
+ *
+ * This may also be used to fill out a fake header structure generated by lazy
+ * maildir parsing.
*/
struct Header *maildir_parse_message(int magic, const char *fname, int is_old,
struct Header *h)
return strcmp(a->h->path, b->h->path);
}
-/*
- * Merge two maildir lists according to the inode numbers.
+/**
+ * maildir_merge_lists - Merge two maildir lists according to the inode numbers
*/
static struct Maildir *maildir_merge_lists(struct Maildir *left, struct Maildir *right,
int (*cmp)(struct Maildir *, struct Maildir *))
return ret;
}
-/*
- * Sort maildir list according to inode.
+/**
+ * maildir_sort - Sort maildir list according to inode
*/
static struct Maildir *maildir_sort(struct Maildir *list, size_t len,
int (*cmp)(struct Maildir *, struct Maildir *))
return maildir_merge_lists(left, right, cmp);
}
-/* Sorts mailbox into its natural order.
+/**
+ * mh_sort_natural - Sorts mailbox into its natural order
+ *
* Currently only defined for MH where files are numbered.
*/
static void mh_sort_natural(struct Context *ctx, struct Maildir **md)
return p;
}
-/*
- * This function does the second parsing pass
+/**
+ * maildir_delayed_parsing - This function does the second parsing pass
*/
static void maildir_delayed_parsing(struct Context *ctx, struct Maildir **md,
struct Progress *progress)
return 0;
}
-/* Read a MH/maildir style mailbox.
- *
- * args:
- * ctx [IN/OUT] context for this mailbox
- * subdir [IN] NULL for MH mailboxes, otherwise the subdir of the
- * maildir mailbox to read from
+/**
+ * mh_read_dir - Read a MH/maildir style mailbox
+ * @param ctx Current mailbox
+ * @param subdir NULL for MH mailboxes,
+ * otherwise the subdir of the maildir mailbox to read from
*/
static int mh_read_dir(struct Context *ctx, const char *subdir)
{
return 0;
}
-/* read a maildir style mailbox */
+/**
+ * maildir_read_dir - read a maildir style mailbox
+ */
static int maildir_read_dir(struct Context *ctx)
{
/* maildir looks sort of like MH, except that there are two subdirectories
return safe_fclose(&msg->fp);
}
-/*
+/**
+ * maildir_open_new_message - Open a new message in a maildir folder
+ *
* Open a new (temporary) message in a maildir folder.
*
- * Note that this uses _almost_ the maildir file name format, but
- * with a {cur,new} prefix.
+ * Note that this uses _almost_ the maildir file name format,
+ * but with a {cur,new} prefix.
*/
static int maildir_open_new_message(struct Message *msg, struct Context *dest,
struct Header *hdr)
}
-/*
- * Commit a message to a maildir folder.
+/**
+ * _maildir_commit_message - Commit a message to a maildir folder
*
* msg->path contains the file name of a file in tmp/. We take the
* flags from this file's name.
}
-/* Sync a message in an MH folder.
+/**
+ * mh_rewrite_message - Sync a message in an MH folder
*
- * This code is also used for attachment deletion in maildir
- * folders.
+ * This code is also used for attachment deletion in maildir folders.
*/
static int mh_rewrite_message(struct Context *ctx, int msgno)
{
mutt_clear_threads(ctx);
}
-/* This function handles arrival of new mail and reopening of
- * maildir folders. The basic idea here is we check to see if either
- * the new or cur subdirectories have changed, and if so, we scan them
- * for the list of files. We check for newly added messages, and
- * then merge the flags messages we already knew about. We don't treat
- * either subdirectory differently, as mail could be copied directly into
- * the cur directory from another agent.
+/**
+ * maildir_check_mailbox - Check for new mail
+ *
+ * This function handles arrival of new mail and reopening of maildir folders.
+ * The basic idea here is we check to see if either the new or cur
+ * subdirectories have changed, and if so, we scan them for the list of files.
+ * We check for newly added messages, and then merge the flags messages we
+ * already knew about. We don't treat either subdirectory differently, as mail
+ * could be copied directly into the cur directory from another agent.
*/
static int maildir_check_mailbox(struct Context *ctx, int *index_hint)
{
return 0;
}
-/*
- * This function handles arrival of new mail and reopening of
- * mh/maildir folders. Things are getting rather complex because we
- * don't have a well-defined "mailbox order", so the tricks from
- * mbox.c and mx.c won't work here.
+/**
+ * mh_check_mailbox - Check for new mail
*
- * Don't change this code unless you _really_ understand what
- * happens.
+ * This function handles arrival of new mail and reopening of mh/maildir
+ * folders. Things are getting rather complex because we don't have a
+ * well-defined "mailbox order", so the tricks from mbox.c and mx.c won't work
+ * here.
+ *
+ * Don't change this code unless you _really_ understand what happens.
*/
static int mh_check_mailbox(struct Context *ctx, int *index_hint)
{
}
-/*
+/**
+ * _maildir_open_find_message - Find a message in a maildir folder
+ *
* These functions try to find a message in a maildir folder when it
* has moved under our feet. Note that this code is rather expensive, but
* then again, it's called rarely.
return 0;
}
-/* convert just for displaying purposes */
+/**
+ * mutt_addr_for_display - convert just for displaying purposes
+ */
const char *mutt_addr_for_display(struct Address *a)
{
char *user = NULL, *domain = NULL;
FREE(&local_mailbox);
return buff;
}
-/* Convert an Envelope structure */
+
+/**
+ * mutt_env_to_local - Convert an Envelope structure
+ */
void mutt_env_to_local(struct Envelope *e)
{
mutt_addrlist_to_local(e->return_path);
lua_pop(l, 1);
return -1;
}
+
static int _handle_error(lua_State *l)
{
mutt_debug(1, "lua runtime error: %s\n", lua_tostring(l, -1));
}
/**
- * query_window_reset - restores vfolder's search window to its original position
+ * query_window_reset - Restore vfolder's search window to its original position
*
* After moving a vfolder search window backward and forward, calling this function
* will reset the search position to its original value, setting to 0 the user settable
static sasl_secret_t *secret_ptr = NULL;
-/* utility function, stolen from sasl2 sample code */
+/**
+ * iptostring - Convert IP Address to string
+ *
+ * utility function, copied from sasl2 sample code
+ */
static int iptostring(const struct sockaddr *addr, socklen_t addrlen, char *out, unsigned outlen)
{
char hbuf[NI_MAXHOST], pbuf[NI_MAXSERV];
return SASL_OK;
}
-/* mutt_sasl_cb_log: callback to log SASL messages */
+/**
+ * mutt_sasl_cb_log - callback to log SASL messages
+ */
static int mutt_sasl_cb_log(void *context, int priority, const char *message)
{
mutt_debug(priority, "SASL: %s\n", message);
return SASL_OK;
}
-/* mutt_sasl_start: called before doing a SASL exchange - initialises library
- * (if necessary). */
+/**
+ * mutt_sasl_start - Initialise SASL library
+ *
+ * Call before doing an SASL exchange - initialises library (if necessary).
+ */
static int mutt_sasl_start(void)
{
static bool sasl_init = false;
return SASL_OK;
}
-/* mutt_sasl_cb_authname: callback to retrieve authname or user from Account */
+/**
+ * mutt_sasl_cb_authname - callback to retrieve authname or user from Account
+ */
static int mutt_sasl_cb_authname(void *context, int id, const char **result, unsigned *len)
{
struct Account *account = (struct Account *) context;
return mutt_sasl_callbacks;
}
-/* mutt_sasl_client_new: wrapper for sasl_client_new which also sets various
- * security properties. If this turns out to be fine for POP too we can
- * probably stop exporting mutt_sasl_get_callbacks(). */
+/**
+ * mutt_sasl_client_new - wrapper for sasl_client_new
+ *
+ * which also sets various security properties. If this turns out to be fine
+ * for POP too we can probably stop exporting mutt_sasl_get_callbacks().
+ */
int mutt_sasl_client_new(struct Connection *conn, sasl_conn_t **saslconn)
{
sasl_security_properties_t secprops;
return SASL_OK;
}
-/* mutt_sasl_conn_open: empty wrapper for underlying open function. We
- * don't know in advance that a connection will use SASL, so we
- * replace conn's methods with sasl methods when authentication
- * is successful, using mutt_sasl_setup_conn */
+/**
+ * mutt_sasl_conn_open - empty wrapper for underlying open function
+ *
+ * We don't know in advance that a connection will use SASL, so we replace
+ * conn's methods with sasl methods when authentication is successful, using
+ * mutt_sasl_setup_conn
+ */
static int mutt_sasl_conn_open(struct Connection *conn)
{
struct SaslData *sasldata = NULL;
return rc;
}
-/* mutt_sasl_conn_close: calls underlying close function and disposes of
- * the sasl_conn_t object, then restores connection to pre-sasl state */
+/**
+ * mutt_sasl_conn_close - close SASL connection
+ *
+ * Calls underlying close function and disposes of the sasl_conn_t object, then
+ * restores connection to pre-sasl state
+ */
static int mutt_sasl_conn_close(struct Connection *conn)
{
struct SaslData *sasldata = NULL;
return rc;
}
+
/* SASL can stack a protection layer on top of an existing connection.
* To handle this, we store a saslconn_t in conn->sockdata, and write
* wrappers which en/decode the read/write stream, then replace sockdata
* abstraction problem is that there is more in Connection than there
* needs to be. Ideally it would have only (void*)data and methods. */
-/* mutt_sasl_setup_conn: replace connection methods, sockdata with
- * SASL wrappers, for protection layers. Also get ssf, as a fastpath
- * for the read/write methods. */
+/**
+ * mutt_sasl_setup_conn - Set up an SASL connection
+ *
+ * replace connection methods, sockdata with SASL wrappers, for protection
+ * layers. Also get ssf, as a fastpath for the read/write methods.
+ */
void mutt_sasl_setup_conn(struct Connection *conn, sasl_conn_t *saslconn)
{
struct SaslData *sasldata = safe_malloc(sizeof(struct SaslData));
return 0;
}
-/* Wrappers */
+/**
+ * mutt_socket_open - Simple wrapper
+ */
int mutt_socket_open(struct Connection *conn)
{
int rc;
return sent;
}
-/* poll whether reads would block.
- * Returns: >0 if there is data to read,
- * 0 if a read would block,
- * -1 if this connection doesn't support polling */
+/**
+ * mutt_socket_poll - poll whether reads would block
+ * @return
+ * * >0 There is data to read,
+ * * 0 Read would block,
+ * * -1 Connection doesn't support polling
+ */
int mutt_socket_poll(struct Connection *conn)
{
if (conn->bufpos < conn->available)
return -1;
}
-/* simple read buffering to speed things up. */
+/**
+ * mutt_socket_readchar - simple read buffering to speed things up
+ */
int mutt_socket_readchar(struct Connection *conn, char *c)
{
if (conn->bufpos >= conn->available)
return Connections;
}
-/* mutt_socket_free: remove connection from connection list and free it */
+/**
+ * mutt_socket_free - remove connection from connection list and free it
+ */
void mutt_socket_free(struct Connection *conn)
{
struct Connection *iter = NULL;
}
}
-/* socket_new_conn: allocate and initialise a new connection. */
+/**
+ * socket_new_conn - allocate and initialise a new connection
+ */
static struct Connection *socket_new_conn(void)
{
struct Connection *conn = NULL;
return conn;
}
-/* mutt_conn_find: find a connection off the list of connections whose
- * account matches account. If start is not null, only search for
- * connections after the given connection (allows higher level socket code
- * to make more fine-grained searches than account info - eg in IMAP we may
- * wish to find a connection which is not in IMAP_SELECTED state) */
+/**
+ * mutt_conn_find - Find a connection from a list
+ *
+ * find a connection off the list of connections whose account matches account.
+ * If start is not null, only search for connections after the given connection
+ * (allows higher level socket code to make more fine-grained searches than
+ * account info - eg in IMAP we may wish to find a connection which is not in
+ * IMAP_SELECTED state)
+ */
struct Connection *mutt_conn_find(const struct Connection *start, const struct Account *account)
{
struct Connection *conn = NULL;
return select(conn->fd + 1, &rfds, NULL, NULL, &tv);
}
-/* socket_connect: set up to connect to a socket fd. */
+/**
+ * socket_connect - set up to connect to a socket fd
+ */
static int socket_connect(int fd, struct sockaddr *sa)
{
int sa_size;
unsigned char isopen;
};
-/* ssl certificate verification can behave strangely if there are expired
- * certs loaded into the trusted store. This function filters out expired
- * certs.
+/**
+ * ssl_load_certificates - Load certificates and filter out the expired ones
+ *
+ * ssl certificate verification can behave strangely if there are expired certs
+ * loaded into the trusted store. This function filters out expired certs.
+ *
* Previously the code used this form:
* SSL_CTX_load_verify_locations (ssldata->ctx, SslCertFile, NULL);
*/
return true;
}
-/* port to mutt from msmtp's tls.c */
+/**
+ * hostname_match - Does the hostname match the certificate
+ */
static bool hostname_match(const char *hostname, const char *certname)
{
const char *cmp1 = NULL, *cmp2 = NULL;
return true;
}
-/*
- * OpenSSL library needs to be fed with sufficient entropy. On systems
- * with /dev/urandom, this is done transparently by the library itself,
- * on other systems we need to fill the entropy pool ourselves.
+/**
+ * ssl_init - Initialist the SSL library
+ *
+ * OpenSSL library needs to be fed with sufficient entropy. On systems with
+ * /dev/urandom, this is done transparently by the library itself, on other
+ * systems we need to fill the entropy pool ourselves.
*
- * Even though only OpenSSL 0.9.5 and later will complain about the
- * lack of entropy, we try to our best and fill the pool with older
- * versions also. (That's the reason for the ugly #ifdefs and macros,
- * otherwise I could have simply #ifdef'd the whole ssl_init funcion)
+ * Even though only OpenSSL 0.9.5 and later will complain about the lack of
+ * entropy, we try to our best and fill the pool with older versions also.
+ * (That's the reason for the ugly ifdefs and macros, otherwise I could have
+ * simply ifdef'd the whole ssl_init funcion)
*/
static int ssl_init(void)
{
return pass;
}
-/* port to mutt from msmtp's tls.c */
+/**
+ * check_host - Check the host on the certificate
+ */
static int check_host(X509 *x509cert, const char *hostname, char *err, size_t errlen)
{
int i, rc = 0;
return (done == 2);
}
-/* certificate verification callback, called for each certificate in the chain
- * sent by the peer, starting from the root; returning 1 means that the given
- * certificate is trusted, returning 0 immediately aborts the SSL connection */
+/**
+ * ssl_verify_callback - certificate verification callback
+ *
+ * called for each certificate in the chain sent by the peer, starting from the
+ * root; returning 1 means that the given certificate is trusted, returning 0
+ * immediately aborts the SSL connection
+ */
static int ssl_verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
{
char buf[STRING];
return 1;
}
-/* ssl_negotiate: After SSL state has been initialized, attempt to negotiate
- * SSL over the wire, including certificate checks. */
+/**
+ * ssl_negotiate - Attempt to negotiate SSL over the wire
+ *
+ * After SSL state has been initialized, attempt to negotiate SSL over the
+ * wire, including certificate checks.
+ */
static int ssl_negotiate(struct Connection *conn, struct SslSockData *ssldata)
{
int err;
return 0;
}
-/* mutt_ssl_starttls: Negotiate TLS over an already opened connection.
- * TODO: Merge this code better with ssl_socket_open. */
+/**
+ * mutt_ssl_starttls - Negotiate TLS over an already opened connection
+ *
+ * TODO: Merge this code better with ssl_socket_open.
+ */
int mutt_ssl_starttls(struct Connection *conn)
{
struct SslSockData *ssldata = NULL;
return rc;
}
-/* sanity-checking wrapper for gnutls_certificate_verify_peers */
+/**
+ * tls_verify_peers - wrapper for gnutls_certificate_verify_peers
+ *
+ * wrapper with sanity-checking
+ */
static gnutls_certificate_status_t tls_verify_peers(gnutls_session_t tlsstate)
{
int verify_ret;
return 0;
}
-/* this bit is based on read_ca_file() in gnutls */
+/**
+ * tls_compare_certificates - Compare certificates
+ */
static int tls_compare_certificates(const gnutls_datum_t *peercert)
{
gnutls_datum_t cert;
}
#endif
-/* tls_negotiate: After TLS state has been initialized, attempt to negotiate
- * TLS over the wire, including certificate checks. */
+/**
+ * tls_negotiate - Negotiate TLS connection
+ *
+ * After TLS state has been initialized, attempt to negotiate TLS over the
+ * wire, including certificate checks.
+ */
static int tls_negotiate(struct Connection *conn)
{
tlssockdata *data = NULL;
return rc;
}
-/* -- public functions -- */
int mutt_tunnel_socket_setup(struct Connection *conn)
{
conn->conn_open = tunnel_socket_open;
}
-/* Modified by blong to accept a "suggestion" for file name. If
- * that file exists, then construct one with unique name but
- * keep any extension. This might fail, I guess.
- * Renamed to mutt_adv_mktemp so I only have to change where it's
- * called, and not all possible cases.
+/**
+ * mutt_adv_mktemp - Advanced mktemp(3)
+ *
+ * Modified by blong to accept a "suggestion" for file name. If that file
+ * exists, then construct one with unique name but keep any extension. This
+ * might fail, I guess.
*/
void mutt_adv_mktemp(char *s, size_t l)
{
}
}
-/* create a send-mode duplicate from a receive-mode body */
+/**
+ * mutt_copy_body - create a send-mode duplicate from a receive-mode body
+ */
int mutt_copy_body(FILE *fp, struct Body **tgt, struct Body *src)
{
if (!tgt || !src)
FREE(h);
}
-/* returns true if the header contained in "s" is in list "t" */
+/**
+ * mutt_matches_list - Is the string in the list
+ * @return true if the header contained in "s" is in list "t"
+ */
bool mutt_matches_list(const char *s, struct List *t)
{
for (; t; t = t->next)
return false;
}
-/* checks Ignore and UnIgnore using mutt_matches_list */
+/**
+ * mutt_matches_ignore - Does the string match the ignore list
+ *
+ * checks Ignore and UnIgnore using mutt_matches_list
+ */
int mutt_matches_ignore(const char *s)
{
return mutt_matches_list(s, Ignore) && !mutt_matches_list(s, UnIgnore);
return s;
}
-/* Extract the real name from /etc/passwd's GECOS field.
- * When set, honor the regular expression in GecosMask,
- * otherwise assume that the GECOS field is a
+/**
+ * mutt_gecos_name - Lookup a user's real name in /etc/passwd
+ *
+ * Extract the real name from /etc/passwd's GECOS field. When set, honor the
+ * regular expression in GecosMask, otherwise assume that the GECOS field is a
* comma-separated list.
- * Replace "&" by a capitalized version of the user's login
- * name.
+ * Replace "&" by a capitalized version of the user's login name.
*/
char *mutt_gecos_name(char *dest, size_t destlen, struct passwd *pw)
{
}
}
-/* returns 1 if Mutt can't display this type of data, 0 otherwise */
+/**
+ * mutt_needs_mailcap - Does this type need a mailcap entry do display
+ * @return
+ * * true Mutt requires a mailcap entry to display
+ * * false otherwise
+ */
bool mutt_needs_mailcap(struct Body *m)
{
switch (m->type)
FREE(p);
}
-/* move all the headers from extra not present in base into base */
+/**
+ * mutt_merge_envelopes - Merge the headers of two emails
+ *
+ * Move all the headers from extra not present in base into base
+ */
void mutt_merge_envelopes(struct Envelope *base, struct Envelope **extra)
{
/* copies each existing element if necessary, and sets the element
}
}
-/* collapse the pathname using ~ or = when possible */
+/**
+ * mutt_pretty_mailbox - Shorten a mailbox path using '~' or '='
+ *
+ * Collapse the pathname using ~ or = when possible
+ */
void mutt_pretty_mailbox(char *s, size_t buflen)
{
char *p = s, *q = s;
}
}
-/* return 0 on success, -1 on abort, 1 on error */
+/**
+ * mutt_check_overwrite - Ask the user if overwriting is necessary
+ * @return
+ * * 0 on success
+ * * -1 on abort
+ * * 1 on error
+ */
int mutt_check_overwrite(const char *attname, const char *path, char *fname,
size_t flen, int *append, char **directory)
{
{
switch (mutt_multi_choice
/* L10N:
- Means "The path you specified as the destination file is a directory."
- See the msgid "Save to file: " (alias.c, recvattach.c) */
+ Means "The path you specified as the destination file is a directory."
+ See the msgid "Save to file: " (alias.c, recvattach.c) */
(_("File is a directory, save under it? [(y)es, (n)o, (a)ll]"), _("yna")))
{
case 3: /* all */
*p = '_';
}
-/* Note this function uses a fixed size buffer of LONG_STRING and so
- * should only be used for visual modifications, such as disp_subj. */
+/**
+ * mutt_apply_replace - Apply replacements to a buffer
+ *
+ * Note this function uses a fixed size buffer of LONG_STRING and so
+ * should only be used for visual modifications, such as disp_subj.
+ */
char *mutt_apply_replace(char *dbuf, size_t dlen, char *sbuf, struct ReplaceList *rlist)
{
struct ReplaceList *l = NULL;
}
-void mutt_FormatString(char *dest, /* output buffer */
- size_t destlen, /* output buffer len */
- size_t col, /* starting column (nonzero when called recursively) */
- int cols, /* maximum columns */
- const char *src, /* template string */
- format_t *callback, /* callback for processing */
- unsigned long data, /* callback data */
- enum FormatFlag flags) /* callback flags */
+/**
+ * mutt_FormatString - Expand expandos (%x) in a string
+ * @param dest output buffer
+ * @param destlen output buffer len
+ * @param col starting column (nonzero when called recursively)
+ * @param cols maximum columns
+ * @param src template string
+ * @param callback callback for processing
+ * @param data callback data
+ * @param flags callback flags
+ */
+void mutt_FormatString(char *dest, size_t destlen, size_t col, int cols, const char *src,
+ format_t *callback, unsigned long data, enum FormatFlag flags)
{
char prefix[SHORT_STRING], buf[LONG_STRING], *cp = NULL, *wptr = dest, ch;
char ifstring[SHORT_STRING], elsestring[SHORT_STRING];
*wptr = 0;
}
-/* This function allows the user to specify a command to read stdout from in
- place of a normal file. If the last character in the string is a pipe (|),
- then we assume it is a command to run instead of a normal file. */
+/**
+ * mutt_open_read - Run a command to read from
+ *
+ * This function allows the user to specify a command to read stdout from in
+ * place of a normal file. If the last character in the string is a pipe (|),
+ * then we assume it is a command to run instead of a normal file.
+ */
FILE *mutt_open_read(const char *path, pid_t *thepid)
{
FILE *f = NULL;
return f;
}
-/* returns 0 if OK to proceed, -1 to abort, 1 to retry */
+/**
+ * mutt_save_confirm - Ask the user to save
+ * @return
+ * * 0 if OK to proceed
+ * * -1 to abort
+ * * 1 to retry
+ */
int mutt_save_confirm(const char *s, struct stat *st)
{
char tmp[_POSIX_PATH_MAX];
sleep(s);
}
-/* Decrease a file's modification time by 1 second */
+/**
+ * mutt_decrease_mtime - Decrease a file's modification time by 1 second
+ */
time_t mutt_decrease_mtime(const char *f, struct stat *st)
{
struct utimbuf utim;
return mtime;
}
-/* sets mtime of 'to' to mtime of 'from' */
+/**
+ * mutt_set_mtime - sets mtime of 'to' to mtime of 'from'
+ */
void mutt_set_mtime(const char *from, const char *to)
{
struct utimbuf utim;
}
}
-/* set atime to current time, just as read() would do on !noatime.
- * Silently ignored if unsupported. */
+/**
+ * mutt_touch_atime - set atime to current time
+ *
+ * This is just as read() would do on !noatime.
+ * Silently ignored if unsupported.
+ */
void mutt_touch_atime(int f)
{
#ifdef HAVE_FUTIMENS
#define mutt_is_spool(s) (mutt_strcmp(Spoolfile, s) == 0)
-/* Args:
- * excl if excl != 0, request an exclusive lock
- * timeout should retry locking?
+/**
+ * mx_lock_file - (try to) lock a file
+ * @param path Path to file
+ * @param fd File descriptor to file
+ * @param excl If set, try to lock exclusively
+ * @param timeout Retry after this time
+ * @return 0 on success, -1 on failure
*/
int mx_lock_file(const char *path, int fd, int excl, int timeout)
{
return magic;
}
-/*
- * set DefaultMagic to the given value
+/**
+ * mx_set_magic - set DefaultMagic to the given value
*/
int mx_set_magic(const char *s)
{
return 0;
}
-/* mx_access: Wrapper for access, checks permissions on a given mailbox.
- * We may be interested in using ACL-style flags at some point, currently
- * we use the normal access() flags. */
+/**
+ * mx_access - Wrapper for access, checks permissions on a given mailbox
+ *
+ * We may be interested in using ACL-style flags at some point, currently we
+ * use the normal access() flags.
+ */
int mx_access(const char *path, int flags)
{
#ifdef USE_IMAP
return ctx->mx_ops->open_append(ctx, flags);
}
-/*
- * open a mailbox and parse it
+/**
+ * mx_open_mailbox - Open a mailbox and parse it
+ * @param path Path to the mailbox
+ * @param flags See below
+ * @param pctx Reuse this Context (if supplied)
*
- * Args:
- * flags MUTT_NOSORT do not sort mailbox
- * MUTT_APPEND open mailbox for appending
- * MUTT_READONLY open mailbox in read-only mode
- * MUTT_QUIET only print error messages
- * MUTT_PEEK revert atime where applicable
- * ctx if non-null, context struct to use
+ * flags:
+ * * #MUTT_NOSORT do not sort mailbox
+ * * #MUTT_APPEND open mailbox for appending
+ * * #MUTT_READONLY open mailbox in read-only mode
+ * * #MUTT_QUIET only print error messages
+ * * #MUTT_PEEK revert atime where applicable
*/
struct Context *mx_open_mailbox(const char *path, int flags, struct Context *pctx)
{
return ctx;
}
-/* free up memory associated with the mailbox context */
+/**
+ * mx_fastclose_mailbox - free up memory associated with the mailbox context
+ */
void mx_fastclose_mailbox(struct Context *ctx)
{
struct utimbuf ut;
memset(ctx, 0, sizeof(struct Context));
}
-/* save changes to disk */
+/**
+ * sync_mailbox - save changes to disk
+ */
static int sync_mailbox(struct Context *ctx, int *index_hint)
{
if (!ctx->mx_ops || !ctx->mx_ops->sync)
return ctx->mx_ops->sync(ctx, index_hint);
}
-/* move deleted mails to the trash folder */
+/**
+ * trash_append - move deleted mails to the trash folder
+ */
static int trash_append(struct Context *ctx)
{
struct Context ctx_trash;
return 0;
}
-/* save changes and close mailbox */
+/**
+ * mx_close_mailbox - save changes and close mailbox
+ */
int mx_close_mailbox(struct Context *ctx, int *index_hint)
{
int i, move_messages = 0, purge = 1, read_msgs = 0;
return 0;
}
-/* update a Context structure's internal tables. */
+/**
+ * mx_update_tables - Update a Context structure's internal tables
+ */
void mx_update_tables(struct Context *ctx, int committing)
{
int i, j;
return rc;
}
-/* args:
- * dest destination mailbox
- * hdr message being copied (required for maildir support, because
+/**
+ * mx_open_new_message - Open a new message
+ * @param dest Destination mailbox
+ * @param hdr Message being copied (required for maildir support, because
* the filename depends on the message flags)
+ * @param flags Flags, e.g. #MUTT_SET_DRAFT
+ * @return new Message
*/
struct Message *mx_open_new_message(struct Context *dest, struct Header *hdr, int flags)
{
return msg;
}
-/* check for new mail */
+/**
+ * mx_check_mailbox - check for new mail
+ */
int mx_check_mailbox(struct Context *ctx, int *index_hint)
{
if (!ctx || !ctx->mx_ops)
return ctx->mx_ops->check(ctx, index_hint);
}
-/* return a stream pointer for a message */
+/**
+ * mx_open_message - return a stream pointer for a message
+ */
struct Message *mx_open_message(struct Context *ctx, int msgno)
{
struct Message *msg = NULL;
return msg;
}
-/* commit a message to a folder */
+/**
+ * mx_commit_message - commit a message to a folder
+ */
int mx_commit_message(struct Message *msg, struct Context *ctx)
{
if (!ctx->mx_ops || !ctx->mx_ops->commit_msg)
return ctx->mx_ops->commit_msg(ctx, msg);
}
-/* close a pointer to a message */
+/**
+ * mx_close_message - close a pointer to a message
+ */
int mx_close_message(struct Context *ctx, struct Message **msg)
{
if (!ctx || !msg)
}
}
-/* this routine is called to update the counts in the context structure for
- * the last message header parsed.
+/**
+ * mx_update_context - Update the Context's message counts
+ *
+ * this routine is called to update the counts in the context structure for the
+ * last message header parsed.
*/
void mx_update_context(struct Context *ctx, int new_messages)
{
#include "rfc822.h"
#include "state.h"
-/* print the current time to avoid spoofing of the signature output */
+/**
+ * crypt_current_time - Print the current time
+ *
+ * print the current time to avoid spoofing of the signature output
+ */
void crypt_current_time(struct State *s, char *app_name)
{
time_t t;
return PGPENCRYPT;
}
-/*
+/**
+ * mutt_is_malformed_multipart_pgp_encrypted - Check for malformed layout
+ *
* This checks for the malformed layout caused by MS Exchange in
* some cases:
+ * ```
* <multipart/mixed>
* <text/plain>
* <application/pgp-encrypted> [BASE64-encoded]
* <application/octet-stream> [BASE64-encoded]
+ * ```
* See ticket #3742
*/
int mutt_is_malformed_multipart_pgp_encrypted(struct Body *b)
return 0;
}
-/*
+/**
+ * crypt_opportunistic_encrypt - Can all recipients be determined
+ *
* Check if all recipients keys can be automatically determined.
* Enable encryption if they can, otherwise disable encryption.
*/
}
}
-/*
- * This routine verifies a "multipart/signed" body.
+/**
+ * mutt_signed_handler - Verify a "multipart/signed" body.
*/
int mutt_signed_handler(struct Body *a, struct State *s)
{
return rc;
}
-/* Obtain pointers to fingerprint or short or long key ID, if any.
+/**
+ * crypt_get_fingerprint_or_id - Get the fingerprint or long key ID
+ *
+ * Obtain pointers to fingerprint or short or long key ID, if any.
* See ncrypt.h for details.
*/
const char *crypt_get_fingerprint_or_id(char *p, const char **pphint,
return pfcopy;
}
-/*
- * Used by pgp_find_keys and find_keys to check if a crypt-hook
- * value is a key id.
+/**
+ * crypt_is_numerical_keyid - Is this a numerical keyid
+ *
+ * Check if a crypt-hook value is a key id.
*/
bool crypt_is_numerical_keyid(const char *s)
{
* General helper functions.
*/
-/* accommodate for a redraw if needed */
+/**
+ * redraw_if_needed - accommodate for a redraw if needed
+ */
static void redraw_if_needed(gpgme_ctx_t ctx)
{
#if (GPGME_VERSION_NUMBER < 0x010800)
#endif
}
-/* return true when s points to a digit or letter. */
+/**
+ * digit_or_letter - Is the character a number or letter
+ * @param s Only the first character of this string is tested
+ * @return true when s points to a digit or letter
+ */
static int digit_or_letter(const unsigned char *s)
{
return ((*s >= '0' && *s < '9') || (*s >= 'A' && *s <= 'Z') || (*s >= 'a' && *s <= 'z'));
}
-/* Print the utf-8 encoded string BUF of length LEN bytes to stream
- FP. Convert the character set. */
+/**
+ * print_utf8 - Write a UTF-8 string to a file
+ *
+ * Print the utf-8 encoded string BUF of length LEN bytes to stream FP. Convert
+ * the character set.
+ */
static void print_utf8(FILE *fp, const char *buf, size_t len)
{
char *tstr = NULL;
* Key management.
*/
-/* Return the keyID for the key K. Note that this string is valid as
- long as K is valid */
+/**
+ * crypt_keyid - Find the ID for the key
+ *
+ * Return the keyID for the key K.
+ * Note that this string is valid as long as K is valid
+ */
static const char *crypt_keyid(struct CryptKeyInfo *k)
{
const char *s = "????????";
return s;
}
-/* Return the long keyID for the key K. */
+/**
+ * crypt_long_keyid - Find the Long ID for the key
+ *
+ * Return the long keyID for the key K.
+ */
static const char *crypt_long_keyid(struct CryptKeyInfo *k)
{
const char *s = "????????????????";
return s;
}
-/* Return the short keyID for the key K. */
+/**
+ * crypt_short_keyid - Get the short keyID for the key K
+ */
static const char *crypt_short_keyid(struct CryptKeyInfo *k)
{
const char *s = "????????";
return s;
}
-/* Return the hexstring fingerprint from the key K. */
+/**
+ * crypt_fpr - Get the hexstring fingerprint from the key K
+ */
static const char *crypt_fpr(struct CryptKeyInfo *k)
{
const char *s = "";
return s;
}
-/* Parse FLAGS and return a statically allocated(!) string with them. */
+/**
+ * crypt_key_abilities - Parse key flags into a string
+ *
+ * Note: The string is statically allocated.
+ */
static char *crypt_key_abilities(int flags)
{
static char buff[3];
return buff;
}
-/* Parse FLAGS and return a character describing the most important flag. */
+/**
+ * crypt_flags - Parse the key flags into a single character
+ *
+ * The returned character describes the most important flag.
+ */
static char crypt_flags(int flags)
{
if (flags & KEYFLAG_REVOKED)
return ' ';
}
-/* Return a copy of KEY. */
+/**
+ * crypt_copy_key - Return a copy of KEY
+ */
static struct CryptKeyInfo *crypt_copy_key(struct CryptKeyInfo *key)
{
struct CryptKeyInfo *k = NULL;
return k;
}
-/* Release all the keys at the address of KEYLIST and set the address
- to NULL. */
+/**
+ * crypt_free_key - Release all the keys in a list
+ * @param keylist List of keys
+ */
static void crypt_free_key(struct CryptKeyInfo **keylist)
{
struct CryptKeyInfo *k = NULL;
}
}
-/* Return true when key K is valid. */
+/**
+ * crypt_key_is_valid - Is the key valid
+ * @return true when key K is valid
+ */
static bool crypt_key_is_valid(struct CryptKeyInfo *k)
{
if (k->flags & KEYFLAG_CANTUSE)
return true;
}
-/* Return true when validity of KEY is sufficient. */
+/**
+ * crypt_id_is_strong - Is the key strong
+ * @return true when validity of KEY is sufficient
+ */
static int crypt_id_is_strong(struct CryptKeyInfo *key)
{
unsigned int is_strong = 0;
return is_strong;
}
-/* Return true when the KEY is valid, i.e. not marked as unusable. */
+/**
+ * crypt_id_is_valid - Is key ID valid
+ * ~return true when the KEY is valid, i.e. not marked as unusable
+ */
static int crypt_id_is_valid(struct CryptKeyInfo *key)
{
return !(key->flags & KEYFLAG_CANTUSE);
}
-/* Return a bit vector describing how well the addresses ADDR and
- U_ADDR match and whether KEY is valid. */
+/**
+ * crypt_id_matches_addr - Does key ID match the address
+ *
+ * Return a bit vector describing how well the addresses ADDR and U_ADDR match
+ * and whether KEY is valid.
+ */
static int crypt_id_matches_addr(struct Address *addr, struct Address *u_addr,
struct CryptKeyInfo *key)
{
* GPGME convenient functions.
*/
-/* Create a new gpgme context and return it. With FOR_SMIME set to
- true, the protocol of the context is set to CMS. */
+/**
+ * create_gpgme_context - Create a new GPGME context
+ * @param for_smime If set, protocol of the context is set to CMS
+ */
static gpgme_ctx_t create_gpgme_context(int for_smime)
{
gpgme_error_t err;
return ctx;
}
-/* Create a new gpgme data object. This is a wrapper to die on
- error. */
+/**
+ * create_gpgme_data - Create a new GPGME data object
+ *
+ * This is a wrapper to die on error.
+ */
static gpgme_data_t create_gpgme_data(void)
{
gpgme_error_t err;
return data;
}
-/* Create a new GPGME Data object from the mail body A. With CONVERT
- passed as true, the lines are converted to CR,LF if required.
- Return NULL on error or the gpgme_data_t object on success. */
+/**
+ * body_to_data_object - Create GPGME object from the mail body
+ *
+ * Create a new GPGME Data object from the mail body A. With CONVERT passed as
+ * true, the lines are converted to CR,LF if required. Return NULL on error or
+ * the gpgme_data_t object on success.
+ */
static gpgme_data_t body_to_data_object(struct Body *a, int convert)
{
char tempfile[_POSIX_PATH_MAX];
return data;
}
-/* Create a GPGME data object from the stream FP but limit the object
- to LENGTH bytes starting at OFFSET bytes from the beginning of the
- file. */
+/**
+ * file_to_data_object - Create GPGME data object from file
+ *
+ * Create a GPGME data object from the stream FP but limit the object
+ * to LENGTH bytes starting at OFFSET bytes from the beginning of the file.
+ */
static gpgme_data_t file_to_data_object(FILE *fp, long offset, long length)
{
int err = 0;
return data;
}
-/* Write a GPGME data object to the stream FP. */
+/**
+ * data_object_to_stream - Write a GPGME data object to a file
+ */
static int data_object_to_stream(gpgme_data_t data, FILE *fp)
{
int err;
return 0;
}
-/* Copy a data object to a temporary file.
+/**
+ * data_object_to_tempfile - Copy a data object to a temporary file
+ *
* The tempfile name may be optionally passed in.
* If ret_fp is passed in, the file will be rewound, left open, and returned
* via that parameter.
FREE(p_rset);
}
-/* Create a GpgmeRecipientSet from the keys in the string KEYLIST.
- The keys must be space delimited. */
+/**
+ * create_recipient_set - Create a GpgmeRecipientSet from a string of keys
+ *
+ * The keys must be space delimited.
+ */
static gpgme_key_t *create_recipient_set(const char *keylist, gpgme_protocol_t protocol)
{
int err;
return rset;
}
-/* Make sure that the correct signer is set. Returns 0 on success. */
+/**
+ * set_signer - Make sure that the correct signer is set
+ * @return 0 on success
+ */
static int set_signer(gpgme_ctx_t ctx, int for_smime)
{
char *signid = for_smime ? SmimeDefaultKey : PgpSignAs;
return err;
}
-/* Encrypt the gpgme data object PLAINTEXT to the recipients in RSET
- and return an allocated filename to a temporary file containing the
- enciphered text. With USE_SMIME set to true, the smime backend is
- used. With COMBINED_SIGNED a PGP message is signed and
- encrypted. Returns NULL in case of error */
+/**
+ * encrypt_gpgme_object - Encrypt the GPGPME data object
+ *
+ * Encrypt the gpgme data object PLAINTEXT to the recipients in RSET and return
+ * an allocated filename to a temporary file containing the enciphered text.
+ * With USE_SMIME set to true, the smime backend is used. With COMBINED_SIGNED
+ * a PGP message is signed and encrypted. Returns NULL in case of error
+ */
static char *encrypt_gpgme_object(gpgme_data_t plaintext, gpgme_key_t *rset,
int use_smime, int combined_signed)
{
return outfile;
}
-/* Find the "micalg" parameter from the last Gpgme operation on
- context CTX. It is expected that this operation was a sign
- operation. Return the algorithm name as a C string in buffer BUF
- which must have been allocated by the caller with size BUFLEN.
- Returns 0 on success or -1 in case of an error. The return string
- is truncated to BUFLEN - 1. */
+/**
+ * get_micalg - Find the "micalg" parameter from the last GPGME operation
+ *
+ * Find the "micalg" parameter from the last Gpgme operation on context CTX.
+ * It is expected that this operation was a sign operation. Return the
+ * algorithm name as a C string in buffer BUF which must have been allocated by
+ * the caller with size BUFLEN. Returns 0 on success or -1 in case of an
+ * error. The return string is truncated to BUFLEN - 1.
+ */
static int get_micalg(gpgme_ctx_t ctx, int use_smime, char *buf, size_t buflen)
{
gpgme_sign_result_t result = NULL;
* Implementation of `sign_message'.
*/
-/* Sign the Message in body A either using OpenPGP or S/MIME when
- USE_SMIME is passed as true. Returns the new body or NULL on
- error. */
+/**
+ * sign_message - Sign a message
+ * @param a Message to sign
+ * @param use_smime If set, use SMIME instead of PGP
+ * @return the new body or NULL on error
+ */
static struct Body *sign_message(struct Body *a, int use_smime)
{
struct Body *t = NULL;
* Implementation of `encrypt_message'.
*/
-/* Encrypt the mail body A to all keys given as space separated keyids
- or fingerprints in KEYLIST and return the encrypted body. */
+/**
+ * pgp_gpgme_encrypt_message - Encrypt a message
+ *
+ * Encrypt the mail body A to all keys given as space separated keyids
+ * or fingerprints in KEYLIST and return the encrypted body.
+ */
struct Body *pgp_gpgme_encrypt_message(struct Body *a, char *keylist, int sign)
{
char *outfile = NULL;
* Implementation of `smime_build_smime_entity'.
*/
-/* Encrypt the mail body A to all keys given as space separated
- fingerprints in KEYLIST and return the S/MIME encrypted body. */
+/**
+ * smime_gpgme_build_smime_entity - Encrypt the email body to all recipients
+ *
+ * Encrypt the mail body A to all keys given as space separated fingerprints in
+ * KEYLIST and return the S/MIME encrypted body.
+ */
struct Body *smime_gpgme_build_smime_entity(struct Body *a, char *keylist)
{
char *outfile = NULL;
* Implementation of `verify_one'.
*/
-/* Display the common attributes of the signature summary SUM.
- Return 1 if there is is a severe warning.
+/**
+ * show_sig_summary - Show a signature summary
+ * @return 1 if there is is a severe warning
+ *
+ * Display the common attributes of the signature summary SUM.
*/
static int show_sig_summary(unsigned long sum, gpgme_ctx_t ctx, gpgme_key_t key,
int idx, struct State *s, gpgme_signature_t sig)
FREE(&buf);
}
-/* Show the validity of a key used for one signature. */
+/**
+ * show_one_sig_validity - Show the validity of a key used for one signature
+ */
static void show_one_sig_validity(gpgme_ctx_t ctx, int idx, struct State *s)
{
gpgme_verify_result_t result = NULL;
}
}
-/* Show information about one signature. This function is called with
- the context CTX of a successful verification operation and the
- enumerator IDX which should start at 0 and increment for each
- call/signature.
-
- Return values are: 0 for normal procession, 1 for a bad signature,
- 2 for a signature with a warning or -1 for no more signature. */
+/**
+ * show_one_sig_status - Show information about one signature
+ * @return
+ * * 0 Normal procession
+ * * 1 A bad signature
+ * * 2 A signature with a warning
+ * * -1 No more signature
+ *
+ * This function is called with the context CTX of a successful verification
+ * operation and the enumerator IDX which should start at 0 and increment for
+ * each call/signature.
+ */
static int show_one_sig_status(gpgme_ctx_t ctx, int idx, struct State *s)
{
const char *fpr = NULL;
return anybad ? 1 : anywarn ? 2 : 0;
}
-/* Do the actual verification step. With IS_SMIME set to true we
- assume S/MIME (surprise!) */
+/**
+ * verify_one - Do the actual verification step
+ *
+ * With IS_SMIME set to true we assume S/MIME (surprise!)
+ */
static int verify_one(struct Body *sigbdy, struct State *s, const char *tempfile, int is_smime)
{
int badsig = -1;
* Implementation of `decrypt_part'.
*/
-/* Decrypt a PGP or SMIME message (depending on the boolean flag
- IS_SMIME) with body A described further by state S. Write
- plaintext out to file FPOUT and return a new body. For PGP returns
- a flag in R_IS_SIGNED to indicate whether this is a combined
- encrypted and signed message, for S/MIME it returns true when it is
- not a encrypted but a signed message. */
+/**
+ * decrypt_part - Decrypt a PGP or SMIME message
+ *
+ * (depending on the boolean flag IS_SMIME) with body A described further by
+ * state S. Write plaintext out to file FPOUT and return a new body. For PGP
+ * returns a flag in R_IS_SIGNED to indicate whether this is a combined
+ * encrypted and signed message, for S/MIME it returns true when it is not a
+ * encrypted but a signed message.
+ */
static struct Body *decrypt_part(struct Body *a, struct State *s, FILE *fpout,
int is_smime, int *r_is_signed)
{
return tattach;
}
-/* Decrypt a PGP/MIME message in FPIN and B and return a new body and
- the stream in CUR and FPOUT. Returns 0 on success. */
+/**
+ * pgp_gpgme_decrypt_mime - Decrypt a PGP/MIME message
+ * @return 0 on success
+ *
+ * The message in FPIN and B and return a new body and the stream in CUR and
+ * FPOUT.
+ */
int pgp_gpgme_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur)
{
char tempfile[_POSIX_PATH_MAX];
return rv;
}
-/* Decrypt a S/MIME message in FPIN and B and return a new body and
- the stream in CUR and FPOUT. Returns 0 on success. */
+/**
+ * smime_gpgme_decrypt_mime - Decrypt a S/MIME message
+ * @returns 0 on success
+ *
+ * The message in FPIN and B and return a new body and
+ * the stream in CUR and FPOUT.
+ */
int smime_gpgme_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur)
{
char tempfile[_POSIX_PATH_MAX];
* Implementation of `application_handler'.
*/
-/*
- Copy a clearsigned message, and strip the signature and PGP's
- dash-escaping.
-
- XXX - charset handling: We assume that it is safe to do
- character set decoding first, dash decoding second here, while
- we do it the other way around in the main handler.
-
- (Note that we aren't worse than Outlook & Cie in this, and also
- note that we can successfully handle anything produced by any
- existing versions of mutt.) */
+/**
+ * copy_clearsigned - Copy a clearsigned message
+ *
+ * strip the signature and PGP's dash-escaping.
+ *
+ * XXX - charset handling: We assume that it is safe to do character set
+ * decoding first, dash decoding second here, while we do it the other way
+ * around in the main handler.
+ *
+ * (Note that we aren't worse than Outlook & Cie in this, and also note that we
+ * can successfully handle anything produced by any existing versions of mutt.)
+ */
static void copy_clearsigned(gpgme_data_t data, struct State *s, char *charset)
{
char buf[HUGE_STRING];
safe_fclose(&fp);
}
-/* Support for classic_application/pgp */
+/**
+ * pgp_gpgme_application_handler - Support for classic_application/pgp
+ */
int pgp_gpgme_application_handler(struct Body *m, struct State *s)
{
int needpass = -1;
* Implementation of `encrypted_handler'.
*/
-/* MIME handler for pgp/mime encrypted messages.
+/**
+ * pgp_gpgme_encrypted_handler - MIME handler for pgp/mime encrypted messages
+ *
* This handler is passed the application/octet-stream directly.
* The caller must propagate a->goodsig to its parent.
*/
return rc;
}
-/* Support for application/smime */
+/**
+ * smime_gpgme_application_handler - Support for application/smime
+ */
int smime_gpgme_application_handler(struct Body *a, struct State *s)
{
char tempfile[_POSIX_PATH_MAX];
return rc;
}
-/*
- * Format an entry on the CRYPT key selection menu.
+/**
+ * crypt_entry_fmt - Format an entry on the CRYPT key selection menu
+ *
+ * * \%u user id
+ * * \%n number
+ * * \%t trust/validity of the key-uid association
+ * * \%p protocol
+ * * \%[...] date of key using strftime(3)
+ *
+ * * \%k key id
+ * * \%a algorithm
+ * * \%l length
+ * * \%f flags
+ * * \%c capabilities
*
- * %n number
- * %k key id %K key id of the principal key
- * %u user id
- * %a algorithm %A algorithm of the princ. key
- * %l length %L length of the princ. key
- * %f flags %F flags of the princ. key
- * %c capabilities %C capabilities of the princ. key
- * %t trust/validity of the key-uid association
- * %p protocol
- * %[...] date of key using strftime(3)
+ * * \%K key id of the principal key
+ * * \%A algorithm of the principal key
+ * * \%L length of the principal key
+ * * \%F flags of the principal key
+ * * \%C capabilities of the principal key
*/
static const char *crypt_entry_fmt(char *dest, size_t destlen, size_t col, int cols,
char op, const char *src, const char *prefix,
return src;
}
-/* Used by the display function to format a line. */
+/**
+ * crypt_entry - Used by the display function to format a line
+ */
static void crypt_entry(char *s, size_t l, struct Menu *menu, int num)
{
struct CryptKeyInfo **key_table = (struct CryptKeyInfo **) menu->data;
crypt_entry_fmt, (unsigned long) &entry, MUTT_FORMAT_ARROWCURSOR);
}
-/* Compare two addresses and the keyid to be used for sorting. */
+/**
+ * _crypt_compare_address - Compare Key addresses and IDs for sorting
+ */
static int _crypt_compare_address(const void *a, const void *b)
{
struct CryptKeyInfo **s = (struct CryptKeyInfo **) a;
_crypt_compare_address(a, b));
}
-/* Compare two key IDs and the addresses to be used for sorting. */
+/**
+ * _crypt_compare_keyid - Compare Key IDs and addresses for sorting
+ */
static int _crypt_compare_keyid(const void *a, const void *b)
{
struct CryptKeyInfo **s = (struct CryptKeyInfo **) a;
_crypt_compare_keyid(a, b));
}
-/* Compare 2 creation dates and the addresses. For sorting. */
+/**
+ * _crypt_compare_date - Compare Key creation dates and addresses for sorting
+ */
static int _crypt_compare_date(const void *a, const void *b)
{
struct CryptKeyInfo **s = (struct CryptKeyInfo **) a;
_crypt_compare_date(a, b));
}
-/* Compare two trust values, the key length, the creation dates. the
- addresses and the key IDs. For sorting. */
+/**
+ * _crypt_compare_trust - Compare the trust of keys for sorting
+ *
+ * Compare two trust values, the key length, the creation dates. the addresses
+ * and the key IDs.
+ */
static int _crypt_compare_trust(const void *a, const void *b)
{
struct CryptKeyInfo **s = (struct CryptKeyInfo **) a;
_crypt_compare_trust(a, b));
}
-/* Print the X.500 Distinguished Name part KEY from the array of parts
- DN to FP. */
+/**
+ * print_dn_part - Print the X.500 Distinguished Name
+ *
+ * Print the X.500 Distinguished Name part KEY from the array of parts DN to FP.
+ */
static int print_dn_part(FILE *fp, struct DnArray *dn, const char *key)
{
int any = 0;
return any;
}
-/* Print all parts of a DN in a standard sequence. */
+/**
+ * print_dn_parts - Print all parts of a DN in a standard sequence
+ */
static void print_dn_parts(FILE *fp, struct DnArray *dn)
{
static const char *const stdpart[] = {
fputs(")", fp);
}
-/* Parse an RDN; this is a helper to parse_dn(). */
+/**
+ * parse_dn_part - Parse an RDN; this is a helper to parse_dn()
+ */
static const char *parse_dn_part(struct DnArray *array, const char *string)
{
const char *s = NULL, *s1 = NULL;
return s;
}
-/* Parse a DN and return an array-ized one. This is not a validating
- parser and it does not support any old-stylish syntax; gpgme is
- expected to return only rfc2253 compatible strings. */
+/**
+ * parse_dn - Parse a DN and return an array-ized one
+ *
+ * This is not a validating parser and it does not support any old-stylish
+ * syntax; gpgme is expected to return only rfc2253 compatible strings.
+ */
static struct DnArray *parse_dn(const char *string)
{
struct DnArray *array = NULL;
return NULL;
}
-/* Print a nice representation of the USERID and make sure it is
- displayed in a proper way, which does mean to reorder some parts
- for S/MIME's DNs. USERID is a string as returned by the gpgme key
- functions. It is utf-8 encoded. */
+/**
+ * parse_and_print_user_id - Print a nice representation of the userid
+ *
+ * Make sure it is displayed in a proper way, which does mean to reorder some
+ * parts for S/MIME's DNs. USERID is a string as returned by the gpgme key
+ * functions. It is utf-8 encoded.
+ */
static void parse_and_print_user_id(FILE *fp, const char *userid)
{
const char *s = NULL;
int KeyInfoPadding[KIP_END] = { 0 };
-/* Print verbose information about a key or certificate to FP. */
+/**
+ * print_key_info - Verbose information about a key or certificate to a file
+ */
static void print_key_info(gpgme_key_t key, FILE *fp)
{
int idx;
}
}
-/* Show detailed information about the selected key */
+/**
+ * verify_key - Show detailed information about the selected key
+ */
static void verify_key(struct CryptKeyInfo *key)
{
FILE *fp = NULL;
* Implementation of `findkeys'.
*/
-/* Convert List into a pattern string suitable to be passed to GPGME.
- We need to convert spaces in an item into a '+' and '%' into
- "%25". */
+/**
+ * list_to_pattern - Convert List to GPGME-compatible pattern
+ *
+ * We need to convert spaces in an item into a '+' and '%' into "%25".
+ */
static char *list_to_pattern(struct List *list)
{
struct List *l = NULL;
return pattern;
}
-/* Return a list of keys which are candidates for the selection.
- Select by looking at the HINTS list. */
+/**
+ * get_candidates - Get a list of keys which are candidates for the selection
+ *
+ * Select by looking at the HINTS list.
+ */
static struct CryptKeyInfo *get_candidates(struct List *hints, unsigned int app, int secret)
{
struct CryptKeyInfo *db = NULL, *k = NULL, **kend = NULL;
return db;
}
-/* Add the string STR to the list HINTS. This list is later used to
- match addresses. */
+/**
+ * crypt_add_string_to_hints - Add the string STR to the list HINTS
+ *
+ * This list is later used to match addresses.
+ */
static struct List *crypt_add_string_to_hints(struct List *hints, const char *str)
{
char *scratch = NULL;
return hints;
}
-/* Display a menu to select a key from the array KEYS. FORCED_VALID
- will be set to true on return if the user did override the
- key's validity. */
+/**
+ * crypt_select_key - Get the user to select a key
+ *
+ * Display a menu to select a key from the array KEYS. FORCED_VALID will be set
+ * to true on return if the user did override the key's validity.
+ */
static struct CryptKeyInfo *crypt_select_key(struct CryptKeyInfo *keys,
struct Address *p, const char *s,
unsigned int app, int *forced_valid)
return NULL;
}
-/* Display TAG as a prompt to ask for a key. If WHATFOR is not null
- use it as default and store it under that label as the next
- default. ABILITIES describe the required key abilities (sign,
- encrypt) and APP the type of the requested key; ether S/MIME or
- PGP. Return a copy of the key or NULL if not found. */
+/**
+ * crypt_ask_for_key - Ask the user for a key
+ *
+ * Display TAG as a prompt to ask for a key. If WHATFOR is not null use it as
+ * default and store it under that label as the next default. ABILITIES
+ * describe the required key abilities (sign, encrypt) and APP the type of the
+ * requested key; ether S/MIME or PGP. Return a copy of the key or NULL if not
+ * found.
+ */
static struct CryptKeyInfo *crypt_ask_for_key(char *tag, char *whatfor, short abilities,
unsigned int app, int *forced_valid)
{
/* not reached */
}
-/* This routine attempts to find the keyids of the recipients of a
- message. It returns NULL if any of the keys can not be found.
- If oppenc_mode is true, only keys that can be determined without
- prompting will be used. */
+/**
+ * find_keys - Find keys of the recipients of the message
+ * @return NULL if any of the keys can not be found
+ *
+ * If oppenc_mode is true, only keys that can be determined without prompting
+ * will be used.
+ */
static char *find_keys(struct Address *adrlist, unsigned int app, int oppenc_mode)
{
struct List *crypt_hook_list = NULL, *crypt_hook = NULL;
* Implementation of `init'.
*/
-/* This function contains common code needed to be executed for both the pgp
- * and smime support of gpgme. */
+/**
+ * init_common - Initialise code common to PGP and SMIME parts of GPGME
+ */
static void init_common(void)
{
/* this initialization should only run one time, but it may be called by
static struct CryptModule *modules;
-/* Register a new crypto module. */
+/**
+ * crypto_module_register - Register a new crypto module
+ */
void crypto_module_register(crypt_module_specs_t specs)
{
struct CryptModule *module_new = safe_malloc(sizeof(*module_new));
modules = module_new;
}
-/* Return the crypto module specs for IDENTIFIER. This function is
- usually used via the CRYPT_MOD_CALL[_CHECK] macros. */
+/**
+ * crypto_module_lookup - Lookup a crypto module by name
+ *
+ * Return the crypto module specs for IDENTIFIER.
+ * This function is usually used via the CRYPT_MOD_CALL[_CHECK] macros.
+ */
crypt_module_specs_t crypto_module_lookup(int identifier)
{
struct CryptModule *module = modules;
{
return pgp_decrypt_mime(a, b, c, d);
}
+
static int crypt_mod_pgp_application_handler(struct Body *m, struct State *s)
{
return pgp_application_pgp_handler(m, s);
{
return smime_decrypt_mime(a, b, c, d);
}
+
static int crypt_mod_smime_application_handler(struct Body *m, struct State *s)
{
return smime_application_smime_handler(m, s);
#endif
}
-/* Show a message that a backend will be invoked. */
+/**
+ * crypt_invoke_message - Display an informative message
+ *
+ * Show a message that a backend will be invoked.
+ */
void crypt_invoke_message(int type)
{
if ((WithCrypto & APPLICATION_PGP) && (type & APPLICATION_PGP))
}
/*
+ * PGP
+ */
- PGP
-
-*/
-
-/* Reset a PGP passphrase */
+/**
+ * crypt_pgp_void_passphrase - Reset a PGP passphrase
+ */
void crypt_pgp_void_passphrase(void)
{
if (CRYPT_MOD_CALL_CHECK(PGP, void_passphrase))
return 0;
}
-/* Decrypt a PGP/MIME message. */
+/**
+ * crypt_pgp_decrypt_mime - Decrypt a PGP/MIME message
+ */
int crypt_pgp_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d)
{
if (CRYPT_MOD_CALL_CHECK(PGP, decrypt_mime))
return -1;
}
-/* MIME handler for the application/pgp content-type. */
+/**
+ * crypt_pgp_application_pgp_handler - MIME handler for the pgp content-type
+ */
int crypt_pgp_application_pgp_handler(struct Body *m, struct State *s)
{
if (CRYPT_MOD_CALL_CHECK(PGP, application_handler))
return -1;
}
-/* MIME handler for an PGP/MIME encrypted message. */
+/**
+ * crypt_pgp_encrypted_handler - MIME handler for an PGP/MIME encrypted message
+ */
int crypt_pgp_encrypted_handler(struct Body *a, struct State *s)
{
if (CRYPT_MOD_CALL_CHECK(PGP, encrypted_handler))
return -1;
}
-/* fixme: needs documentation. */
void crypt_pgp_invoke_getkeys(struct Address *addr)
{
if (CRYPT_MOD_CALL_CHECK(PGP, pgp_invoke_getkeys))
(CRYPT_MOD_CALL(PGP, pgp_invoke_getkeys))(addr);
}
-/* Check for a traditional PGP message in body B. */
+/**
+ * crypt_pgp_check_traditional - Check for a traditional PGP message in body B
+ */
int crypt_pgp_check_traditional(FILE *fp, struct Body *b, int tagged_only)
{
if (CRYPT_MOD_CALL_CHECK(PGP, pgp_check_traditional))
return 0;
}
-/* fixme: needs documentation. */
struct Body *crypt_pgp_traditional_encryptsign(struct Body *a, int flags, char *keylist)
{
if (CRYPT_MOD_CALL_CHECK(PGP, pgp_traditional_encryptsign))
return NULL;
}
-/* Generate a PGP public key attachment. */
+/**
+ * crypt_pgp_make_key_attachment - Generate a PGP public key attachment
+ */
struct Body *crypt_pgp_make_key_attachment(char *tempf)
{
if (CRYPT_MOD_CALL_CHECK(PGP, pgp_make_key_attachment))
return NULL;
}
-/* This routine attempts to find the keyids of the recipients of a
- message. It returns NULL if any of the keys can not be found.
- If oppenc_mode is true, only keys that can be determined without
- prompting will be used. */
+/**
+ * crypt_pgp_findkeys - Find the keyids of the recipients of the message
+ *
+ * It returns NULL if any of the keys can not be found. If oppenc_mode is
+ * true, only keys that can be determined without prompting will be used.
+ */
char *crypt_pgp_findkeys(struct Address *adrlist, int oppenc_mode)
{
if (CRYPT_MOD_CALL_CHECK(PGP, findkeys))
return NULL;
}
-/* Create a new body with a PGP signed message from A. */
+/**
+ * crypt_pgp_sign_message - Create a new body with a PGP signed message from A
+ */
struct Body *crypt_pgp_sign_message(struct Body *a)
{
if (CRYPT_MOD_CALL_CHECK(PGP, sign_message))
return NULL;
}
-/* Warning: A is no longer freed in this routine, you need to free it
- later. This is necessary for $fcc_attach. */
+/**
+ * crypt_pgp_encrypt_message - Encrypt a message
+ *
+ * Warning: A is no longer freed in this routine, you need to free it later.
+ * This is necessary for $fcc_attach.
+ */
struct Body *crypt_pgp_encrypt_message(struct Body *a, char *keylist, int sign)
{
if (CRYPT_MOD_CALL_CHECK(PGP, pgp_encrypt_message))
return NULL;
}
-/* Invoke the PGP command to import a key. */
+/**
+ * crypt_pgp_invoke_import - Invoke the PGP command to import a key
+ */
void crypt_pgp_invoke_import(const char *fname)
{
if (CRYPT_MOD_CALL_CHECK(PGP, pgp_invoke_import))
(CRYPT_MOD_CALL(PGP, pgp_invoke_import))(fname);
}
-/* fixme: needs documentation */
int crypt_pgp_verify_one(struct Body *sigbdy, struct State *s, const char *tempf)
{
if (CRYPT_MOD_CALL_CHECK(PGP, verify_one))
return 0;
}
-/* fixme: needs documentation */
void crypt_pgp_extract_keys_from_attachment_list(FILE *fp, int tag, struct Body *top)
{
if (CRYPT_MOD_CALL_CHECK(PGP, pgp_extract_keys_from_attachment_list))
}
/*
+ * S/MIME
+ */
- S/MIME
-
-*/
-
-/* Reset an SMIME passphrase */
+/**
+ * crypt_smime_void_passphrase - Reset an SMIME passphrase
+ */
void crypt_smime_void_passphrase(void)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, void_passphrase))
return 0;
}
-/* Decrypt am S/MIME message. */
+/**
+ * crypt_smime_decrypt_mime - Decrypt am S/MIME message
+ */
int crypt_smime_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, decrypt_mime))
return -1;
}
-/* MIME handler for the application/smime content-type. */
+/**
+ * crypt_smime_application_smime_handler - Handler for application/smime
+ */
int crypt_smime_application_smime_handler(struct Body *m, struct State *s)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, application_handler))
return -1;
}
-/* MIME handler for an PGP/MIME encrypted message. */
+/**
+ * crypt_smime_encrypted_handler - Handler for an PGP/MIME encrypted message
+ */
void crypt_smime_encrypted_handler(struct Body *a, struct State *s)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, encrypted_handler))
(CRYPT_MOD_CALL(SMIME, encrypted_handler))(a, s);
}
-/* fixme: Needs documentation. */
void crypt_smime_getkeys(struct Envelope *env)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, smime_getkeys))
(CRYPT_MOD_CALL(SMIME, smime_getkeys))(env);
}
-/* Check that the sender matches. */
+/**
+ * crypt_smime_verify_sender - Check that the sender matches
+ */
int crypt_smime_verify_sender(struct Header *h)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, smime_verify_sender))
return 1;
}
-/* This routine attempts to find the keyids of the recipients of a
- message. It returns NULL if any of the keys can not be found.
- If oppenc_mode is true, only keys that can be determined without
- prompting will be used. */
+/**
+ * crypt_smime_findkeys - Find the keyids of the recipients of the message
+ *
+ * It returns NULL if any of the keys can not be found. If oppenc_mode is
+ * true, only keys that can be determined without prompting will be used.
+ */
char *crypt_smime_findkeys(struct Address *adrlist, int oppenc_mode)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, findkeys))
return NULL;
}
-/* fixme: Needs documentation. */
struct Body *crypt_smime_sign_message(struct Body *a)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, sign_message))
return NULL;
}
-/* fixme: needs documentation. */
struct Body *crypt_smime_build_smime_entity(struct Body *a, char *certlist)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, smime_build_smime_entity))
return NULL;
}
-/* Add a certificate and update index file (externally). */
+/**
+ * crypt_smime_invoke_import - Add a certificate and update index file
+ *
+ * This is done externally.
+ */
void crypt_smime_invoke_import(char *infile, char *mailbox)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, smime_invoke_import))
(CRYPT_MOD_CALL(SMIME, smime_invoke_import))(infile, mailbox);
}
-/* fixme: needs documentation */
int crypt_smime_verify_one(struct Body *sigbdy, struct State *s, const char *tempf)
{
if (CRYPT_MOD_CALL_CHECK(SMIME, verify_one))
return k->fingerprint;
}
-/* Grab the longest key identifier available: fingerprint or else
+/**
+ * pgp_fpr_or_lkeyid - Get the fingerprint or long keyid
+ *
+ * Grab the longest key identifier available: fingerprint or else
* the long keyid.
*
* The longest available should be used for internally identifying
* Routines for handing PGP input.
*/
-/* Copy PGP output messages and look for signs of a good signature */
+/**
+ * pgp_copy_checksig - Copy PGP output and look for signs of a good signature
+ */
static int pgp_copy_checksig(FILE *fpin, FILE *fpout)
{
int rv = -1;
return rv;
}
-/* Checks PGP output messages to look for the $pgp_decryption_okay message.
- * This protects against messages with multipart/encrypted headers
- * but which aren't actually encrypted. See ticket #3770
+/**
+ * pgp_check_decryption_okay - Check PGP output to look for successful outcome
+ *
+ * Checks PGP output messages to look for the $pgp_decryption_okay message.
+ * This protects against messages with multipart/encrypted headers but which
+ * aren't actually encrypted. See ticket #3770
*/
static int pgp_check_decryption_okay(FILE *fpin)
{
return rv;
}
-/*
- * Copy a clearsigned message, and strip the signature and PGP's
- * dash-escaping.
+/**
+ * pgp_copy_clearsigned - Copy a clearsigned message, stripping the signature
*
- * XXX - charset handling: We assume that it is safe to do
- * character set decoding first, dash decoding second here, while
- * we do it the other way around in the main handler.
+ * XXX - charset handling: We assume that it is safe to do character set
+ * decoding first, dash decoding second here, while we do it the other way
+ * around in the main handler.
*
- * (Note that we aren't worse than Outlook &c in this, and also
- * note that we can successfully handle anything produced by any
- * existing versions of mutt.)
+ * (Note that we aren't worse than Outlook &c in this, and also note that we
+ * can successfully handle anything produced by any existing versions of mutt.)
*/
static void pgp_copy_clearsigned(FILE *fpin, struct State *s, char *charset)
{
fgetconv_close(&fc);
}
-/* Support for the Application/PGP Content Type. */
+/**
+ * pgp_application_pgp_handler - Support for the Application/PGP Content Type
+ */
int pgp_application_pgp_handler(struct Body *m, struct State *s)
{
bool could_not_decrypt = false;
return badsig;
}
-/* Extract pgp public keys from messages or attachments */
+/**
+ * pgp_extract_keys_from_attachment - Extract pgp keys from messages/attachments
+ */
static void pgp_extract_keys_from_attachment(FILE *fp, struct Body *top)
{
struct State s;
return rv;
}
-/*
+/**
+ * pgp_encrypted_handler - Handler of PGP encrypted data
+ *
* This handler is passed the application/octet-stream directly.
* The caller must propagate a->goodsig to its parent.
*/
return a;
}
-/* This routine attempts to find the keyids of the recipients of a message.
- * It returns NULL if any of the keys can not be found.
- * If oppenc_mode is true, only keys that can be determined without
- * prompting will be used.
+/**
+ * pgp_find_keys - Find the keyids of the recipients of a message
+ *
+ * It returns NULL if any of the keys can not be found. If oppenc_mode is
+ * true, only keys that can be determined without prompting will be used.
*/
char *pgp_find_keys(struct Address *adrlist, int oppenc_mode)
{
return keylist;
}
-/* Warning: "a" is no longer freed in this routine, you need
- * to free it later. This is necessary for $fcc_attach. */
+/**
+ * pgp_encrypt_message - Encrypt a message
+ *
+ * Warning: "a" is no longer freed in this routine, you need to free it later.
+ * This is necessary for $fcc_attach.
+ */
struct Body *pgp_encrypt_message(struct Body *a, char *keylist, int sign)
{
char buf[LONG_STRING];
/* not reached */
}
-/* generate a public key attachment */
+/**
+ * pgp_make_key_attachment - generate a public key attachment
+ */
struct Body *pgp_make_key_attachment(char *tempf)
{
struct Body *att = NULL;
* The OpenSSL interface
*/
-/* This is almost identical to ppgp's invoking interface. */
+/**
+ * _mutt_fmt_smime_command - Format an SMIME command
+ *
+ * This is almost identical to pgp's invoking interface.
+ */
static const char *_mutt_fmt_smime_command(char *dest, size_t destlen, size_t col,
int cols, char op, const char *src,
const char *prefix, const char *ifstring,
return results;
}
-/* Returns the first matching key record, without prompting or checking of
+/**
+ * smime_get_key_by_hash - Find a key by its hash
+ *
+ * Returns the first matching key record, without prompting or checking of
* abilities or trust.
*/
static struct SmimeKey *smime_get_key_by_hash(char *hash, short public)
}
}
-/*
- This sets the '*ToUse' variables for an upcoming decryption, where
- the required key is different from SmimeDefaultKey.
-*/
+/**
+ * _smime_getkeys - Get the keys for a mailbox
+ *
+ * This sets the '*ToUse' variables for an upcoming decryption, where the
+ * required key is different from SmimeDefaultKey.
+ */
static void _smime_getkeys(char *mailbox)
{
struct SmimeKey *key = NULL;
}
}
-/* This routine attempts to find the keyids of the recipients of a message.
- * It returns NULL if any of the keys can not be found.
+/**
+ * smime_find_keys - Find the keys of the recipients of a message
+ * @return NULL if any of the keys can not be found
+ *
* If oppenc_mode is true, only keys that can be determined without
* prompting will be used.
*/
return safe_strdup(certfile);
}
-/* Add a certificate and update index file (externally). */
+/**
+ * smime_invoke_import - Add a certificate and update index file (externally)
+ */
void smime_invoke_import(char *infile, char *mailbox)
{
char tmpfname[_POSIX_PATH_MAX], *certfile = NULL, buf[STRING];
return t;
}
-/* The openssl -md doesn't want hyphens:
+/**
+ * openssl_md_to_smime_micalg - Change the algorithm names
+ *
+ * The openssl -md doesn't want hyphens:
* md5, sha1, sha224, sha256, sha384, sha512
* However, the micalg does:
* md5, sha-1, sha-224, sha-256, sha-384, sha-512
return badsig;
}
-/*
- This handles application/pkcs7-mime which can either be a signed
- or an encrypted message.
-*/
+/**
+ * smime_handle_entity - Handle type application/pkcs7-mime
+ *
+ * This can either be a signed or an encrypted message.
+ */
static struct Body *smime_handle_entity(struct Body *m, struct State *s, FILE *outFile)
{
int len = 0;
struct BodyCache;
-/* Find NntpData for given newsgroup or add it */
+/**
+ * nntp_data_find - Find NntpData for given newsgroup or add it
+ */
static struct NntpData *nntp_data_find(struct NntpServer *nserv, const char *group)
{
struct NntpData *nntp_data = hash_find(nserv->groups_hash, group);
return nntp_data;
}
-/* Remove all temporarily cache files */
+/**
+ * nntp_acache_free - Remove all temporarily cache files
+ */
void nntp_acache_free(struct NntpData *nntp_data)
{
for (int i = 0; i < NNTP_ACACHE_LEN; i++)
}
}
-/* Free NntpData, used to destroy hash elements */
+/**
+ * nntp_data_free - Free NntpData, used to destroy hash elements
+ */
void nntp_data_free(void *data)
{
struct NntpData *nntp_data = data;
FREE(&data);
}
-/* Unlock and close .newsrc file */
+/**
+ * nntp_newsrc_close - Unlock and close .newsrc file
+ */
void nntp_newsrc_close(struct NntpServer *nserv)
{
if (!nserv->newsrc_fp)
safe_fclose(&nserv->newsrc_fp);
}
-/* calculate number of unread articles using .newsrc data */
+/**
+ * nntp_group_unread_stat - Count number of unread articles using .newsrc data
+ */
void nntp_group_unread_stat(struct NntpData *nntp_data)
{
anum_t first, last;
}
}
-/* Parse .newsrc file:
- * 0 - not changed
- * 1 - parsed
- * -1 - error */
+/**
+ * nntp_newsrc_parse - Parse .newsrc file
+ * @param nserv NNTP server
+ * @return
+ * * 0 Not changed
+ * * 1 Parsed
+ * * -1 Error
+ */
int nntp_newsrc_parse(struct NntpServer *nserv)
{
char *line = NULL;
return 1;
}
-/* Generate array of .newsrc entries */
+/**
+ * nntp_newsrc_gen_entries - Generate array of .newsrc entries
+ */
void nntp_newsrc_gen_entries(struct Context *ctx)
{
struct NntpData *nntp_data = ctx->data;
}
}
-/* Update file with new contents */
+/**
+ * update_file - Update file with new contents
+ */
static int update_file(char *filename, char *buf)
{
FILE *fp = NULL;
return rc;
}
-/* Update .newsrc file */
+/**
+ * nntp_newsrc_update - Update .newsrc file
+ */
int nntp_newsrc_update(struct NntpServer *nserv)
{
char *buf = NULL;
return rc;
}
-/* Make fully qualified cache file name */
+/**
+ * cache_expand - Make fully qualified cache file name
+ */
static void cache_expand(char *dst, size_t dstlen, struct Account *acct, char *src)
{
char *c = NULL;
mutt_expand_path(dst, dstlen);
}
-/* Make fully qualified url from newsgroup name */
+/**
+ * nntp_expand_path - Make fully qualified url from newsgroup name
+ */
void nntp_expand_path(char *line, size_t len, struct Account *acct)
{
struct CissUrl url;
FREE(&url.path);
}
-/* Parse newsgroup */
+/**
+ * nntp_add_group - Parse newsgroup
+ */
int nntp_add_group(char *line, void *data)
{
struct NntpServer *nserv = data;
return 0;
}
-/* Load list of all newsgroups from cache */
+/**
+ * active_get_cache - Load list of all newsgroups from cache
+ */
static int active_get_cache(struct NntpServer *nserv)
{
char buf[HUGE_STRING];
return 0;
}
-/* Save list of all newsgroups to cache */
+/**
+ * nntp_active_save_cache - Save list of all newsgroups to cache
+ */
int nntp_active_save_cache(struct NntpServer *nserv)
{
char file[_POSIX_PATH_MAX];
}
#ifdef USE_HCACHE
-/* Used by mutt_hcache_open() to compose hcache file name */
+/**
+ * nntp_hcache_namer - Compose hcache file names
+ *
+ * Used by mutt_hcache_open() to compose hcache file name
+ */
static int nntp_hcache_namer(const char *path, char *dest, size_t destlen)
{
return snprintf(dest, destlen, "%s.hcache", path);
}
-/* Open newsgroup hcache */
+/**
+ * nntp_hcache_open - Open newsgroup hcache
+ */
header_cache_t *nntp_hcache_open(struct NntpData *nntp_data)
{
struct CissUrl url;
return mutt_hcache_open(NewsCacheDir, file, nntp_hcache_namer);
}
-/* Remove stale cached headers */
+/**
+ * nntp_hcache_update - Remove stale cached headers
+ */
void nntp_hcache_update(struct NntpData *nntp_data, header_cache_t *hc)
{
char buf[16];
}
#endif
-/* Remove bcache file */
+/**
+ * nntp_bcache_delete - Remove bcache file
+ */
static int nntp_bcache_delete(const char *id, struct BodyCache *bcache, void *data)
{
struct NntpData *nntp_data = data;
return 0;
}
-/* Remove stale cached messages */
+/**
+ * nntp_bcache_update - Remove stale cached messages
+ */
void nntp_bcache_update(struct NntpData *nntp_data)
{
mutt_bcache_list(nntp_data->bcache, nntp_bcache_delete, nntp_data);
}
-/* Remove hcache and bcache of newsgroup */
+/**
+ * nntp_delete_group_cache - Remove hcache and bcache of newsgroup
+ */
void nntp_delete_group_cache(struct NntpData *nntp_data)
{
if (!nntp_data || !nntp_data->nserv || !nntp_data->nserv->cacheable)
}
}
-/* Remove hcache and bcache of all unexistent and unsubscribed newsgroups */
+/**
+ * nntp_clear_cache - Clear the NNTP cache
+ *
+ * Remove hcache and bcache of all unexistent and unsubscribed newsgroups
+ */
void nntp_clear_cache(struct NntpServer *nserv)
{
char file[_POSIX_PATH_MAX];
}
closedir(dp);
}
- return;
}
-/* %a = account url
+/**
+ * nntp_format_str - Format a string, like printf()
+ *
+ * %a = account url
* %p = port
* %P = port if specified
* %s = news server name
* %S = url schema
- * %u = username */
+ * %u = username
+ */
const char *nntp_format_str(char *dest, size_t destlen, size_t col, int cols,
char op, const char *src, const char *fmt,
const char *ifstring, const char *elsestring,
return src;
}
-/* Automatically loads a newsrc into memory, if necessary.
- * Checks the size/mtime of a newsrc file, if it doesn't match, load
- * again. Hmm, if a system has broken mtimes, this might mean the file
- * is reloaded every time, which we'd have to fix. */
+/**
+ * nntp_select_server - Open a connection to an NNTP server
+ *
+ * Automatically loads a newsrc into memory, if necessary. Checks the
+ * size/mtime of a newsrc file, if it doesn't match, load again. Hmm, if a
+ * system has broken mtimes, this might mean the file is reloaded every time,
+ * which we'd have to fix.
+ */
struct NntpServer *nntp_select_server(char *server, int leave_lock)
{
char file[_POSIX_PATH_MAX];
return nserv;
}
-/* Full status flags are not supported by nntp, but we can fake some of them:
+/**
+ * nntp_article_status - Get status of articles from .newsrc
+ *
+ * Full status flags are not supported by nntp, but we can fake some of them:
* Read = a read message number is in the .newsrc
* New = not read and not cached
- * Old = not read but cached */
+ * Old = not read but cached
+ */
void nntp_article_status(struct Context *ctx, struct Header *hdr, char *group, anum_t anum)
{
struct NntpData *nntp_data = ctx->data;
hdr->old = true;
}
-/* Subscribe newsgroup */
+/**
+ * mutt_newsgroup_subscribe - Subscribe newsgroup
+ */
struct NntpData *mutt_newsgroup_subscribe(struct NntpServer *nserv, char *group)
{
struct NntpData *nntp_data = NULL;
return nntp_data;
}
-/* Unsubscribe newsgroup */
+/**
+ * mutt_newsgroup_unsubscribe - Unsubscribe newsgroup
+ */
struct NntpData *mutt_newsgroup_unsubscribe(struct NntpServer *nserv, char *group)
{
struct NntpData *nntp_data = NULL;
return nntp_data;
}
-/* Catchup newsgroup */
+/**
+ * mutt_newsgroup_catchup - Catchup newsgroup
+ */
struct NntpData *mutt_newsgroup_catchup(struct NntpServer *nserv, char *group)
{
struct NntpData *nntp_data = NULL;
return nntp_data;
}
-/* Uncatchup newsgroup */
+/**
+ * mutt_newsgroup_uncatchup - Uncatchup newsgroup
+ */
struct NntpData *mutt_newsgroup_uncatchup(struct NntpServer *nserv, char *group)
{
struct NntpData *nntp_data = NULL;
return nntp_data;
}
-/* Get first newsgroup with new messages */
+/**
+ * nntp_buffy - Get first newsgroup with new messages
+ */
void nntp_buffy(char *buf, size_t len)
{
for (unsigned int i = 0; i < CurrentNewsSrv->groups_num; i++)
return -1;
}
-/* Get capabilities:
- * -1 - error, connection is closed
- * 0 - mode is reader, capabilities setted up
- * 1 - need to switch to reader mode */
+/**
+ * nntp_capabilities - Get capabilities
+ * @return
+ * * -1 Error, connection is closed
+ * * 0 Mode is reader, capabilities setted up
+ * * 1 Need to switch to reader mode
+ */
static int nntp_capabilities(struct NntpServer *nserv)
{
struct Connection *conn = nserv->conn;
"Lines:\0"
"\0";
-/* Detect supported commands */
+/**
+ * nntp_attempt_features - Detect supported commands
+ */
static int nntp_attempt_features(struct NntpServer *nserv)
{
struct Connection *conn = nserv->conn;
return 0;
}
-/* Get login, password and authenticate */
+/**
+ * nntp_auth - Get login, password and authenticate
+ */
static int nntp_auth(struct NntpServer *nserv)
{
struct Connection *conn = nserv->conn;
return -1;
}
-/* Connect to server, authenticate and get capabilities */
+/**
+ * nntp_open_connection - Connect to server, authenticate and get capabilities
+ */
int nntp_open_connection(struct NntpServer *nserv)
{
struct Connection *conn = nserv->conn;
return 0;
}
-/* Send data from buffer and receive answer to same buffer */
+/**
+ * nntp_query - Send data from buffer and receive answer to same buffer
+ */
static int nntp_query(struct NntpData *nntp_data, char *line, size_t linelen)
{
struct NntpServer *nserv = nntp_data->nserv;
return 0;
}
-/* This function calls funct(*line, *data) for each received line,
+/**
+ * nntp_fetch_lines - Read lines, calling a callback function for each
+ * @return
+ * * 0 Success
+ * * 1 Bad response (answer in query buffer)
+ * * -1 Connection lost
+ * * -2 Error in funct(*line, *data)
+ *
+ * This function calls funct(*line, *data) for each received line,
* funct(NULL, *data) if rewind(*data) needs, exits when fail or done:
- * 0 - success
- * 1 - bad response (answer in query buffer)
- * -1 - connection lost
- * -2 - error in funct(*line, *data) */
+ */
static int nntp_fetch_lines(struct NntpData *nntp_data, char *query, size_t qlen,
char *msg, int (*funct)(char *, void *), void *data)
{
return rc;
}
-/* Parse newsgroup description */
+/**
+ * fetch_description - Parse newsgroup description
+ */
static int fetch_description(char *line, void *data)
{
struct NntpServer *nserv = data;
return rc;
}
-/* Update read flag and set article number if empty */
+/**
+ * nntp_parse_xref - Parse cross-reference
+ *
+ * Update read flag and set article number if empty
+ */
static void nntp_parse_xref(struct Context *ctx, struct Header *hdr)
{
struct NntpData *nntp_data = ctx->data;
FREE(&buf);
}
-/* Write line to temporarily file */
+/**
+ * fetch_tempfile - Write line to temporarily file
+ */
static int fetch_tempfile(char *line, void *data)
{
FILE *fp = data;
#endif
};
-/* Parse article number */
+/**
+ * fetch_numbers - Parse article number
+ */
static int fetch_numbers(char *line, void *data)
{
struct FetchCtx *fc = data;
return 0;
}
-/* Parse overview line */
+/**
+ * parse_overview_line - Parse overview line
+ */
static int parse_overview_line(char *line, void *data)
{
struct FetchCtx *fc = data;
return 0;
}
-/* Fetch headers */
+/**
+ * nntp_fetch_headers - Fetch headers
+ */
static int nntp_fetch_headers(struct Context *ctx, void *hc, anum_t first,
anum_t last, int restore)
{
return 0;
}
-/* Open newsgroup */
+/**
+ * nntp_open_mailbox - Open newsgroup
+ */
static int nntp_open_mailbox(struct Context *ctx)
{
struct NntpServer *nserv = NULL;
return 0;
}
-/* Fetch message */
+/**
+ * nntp_open_message - Fetch message
+ */
static int nntp_open_message(struct Context *ctx, struct Message *msg, int msgno)
{
struct NntpData *nntp_data = ctx->data;
return 0;
}
-/* Close message */
+/**
+ * nntp_close_message - Close message
+ */
static int nntp_close_message(struct Context *ctx, struct Message *msg)
{
return safe_fclose(&msg->fp);
}
-/* Post article */
+/**
+ * nntp_post - Post article
+ */
int nntp_post(const char *msg)
{
struct NntpData *nntp_data, nntp_tmp;
return 0;
}
-/* Check newsgroup for new articles:
- * 1 - new articles found
- * 0 - no change
- * -1 - lost connection */
+/**
+ * nntp_group_poll - Check newsgroup for new articles
+ * @return
+ * * 1 New articles found
+ * * 0 No change
+ * * -1 Lost connection
+ */
static int nntp_group_poll(struct NntpData *nntp_data, int update_stat)
{
char buf[LONG_STRING] = "";
return 1;
}
-/* Check current newsgroup for new articles, leave newsrc locked:
- * MUTT_REOPENED - articles have been renumbered or removed from server
- * MUTT_NEW_MAIL - new articles found
- * 0 - no change
- * -1 - lost connection */
+/**
+ * check_mailbox - Check current newsgroup for new articles
+ * @return
+ * * #MUTT_REOPENED Articles have been renumbered or removed from server
+ * * #MUTT_NEW_MAIL New articles found
+ * * 0 No change
+ * * -1 Lost connection
+ *
+ * Leave newsrc locked
+ */
static int check_mailbox(struct Context *ctx)
{
struct NntpData *nntp_data = ctx->data;
return ret;
}
-/* Check current newsgroup for new articles:
- * MUTT_REOPENED - articles have been renumbered or removed from server
- * MUTT_NEW_MAIL - new articles found
- * 0 - no change
- * -1 - lost connection */
+/**
+ * nntp_check_mailbox - Check current newsgroup for new articles
+ * @return
+ * * #MUTT_REOPENED Articles have been renumbered or removed from server
+ * * #MUTT_NEW_MAIL New articles found
+ * * 0 No change
+ * * -1 Lost connection
+ */
static int nntp_check_mailbox(struct Context *ctx, int *index_hint)
{
int ret = check_mailbox(ctx);
return ret;
}
-/* Save changes to .newsrc and cache */
+/**
+ * nntp_sync_mailbox - Save changes to .newsrc and cache
+ */
static int nntp_sync_mailbox(struct Context *ctx, int *index_hint)
{
struct NntpData *nntp_data = ctx->data;
return 0;
}
-/* Free up memory associated with the newsgroup context */
+/**
+ * nntp_close_mailbox - Free up memory associated with the newsgroup context
+ */
static int nntp_close_mailbox(struct Context *ctx)
{
struct NntpData *nntp_data = ctx->data, *nntp_tmp = NULL;
return 0;
}
-/* Get date and time from server */
+/**
+ * nntp_date - Get date and time from server
+ */
static int nntp_date(struct NntpServer *nserv, time_t *now)
{
if (nserv->hasDATE)
return 0;
}
-/* Fetch list of all newsgroups from server */
+/**
+ * nntp_active_fetch - Fetch list of all newsgroups from server
+ */
int nntp_active_fetch(struct NntpServer *nserv, unsigned int new)
{
struct NntpData nntp_data;
return 0;
}
-/* Check for new groups and new articles in subscribed groups:
- * 1 - new groups found
- * 0 - no new groups
- * -1 - error */
+/**
+ * nntp_check_new_groups - Check for new groups/articles in subscribed groups
+ * @return
+ * * 1 New groups found
+ * * 0 No new groups
+ * * -1 Error
+ */
int nntp_check_new_groups(struct NntpServer *nserv)
{
struct NntpData nntp_data;
return rc;
}
-/* Fetch article by Message-ID:
- * 0 - success
- * 1 - no such article
- * -1 - error */
+/**
+ * nntp_check_msgid - Fetch article by Message-ID
+ * @return
+ * * 0 Success
+ * * 1 No such article
+ * * -1 Error
+ */
int nntp_check_msgid(struct Context *ctx, const char *msgid)
{
struct NntpData *nntp_data = ctx->data;
anum_t *child;
};
-/* Parse XPAT line */
+/**
+ * fetch_children - Parse XPAT line
+ */
static int fetch_children(char *line, void *data)
{
struct ChildCtx *cc = data;
return 0;
}
-/* Fetch children of article with the Message-ID */
+/**
+ * nntp_check_children - Fetch children of article with the Message-ID
+ */
int nntp_check_children(struct Context *ctx, const char *msgid)
{
struct NntpData *nntp_data = ctx->data;
return pos;
}
-/* trim tail of buf so that it contains complete multibyte characters */
+/**
+ * trim_incomplete_mbyte - Remove an incomplete character
+ *
+ * trim tail of buf so that it contains complete multibyte characters
+ */
static int trim_incomplete_mbyte(unsigned char *buf, size_t len)
{
mbstate_t mbstate;
pager_menu->redraw = 0;
}
-/* This pager is actually not so simple as it once was. It now operates in
- two modes: one for viewing messages and the other for viewing help. These
- can be distinguished by whether or not ``hdr'' is NULL. The ``hdr'' arg
- is there so that we can do operations on the current message without the
- need to pop back out to the main-menu. */
+/**
+ * mutt_pager - Display a file, or help, in a window
+ *
+ * This pager is actually not so simple as it once was. It now operates in two
+ * modes: one for viewing messages and the other for viewing help. These can
+ * be distinguished by whether or not ``hdr'' is NULL. The ``hdr'' arg is
+ * there so that we can do operations on the current message without the need
+ * to pop back out to the main-menu.
+ */
int mutt_pager(const char *banner, const char *fname, int flags, struct Pager *extra)
{
static char searchbuf[STRING] = "";
struct Address;
struct Context;
-/* Reads an arbitrarily long header field, and looks ahead for continuation
+/**
+ * mutt_read_rfc822_line - Read a header line from a file
+ *
+ * Reads an arbitrarily long header field, and looks ahead for continuation
* lines. ``line'' must point to a dynamically allocated string; it is
* increased if more space is required to fit the whole line.
*/
}
}
-/* args:
- * fp stream to read from
- *
- * digest 1 if reading subparts of a multipart/digest, 0
- * otherwise
+/**
+ * mutt_read_mime_header - Parse a MIME header
+ * @param fp stream to read from
+ * @param digest 1 if reading subparts of a multipart/digest, 0 otherwise
*/
struct Body *mutt_read_mime_header(FILE *fp, int digest)
{
}
}
-/* parse a Message/RFC822 body
- *
- * args:
- * fp stream to read from
- *
- * parent structure which contains info about the message/rfc822
- * body part
+/**
+ * mutt_parse_message_rfc822 - parse a Message/RFC822 body
+ * @param fp stream to read from
+ * @param parent info about the message/rfc822 body part
*
* NOTE: this assumes that `parent->length' has been set!
*/
return msg;
}
-/* parse a multipart structure
- *
- * args:
- * fp stream to read from
- *
- * boundary body separator
- *
- * end_off length of the multipart body (used when the final
- * boundary is missing to avoid reading too far)
- *
- * digest 1 if reading a multipart/digest, 0 otherwise
+/**
+ * mutt_parse_multipart - parse a multipart structure
+ * @param fp stream to read from
+ * @param boundary body separator
+ * @param end_off length of the multipart body (used when the final
+ * boundary is missing to avoid reading too far)
+ * @param digest 1 if reading a multipart/digest, 0 otherwise
*/
struct Body *mutt_parse_multipart(FILE *fp, const char *boundary, LOFF_T end_off, int digest)
{
{ "wst", 8, 0, false }, /* Western Australia */
};
-/* parses a date string in RFC822 format:
+/**
+ * mutt_parse_date - parses a date string in RFC822 format
*
* Date: [ weekday , ] day-of-month month year hour:minute:second timezone
*
return (mutt_mktime(&tm, 0) + tz_offset);
}
-/* extract the first substring that looks like a message-id.
+/**
+ * mutt_extract_message_id - Find a message-id
+ *
+ * extract the first substring that looks like a message-id.
* call back with NULL for more (like strtok).
*/
char *mutt_extract_message_id(const char *s, const char **saveptr)
return p;
}
-/* Compares mime types to the ok and except lists */
+/**
+ * count_body_parts_check - Compares mime types to the ok and except lists
+ */
static bool count_body_parts_check(struct List **checklist, struct Body *b, bool dflt)
{
struct List *type = NULL;
return true;
}
-/* Ny years
- Nm months
- Nw weeks
- Nd days */
+/**
+ * get_offset - Calculate a symbolic offset
+ *
+ * Ny years
+ * Nm months
+ * Nw weeks
+ * Nd days
+ */
static const char *get_offset(struct tm *tm, const char *s, int sign)
{
char *ps = NULL;
LastSearch */
-/* if no uppercase letters are given, do a case-insensitive search */
+/**
+ * mutt_which_case - Smart-case searching
+ *
+ * if no uppercase letters are given, do a case-insensitive search
+ */
int mutt_which_case(const char *s)
{
wchar_t w;
return false;
}
-/*
- * Matches subscribed mailing lists
+/**
+ * mutt_is_list_recipient - Matches subscribed mailing lists
*/
int mutt_is_list_recipient(int alladdr, struct Address *a1, struct Address *a2)
{
return alladdr;
}
-/*
- * Matches known mailing lists
+/**
+ * mutt_is_list_cc - Matches known mailing lists
+ *
* The function name may seem a little bit misleading: It checks all
* recipients in To and Cc for known mailing lists, subscribed or not.
*/
}
-/* Sets a value in the PatternCache cache entry.
- * Normalizes the "true" value to 2. */
+/**
+ * set_pattern_cache_value - Sets a value in the PatternCache cache entry
+ *
+ * Normalizes the "true" value to 2.
+ */
static void set_pattern_cache_value(int *cache_entry, int value)
{
*cache_entry = value ? 2 : 1;
}
-/* Returns 1 if the cache value is set and has a true value.
- * 0 otherwise (even if unset!) */
+/**
+ * get_pattern_cache_value - Get pattern cache value
+ * @return
+ * * 1 if the cache value is set and has a true value.
+ * * 0 otherwise (even if unset!)
+ */
static int get_pattern_cache_value(int cache_entry)
{
return cache_entry == 2;
}
-/*
+/**
+ * mutt_pattern_exec - Match a pattern against an email header
+ *
* flags: MUTT_MATCH_FULL_ADDRESS - match both personal and machine address
* cache: For repeated matches against the same Header, passing in non-NULL will
- * store some of the cacheable pattern matches in this structure. */
+ * store some of the cacheable pattern matches in this structure.
+ */
int mutt_pattern_exec(struct Pattern *pat, enum PatternExecFlag flags,
struct Context *ctx, struct Header *h, struct PatternCache *cache)
{
tmp[i] = 0;
}
-/* convert a simple search into a real request */
+/**
+ * mutt_check_simple - convert a simple search into a real request
+ */
void mutt_check_simple(char *s, size_t len, const char *simple)
{
char tmp[LONG_STRING];
return false;
}
-/* The actual key ring parser */
+/**
+ * pgp_make_pgp2_fingerprint - The actual key ring parser
+ */
static void pgp_make_pgp2_fingerprint(unsigned char *buff, unsigned char *digest)
{
struct Md5Ctx ctx;
#define HC_FEXT "hcache" /* extension for hcache as POP lacks paths */
#endif
-/* write line to file */
+/**
+ * fetch_message - write line to file
+ */
static int fetch_message(char *line, void *file)
{
FILE *f = (FILE *) file;
return ret;
}
-/* parse UIDL */
+/**
+ * fetch_uidl - parse UIDL
+ */
static int fetch_uidl(char *line, void *data)
{
int i, index;
return (new_count - old_count);
}
-/* open POP mailbox - fetch only headers */
+/**
+ * pop_open_mailbox - open POP mailbox, fetch only headers
+ */
static int pop_open_mailbox(struct Context *ctx)
{
int ret;
}
}
-/* delete all cached messages */
+/**
+ * pop_clear_cache - delete all cached messages
+ */
static void pop_clear_cache(struct PopData *pop_data)
{
if (!pop_data->clear_cache)
}
}
-/* close POP mailbox */
+/**
+ * pop_close_mailbox - close POP mailbox
+ */
static int pop_close_mailbox(struct Context *ctx)
{
struct PopData *pop_data = (struct PopData *) ctx->data;
return 0;
}
-/* fetch message from POP server */
+/**
+ * pop_fetch_message - fetch message from POP server
+ */
static int pop_fetch_message(struct Context *ctx, struct Message *msg, int msgno)
{
int ret;
return safe_fclose(&msg->fp);
}
-/* update POP mailbox - delete messages from server */
+/**
+ * pop_sync_mailbox - update POP mailbox, delete messages from server
+ */
static int pop_sync_mailbox(struct Context *ctx, int *index_hint)
{
int i, j, ret = 0;
}
}
-/* Check for new messages and fetch headers */
+/**
+ * pop_check_mailbox - Check for new messages and fetch headers
+ */
static int pop_check_mailbox(struct Context *ctx, int *index_hint)
{
int ret;
return 0;
}
-/* Fetch messages and save them in $spoolfile */
+/**
+ * pop_fetch_mail - Fetch messages and save them in $spoolfile
+ */
void pop_fetch_mail(void)
{
char buffer[LONG_STRING];
#endif
#ifdef USE_SASL
-/* SASL authenticator */
+/**
+ * pop_auth_sasl - POP SASL authenticator
+ */
static enum PopAuthRes pop_auth_sasl(struct PopData *pop_data, const char *method)
{
sasl_conn_t *saslconn = NULL;
}
#endif
-/* Get the server timestamp for APOP authentication */
+/**
+ * pop_apop_timestamp - Get the server timestamp for APOP authentication
+ */
void pop_apop_timestamp(struct PopData *pop_data, char *buf)
{
char *p1 = NULL, *p2 = NULL;
}
}
-/* APOP authenticator */
+/**
+ * pop_auth_apop - APOP authenticator
+ */
static enum PopAuthRes pop_auth_apop(struct PopData *pop_data, const char *method)
{
struct Md5Ctx ctx;
return POP_A_FAILURE;
}
-/* USER authenticator */
+/**
+ * pop_auth_user - USER authenticator
+ */
static enum PopAuthRes pop_auth_user(struct PopData *pop_data, const char *method)
{
char buf[LONG_STRING];
{ NULL, NULL },
};
-/*
- * Authentication
- * 0 - successful,
- * -1 - connection lost,
- * -2 - login failed,
- * -3 - authentication canceled.
+/**
+ * pop_authenticate - Authenticate with a POP server
+ * @return
+ * * 0 Successful
+ * * -1 Connection lost
+ * * -2 Login failed
+ * * -3 Authentication cancelled
*/
int pop_authenticate(struct PopData *pop_data)
{
/**
* pop_fetch_data - Read Headers with callback function
- *
+ * @return
+ * * 0 Successful
+ * * -1 Connection lost
+ * * -2 Invalid command or execution error
+ * * -3 Error in funct(*line, *data)
*
* This function calls funct(*line, *data) for each received line,
* funct(NULL, *data) if rewind(*data) needs, exits when fail or done.
- * Returned codes:
- * 0 - successful,
- * -1 - connection lost,
- * -2 - invalid command or execution error,
- * -3 - error in funct(*line, *data)
*/
int pop_fetch_data(struct PopData *pop_data, char *query, struct Progress *progressbar,
int (*funct)(char *, void *), void *data)
static struct Context *PostContext = NULL;
static short UpdateNumPostponed = 0;
-/* Return the number of postponed messages.
- * if force is 0, use a cached value if it is costly to get a fresh
- * count (IMAP) - else check.
+/**
+ * mutt_num_postponed - Return the number of postponed messages
+ * @param force
+ * * 0 Use a cached value if costly to get a fresh count (IMAP)
+ * * 1 Force check
+ * @return Number of postponed messages
*/
int mutt_num_postponed(int force)
{
}
-/* args:
- * fp If not NULL, file containing the template
- * ctx If fp is NULL, the context containing the header with the template
- * newhdr The template is read into this Header
- * hdr The message to recall/resend
- * resend Set if resending (as opposed to recalling a postponed msg).
- * Resent messages enable header weeding, and also
- * discard any existing Message-ID and Mail-Followup-To.
+/**
+ * mutt_prepare_template - Prepare a message template
+ * @param fp If not NULL, file containing the template
+ * @param ctx If fp is NULL, the context containing the header with the template
+ * @param newhdr The template is read into this Header
+ * @param hdr The message to recall/resend
+ * @param resend Set if resending (as opposed to recalling a postponed msg).
+ * Resent messages enable header weeding, and also
+ * discard any existing Message-ID and Mail-Followup-To.
+ * @return 0 on success, -1 on error
*/
int mutt_prepare_template(FILE *fp, struct Context *ctx, struct Header *newhdr,
struct Header *hdr, short resend)
mutt_menu_destroy(&menu);
}
}
+
int mutt_query_complete(char *buf, size_t buflen)
{
struct Query *results = NULL;
return idx;
}
-/* %c = character set: convert?
- * %C = character set
- * %D = deleted flag
- * %d = description
- * %e = MIME content-transfer-encoding
- * %F = filename for content-disposition header
- * %f = filename
- * %I = content-disposition, either I (inline) or A (attachment)
- * %t = tagged flag
- * %T = tree chars
- * %m = major MIME type
- * %M = MIME subtype
- * %n = attachment number
- * %s = size
- * %u = unlink
+/**
+ * mutt_attach_fmt - Format string for attachment menu
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%c | character set: convert?
+ * | \%C | character set
+ * | \%D | deleted flag
+ * | \%d | description
+ * | \%e | MIME content-transfer-encoding
+ * | \%F | filename for content-disposition header
+ * | \%f | filename
+ * | \%I | content-disposition, either I (inline) or A (attachment)
+ * | \%t | tagged flag
+ * | \%T | tree chars
+ * | \%m | major MIME type
+ * | \%M | MIME subtype
+ * | \%n | attachment number
+ * | \%s | size
+ * | \%u | unlink
*/
const char *mutt_attach_fmt(char *dest, size_t destlen, size_t col, int cols,
char op, const char *src, const char *prefix,
#include "rfc822.h"
#include "state.h"
-/* some helper functions to verify that we are exclusively operating
- * on message/rfc822 attachments
+/**
+ * check_msg - Are we working with an RFC822 message
+ *
+ * some helper functions to verify that we are exclusively operating on
+ * message/rfc822 attachments
*/
static bool check_msg(struct Body *b, bool err)
{
}
-/* can we decode all tagged attachments? */
+/**
+ * check_can_decode - can we decode all tagged attachments?
+ */
static short check_can_decode(struct AttachPtr **idx, short idxlen, struct Body *cur)
{
if (cur)
return count;
}
-/* count the number of tagged children below a multipart or message
- * attachment.
+/**
+ * count_tagged_children - tagged children below a multipart/message attachment
*/
static short count_tagged_children(struct AttachPtr **idx, short idxlen, short i)
{
/**
- **
- ** The bounce function, from the attachment menu
- **
- **/
+ * mutt_attach_bounce - Bounce function, from the attachment menu
+ */
void mutt_attach_bounce(FILE *fp, struct Header *hdr, struct AttachPtr **idx,
short idxlen, struct Body *cur)
{
/**
- **
- ** resend-message, from the attachment menu
- **
- **
- **/
+ * mutt_attach_resend - resend-message, from the attachment menu
+ */
void mutt_attach_resend(FILE *fp, struct Header *hdr, struct AttachPtr **idx,
short idxlen, struct Body *cur)
{
/**
- **
** forward-message, from the attachment menu
- **
**/
-/* try to find a common parent message for the tagged attachments. */
+/**
+ * find_common_parent - find a common parent message for the tagged attachments
+ */
static struct Header *find_common_parent(struct AttachPtr **idx, short idxlen, short nattach)
{
short i;
return NULL;
}
-/*
- * check whether attachment #i is a parent of the attachment
- * pointed to by cur
+/**
+ * is_parent - Check whether one attachment is the parent of another
*
- * Note: This and the calling procedure could be optimized quite a
- * bit. For now, it's not worth the effort.
+ * check whether attachment i is a parent of the attachment pointed to by cur
+ *
+ * Note: This and the calling procedure could be optimized quite a bit.
+ * For now, it's not worth the effort.
*/
static bool is_parent(short i, struct AttachPtr **idx, short idxlen, struct Body *cur)
{
mutt_copy_header(ifp, hdr, ofp, chflags, quote ? prefix : NULL);
}
-/* Attach all the body parts which can't be decoded.
- * This code is shared by forwarding and replying. */
+/**
+ * copy_problematic_attachments - Attach the body parts which can't be decoded
+ *
+ * This code is shared by forwarding and replying.
+ */
static struct Body **copy_problematic_attachments(FILE *fp, struct Body **last,
struct AttachPtr **idx,
short idxlen, short force)
return last;
}
-/*
- * forward one or several MIME bodies
+/**
+ * attach_forward_bodies - forward one or several MIME bodies
+ *
* (non-message types)
*/
static void attach_forward_bodies(FILE *fp, struct Header *hdr,
}
-/*
- * Forward one or several message-type attachments. This
- * is different from the previous function
- * since we want to mimic the index menu's behavior.
+/**
+ * attach_forward_msgs - Forward one or several message-type attachments
+ *
+ * This is different from the previous function since we want to mimic the
+ * index menu's behavior.
*
- * Code reuse from ci_send_message is not possible here -
- * ci_send_message relies on a context structure to find messages,
- * while, on the attachment menu, messages are referenced through
- * the attachment index.
+ * Code reuse from ci_send_message is not possible here - ci_send_message
+ * relies on a context structure to find messages, while, on the attachment
+ * menu, messages are referenced through the attachment index.
*/
static void attach_forward_msgs(FILE *fp, struct Header *hdr, struct AttachPtr **idx,
short idxlen, struct Body *cur, int flags)
/**
- **
** the various reply functions, from the attachment menu
- **
- **
**/
-/* Create the envelope defaults for a reply.
+/**
+ * attach_reply_envelope_defaults - Create the envelope defaults for a reply
*
* This function can be invoked in two ways.
*
* Or, parent is non-NULL. In this case, cur is the common parent of all the
* tagged attachments.
*
- * Note that this code is horribly similar to envelope_defaults () from send.c.
+ * Note that this code is horribly similar to envelope_defaults() from send.c.
*/
static int attach_reply_envelope_defaults(struct Envelope *env, struct AttachPtr **idx,
short idxlen, struct Header *parent, int flags)
}
-/* This is _very_ similar to send.c's include_reply(). */
+/**
+ * attach_include_reply - This is _very_ similar to send.c's include_reply()
+ */
static void attach_include_reply(FILE *fp, FILE *tmpfp, struct Header *cur, int flags)
{
int cmflags = MUTT_CM_PREFIX | MUTT_CM_DECODE | MUTT_CM_CHARCONV;
FREE(r);
}
-/* parse the type2.list as given by mixmaster -T */
+/**
+ * mix_type2_list - parse the type2.list as given by mixmaster -T
+ */
static struct Remailer **mix_type2_list(size_t *l)
{
FILE *fp = NULL;
return capbuff;
}
-/*
- * Format an entry for the remailer menu.
+/**
+ * mix_entry_fmt - Format an entry for the remailer menu
*
- * %n number
- * %c capabilities
- * %s short name
- * %a address
+ * * %n number
+ * * %c capabilities
+ * * %s short name
+ * * %a address
*/
static const char *mix_entry_fmt(char *dest, size_t destlen, size_t col, int cols,
char op, const char *src, const char *prefix,
FREE(&chain);
}
-/* some safety checks before piping the message to mixmaster */
+/**
+ * mix_check_message - Safety-check the message before passing it to mixmaster
+ */
int mix_check_message(struct Header *msg)
{
const char *fqdn = NULL;
#endif
#endif
-/* this routine should be called after receiving SIGWINCH */
+/**
+ * mutt_resize_screen - Called after receiving SIGWINCH
+ */
void mutt_resize_screen(void)
{
char *cp = NULL;
#include "options.h"
#include "protos.h"
-/* The command semantics include the following:
+/**
+ * rfc1524_expand_command - Expand expandos in a command
+ *
+ * The command semantics include the following:
* %s is the filename that contains the mail body data
* %t is the content type, like text/plain
* %{parameter} is replaced by the parameter value from the content-type field
FREE(entry);
}
-/*
- * rfc1524_mailcap_lookup attempts to find the given type in the
- * list of mailcap files. On success, this returns the entry information
- * in *entry, and returns 1. On failure (not found), returns 0.
- * If entry == NULL just return 1 if the given type is found.
+/**
+ * rfc1524_mailcap_lookup - Find given type in the list of mailcap files
+ *
+ * On success, this returns the entry information in *entry, and returns 1. On
+ * failure (not found), returns 0. If entry == NULL just return 1 if the given
+ * type is found.
*/
int rfc1524_mailcap_lookup(struct Body *a, char *type,
struct Rfc1524MailcapEntry *entry, int opt)
return (*encoder)(s, d, dlen, tocode);
}
-/*
- * Discover how much of the data (d, dlen) can be converted into
- * a single encoded word. Return how much data can be converted,
- * and set the length *wlen of the encoded word and *encoder.
- * We start in column col, which limits the length of the word.
+/**
+ * choose_block - Calculate how much data can be converted
+ *
+ * Discover how much of the data (d, dlen) can be converted into a single
+ * encoded word. Return how much data can be converted, and set the length
+ * *wlen of the encoded word and *encoder. We start in column col, which
+ * limits the length of the word.
*/
static size_t choose_block(char *d, size_t dlen, int col, const char *fromcode,
const char *tocode, encoder_t *encoder, size_t *wlen)
return rv;
}
-/*
- * Find the start and end of the first encoded word in the string.
- * We use the grammar in section 2 of RFC 2047, but the "encoding"
- * must be B or Q. Also, we don't require the encoded word to be
- * separated by linear-white-space (section 5(1)).
+/**
+ * find_encoded_word - Find limits of first encoded word in a string
+ *
+ * Find the start and end of the first encoded word in the string. We use the
+ * grammar in section 2 of RFC 2047, but the "encoding" must be B or Q. Also,
+ * we don't require the encoded word to be separated by linear-white-space
+ * (section 5(1)).
*/
static const char *find_encoded_word(const char *s, const char **x)
{
return 0;
}
-/* return length of linear-white-space */
+/**
+ * lwslen - return length of linear-white-space
+ */
static size_t lwslen(const char *s, size_t n)
{
const char *p = s;
return len;
}
-/* return length of linear-white-space : reverse */
+/**
+ * lwsrlen - return length of linear-white-space : reverse
+ */
static size_t lwsrlen(const char *s, size_t n)
{
const char *p = s + n - 1;
return len;
}
-/* try to decode anything that looks like a valid RFC2047 encoded
+/**
+ * rfc2047_decode - Decode any RFC2047-encoded header fields
+ *
+ * try to decode anything that looks like a valid RFC2047 encoded
* header field, ignoring RFC822 parsing rules
*/
void rfc2047_decode(char **pd)
return safe_calloc(1, sizeof(struct Rfc2231Parameter));
}
-/* insert parameter into an ordered list.
+/**
+ * rfc2231_list_insert - insert parameter into an ordered list
*
* Primary sorting key: attribute
* Secondary sorting key: index
}
}
-/* process continuation parameters */
+/**
+ * rfc2231_join_continuations - process continuation parameters
+ */
static void rfc2231_join_continuations(struct Parameter **head, struct Rfc2231Parameter *par)
{
struct Rfc2231Parameter *q = NULL;
return quoted;
}
-/* Determines whether to add spacing between/after each quote level:
- * >>>foo
+/**
+ * space_quotes - Should we add spaces between quote levels
+ *
+ * Determines whether to add spacing between/after each quote level:
+ * ` >>>foo`
* becomes
- * > > > foo
+ * ` > > > foo`
*/
static int space_quotes(struct State *s)
{
return option(OPTREFLOWSPACEQUOTES);
}
-/* Determines whether to add a trailing space to quotes:
- * >>> foo
+/**
+ * add_quote_suffix - Should we add a trailing space to quotes
+ *
+ * Determines whether to add a trailing space to quotes:
+ * ` >>> foo`
* as opposed to
- * >>>foo
+ * ` >>>foo`
*/
static bool add_quote_suffix(struct State *s, int ql)
{
fst->spaces = 0;
}
-/* Calculate the paragraph width based upon the current quote level. The start
- * of a quoted line will be ">>> ", so we need to subtract the space required
- * for the prefix from the terminal width. */
+/**
+ * quote_width - Calculate the paragraph width based upon the quote level
+ *
+ * The start of a quoted line will be ">>> ", so we need to subtract the space
+ * required for the prefix from the terminal width.
+ */
static int quote_width(struct State *s, int ql)
{
int width = mutt_window_wrap_cols(MuttIndexWindow, ReflowWrap);
return 0;
}
-/*
- * This routine does RfC3676 space stuffing since it's a MUST.
+/**
+ * rfc3676_space_stuff - Perform required RFC3676 space stuffing
+ *
* Space stuffing means that we have to add leading spaces to
* certain lines:
* - lines starting with a space
* - lines starting with 'From '
- * This routine is only called once right after editing the
- * initial message so it's up to the user to take care of stuffing
- * when editing the message several times before actually sending it
+ * This routine is only called once right after editing the initial message so
+ * it's up to the user to take care of stuffing when editing the message
+ * several times before actually sending it
*
- * This is more or less a hack as it replaces the message's content with
- * a freshly created copy in a tempfile and modifies the file's mtime
- * so we don't trigger code paths watching for mtime changes
+ * This is more or less a hack as it replaces the message's content with a
+ * freshly created copy in a tempfile and modifies the file's mtime so we don't
+ * trigger code paths watching for mtime changes
*/
void rfc3676_space_stuff(struct Header *hdr)
{
*pbuf = 0;
}
-/* note: it is assumed that `buf' is nul terminated! */
+/**
+ * rfc822_write_address - Write an address to a buffer
+ *
+ * Note: it is assumed that `buf' is nul terminated!
+ */
int rfc822_write_address(char *buf, size_t buflen, struct Address *addr, int display)
{
char *pbuf = buf;
return pbuf - buf;
}
-/* this should be rfc822_cpy_adr */
+/**
+ * rfc822_cpy_adr_real - Copy the real address
+ *
+ * this should be rfc822_cpy_adr
+ */
struct Address *rfc822_cpy_adr_real(struct Address *addr)
{
struct Address *p = rfc822_new_address();
return p;
}
-/* this should be rfc822_cpy_adrlist */
+/**
+ * rfc822_cpy_adr - Copy a list of addresses
+ *
+ * this should be rfc822_cpy_adrlist
+ */
struct Address *rfc822_cpy_adr(struct Address *addr, int prune)
{
struct Address *top = NULL, *last = NULL;
return top;
}
-/* append list 'b' to list 'a' and return the last element in the new list */
+/**
+ * rfc822_append - Append one list of addresses on another
+ *
+ * append list 'b' to list 'a' and return the last element in the new list
+ */
struct Address *rfc822_append(struct Address **a, struct Address *b, int prune)
{
struct Address *tmp = *a;
return tmp;
}
-/* incomplete. Only used to thwart the APOP MD5 attack (#2846). */
+/**
+ * rfc822_valid_msgid - Is the message id valid
+ *
+ * incomplete. Only used to thwart the APOP MD5 attack (#2846).
+ */
bool rfc822_valid_msgid(const char *msgid)
{
/* msg-id = "<" addr-spec ">"
* version using it.
*/
+/**
+ * safe_asprintf - Wrapper for vasprintf()
+ */
#ifdef HAVE_VASPRINTF
int safe_asprintf(char **strp, const char *fmt, ...)
{
}
}
-/* compare two e-mail addresses and return 1 if they are equivalent */
+/**
+ * addrcmp - compare two e-mail addresses
+ * @param a Address 1
+ * @param b Address 2
+ * @return true if they are equivalent
+ */
static bool addrcmp(struct Address *a, struct Address *b)
{
if (!a->mailbox || !b->mailbox)
return true;
}
-/* search an e-mail address in a list */
+/**
+ * addrsrc - search an e-mail address in a list
+ */
static int addrsrc(struct Address *a, struct Address *lst)
{
for (; lst; lst = lst->next)
return 0;
}
-/* removes addresses from "b" which are contained in "a" */
+/**
+ * mutt_remove_xrefs - Remove cross-references
+ *
+ * Remove addresses from "b" which are contained in "a"
+ */
struct Address *mutt_remove_xrefs(struct Address *a, struct Address *b)
{
struct Address *top = NULL, *p = NULL, *prev = NULL;
return top;
}
-/* remove any address which matches the current user. if `leave_only' is
- * nonzero, don't remove the user's address if it is the only one in the list
+/**
+ * remove_user - Remove any address which matches the current user
+ * @param a List of addresses
+ * @param leave_only If set, don't remove the user's address if it it the only
+ * one in the list
*/
static struct Address *remove_user(struct Address *a, int leave_only)
{
return 0;
}
-static int generate_body(FILE *tempfp, /* stream for outgoing message */
- struct Header *msg, /* header for outgoing message */
- int flags, /* compose mode */
- struct Context *ctx, /* current mailbox */
- struct Header *cur) /* current message */
+/**
+ * generate_body - Create a new email body
+ * @param tempfp stream for outgoing message
+ * @param msg header for outgoing message
+ * @param flags compose mode
+ * @param ctx current mailbox
+ * @param cur current message
+ * @return 0 on success, -1 on error
+ */
+static int generate_body(FILE *tempfp, struct Header *msg, int flags,
+ struct Context *ctx, struct Header *cur)
{
int i;
struct Header *h = NULL;
}
-/* look through the recipients of the message we are replying to, and if
- we find an address that matches $alternates, we use that as the default
- from field */
+/**
+ * set_reverse_name - Try to set the 'from' field from the recipients
+ *
+ * look through the recipients of the message we are replying to, and if we
+ * find an address that matches $alternates, we use that as the default from
+ * field
+ */
static struct Address *set_reverse_name(struct Envelope *env)
{
struct Address *tmp = NULL;
return i;
}
-/* rfc2047 encode the content-descriptions */
+/**
+ * mutt_encode_descriptions - rfc2047 encode the content-descriptions
+ */
void mutt_encode_descriptions(struct Body *b, short recurse)
{
struct Body *t = NULL;
}
}
-/* rfc2047 decode them in case of an error */
+/**
+ * decode_descriptions - rfc2047 decode them in case of an error
+ */
static void decode_descriptions(struct Body *b)
{
struct Body *t = NULL;
return ret;
}
-/*
- * Find the first of the fromcodes that gives a valid conversion and
- * the best charset conversion of the file into one of the tocodes. If
- * successful, set *fromcode and *tocode to dynamically allocated
- * strings, set Content *info, and return the number of characters
- * converted inexactly. If no conversion was possible, return -1.
+/**
+ * convert_file_from_to - Convert a file between encodings
+ *
+ * Find the first of the fromcodes that gives a valid conversion and the best
+ * charset conversion of the file into one of the tocodes. If successful, set
+ * *fromcode and *tocode to dynamically allocated strings, set Content *info,
+ * and return the number of characters converted inexactly. If no conversion
+ * was possible, return -1.
*
* Both fromcodes and tocodes may be colon-separated lists of charsets.
- * However, if fromcode is zero then fromcodes is assumed to be the
- * name of a single charset even if it contains a colon.
+ * However, if fromcode is zero then fromcodes is assumed to be the name of a
+ * single charset even if it contains a colon.
*/
static size_t convert_file_from_to(FILE *file, const char *fromcodes, const char *tocodes,
char **fromcode, char **tocode, struct Content *info)
return ret;
}
-/*
- * Analyze the contents of a file to determine which MIME encoding to use.
+/**
+ * mutt_get_content_info - Analyze file to determine MIME encoding to use
+ *
* Also set the body charset, sometimes, or not.
*/
struct Content *mutt_get_content_info(const char *fname, struct Body *b)
a->hdr->content = NULL;
}
-/* determine which Content-Transfer-Encoding to use */
+/**
+ * set_encoding - determine which Content-Transfer-Encoding to use
+ */
static void set_encoding(struct Body *b, struct Content *info)
{
char send_charset[SHORT_STRING];
a->stamp = time(NULL);
}
-/* Get a body's character set */
+/**
+ * mutt_get_body_charset - Get a body's character set
+ */
char *mutt_get_body_charset(char *d, size_t dlen, struct Body *b)
{
char *p = NULL;
}
-/* Assumes called from send mode where Body->filename points to actual file */
+/**
+ * mutt_update_encoding - Update the encoding type
+ *
+ * Assumes called from send mode where Body->filename points to actual file
+ */
void mutt_update_encoding(struct Body *a)
{
struct Content *info = NULL;
return e;
}
-/* check for duplicate boundary. return 1 if duplicate */
+/**
+ * check_boundary - check for duplicate boundary
+ * @return true if duplicate found
+ */
static bool check_boundary(const char *boundary, struct Body *b)
{
char *p = NULL;
return new;
}
-/* remove the multipart body if it exists */
+/**
+ * mutt_remove_multipart - remove the multipart body if it exists
+ */
struct Body *mutt_remove_multipart(struct Body *b)
{
struct Body *t = NULL;
return s;
}
-/* wrapper around mutt_write_address() so we can handle very large
- recipient lists without needing a huge temporary buffer in memory */
+/**
+ * mutt_write_address_list - wrapper around mutt_write_address()
+ *
+ * So we can handle very large recipient lists without needing a huge temporary
+ * buffer in memory
+ */
void mutt_write_address_list(struct Address *adr, FILE *fp, int linelen, int display)
{
struct Address *tmp = NULL;
/* arbitrary number of elements to grow the array by */
#define REF_INC 16
-/* need to write the list in reverse because they are stored in reverse order
+/**
+ * mutt_write_references - Add the message refrerences to a list
+ *
+ * need to write the list in reverse because they are stored in reverse order
* when parsed to speed up threading
*/
void mutt_write_references(struct List *r, FILE *f, int trim)
return p;
}
-/* like wcwidth(), but gets const char* not wchar_t* */
+/**
+ * my_width - like wcwidth(), but gets const char* not wchar_t*
+ */
static int my_width(const char *str, int col, int flags)
{
wchar_t wc;
return 0;
}
-/* split several headers into individual ones and call write_one_header
- * for each one */
+/**
+ * mutt_write_one_header - Write one header line to a file
+ *
+ * split several headers into individual ones and call write_one_header
+ * for each one
+ */
int mutt_write_one_header(FILE *fp, const char *tag, const char *value,
const char *pfx, int wraplen, int flags)
{
SigAlrm = 1;
}
-/* invoke sendmail in a subshell
- path (in) path to program to execute
- args (in) arguments to pass to program
- msg (in) temp file containing message to send
- tempfile (out) if sendmail is put in the background, this points
- to the temporary file containing the stdout of the
- child process. If it is NULL, stderr and stdout
- are not redirected. */
+/**
+ * send_msg - invoke sendmail in a subshell
+ * @param[in] path Path to program to execute
+ * @param[in] args Arguments to pass to program
+ * @param[in] msg Temp file containing message to send
+ * @param[out] tempfile If sendmail is put in the background, this points
+ * to the temporary file containing the stdout of the
+ * child process. If it is NULL, stderr and stdout
+ * are not redirected.
+ */
static int send_msg(const char *path, char **args, const char *msg, char **tempfile)
{
sigset_t set;
return args;
}
-int mutt_invoke_sendmail(struct Address *from, /* the sender */
- struct Address *to, struct Address *cc, struct Address *bcc, /* recips */
- const char *msg, /* file containing message */
- int eightbit) /* message contains 8bit chars */
+/**
+ * mutt_invoke_sendmail - Run sendmail
+ * @param from The sender
+ * @param to Recipients
+ * @param cc Recipients
+ * @param bcc Recipients
+ * @param msg File containing message
+ * @param eightbit Message contains 8bit chars
+ */
+int mutt_invoke_sendmail(struct Address *from, struct Address *to, struct Address *cc,
+ struct Address *bcc, const char *msg, int eightbit)
{
char *ps = NULL, *path = NULL, *s = NULL, *childout = NULL;
char **args = NULL;
return i;
}
-/* For postponing (!final) do the necessary encodings only */
+/**
+ * mutt_prepare_envelope - Prepare an email header
+ *
+ * For postponing (!final) do the necessary encodings only
+ */
void mutt_prepare_envelope(struct Envelope *env, int final)
{
char buffer[LONG_STRING];
}
-/* given a list of addresses, return a list of unique addresses */
+/**
+ * mutt_remove_duplicates - Remove duplicate addresses
+ *
+ * given a list of addresses, return a list of unique addresses
+ */
struct Address *mutt_remove_duplicates(struct Address *addr)
{
struct Address *top = addr;
}
}
-/* Handle a Fcc with multiple, comma separated entries. */
+/**
+ * mutt_write_multiple_fcc - Handle FCC with multiple, comma separated entries
+ */
int mutt_write_multiple_fcc(const char *path, struct Header *hdr, const char *msgid,
int post, char *fcc, char **finalpath)
{
w = rol(w, 30);
-/* Hash a single 512-bit block. This is the core of the algorithm. */
+/**
+ * sha1_transform - Hash a single 512-bit block
+ *
+ * This is the core of the algorithm.
+ */
void sha1_transform(uint32_t state[5], const unsigned char buffer[64])
{
uint32_t a, b, c, d, e;
}
-/* sha1_init - Initialize new context */
+/**
+ * sha1_init - Initialize new context
+ */
void sha1_init(struct Sha1Ctx *context)
{
/* SHA1 initialization constants */
}
-/* Run your data through this. */
+/**
+ * sha1_update - Run your data through this
+ */
void sha1_update(struct Sha1Ctx *context, const unsigned char *data, uint32_t len)
{
uint32_t i;
}
-/* Add padding and return the message digest. */
+/**
+ * sha1_final - Add padding and return the message digest
+ */
void sha1_final(unsigned char digest[20], struct Sha1Ctx *context)
{
unsigned i;
static struct sigaction SysOldQuit;
static int IsEndwin = 0;
-/* Attempt to catch "ordinary" signals and shut down gracefully. */
+/**
+ * exit_handler - Attempt to catch "ordinary" signals and shut down gracefully
+ */
static void exit_handler(int sig)
{
curs_set(1);
#endif
}
-/* signals which are important to block while doing critical ops */
+/**
+ * mutt_block_signals - Block signals during critical ops
+ *
+ * signals which are important to block while doing critical ops
+ */
void mutt_block_signals(void)
{
if (!option(OPTSIGNALSBLOCKED))
}
}
-/* restore the previous signal mask */
+/**
+ * mutt_unblock_signals - restore the previous signal mask
+ */
void mutt_unblock_signals(void)
{
if (option(OPTSIGNALSBLOCKED))
}
-/* Returns true if a contains at least one 8-bit character, false if none do.
+/**
+ * address_uses_unicode - Do any addresses use Unicode
+ * @return true if any of the string of addresses use 8-bit characters
*/
static bool address_uses_unicode(const char *a)
{
}
-/* Returns 1 if any address in a contains at least one 8-bit
- * character, 0 if none do.
+/**
+ * addresses_use_unicode - Do any of a list of addresses use Unicode
+ * @return true if any use 8-bit characters
*/
static bool addresses_use_unicode(const struct Address *a)
{
return -1;
}
#endif /* USE_SASL */
+
static int smtp_open(struct Connection *conn)
{
int rc;
static void _menu_status_line(char *buf, size_t buflen, size_t col, int cols,
struct Menu *menu, const char *p);
-/* %b = number of incoming folders with unread messages [option]
- * %d = number of deleted messages [option]
- * %f = full mailbox path
- * %F = number of flagged messages [option]
- * %h = hostname
- * %l = length of mailbox (in bytes) [option]
- * %m = total number of messages [option]
- * %M = number of messages shown (virtual message count when limiting) [option]
- * %n = number of new messages [option]
- * %o = number of old unread messages [option]
- * %p = number of postponed messages [option]
- * %P = percent of way through index
- * %r = readonly/wontwrite/changed flag
- * %s = current sorting method ($sort)
- * %S = current aux sorting method ($sort_aux)
- * %t = # of tagged messages [option]
- * %u = number of unread messages [option]
- * %v = Mutt version
- * %V = currently active limit pattern [option] */
+/**
+ * status_format_str - Format a string for the status bar
+ *
+ * | Expando | Description
+ * |:--------|:----------------------------------------------------------------
+ * | \%b | number of incoming folders with unread messages [option]
+ * | \%d | number of deleted messages [option]
+ * | \%f | full mailbox path
+ * | \%F | number of flagged messages [option]
+ * | \%h | hostname
+ * | \%l | length of mailbox (in bytes) [option]
+ * | \%m | total number of messages [option]
+ * | \%M | number of messages shown (virtual message count when limiting) [option]
+ * | \%n | number of new messages [option]
+ * | \%o | number of old unread messages [option]
+ * | \%p | number of postponed messages [option]
+ * | \%P | percent of way through index
+ * | \%r | readonly/wontwrite/changed flag
+ * | \%s | current sorting method ($sort)
+ * | \%S | current aux sorting method ($sort_aux)
+ * | \%t | # of tagged messages [option]
+ * | \%u | number of unread messages [option]
+ * | \%v | Mutt version
+ * | \%V | currently active limit pattern [option]
+ */
static const char *status_format_str(char *buf, size_t buflen, size_t col, int cols,
char op, const char *src, const char *prefix,
const char *ifstring, const char *elsestring,
#define VISIBLE(hdr, ctx) \
(hdr->virtual >= 0 || (hdr->collapsed && (!ctx->pattern || hdr->limited)))
-/* determine whether a is a descendant of b */
+/**
+ * is_descendant - Is one thread a descendant of another
+ */
static int is_descendant(struct MuttThread *a, struct MuttThread *b)
{
while (a)
return 0;
}
-/* Determines whether to display a message's subject. */
+/**
+ * need_display_subject - Determines whether to display a message's subject
+ */
static int need_display_subject(struct Context *ctx, struct Header *hdr)
{
struct MuttThread *tmp = NULL, *tree = hdr->thread;
}
}
-/* this calculates whether a node is the root of a subtree that has visible
+/**
+ * calculate_visibility - Are tree nodes visible
+ *
+ * this calculates whether a node is the root of a subtree that has visible
* nodes, whether a node itself is visible, whether, if invisible, it has
* depth anyway, and whether any of its later siblings are roots of visible
* subtrees. while it's at it, it frees the old thread display, so we can
}
}
-/* Since the graphics characters have a value >255, I have to resort to
- * using escape sequences to pass the information to print_enriched_string().
- * These are the macros MUTT_TREE_* defined in mutt.h.
+/**
+ * mutt_draw_tree - Draw a tree of threaded emails
+ *
+ * Since the graphics characters have a value >255, I have to resort to using
+ * escape sequences to pass the information to print_enriched_string(). These
+ * are the macros MUTT_TREE_* defined in mutt.h.
*
* ncurses should automatically use the default ASCII characters instead of
- * graphics chars on terminals which don't support them (see the man page
- * for curs_addch).
+ * graphics chars on terminals which don't support them (see the man page for
+ * curs_addch).
*/
void mutt_draw_tree(struct Context *ctx)
{
FREE(&arrow);
}
-/* since we may be trying to attach as a pseudo-thread a MuttThread that
+/**
+ * make_subject_list - Create a list of all subjects in a thread
+ *
+ * since we may be trying to attach as a pseudo-thread a MuttThread that
* has no message, we have to make a list of all the subjects of its
* most immediate existing descendants. we also note the earliest
- * date on any of the parents and put it in *dateptr. */
+ * date on any of the parents and put it in *dateptr.
+ */
static struct List *make_subject_list(struct MuttThread *cur, time_t *dateptr)
{
struct MuttThread *start = cur;
return subjects;
}
-/* find the best possible match for a parent message based upon subject.
- * if there are multiple matches, the one which was sent the latest, but
- * before the current message, is used.
+/**
+ * find_subject - Find the best possible match for a parent based on subject
+ *
+ * If there are multiple matches, the one which was sent the latest, but before
+ * the current message, is used.
*/
static struct MuttThread *find_subject(struct Context *ctx, struct MuttThread *cur)
{
return last;
}
-/* remove cur and its descendants from their current location.
- * also make sure ancestors of cur no longer are sorted by the
- * fact that cur is their descendant. */
+/**
+ * unlink_message - Break the message out of the thread
+ *
+ * Remove cur and its descendants from their current location. Also make sure
+ * ancestors of cur no longer are sorted by the fact that cur is their
+ * descendant.
+ */
static void unlink_message(struct MuttThread **old, struct MuttThread *cur)
{
struct MuttThread *tmp = NULL;
}
}
-/* add cur as a prior sibling of *new, with parent newparent */
+/**
+ * insert_message - Insert a message into a thread
+ *
+ * add cur as a prior sibling of *new, with parent newparent
+ */
static void insert_message(struct MuttThread **new,
struct MuttThread *newparent, struct MuttThread *cur)
{
return hash;
}
-/* thread by subject things that didn't get threaded by message-id */
+/**
+ * pseudo_threads - Thread messages by subject
+ *
+ * Thread by subject things that didn't get threaded by message-id
+ */
static void pseudo_threads(struct Context *ctx)
{
struct MuttThread *tree = ctx->tree, *top = tree;
}
}
-/* dir => true when moving forward, false when moving in reverse
- * subthreads => false when moving to next thread, true when moving to next subthread
+/**
+ * _mutt_aside_thread - Find the next/previous (sub)thread
+ * @param hdr Search from this message
+ * @param dir Direction to search: 'true' forwards, 'false' backwards
+ * @param subthreads Search subthreads: 'true' subthread, 'false' not
+ * @return index into the virtual email table
*/
int _mutt_aside_thread(struct Header *hdr, short dir, short subthreads)
{
}
-/* if flag is 0, we want to know how many messages
- * are in the thread. if flag is 1, we want to know
- * our position in the thread. */
+/**
+ * mutt_messages_in_thread - Count the messages in a thread
+ *
+ * If flag is 0, we want to know how many messages are in the thread.
+ * If flag is 1, we want to know our position in the thread.
+ */
int mutt_messages_in_thread(struct Context *ctx, struct Header *hdr, int flag)
{
struct MuttThread *threads[2];
return (enum UrlScheme) i;
}
-/* ciss_parse_userhost: fill in components of ciss with info from src. Note
- * these are pointers into src, which is altered with '\0's. Port of 0
- * means no port given. */
+/**
+ * ciss_parse_userhost - fill in components of ciss with info from src
+ *
+ * Note: These are pointers into src, which is altered with '\0's.
+ * Port of 0 means no port given.
+ */
static int ciss_parse_userhost(struct CissUrl *ciss, char *src)
{
char *t = NULL, *p = NULL;
-1;
}
-/* url_parse_ciss: Fill in CissUrl. char* elements are pointers into src,
- * which is modified by this call (duplicate it first if you need to). */
+/**
+ * url_parse_ciss - Fill in CissUrl.
+ *
+ * char* elements are pointers into src, which is modified by this call
+ * (duplicate it first if you need to).
+ */
int url_parse_ciss(struct CissUrl *ciss, char *src)
{
char *tmp = NULL;
*dst = 0;
}
-/* url_ciss_tostring: output the URL string for a given CISS object. */
+/**
+ * url_ciss_tostring - output the URL string for a given CISS object
+ */
int url_ciss_tostring(struct CissUrl *ciss, char *dest, size_t len, int flags)
{
long l;
projects / neomutt / commitdiff