/* make up a Url we can turn into a string */
mutt_account_tourl(account, &url);
- /*
- * mutt_account_tourl() just sets up some pointers;
+ /* mutt_account_tourl() just sets up some pointers;
* if this ever changes, we have a memleak here
*/
url.path = NULL;
/**
* destroy_state - Free the BrowserState
+ * @param state State to free
*
* Frees up the memory allocated for the local-global variables.
*/
/**
* browser_compare - Sort the items in the browser
+ * @param a First item
+ * @param b Second item
+ * @retval -1 a precedes b
+ * @retval 0 a and b are identical
+ * @retval 1 b precedes a
*
* 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
/**
* browser_sort - Sort the entries in the browser
+ * @param state Browser state
*
* Call to qsort using browser_compare function.
* Some specific sort methods are not used via NNTP.
}
/**
- * examine_directory - get list of all files/newsgroups with mask
+ * examine_directory - Get list of all files/newsgroups with mask
+ * @param menu Current Menu
+ * @param state State of browser
+ * @param d Directory
+ * @param prefix Files/newsgroups must match this prefix
+ * @retval 0 Success
+ * @retval -1 Error
*/
static int examine_directory(struct Menu *menu, struct BrowserState *state,
char *d, const char *prefix)
/**
* examine_mailboxes - Get list of mailboxes/subscribed newsgroups
+ * @param menu Current menu
+ * @param state State of browser
+ * @retval 0 Success
+ * @retval -1 Error
*/
static int examine_mailboxes(struct Menu *menu, struct BrowserState *state)
{
/**
* browser_highlight_default - Decide which browser item should be highlighted
+ * @param state Browser state
+ * @param menu Current Menu
*
* This function takes a menu and a state and defines the current entry that
* should be highlighted.
/**
* mutt_browser_select_dir - Remember the last directory selected
+ * @param f Directory name to save
*
* 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
/**
* parse_uncolor - Parse an 'uncolor' command
+ * @param buf Temporary Buffer space
+ * @param s Buffer containing string to be parsed
+ * @param data Flags associated with the command
+ * @param err Buffer for error messages
+ * @param parse_uncolor If true, 'uncolor', else 'unmono'
+ * @retval 0 Success
+ * @retval -1 Error
*
* usage:
* * uncolor index pattern [pattern...]
/**
* parse_color - Parse a "color" command
+ * @param buf Temporary Buffer space
+ * @param s Buffer containing string to be parsed
+ * @param err Buffer for error messages
+ * @param callback Function to handle command
+ * @param dry_run If true, test the command, but don't apply it
+ * @param color If true "color", else "mono"
+ * @retval 0 Success
+ * @retval -1 Error
*
* usage: color OBJECT FG BG [ REGEX ]
* mono OBJECT ATTR [ REGEX ]
/**
* pipe_message - Pipe message to a command
+ * @param h Header of email
+ * @param cmd Command to pipe to
+ * @param decode Should the message be decrypted
+ * @param print True if this is a print job
+ * @param split Should a separator be send between messages?
+ * @param sep Separator string
+ * @retval 0 Success
+ * @retval 1 Error
*
* The following code is shared between printing and piping.
*/
if (!addr)
return;
- /*
- * Note: We don't convert IDNA to local representation this time.
+ /* Note: We don't convert IDNA to local representation this time.
* That is intentional, so the user has an opportunity to copy &
* paste the on-the-wire form of the address to other, IDN-unable
* software.
/**
* mutt_save_message - Save an email
+ * @param h Header of email
+ * @param delete If true, delete the original (save)
+ * @param decode If true, decode the message
+ * @param decrypt If true, decrypt the message
* @retval 0 Copy/save was successful
* @retval -1 Error/abort
*/
mutt_message("NeoMutt %s%s", PACKAGE_VERSION, GitVer);
}
-/*
- * Returns:
- * 1 when a structural change is made.
- * recvattach requires this to know when to regenerate the actx.
- * 0 otherwise.
+/**
+ * mutt_edit_content_type - Edit the content type of an attachment
+ * @param h Header of email
+ * @param b Attachment
+ * @param fp File handle to the attachment
+ * @retval 1 A structural change is made
+ * @retval 0 Otherwise
+ *
+ * recvattach requires the return code to know when to regenerate the actx.
*/
int mutt_edit_content_type(struct Header *h, struct Body *b, FILE *fp)
{
return -1;
}
- /*
- * special case to handle when there is no filepart yet. find the first
+ /* special case to handle when there is no filepart yet. find the first
* file/directory which is not ``.'' or ``..''
*/
len = mutt_str_strlen(filepart);
ret = mutt_get_field(_("Send attachment with name: "), fname, sizeof(fname), MUTT_FILE);
if (ret == 0)
{
- /*
- * As opposed to RENAME_FILE, we don't check fname[0] because it's
- * valid to set an empty string here, to erase what was set
- */
+ /* As opposed to RENAME_FILE, we don't check fname[0] because it's
+ * valid to set an empty string here, to erase what was set
+ */
mutt_str_replace(&CURATTACH->content->d_filename, fname);
menu->redraw = REDRAW_CURRENT;
}
/**
* mutt_socket_free - remove connection from connection list and free it
+ * @param conn Connection to free
*/
void mutt_socket_free(struct Connection *conn)
{
/* update the total size of the mailbox to reflect this deletion */
Context->size -= body->length - new_length;
- /*
- * if the message is visible, update the visible size of the mailbox
- * as well.
- */
+ /* if the message is visible, update the visible size of the mailbox as well. */
if (Context->v2r[hdr->msgno] != -1)
Context->vsize -= body->length - new_length;
reno_ok = (expr = nl_langinfo(NOEXPR)) && (expr[0] == '^') &&
(REGCOMP(&reno, expr, REG_NOSUB) == 0);
- /*
- * In order to prevent the default answer to the question to wrapped
+ /* In order to prevent the default answer to the question to wrapped
* around the screen in the even the question is wider than the screen,
* ensure there is enough room for the answer and truncate the question
* to fit.
/**
* mutt_push_macro_event - Add the character/operation to the macro buffer
+ * @param ch Character to add
+ * @param op Operation to add
*
* Adds the ch/op to the macro buffer.
* This should be used for macros, push, and exec commands only.
/**
* mutt_addwch - addwch would be provided by an up-to-date curses library
+ * @param wc Wide char to display
+ * @retval 0 Success
+ * @retval -1 Error
*/
int mutt_addwch(wchar_t wc)
{
/**
* ci_first_message - Get index of first new message
+ * @retval num Index of first new message
*
* Return the index of the first new message, or failing that, the first
* unread message.
/**
* mx_toggle_write - Toggle the mailbox's readonly flag
+ * @param ctx Mailbox
+ * @retval 0 Success
+ * @retval -1 Error
*
* This should be in mx.c, but it only gets used here.
*/
/**
* mutt_index_menu - Display a list of emails
+ * @retval num How the menu was finished, e.g. OP_QUIT, OP_EXIT
*
* This function handles the message index window as well as commands returned
* from the pager (MENU_PAGER).
mutt_resize_screen();
SigWinch = 0;
menu->top = 0; /* so we scroll the right amount */
- /*
- * force a real complete redraw. clrtobot() doesn't seem to be able
+ /* force a real complete redraw. clrtobot() doesn't seem to be able
* to handle every case without this.
*/
clearok(stdscr, true);
else if (check == MUTT_NEW_MAIL || check == MUTT_REOPENED)
update_index(menu, Context, check, oc, index_hint);
- /*
- * do a sanity check even if mx_mbox_sync failed.
- */
+ /* do a sanity check even if mx_mbox_sync failed. */
if (menu->current < 0 || menu->current >= Context->vcount)
menu->current = ci_first_message();
CHECK_MSGCOUNT;
CHECK_VISIBLE;
- /*
- * toggle the weeding of headers so that a user can press the key
+ /* toggle the weeding of headers so that a user can press the key
* again while reading the message.
*/
if (op == OP_DISPLAY_HEADERS)
/* These Config Variables are only used in edit.c */
char *Escape;
-/*
- * SLcurses_waddnstr() can't take a "const char *", so this is only
+/* SLcurses_waddnstr() can't take a "const char *", so this is only
* declared "static" (sigh)
*/
static char *EditorHelp1 =
if (!*s)
return false;
- /*
- * some places have two timezone fields after the time, e.g.
+ /* some places have two timezone fields after the time, e.g.
* From xxxx@yyyyyyy.fr Wed Aug 2 00:39:12 MET DST 1995
*/
if (isalpha((unsigned char) *s))
* struct UrlQueryString - Parsed Query String
*
* The arguments in a URL are saved in a linked list.
- *
*/
struct UrlQueryString
{
ctx->changed = true;
}
#endif
- /*
- * If the user undeletes a message which is marked as
+ /* If the user undeletes a message which is marked as
* "trash" in the maildir folder on disk, the folder has
* been changed, and is marked accordingly. However, we do
* _not_ mark the message itself changed, because trashing
/**
* check_for_mailing_list_addr - Check an address list for a mailing list
+ * @param addr Address list
+ * @param buf Buffer for the result
+ * @param buflen Length of buffer
+ * @retval true Mailing list found
*
- * If one is found, print the address of the list into buf, then return 1.
- * Otherwise, simply return 0.
+ * If one is found, print the address of the list into buf.
*/
static bool check_for_mailing_list_addr(struct Address *addr, char *buf, int buflen)
{
/**
* user_is_recipient - Is the user a recipient of the message
+ * @param h Header of email to test
* @retval 0 User is not in list
* @retval 1 User is unique recipient
* @retval 2 User is in the TO list
/**
* imap_msg_close - Close an email
+ * @param ctx Mailbox
+ * @param msg Message to close
+ * @retval 0 Success
*
* @note May also return EOF Failure, see errno
*/
int n, b = 0, k = 0;
bool base64 = false;
- /*
- * In the worst case we convert 2 chars to 7 chars. For example:
+ /* In the worst case we convert 2 chars to 7 chars. For example:
* "\x10&\x10&..." -> "&ABA-&-&ABA-&-...".
*/
char *buf = mutt_mem_malloc((u8len / 2) * 7 + 6);
do
{
mutt_extract_token(buf, s, 0);
- /*
- * Check for deletion of entire list
- */
+ /* Check for deletion of entire list */
if (mutt_str_strcmp(buf->data, "*") == 0)
{
mutt_list_free((struct ListHead *) data);
do
{
mutt_extract_token(buf, s, 0);
- /*
- * Check for deletion of entire list
- */
+ /* Check for deletion of entire list */
if (mutt_str_strcmp(buf->data, "*") == 0)
{
mutt_list_free((struct ListHead *) data);
/**
* mbox_parse_mailbox - Read a mailbox from disk
+ * @param ctx Mailbox
+ * @retval 0 Success
+ * @retval -1 Error
+ * @retval -2 Aborted
*
* 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.
if ((tmploc > 0) && (tmploc < ctx->size))
{
- /*
- * check to see if the content-length looks valid. we expect to
+ /* check to see if the content-length looks valid. we expect to
* to see a valid message separator at this point in the stream
*/
if (fseeko(ctx->fp, tmploc, SEEK_SET) != 0 ||
loc = ftello(ctx->fp);
}
- /*
- * Only set the content-length of the previous message if we have read more
+ /* Only set the content-length of the previous message if we have read more
* than one message during _this_ invocation. If this routine is called
* when new mail is received, we need to make sure not to clobber what
* previously was the last message since the headers may be sorted.
unlock = 1;
}
- /*
- * Check to make sure that the only change to the mailbox is that
+ /* Check to make sure that the only change to the mailbox is that
* message(s) were appended to this file. My heuristic is that we should
* see the message separator at *exactly* what used to be the end of the
* folder.
/**
* mbox_reset_atime - Reset the access time on the mailbox file
+ * @param ctx Mailbox
+ * @param st Timestamp
*
* if mailbox has at least 1 new message, sets mtime > atime of mailbox so
* buffy check reports new mail
utimebuf.actime = st->st_atime;
utimebuf.modtime = st->st_mtime;
- /*
- * When $mbox_check_recent is set, existing new mail is ignored, so do not
+ /* When $mbox_check_recent is set, existing new mail is ignored, so do not
* reset the atime to mtime-1 to signal new mail.
*/
if (!MailCheckRecent && utimebuf.actime >= utimebuf.modtime && mbox_has_new(ctx))
{
if (!ctx->quiet)
mutt_progress_update(&progress, i, (int) (ftello(ctx->fp) / (ctx->size / 100 + 1)));
- /*
- * back up some information which is needed to restore offsets when
+ /* back up some information which is needed to restore offsets when
* something fails.
*/
/**
* mutt_menu_current_redraw - Redraw the current menu
*/
-void mutt_menu_current_redraw()
+void mutt_menu_current_redraw(void)
{
struct Menu *current_menu = get_current_menu();
if (current_menu)
#include "sendlib.h"
#include "state.h"
+/**
+ * mutt_get_tmp_attachment - Get a temporary copy of an attachment
+ * @param a Attachment to copy
+ * @retval 0 Success
+ * @retval -1 Error
+ */
int mutt_get_tmp_attachment(struct Body *a)
{
char type[STRING];
/**
* mutt_compose_attachment - Create an attachment
+ * @param a Body of email
* @retval 1 if require full screen redraw
* @retval 0 otherwise
*/
{
/* Use built-in handler */
OptViewAttach = true; /* disable the "use 'v' to view this part"
- * message in case of error */
+ * message in case of error */
if (mutt_decode_save_attachment(fp, a, pagerfile, MUTT_DISPLAY, 0))
{
OptViewAttach = false;
/**
* mutt_pipe_attachment - Pipe an attachment to a command
+ * @param fp File to pipe into the command
+ * @param b Attachment
+ * @param path Path to command
+ * @param outfile File to save output to
* @retval 1 Success
* @retval 0 Error
*/
if (outfile && *outfile)
close(out);
- /*
- * check for error exit from child process
- */
+ /* check for error exit from child process */
if (mutt_wait_filter(thepid) != 0)
rc = 0;
return rc;
}
+/**
+ * save_attachment_open - Open a file to write an attachment to
+ * @param path Path to file to open
+ * @param flags Flags, e.g. #MUTT_SAVE_APPEND
+ * @retval ptr File handle to attachment file
+ */
static FILE *save_attachment_open(char *path, int flags)
{
if (flags == MUTT_SAVE_APPEND)
/**
* mutt_decode_save_attachment - Decode, then save an attachment
+ * @param fp File to read from (OPTIONAL)
+ * @param m Attachment
+ * @param path Path to save the Attachment to
+ * @param displaying Flags, e.g. #MUTT_DISPLAY
+ * @param flags Flags, e.g. #MUTT_SAVE_APPEND
* @retval 0 Success
* @retval -1 Error
*/
/**
* mutt_print_attachment - Print out an attachment
+ * @param fp File to write to
+ * @param a Attachment
+ * @retval 1 Success
+ * @retval 0 Error
*
* Ok, the difference between send and receive:
* recv: Body->filename is a suggested name, and Context|Header points
b->d_filename = mutt_str_strdup(src->filename);
b->description = mutt_str_strdup(b->description);
- /*
- * we don't seem to need the Header structure currently.
- * XXX - this may change in the future
+ /* we don't seem to need the Header structure currently.
+ * XXX this may change in the future
*/
if (b->hdr)
/**
* label_message - add an X-Label: field
+ * @param[in] ctx Mailbox
+ * @param[in] hdr Header of email
+ * @param[out] new Set to true if this is a new label
+ * @retval true If the label was added
*/
static bool label_message(struct Context *ctx, struct Header *hdr, char *new)
{
#define MUTT_PARTS_TOPLEVEL (1 << 0) /* is the top-level part */
+/**
+ * mutt_parse_mime_message - Parse a MIME email
+ * @param ctx Mailbox
+ * @param cur Header of email
+ */
void mutt_parse_mime_message(struct Context *ctx, struct Header *cur)
{
struct Message *msg = NULL;
return false;
}
+/**
+ * count_body_parts - Count the MIME Body parts
+ * @param body Body of email
+ * @param flags Flags, e.g. #MUTT_PARTS_TOPLEVEL
+ * @retval num Number of MIME Body parts
+ */
static int count_body_parts(struct Body *body, int flags)
{
int count = 0;
return (count < 0) ? 0 : count;
}
+/**
+ * mutt_count_body_parts - Count the MIME Body parts
+ * @param ctx Mailbox
+ * @param hdr Header of email
+ * @retval num Number of MIME Body parts
+ */
int mutt_count_body_parts(struct Context *ctx, struct Header *hdr)
{
bool keep_parts = false;
/**
* need_display_subject - Determines whether to display a message's subject
+ * @param ctx Mailbox
+ * @param hdr Header of email
+ * @retval true If the subject should be displayed
*/
static int need_display_subject(struct Context *ctx, struct Header *hdr)
{
/**
* calculate_visibility - Are tree nodes visible
+ * @param ctx Mailbox
+ * @param max_depth Maximum depth to check
*
* 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
/**
* mutt_draw_tree - Draw a tree of threaded emails
+ * @param ctx Mailbox
*
* 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
/**
* pseudo_threads - Thread messages by subject
+ * @param ctx Mailbox
*
* Thread by subject things that didn't get threaded by message-id
*/
/**
* mutt_messages_in_thread - Count the messages in a thread
+ * @param ctx Mailbox
+ * @param hdr Header of email
+ * @param flag Flag, see notes below
+ * @retval num Number of message / Our position
*
* 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.
#include "mutt.h"
#include "globals.h"
+/**
+ * url_parse_mailto - Parse a mailto:// url
+ * @param[in] e Envelope to fill
+ * @param[out] body Body to
+ * @param[in] src String to parse
+ * @retval 0 Success
+ * @retval -1 Error
+ */
int url_parse_mailto(struct Envelope *e, char **body, const char *src)
{
char *p = NULL;
/**
* mutt_adv_mktemp - Advanced mktemp(3)
+ * @param s Buffer for result
+ * @param l Length of buffer
*
* 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
/**
* mutt_gecos_name - Lookup a user's real name in /etc/passwd
+ * @param dest Buffer for the result
+ * @param destlen Length of buffer
+ * @param pw Passwd entry
+ * @retval ptr Result buffer on success
*
* 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_pretty_mailbox - Shorten a mailbox path using '~' or '='
+ * @param s Buffer containing string to shorten
+ * @param buflen Length of buffer
*
* Collapse the pathname using ~ or = when possible
*/
/**
* mutt_check_overwrite - Ask the user if overwriting is necessary
+ * @param[in] attname Attachment name
+ * @param[in] path Path to save the file
+ * @param[out] fname Buffer for filename
+ * @param[out] flen Length of buffer
+ * @param[out] append Flags set to #MUTT_SAVE_APPEND or #MUTT_SAVE_OVERWRITE
+ * @param[out] directory Directory to save under (OPTIONAL)
* @retval 0 Success
* @retval -1 Abort
* @retval 1 Error
/**
* mutt_open_read - Run a command to read from
+ * @param[in] path Path to command
+ * @param[out] thepid PID of the command
+ * @retval ptr File containing output of command
*
* 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 (|),
/**
* mutt_save_confirm - Ask the user to save
+ * @param s Save location
+ * @param st Timestamp
* @retval 0 if OK to proceed
* @retval -1 to abort
* @retval 1 to retry
}
}
- /*
- * There is no point in asking whether or not to purge if we are
+ /* There is no point in asking whether or not to purge if we are
* just marking messages as "trash".
*/
if (ctx->deleted && !(ctx->magic == MUTT_MAILDIR && MaildirTrash))
/**
* crypt_current_time - Print the current time
+ * @param s State to use
+ * @param app_name App name, e.g. "PGP"
*
* print the current time to avoid spoofing of the signature output
*/
/**
* crypt_valid_passphrase - Check that we have a usable passphrase, ask if not
+ * @param flags Flags, e.g. #APPLICATION_PGP
+ * @retval 0 Success
+ * @retval -1 Failure
*/
int crypt_valid_passphrase(int flags)
{
/**
* mutt_is_malformed_multipart_pgp_encrypted - Check for malformed layout
+ * @param b Body of email
+ * @retval PGPENCRYPT Success
+ * @retval 0 Error
*
* This checks for the malformed layout caused by MS Exchange in
* some cases:
/**
* crypt_query - Check out the type of encryption used
+ * @param m Body of email
+ * @retval num Flags, e.g. #GOODSIGN
+ * @retval 0 Error
*
* Set the cached status values if there are any.
*/
/**
* crypt_write_signed - Write the message body/part
+ * @param a Body to write
+ * @param s State to use
+ * @param tempfile File to write to
+ * @retval 0 Success
+ * @retval -1 Error
*
* Body/part A described by state S to the given TEMPFILE.
*/
/**
* crypt_get_keys - Check we have all the keys we need
+ * @param[in] msg Message with addresses to match
+ * @param[out] keylist Keys needed
+ * @param[in] oppenc_mode If true, use opportunistic encryption
+ * @retval 0 Success
+ * @retval -1 Error
*
* Do a quick check to make sure that we can find all of the
* encryption keys if the user has requested this service.
/**
* crypt_opportunistic_encrypt - Can all recipients be determined
+ * @param msg Header of email
*
* Check if all recipients keys can be automatically determined.
* Enable encryption if they can, otherwise disable encryption.
/**
* mutt_signed_handler - Verify a "multipart/signed" body
+ * @param a Body to verify
+ * @param s State to use
+ * @retval 0 Success
+ * @retval -1 Error
*/
int mutt_signed_handler(struct Body *a, struct State *s)
{
/**
* crypt_is_numerical_keyid - Is this a numerical keyid
+ * @param s Key to test
+ * @retval true If keyid is numeric
*
* Check if a crypt-hook value is a key id.
*/
static gpgme_key_t signature_key = NULL;
static char *current_sender = NULL;
-/*
- * General helper functions.
- */
-
#define PKA_NOTATION_NAME "pka-address@gnupg.org"
static bool is_pka_notation(gpgme_sig_notation_t notation)
/**
* redraw_if_needed - accommodate for a redraw if needed
+ * @param ctx GPGME handle
*/
static void redraw_if_needed(gpgme_ctx_t ctx)
{
/**
* print_utf8 - Write a UTF-8 string to a file
+ * @param fp File to write to
+ * @param buf Buffer to read from
+ * @param len Length to read
*
- * Print the utf-8 encoded string BUF of length LEN bytes to stream FP. Convert
- * the character set.
+ * Convert the character set.
*/
static void print_utf8(FILE *fp, const char *buf, size_t len)
{
/**
* crypt_keyid - Find the ID for the key
+ * @param k Key to use
+ * @retval ptr ID string for the key
*
* Return the keyID for the key K.
* Note that this string is valid as long as K is valid
/**
* crypt_long_keyid - Find the Long ID for the key
+ * @param k Key to use
+ * @retval ptr Long ID string for the key
*
* Return the long keyID for the key K.
*/
}
/**
- * crypt_short_keyid - Get the short keyID for the key K
+ * crypt_short_keyid - Get the short keyID for a key
+ * @param k Key to use
+ * @retval ptr Short key string
*/
static const char *crypt_short_keyid(struct CryptKeyInfo *k)
{
}
/**
- * crypt_fpr - Get the hexstring fingerprint from the key K
+ * crypt_fpr - Get the hexstring fingerprint from a key
+ * @param k Key to use
+ * @retval ptr Hexstring fingerprint
*/
static const char *crypt_fpr(struct CryptKeyInfo *k)
{
/**
* crypt_key_abilities - Parse key flags into a string
+ * @param flags Flags, e.g. #KEYFLAG_CANENCRYPT
+ * @retval ptr Flag string
*
* Note: The string is statically allocated.
*/
/**
* crypt_flags - Parse the key flags into a single character
+ * @param flags Flags, e.g. #KEYFLAG_EXPIRED
+ * @retval char Flag character
*
* The returned character describes the most important flag.
*/
/**
* crypt_copy_key - Return a copy of KEY
+ * @param key Key to copy
+ * @retval ptr Copy of key
*/
static struct CryptKeyInfo *crypt_copy_key(struct CryptKeyInfo *key)
{
/**
* crypt_key_is_valid - Is the key valid
- * @retval true when key K is valid
+ * @param k Key to test
+ * @retval true If key is valid
*/
static bool crypt_key_is_valid(struct CryptKeyInfo *k)
{
/**
* crypt_id_is_strong - Is the key strong
- * @retval true when validity of KEY is sufficient
+ * @param key Key to test
+ * @retval true Validity of key is sufficient
*/
static int crypt_id_is_strong(struct CryptKeyInfo *key)
{
/**
* crypt_id_is_valid - Is key ID valid
- * ~return true when the KEY is valid, i.e. not marked as unusable
+ * @param key Key to test
+ * @retval true Key is valid
+ *
+ * When the key is not marked as unusable
*/
static int crypt_id_is_valid(struct CryptKeyInfo *key)
{
/**
* crypt_id_matches_addr - Does key ID match the address
+ * @param addr First email address
+ * @param u_addr Second email address
+ * @param key Key to use
+ * @retval num Flags, e.g. #CRYPT_KV_VALID
*
* Return a bit vector describing how well the addresses ADDR and U_ADDR match
* and whether KEY is valid.
return rc;
}
-/*
- * GPGME convenient functions.
- */
-
/**
* create_gpgme_context - Create a new GPGME context
* @param for_smime If true, protocol of the context is set to CMS
/**
* create_gpgme_data - Create a new GPGME data object
+ * @retval ptr GPGPE data object
*
* This is a wrapper to die on error.
+ *
+ * @note Call gpgme_data_release() to free the data object
*/
static gpgme_data_t create_gpgme_data(void)
{
/**
* 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.
+ * @param a Body to use
+ * @param convert If trye, lines are converted to CR-LF if required
+ * @retval ptr Newly created GPGME data object
*/
static gpgme_data_t body_to_data_object(struct Body *a, int convert)
{
/**
* 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.
+ * @param fp File to read from
+ * @param offset Offset to start reading from
+ * @param length Length of data to read
+ * @retval ptr Newly created GPGME data object
*/
static gpgme_data_t file_to_data_object(FILE *fp, long offset, size_t length)
{
/**
* data_object_to_stream - Write a GPGME data object to a file
+ * @param data GPGME data object
+ * @param fp File to write to
+ * @retval 0 Success
+ * @retval -1 Error
*/
static int data_object_to_stream(gpgme_data_t data, FILE *fp)
{
/**
* data_object_to_tempfile - Copy a data object to a temporary file
+ * @param[in] data GPGME data object
+ * @param[out] ret_fp Temporary file
+ * @retval ptr Name of temporary file
*
* If ret_fp is passed in, the file will be rewound, left open, and returned
* via that parameter.
- * The tempfile name is returned, and must be freed.
+ *
+ * @note The caller must free the returned file name
*/
static char *data_object_to_tempfile(gpgme_data_t data, FILE **ret_fp)
{
/**
* create_recipient_set - Create a GpgmeRecipientSet from a string of keys
- *
- * The keys must be space delimited.
+ * @param keylist Keys, space-separated
+ * @param protocol GPGME protocol
+ * @retval ptr GPGME key set
*/
static gpgme_key_t *create_recipient_set(const char *keylist, gpgme_protocol_t protocol)
{
/**
* set_signer - Make sure that the correct signer is set
- * @param ctx gpgme Context
+ * @param ctx GPGME handle
* @param for_smime Use S/MIME
* @retval 0 Success
* @retval -1 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
+ * @param plaintext GPGME data object with plain text message
+ * @param rset Set of recipients to encrypt to
+ * @param use_smime If true, use SMIME
+ * @param combined_signed If true, sign and encrypt the message (PGP only)
+ * @retval ptr Name of temporary file containing encrypted text
*/
static char *encrypt_gpgme_object(gpgme_data_t plaintext, gpgme_key_t *rset,
bool use_smime, bool combined_signed)
/**
* get_micalg - Find the "micalg" parameter from the last GPGME operation
+ * @param ctx GPGME handle
+ * @param use_smime If set, use SMIME instead of PGP
+ * @param buf Buffer for the result
+ * @param buflen Length of buffer
+ * @retval 0 Success
+ * @retval -1 Error
*
- * 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.
+ * Find the "Message Integrity Check algorithm" from the last GPGME operation.
+ * It is expected that this operation was a sign operation.
*/
static int get_micalg(gpgme_ctx_t ctx, int use_smime, char *buf, size_t buflen)
{
/**
* show_sig_summary - Show a signature summary
- * @retval 1 if there is is a severe warning
+ * @param sum Flags, e.g. GPGME_SIGSUM_KEY_REVOKED
+ * @param ctx GPGME handle
+ * @param key Set of keys
+ * @param idx Index into key set
+ * @param s State to use
+ * @param sig GPGME signature
+ * @retval 0 Success
+ * @retval 1 There is is a severe warning
*
* Display the common attributes of the signature summary SUM.
*/
/**
* show_one_sig_validity - Show the validity of a key used for one signature
+ * @param ctx GPGME handle
+ * @param idx Index of signature to check
+ * @param s State to use
*/
static void show_one_sig_validity(gpgme_ctx_t ctx, int idx, struct State *s)
{
/**
* show_one_sig_status - Show information about one signature
+ * @param ctx GPGME handle of a successful verification
+ * @param idx Index
+ * @param s State to use
* @retval 0 Normal procession
* @retval 1 A bad signature
* @retval 2 A signature with a warning
* @retval -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.
+ * The index 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)
{
/**
* decrypt_part - Decrypt a PGP or SMIME message
+ * @param[in] a Body of message
+ * @param[in] s State to use
+ * @param[in] fpout File to write to
+ * @param[in] is_smime True if an SMIME message
+ * @param[out] r_is_signed Flag, R_IS_SIGNED (PGP only)
+ * @retval ptr Newly allocated Body
*
- * (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
+ * 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.
*/
tattach = mutt_read_mime_header(fpout, 0);
if (tattach)
{
- /*
- * Need to set the length of this body part.
- */
+ /* Need to set the length of this body part. */
fstat(fileno(fpout), &info);
tattach->length = info.st_size - tattach->offset;
/**
* copy_clearsigned - Copy a clearsigned message
+ * @param data GPGME data object
+ * @param s State to use
+ * @param charset Charset of message
*
* strip the signature and PGP's dash-escaping.
*
gpgme_release(ctx);
}
- /*
- * Now, copy cleartext to the screen. NOTE - we expect that PGP
- * outputs utf-8 cleartext. This may not always be true, but it
- * seems to be a reasonable guess.
- */
-
+ /* Now, copy cleartext to the screen. NOTE - we expect that PGP
+ * outputs utf-8 cleartext. This may not always be true, but it
+ * seems to be a reasonable guess.
+ */
if (s->flags & MUTT_DISPLAY)
{
if (needpass)
s->fpin = savefp;
}
- /*
- * if a multipart/signed is the _only_ sub-part of a
- * multipart/encrypted, cache signature verification
- * status.
- */
+ /* if a multipart/signed is the _only_ sub-part of a multipart/encrypted,
+ * cache signature verification status.
+ */
if (mutt_is_multipart_signed(tattach) && !tattach->next)
{
a->goodsig = tattach->goodsig;
/**
* compare_key_address - Compare Key addresses and IDs for sorting
+ * @param a First key
+ * @param b Second key
+ * @retval -1 a precedes b
+ * @retval 0 a and b are identical
+ * @retval 1 b precedes a
*/
static int compare_key_address(const void *a, const void *b)
{
/**
* compare_keyid - Compare Key IDs and addresses for sorting
+ * @param a First key ID
+ * @param b Second key ID
+ * @retval -1 a precedes b
+ * @retval 0 a and b are identical
+ * @retval 1 b precedes a
*/
static int compare_keyid(const void *a, const void *b)
{
/**
* compare_key_date - Compare Key creation dates and addresses for sorting
+ * @param a First key
+ * @param b Second key
+ * @retval -1 a precedes b
+ * @retval 0 a and b are identical
+ * @retval 1 b precedes a
*/
static int compare_key_date(const void *a, const void *b)
{
/**
* compare_key_trust - Compare the trust of keys for sorting
+ * @param a First key
+ * @param b Second key
+ * @retval -1 a precedes b
+ * @retval 0 a and b are identical
+ * @retval 1 b precedes a
*
* Compare two trust values, the key length, the creation dates. the addresses
* and the key IDs.
/**
* print_dn_part - Print the X.500 Distinguished Name
+ * @param fp File to write to
+ * @param dn Distinguished Name
+ * @param key Key string
+ * @retval 1 If any DN keys match the given key string
+ * @retval 0 Otherwise
*
* Print the X.500 Distinguished Name part KEY from the array of parts DN to FP.
*/
/**
* print_dn_parts - Print all parts of a DN in a standard sequence
+ * @param fp File to write to
+ * @param dn Array of Distinguished Names
*/
static void print_dn_parts(FILE *fp, struct DnArray *dn)
{
}
/**
- * parse_dn_part - Parse an RDN; this is a helper to parse_dn()
+ * parse_dn_part - Parse an RDN
+ * @param array Array for results
+ * @param string String to parse
+ * @retval ptr First character after Distinguished Name
+ *
+ * This is a helper to parse_dn()
*/
static const char *parse_dn_part(struct DnArray *array, const char *string)
{
/**
* parse_dn - Parse a DN and return an array-ized one
+ * @param string String to parse
+ * @retval ptr Array of Distinguished Names
*
* 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_and_print_user_id - Print a nice representation of the userid
+ * @param fp File to write to
+ * @param userid String returned by GPGME key functions (utf-8 encoded)
*
* 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.
+ * parts for S/MIME's DNs.
*/
static void parse_and_print_user_id(FILE *fp, const char *userid)
{
/**
* print_key_info - Verbose information about a key or certificate to a file
+ * @param key Key to use
+ * @param fp File to write to
*/
static void print_key_info(gpgme_key_t key, FILE *fp)
{
/**
* verify_key - Show detailed information about the selected key
+ * @param key Key to show
*/
static void verify_key(struct CryptKeyInfo *key)
{
/**
* crypt_select_key - Get the user to select a key
+ * @param[in] keys List of keys to select from
+ * @param[in] p Address to match
+ * @param[in] s Real name to display
+ * @param[in] app Flags, e.g. #APPLICATION_PGP
+ * @param[out] forced_valid Set to true if user overrode key's validity
+ * @retval ptr Key selected by user
*
- * 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.
+ * Display a menu to select a key from the array of keys.
*/
static struct CryptKeyInfo *crypt_select_key(struct CryptKeyInfo *keys,
struct Address *p, const char *s,
}
else if (the_strong_valid_key && !multi)
{
- /*
- * There was precisely one strong match on a valid ID.
- *
- * Proceed without asking the user.
- */
+ /* There was precisely one strong match on a valid ID.
+ * Proceed without asking the user.
+ */
k = crypt_copy_key(the_strong_valid_key);
}
else
{
- /*
- * Else: Ask the user.
- */
+ /* Else: Ask the user. */
k = crypt_select_key(matches, a, NULL, app, forced_valid);
}
/**
* crypt_ask_for_key - Ask the user for a key
+ * @param[in] tag Prompt to display
+ * @param[in] whatfor Label to use (OPTIONAL)
+ * @param[in] abilities Flags, e.g. #KEYFLAG_CANSIGN
+ * @param[in] app Application type, e.g. #APPLICATION_PGP
+ * @param[out] forced_valid Set to true if user overrode key's validity
+ * @retval ptr Copy of the selected 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.
+ * If whatfor is not null use it as default and store it under that label as
+ * the next default.
*/
static struct CryptKeyInfo *crypt_ask_for_key(char *tag, char *whatfor, short abilities,
unsigned int app, int *forced_valid)
else
msg->security |= APPLICATION_PGP;
- /*
- * Opportunistic encrypt is controlling encryption.
+ /* Opportunistic encrypt is controlling encryption.
* NOTE: "Signing" and "Clearing" only adjust the sign bit, so we have different
* letter choices for those.
*/
choices = "SamCo";
}
}
- /*
- * Opportunistic encryption option is set, but is toggled off
- * for this message.
- */
+ /* Opportunistic encryption option is set, but is toggled off for this message. */
else if (CryptOpportunisticEncrypt)
{
if (is_smime)
choices = "esabmcO";
}
}
- /*
- * Opportunistic encryption is unset
- */
+ /* Opportunistic encryption is unset */
else
{
if (is_smime)
}
else
{
- /*
- * Assume address is 'mailbox@domainname'.
+ /* Assume address is 'mailbox@domainname'.
* The mailbox part is case-sensitive,
* the domainname is not. (RFC2821)
*/
*
* A type of a variable to keep track of registered crypto modules.
*/
+static STAILQ_HEAD(CryptModuleHead, CryptModule) CryptModules = STAILQ_HEAD_INITIALIZER(CryptModules);
struct CryptModule
{
struct CryptModuleSpecs *specs;
STAILQ_ENTRY(CryptModule) entries;
};
-static STAILQ_HEAD(, CryptModule) CryptModules = STAILQ_HEAD_INITIALIZER(CryptModules);
/**
* crypto_module_register - Register a new crypto module
+ * @param specs API functions
*/
void crypto_module_register(struct CryptModuleSpecs *specs)
{
/**
* crypto_module_lookup - Lookup a crypto module by name
+ * @param identifier Name, e.g. #APPLICATION_PGP
+ * @retval ptr Crypto module
*
- * Return the crypto module specs for IDENTIFIER.
* This function is usually used via the CRYPT_MOD_CALL[_CHECK] macros.
*/
struct CryptModuleSpecs *crypto_module_lookup(int identifier)
/**
* pgp_fpr_or_lkeyid - Get the fingerprint or long keyid
+ * @param k PGP key
+ * @retval ptr String fingerprint or long keyid
*
* Grab the longest key identifier available: fingerprint or else
* the long keyid.
/**
* pgp_copy_checksig - Copy PGP output and look for signs of a good signature
+ * @param fpin File to read from
+ * @param fpout File to write to
+ * @retval 0 Success
+ * @retval -1 Error
*/
static int pgp_copy_checksig(FILE *fpin, FILE *fpout)
{
/**
* pgp_check_decryption_okay - Check PGP output to look for successful outcome
+ * @param fpin File to read from
+ * @retval 0 Success
+ * @retval -1 Error
*
* Checks PGP output messages to look for the $pgp_decryption_okay message.
* This protects against messages with multipart/encrypted headers but which
return rc;
}
-/* Checks GnuPGP status fd output for various status codes indicating
+/**
+ * pgp_check_decryption_okay - Check GPG output for status codes
+ * @param fpin File to read from
+ * @retval 1 - no patterns were matched (if delegated to decryption_okay_regexp)
+ * @retval 0 - DECRYPTION_OKAY was seen, with no PLAINTEXT outside.
+ * @retval -1 - No decryption status codes were encountered
+ * @retval -2 - PLAINTEXT was encountered outside of DECRYPTION delimeters.
+ * @retval -3 - DECRYPTION_FAILED was encountered
+ *
+ * Checks GnuPGP status fd output for various status codes indicating
* an issue. If $pgp_check_gpg_decrypt_status_fd is unset, it falls
* back to the old behavior of just scanning for $pgp_decryption_okay.
*
* On the other hand, for pgp_application_pgp_handler(), a
* "BEGIN PGP MESSAGE" could indicate a signed and armored message.
* For that we allow -1 and -2 as "valid" (with a warning).
- *
- * Returns:
- * 1 - no patterns were matched (if delegated to decryption_okay_regexp)
- * 0 - DECRYPTION_OKAY was seen, with no PLAINTEXT outside.
- * -1 - No decryption status codes were encountered
- * -2 - PLAINTEXT was encountered outside of DECRYPTION delimeters.
- * -3 - DECRYPTION_FAILED was encountered
*/
static int pgp_check_decryption_okay(FILE *fpin)
{
/**
* pgp_copy_clearsigned - Copy a clearsigned message, stripping the signature
+ * @param fpin File to read from
+ * @param s State to use
+ * @param charset Charset of file
*
* 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
if (rc == 0)
have_any_sigs = true;
- /*
- * Sig is bad if
+ /* Sig is bad if
* gpg_good_sign-pattern did not match || pgp_decode_command returned not 0
* Sig _is_ correct if
* gpg_good_sign="" && pgp_decode_command returned 0
}
}
- /*
- * Now, copy cleartext to the screen.
- */
-
+ /* Now, copy cleartext to the screen. */
if (s->flags & MUTT_DISPLAY)
{
if (needpass)
mutt_ch_fgetconv_close(&fc);
}
- /*
- * Multiple PGP blocks can exist, so these need to be closed and
+ /* Multiple PGP blocks can exist, so these need to be closed and
* unlinked inside the loop.
*/
mutt_file_fclose(&tmpfp);
/**
* pgp_extract_keys_from_attachment - Extract pgp keys from messages/attachments
+ * @param fp File to read from
+ * @param top Top Attachment
*/
static void pgp_extract_keys_from_attachment(FILE *fp, struct Body *top)
{
tattach = mutt_read_mime_header(fpout, 0);
if (tattach)
{
- /*
- * Need to set the length of this body part.
- */
+ /* Need to set the length of this body part. */
fstat(fileno(fpout), &info);
tattach->length = info.st_size - tattach->offset;
/* See if we need to recurse on this MIME part. */
-
mutt_parse_part(fpout, tattach);
}
rc = mutt_body_handler(tattach, s);
s->fpin = fpin;
- /*
- * if a multipart/signed is the _only_ sub-part of a
+ /* if a multipart/signed is the _only_ sub-part of a
* multipart/encrypted, cache signature verification
* status.
- *
*/
-
if (mutt_is_multipart_signed(tattach) && !tattach->next)
a->goodsig |= tattach->goodsig;
fputc('\n', pgpin);
mutt_file_fclose(&pgpin);
- /*
- * Read back the PGP signature. Also, change MESSAGE=>SIGNATURE as
+ /* Read back the PGP signature. Also, change MESSAGE=>SIGNATURE as
* recommended for future releases of PGP.
*/
while (fgets(buffer, sizeof(buffer) - 1, pgpout) != NULL)
One of them will appear in each of the three strings marked "(inline"), below. */
mime_inline = _("(i)nline");
}
- /*
- * Opportunistic encrypt is controlling encryption. Allow to toggle
+ /* Opportunistic encrypt is controlling encryption. Allow to toggle
* between inline and mime, but not turn encryption on or off.
* NOTE: "Signing" and "Clearing" only adjust the sign bit, so we have different
* letter choices for those.
choices = "SaCo";
}
}
- /*
- * Opportunistic encryption option is set, but is toggled off
+ /* Opportunistic encryption option is set, but is toggled off
* for this message.
*/
else if (CryptOpportunisticEncrypt)
choices = "esabcO";
}
}
- /*
- * Opportunistic encryption is unset
- */
+ /* Opportunistic encryption is unset */
else
{
if (msg->security & (ENCRYPT | SIGN))
mutt_debug(2, "%s\n", buf);
}
-/*
- * Glue.
- */
-
static pid_t pgp_invoke(FILE **pgpin, FILE **pgpout, FILE **pgperr, int pgpinfd, int pgpoutfd,
int pgperrfd, bool need_passphrase, const char *fname,
const char *sig_fname, const char *ids, const char *format)
return key;
}
-/*
- * Format an entry on the PGP key selection menu.
- *
- * %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
- * %[...] date of key using strftime(3)
- */
-
/**
* struct PgpEntry - An entry in a PGP key menu
*/
struct PgpUid *uid;
};
+/**
+ * pgp_entry_fmt - Format an entry on the PGP key selection menu
+ * @param[out] buf Buffer in which to save string
+ * @param[in] buflen Buffer length
+ * @param[in] col Starting column
+ * @param[in] cols Number of screen columns
+ * @param[in] op printf-like operator, e.g. 't'
+ * @param[in] src printf-like format string
+ * @param[in] prec Field precision, e.g. "-3.4"
+ * @param[in] if_str If condition is met, display this string
+ * @param[in] else_str Otherwise, display this string
+ * @param[in] data Pointer to the mailbox Context
+ * @param[in] flags Format flags
+ * @retval src (unchanged)
+ *
+ * pgp_entry_fmt() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:--------------------------------------------------------
+ * | \%a | Algorithm
+ * | \%A | Algorithm of the princ. key
+ * | \%c | Capabilities
+ * | \%C | Capabilities of the princ. key
+ * | \%f | Flags
+ * | \%F | Flags of the princ. key
+ * | \%k | Key id
+ * | \%K | Key id of the principal key
+ * | \%l | Length
+ * | \%L | Length of the princ. key
+ * | \%n | Number
+ * | \%t | Trust/validity of the key-uid association
+ * | \%u | User id
+ * | \%[...] | Date of key using strftime(3)
+ */
static const char *pgp_entry_fmt(char *buf, size_t buflen, size_t col, int cols,
char op, const char *src, const char *prec,
const char *if_str, const char *else_str,
}
else if (the_strong_valid_key && !multi)
{
- /*
- * There was precisely one strong match on a valid ID.
- *
+ /* There was precisely one strong match on a valid ID.
* Proceed without asking the user.
*/
pgp_remove_key(&matches, the_strong_valid_key);
}
else
{
- /*
- * Else: Ask the user.
- */
+ /* Else: Ask the user. */
k = pgp_select_key(matches, a, NULL);
if (k)
pgp_remove_key(&matches, k);
}
}
-/* return values:
-
- * 1 = sign only
- * 2 = encrypt only
- * 3 = both
- */
-
short pgp_get_abilities(unsigned char type)
{
return (pgp_canencrypt(type) << 1) | pgp_cansign(type);
/**
* fmt_smime_command - Format an SMIME command
+ * @param[out] buf Buffer in which to save string
+ * @param[in] buflen Buffer length
+ * @param[in] col Starting column
+ * @param[in] cols Number of screen columns
+ * @param[in] op printf-like operator, e.g. 't'
+ * @param[in] src printf-like format string
+ * @param[in] prec Field precision, e.g. "-3.4"
+ * @param[in] if_str If condition is met, display this string
+ * @param[in] else_str Otherwise, display this string
+ * @param[in] data Pointer to the mailbox Context
+ * @param[in] flags Format flags
+ * @retval src (unchanged)
*
* This is almost identical to pgp's invoking interface.
+ *
+ * fmt_smime_command() is a callback function for mutt_expando_format().
+ *
+ * | Expando | Description
+ * |:--------|:-----------------------------------------------------------------
+ * | \%a | Algorithm used for encryption
+ * | \%C | CA location: Depending on whether $smime_ca_location points to a directory or file
+ * | \%c | One or more certificate IDs
+ * | \%d | Message digest algorithm specified with $smime_sign_digest_alg
+ * | \%f | File containing a message
+ * | \%i | Intermediate certificates
+ * | \%k | The key-pair specified with $smime_default_key
+ * | \%s | File containing the signature part of a multipart/signed attachment when verifying it
*/
static const char *fmt_smime_command(char *buf, size_t buflen, size_t col, int cols,
char op, const char *src, const char *prec,
/**
* smime_get_key_by_hash - Find a key by its hash
+ * @param hash Hash to find
+ * @param public If true, only get the public keys
+ * @retval ptr Matching key
*
* Returns the first matching key record, without prompting or checking of
* abilities or trust.
/**
* getkeys - Get the keys for a mailbox
+ * @param mailbox Email address
*
* This sets the '*ToUse' variables for an upcoming decryption, where the
* required key is different from SmimeDefaultKey.
/**
* openssl_md_to_smime_micalg - Change the algorithm names
+ * @param md OpenSSL message digest name
+ * @retval ptr SMIME Message Integrity Check algorithm
*
* 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
+ *
+ * @note The caller should free the returned string
*/
static char *openssl_md_to_smime_micalg(char *md)
{
/**
* smime_handle_entity - Handle type application/pkcs7-mime
+ * @param m Body to handle
+ * @param s State to use
+ * @param out_file File for the result
+ * @retval ptr Body for parsed MIME part
*
* This can either be a signed or an encrypted message.
*/
msg->security |= APPLICATION_SMIME;
- /*
- * Opportunistic encrypt is controlling encryption.
+ /* Opportunistic encrypt is controlling encryption.
* NOTE: "Signing" and "Clearing" only adjust the sign bit, so we have different
* letter choices for those.
*/
letters = _("swaco");
choices = "SwaCo";
}
- /*
- * Opportunistic encryption option is set, but is toggled off
+ /* Opportunistic encryption option is set, but is toggled off
* for this message.
*/
else if (CryptOpportunisticEncrypt)
letters = _("eswabco");
choices = "eswabcO";
}
- /*
- * Opportunistic encryption is unset
- */
+ /* Opportunistic encryption is unset */
else
{
/* L10N: S/MIME options */
h->data = mutt_mem_calloc(1, sizeof(struct NmHdrData));
h->free_cb = deinit_header;
- /*
- * Notmuch ensures that message Id exists (if not notmuch Notmuch will
+ /* Notmuch ensures that message Id exists (if not notmuch Notmuch will
* generate an ID), so it's more safe than use neomutt Header->env->id
*/
((struct NmHdrData *) h->data)->virtual_id = mutt_str_strdup(id);
if (trans < 0)
return -1;
- /*
- * note that unlink() is probably unnecessary here, it's already removed
+ /* note that unlink() is probably unnecessary here, it's already removed
* by mh_sync_mailbox_message(), but for sure...
*/
st = notmuch_database_remove_message(db, path);
/**
* trim_incomplete_mbyte - Remove an incomplete character
+ * @param buf Buffer containing string
+ * @param len Length of buffer
+ * @retval num Number of bytes remaining
*
* trim tail of buf so that it contains complete multibyte characters
*/
if (special || (col != pager_window->cols && (flags & (MUTT_SHOWCOLOR | MUTT_SEARCH))))
resolve_color(*line_info, n, vch, flags, 0, &a);
- /*
- * Fill the blank space at the end of the line with the prevailing color.
+ /* Fill the blank space at the end of the line with the prevailing color.
* ncurses does an implicit clrtoeol() when you do addch('\n') so we have
* to make sure to reset the color *after* that
*/
if (col < pager_window->cols)
mutt_window_clrtoeol(pager_window);
- /*
- * reset the color back to normal. This *must* come after the
+ /* reset the color back to normal. This *must* come after the
* clrtoeol, otherwise the color for this line will not be
* filled to the right margin.
*/
/**
* mutt_pager - Display a file, or help, in a window
+ * @param banner Title to display in status bar
+ * @param fname Name of file to read
+ * @param flags Flags, e.g. #MUTT_SHOWCOLOR
+ * @param extra Info about email to display
+ * @retval 0 Success
+ * @retval -1 Error
*
* 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
char *uidl = mutt_str_strdup(ctx->hdrs[i]->data);
int refno = ctx->hdrs[i]->refno;
int index = ctx->hdrs[i]->index;
- /*
- * - POP dynamically numbers headers and relies on h->refno
+ /* - POP dynamically numbers headers and relies on h->refno
* to map messages; so restore header and overwrite restored
* refno with current refno, same for index
* - h->data needs to a separate pointer as it's driver-specific
}
#endif
- /*
- * faked support for flags works like this:
+ /* faked support for flags works like this:
* - if 'hcached' is true, we have the message in our hcache:
* - if we also have a body: read
* - if we don't have a body: old
if (msg->fp)
return 0;
- /*
- * see if we already have the message in our cache in
+ /* see if we already have the message in our cache in
* case $message_cachedir is unset
*/
cache = &pop_data->cache[h->index % POP_CACHE_LEN];
/**
* pop_fetch_data - Read Headers with callback function
+ * @param pop_data POP data
+ * @param query POP query to send to server
+ * @param progressbar Progress bar
+ * @param funct Function called for each header read
+ * @param data Data to pass to the callback
* @retval 0 Successful
* @retval -1 Connection lost
* @retval -2 Invalid command or execution error
mutt_clear_error();
}
- /*
- * remove a potential multipart/signed layer - useful when
+ /* remove a potential multipart/signed layer - useful when
* resending messages
*/
-
if ((WithCrypto != 0) && mutt_is_multipart_signed(newhdr->content))
{
newhdr->security |= SIGN;
newhdr->content = mutt_remove_multipart(newhdr->content);
}
- /*
- * We don't need no primary multipart.
+ /* We don't need no primary multipart.
* Note: We _do_ preserve messages!
*
* XXX - we don't handle multipart/alternative in any
* smart way when sending messages. However, one may
* consider this a feature.
- *
*/
-
if (newhdr->content->type == TYPE_MULTIPART)
newhdr->content = mutt_remove_multipart(newhdr->content);
*
* If percent is -1, then the percentage will be calculated using pos and the
* size in progress.
+ *
+ * If percent is positive, it is displayed as percentage, otherwise
+ * percentage is calculated from progress->size and pos if progress
+ * was initialized with positive size, otherwise no percentage is shown
*/
void mutt_progress_update(struct Progress *progress, long pos, int percent)
{
void mutt_progress_init(struct Progress *progress, const char *msg,
unsigned short flags, unsigned short inc, size_t size);
-/* If percent is positive, it is displayed as percentage, otherwise
- * percentage is calculated from progress->size and pos if progress
- * was initialized with positive size, otherwise no percentage is shown */
void mutt_progress_update(struct Progress *progress, long pos, int percent);
#endif /* _MUTT_PROGRESS_H */
return op;
}
+/**
+ * mutt_generate_recvattach_list - Create a list of attachments
+ * @param actx Attachment context
+ * @param hdr Header of the email
+ * @param m Body of email
+ * @param fp File to read from
+ * @param parent_type Type, e.g. #TYPE_MULTIPART
+ * @param level Attachment depth
+ * @param decrypted True if attachment has been decrypted
+ */
static void mutt_generate_recvattach_list(struct AttachCtx *actx, struct Header *hdr,
struct Body *m, FILE *fp,
int parent_type, int level, int decrypted)
}
}
+/**
+ * mutt_attach_init - Create a new Attachment context
+ * @param actx Attachment context
+ */
void mutt_attach_init(struct AttachCtx *actx)
{
/* Collapse the attachments if '$digest_collapse' is set AND if...
}
}
+/**
+ * mutt_update_recvattach_menu - Update the Attachment Menu
+ * @param actx Attachment context
+ * @param menu Menu listing Attachments
+ * @param init If true, create a new Attachments context
+ */
static void mutt_update_recvattach_menu(struct AttachCtx *actx, struct Menu *menu, bool init)
{
if (init)
/**
* check_msg - Are we working with an RFC822 message
+ * @param b Body of email
+ * @param err If true, display a message if this isn't an RFC822 message
+ * @retval true This is an RFC822 message
*
* some helper functions to verify that we are exclusively operating on
* message/rfc822 attachments
}
/**
- * check_can_decode - can we decode all tagged attachments?
+ * check_can_decode - Can we decode all tagged attachments?
+ * @param actx Attachment context
+ * @param cur Body of email
+ * @retval true All tagged attachments are decodable
*/
static bool check_can_decode(struct AttachCtx *actx, struct Body *cur)
{
/**
* count_tagged_children - tagged children below a multipart/message attachment
+ * @param actx Attachment context
+ * @param i Index of first attachment
+ * @retval num Number of tagged attachments
*/
static short count_tagged_children(struct AttachCtx *actx, short i)
{
/**
* mutt_attach_bounce - Bounce function, from the attachment menu
+ * @param fp Handle of message
+ * @param actx Attachment context
+ * @param cur Body of email
*/
void mutt_attach_bounce(FILE *fp, struct AttachCtx *actx, struct Body *cur)
{
mutt_addr_write(buf, sizeof(buf), addr, true);
#define EXTRA_SPACE (15 + 7 + 2)
- /*
- * See commands.c.
- */
+ /* See commands.c. */
snprintf(prompt, sizeof(prompt) - 4,
ngettext("Bounce message to %s", "Bounce messages to %s", p), buf);
/**
* mutt_attach_resend - resend-message, from the attachment menu
+ * @param fp File containing email
+ * @param actx Attachment context
+ * @param cur Attachment
*/
void mutt_attach_resend(FILE *fp, struct AttachCtx *actx, struct Body *cur)
{
/**
* find_common_parent - find a common parent message for the tagged attachments
+ * @param actx Attachment context
+ * @param nattach Number of tagged attachments
+ * @retval ptr Parent attachment
+ * @retval NULL Failure, no common parent
*/
static struct AttachPtr *find_common_parent(struct AttachCtx *actx, short nattach)
{
/**
* is_parent - Check whether one attachment is the parent of another
+ * @param i Index of parent Attachment
+ * @param actx Attachment context
+ * @param cur Potential child Attachemnt
+ * @retval true Attachment
*
* check whether attachment i is a parent of the attachment pointed to by cur
*
/**
* copy_problematic_attachments - Attach the body parts which can't be decoded
+ * @param[out] last Body pointer to update
+ * @param[in] actx Attachment context
+ * @param[in] force If true, attach parts that can't be decoded
+ * @retval ptr Pointer to last Body part
*
* This code is shared by forwarding and replying.
*/
/**
* attach_forward_bodies - forward one or several MIME bodies
+ * @param fp File to read from
+ * @param hdr Header of email
+ * @param actx Attachment Context
+ * @param cur Body of email
+ * @param nattach Number of tagged attachments
*
* (non-message types)
*/
char prefix[STRING];
int rc = 0;
- /*
- * First, find the parent message.
+ /* First, find the parent message.
* Note: This could be made an option by just
* putting the following lines into an if block.
*/
-
struct AttachPtr *parent = find_parent(actx, cur, nattach);
if (parent)
{
include_header(ForwardQuote, parent_fp, parent_hdr, tmpfp, prefix);
- /*
- * Now, we have prepared the first part of the message body: The
+ /* Now, we have prepared the first part of the message body: The
* original message's header.
*
* The next part is more interesting: either include the message bodies,
* or attach them.
*/
-
if ((!cur || mutt_can_decode(cur)) &&
(rc = query_quadoption(MimeForward, _("Forward as attachments?"))) == MUTT_YES)
{
goto bail;
}
- /*
- * shortcut MIMEFWDREST when there is only one attachment. Is
- * this intuitive?
+ /* shortcut MIMEFWDREST when there is only one attachment.
+ * Is this intuitive?
*/
-
if (!mime_fwd_all && !cur && (nattach > 1) && !check_can_decode(actx, cur))
{
rc = query_quadoption(
/**
* attach_forward_msgs - Forward one or several message-type attachments
+ * @param fp File handle to attachment
+ * @param actx Attachment Context
+ * @param cur Attachment to forward (OPTIONAL)
+ * @param flags Send mode, e.g. #SEND_RESEND
*
* This is different from the previous function since we want to mimic the
* index menu's behavior.
/**
* attach_reply_envelope_defaults - Create the envelope defaults for a reply
+ * @param env Envelope to fill in
+ * @param actx Attachment Context
+ * @param parent Header of parent email
+ * @param flags Flags, e.g. #SEND_LIST_REPLY
+ * @retval 0 Success
+ * @retval -1 Error
*
* This function can be invoked in two ways.
*
/**
* attach_include_reply - This is _very_ similar to send.c's include_reply()
+ * @param fp File handle to attachment
+ * @param tmpfp File handle to temporary file
+ * @param cur Header of email
*/
static void attach_include_reply(FILE *fp, FILE *tmpfp, struct Header *cur)
{
/**
* mix_type2_list - parse the type2.list as given by mixmaster -T
+ * @param[out] l Length of list
+ * @retval ptr type2.list
*/
static struct Remailer **mix_type2_list(size_t *l)
{
/**
* mix_check_message - Safety-check the message before passing it to mixmaster
+ * @param msg Header of email
+ * @retval 0 Success
+ * @retval -1 Error
*/
int mix_check_message(struct Header *msg)
{
#endif
#endif
+/**
+ * mutt_get_winsize - Use an ioctl to get the window size
+ * @retval obj Window size
+ */
struct winsize mutt_get_winsize(void)
{
struct winsize w = { 0 };
}
#ifdef USE_SLANG_CURSES
+/**
+ * mutt_resize_screen - Update NeoMutt's opinion about the window size (SLANG)
+ */
void mutt_resize_screen(void)
{
struct winsize w = mutt_get_winsize();
mutt_window_reflow();
}
#else
+/**
+ * mutt_resize_screen - Update NeoMutt's opinion about the window size (CURSES)
+ */
void mutt_resize_screen(void)
{
struct winsize w = mutt_get_winsize();
}
else if (mutt_str_strncasecmp(field, "test", 4) == 0)
{
- /*
- * This routine executes the given test command to determine
+ /* This routine executes the given test command to determine
* if this is the right entry.
*/
char *test_command = NULL;
/**
* space_quotes - Should we add spaces between quote levels
+ * @param s State to use
+ * @retval true If spaces should be added
*
* Determines whether to add spacing between/after each quote level:
* ` >>>foo`
/**
* add_quote_suffix - Should we add a trailing space to quotes
+ * @param s State to use
+ * @param ql Quote level
+ * @retval true If spaces should be added
*
* Determines whether to add a trailing space to quotes:
* ` >>> foo`
/**
* quote_width - Calculate the paragraph width based upon the quote level
+ * @param s State to use
+ * @param ql Quote level
+ * @retval int Paragraph width
*
* The start of a quoted line will be ">>> ", so we need to subtract the space
* required for the prefix from the terminal width.
}
/**
- * rfc3676_handler - body handler implementing RFC3676 for format=flowed
+ * rfc3676_handler - Body handler implementing RFC3676 for format=flowed
+ * @param a Body to handle
+ * @param s State to use
+ * @retval 0 Always
*/
int rfc3676_handler(struct Body *a, struct State *s)
{
/**
* rfc3676_space_stuff - Perform required RFC3676 space stuffing
+ * @param hdr Header of email
*
* Space stuffing means that we have to add leading spaces to
* certain lines:
bool SigOnTop;
bool UseFrom;
+/**
+ * append_signature - Append a signature to an email
+ * @param f File to write to
+ */
static void append_signature(FILE *f)
{
FILE *tmpfp = NULL;
return top;
}
+/**
+ * edit_address - Edit an email address
+ * @param a Address to edit
+ * @param field Prompt for user
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int edit_address(struct Address **a, /* const */ char *field)
{
char buf[HUGE_STRING];
}
#endif
+/**
+ * process_user_recips - Process the user headers
+ * @param env Envelope to populate
+ */
static void process_user_recips(struct Envelope *env)
{
struct ListNode *uh = NULL;
}
}
+/**
+ * process_user_header - Process the user headers
+ * @param env Envelope to populate
+ */
static void process_user_header(struct Envelope *env)
{
struct ListNode *uh = NULL;
}
}
+/**
+ * mutt_forward_intro - Add the "start of forwarded message" text
+ * @param ctx Mailbox
+ * @param cur Header of email
+ * @param fp File to write to
+ */
void mutt_forward_intro(struct Context *ctx, struct Header *cur, FILE *fp)
{
if (!ForwardAttributionIntro || !fp)
fputs("\n\n", fp);
}
+/**
+ * mutt_forward_trailer - Add a "end of forwarded message" text
+ * @param ctx Mailbox
+ * @param cur Header of email
+ * @param fp File to write to
+ */
void mutt_forward_trailer(struct Context *ctx, struct Header *cur, FILE *fp)
{
if (!ForwardAttributionTrailer || !fp)
fputc('\n', fp);
}
+/**
+ * include_forward - Write out a forwarded message
+ * @param ctx Mailbox
+ * @param cur Header of email
+ * @param out File to write to
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int include_forward(struct Context *ctx, struct Header *cur, FILE *out)
{
int chflags = CH_DECODE, cmflags = 0;
return 0;
}
+/**
+ * mutt_make_attribution - Add "on DATE, PERSON wrote" header
+ * @param ctx Mailbox
+ * @param cur Header of email
+ * @param out File to write to
+ */
void mutt_make_attribution(struct Context *ctx, struct Header *cur, FILE *out)
{
if (!Attribution || !out)
fputc('\n', out);
}
+/**
+ * mutt_make_post_indent - Add suffix to replied email text
+ * @param ctx Mailbox
+ * @param cur Header of email
+ * @param out File to write to
+ */
void mutt_make_post_indent(struct Context *ctx, struct Header *cur, FILE *out)
{
if (!PostIndentString || !out)
fputc('\n', out);
}
+/**
+ * include_reply - Generate the reply text for an email
+ * @param ctx Mailbox
+ * @param cur Header of email
+ * @param out File to write to
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int include_reply(struct Context *ctx, struct Header *cur, FILE *out)
{
int cmflags = MUTT_CM_PREFIX | MUTT_CM_DECODE | MUTT_CM_CHARCONV | MUTT_CM_REPLYING;
return 0;
}
+/**
+ * default_to - Generate default email addresses
+ * @param to 'To' address
+ * @param env Envelope to populate
+ * @param flags Flags, e.g. #SEND_LIST_REPLY
+ * @param hmfupto If true, add 'followup-to' address to 'to' address
+ * @retval 0 Success
+ * @retval -1 Aborted
+ */
static int default_to(struct Address **to, struct Envelope *env, int flags, int hmfupto)
{
char prompt[STRING];
return 0;
}
+/**
+ * mutt_fetch_recips - Generate recpients for a reply email
+ * @param out Envelope to populate
+ * @param in Envelope of source email
+ * @param flags Flags, e.g. SENDLISTREPLY
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int mutt_fetch_recips(struct Envelope *out, struct Envelope *in, int flags)
{
struct Address *tmp = NULL;
}
}
+/**
+ * mutt_fix_reply_recipients - Remove duplicate recipients
+ * @param env Envelope to fix
+ */
void mutt_fix_reply_recipients(struct Envelope *env)
{
if (!Metoo)
}
}
+/**
+ * mutt_make_forward_subject - Create a subject for a forwarded email
+ * @param env Envelope for result
+ * @param ctx Mailbox
+ * @param cur Header of email
+ */
void mutt_make_forward_subject(struct Envelope *env, struct Context *ctx, struct Header *cur)
{
if (!env)
mutt_str_replace(&env->subject, buffer);
}
+/**
+ * mutt_make_misc_reply_headers - Set subject for a reply
+ * @param env Envelope for result
+ * @param curenv Envelope of source email
+ */
void mutt_make_misc_reply_headers(struct Envelope *env, struct Envelope *curenv)
{
if (!env || !curenv)
env->subject = mutt_str_strdup(EmptySubject);
}
+/**
+ * mutt_add_to_reference_headers - Generate references for a reply email
+ * @param env Envelope for result
+ * @param curenv Envelope of source email
+ */
void mutt_add_to_reference_headers(struct Envelope *env, struct Envelope *curenv)
{
add_references(&env->references, curenv);
#endif
}
+/**
+ * make_reference_headers - Generate reference headers for an email
+ * @param curenv Envelope of source email
+ * @param env Envelope for result
+ * @param ctx Mailbox
+ */
static void make_reference_headers(struct Envelope *curenv,
struct Envelope *env, struct Context *ctx)
{
}
}
+/**
+ * envelope_defaults - Fill in some defaults for a new email
+ * @param env Envelope for result
+ * @param ctx Mailbox
+ * @param cur Header of email
+ * @param flags Flags, e.g. #SEND_REPLY
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int envelope_defaults(struct Envelope *env, struct Context *ctx,
struct Header *cur, int flags)
{
return 0;
}
+/**
+ * mutt_set_followup_to - Set followup-to field
+ * @param e Envelope to modify
+ */
void mutt_set_followup_to(struct Envelope *e)
{
struct Address *t = NULL;
struct Address *from = NULL;
- /*
- * Only generate the Mail-Followup-To if the user has requested it, and
+ /* Only generate the Mail-Followup-To if the user has requested it, and
* it hasn't already been set
*/
/**
* mutt_encode_descriptions - rfc2047 encode the content-descriptions
+ * @param b Body of email
+ * @param recurse If true, encode children parts
*/
void mutt_encode_descriptions(struct Body *b, short recurse)
{
/**
* decode_descriptions - rfc2047 decode them in case of an error
+ * @param b MIME parts to decode
*/
static void decode_descriptions(struct Body *b)
{
}
}
+/**
+ * fix_end_of_file - Ensure a file ends with a linefeed
+ * @param data Name of file to fix
+ */
static void fix_end_of_file(const char *data)
{
FILE *fp = mutt_file_fopen(data, "a+");
return ci_send_message(0, msg, NULL, NULL, NULL);
}
+/**
+ * mutt_resend_message - Resend an email
+ * @param fp File containing email
+ * @param ctx Mailbox
+ * @param cur Header of email to resend
+ * @retval 0 Message was successfully sent
+ * @retval -1 Message was aborted or an error occurred
+ * @retval 1 Message was postponed
+ */
int mutt_resend_message(FILE *fp, struct Context *ctx, struct Header *cur)
{
struct Header *msg = mutt_header_new();
}
}
+/**
+ * mutt_write_mime_header - Create a MIME header
+ * @param a Body part
+ * @param f File to write to
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int mutt_write_mime_header(struct Body *a, FILE *f)
{
fprintf(f, "Content-Type: %s/%s", TYPE(a), a->subtype);
bool was_cr;
};
+/**
+ * update_content_info - Cache some info about an email
+ * @param info Info about an Attachment
+ * @param s Info about the Body of an email
+ * @param buf Buffer for the result
+ * @param buflen Length of the buffer
+ */
static void update_content_info(struct Content *info, struct ContentState *s,
char *buf, size_t buflen)
{
/**
* convert_file_from_to - Convert a file between encodings
+ * @param[in] file File to read from
+ * @param[in] fromcodes Charsets to try converting FROM
+ * @param[in] tocodes Charsets to try converting TO
+ * @param[out] fromcode From charset selected
+ * @param[out] tocode To charset selected
+ * @param[out] info Info about the file
+ * @retval num Characters converted
+ * @retval -1 Error (as a size_t)
*
* 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
/**
* set_encoding - determine which Content-Transfer-Encoding to use
+ * @param[in] b Body of email
+ * @param[out] info Info about the email
*/
static void set_encoding(struct Body *b, struct Content *info)
{
/**
* check_boundary - check for duplicate boundary
+ * @param boundary Boundary to look for
+ * @param b Body parts to check
* @retval true if duplicate found
*/
static bool check_boundary(const char *boundary, struct Body *b)
/**
* mutt_write_address_list - wrapper around mutt_write_address()
+ * @param addr Address list
+ * @param fp File to write to
+ * @param linelen Line length to use
+ * @param display True if these addresses will be displayed to the user
*
* So we can handle very large recipient lists without needing a huge temporary
* buffer in memory
FREE(&ref);
}
+/**
+ * print_val - Add pieces to an email header, wrapping where necessary
+ * @param fp File to write to
+ * @param pfx Prefix for headers
+ * @param value Text to be added
+ * @param flags Flags, e.g. #CH_DISPLAY
+ * @param col Column that this text starts at
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int print_val(FILE *fp, const char *pfx, const char *value, int flags, size_t col)
{
while (value && *value)
return 0;
}
+/**
+ * fold_one_header - Fold one header line
+ * @param fp File to write to
+ * @param tag Header key, e.g. "From"
+ * @param value Header value
+ * @param pfx Prefix for header
+ * @param wraplen Column to wrap at
+ * @param flags Flags, e.g. #CH_DISPLAY
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int fold_one_header(FILE *fp, const char *tag, const char *value,
const char *pfx, int wraplen, int flags)
{
* even none) on a line if the trailing spaces are located at our
* current line width
* XXX this covers ASCII space only, for display we probably
- * XXX want something like iswspace() here */
+ * want something like iswspace() here */
const char *sp = next;
while (*sp && (*sp == ' ' || *sp == '\t'))
sp++;
return s;
}
+/**
+ * write_one_header - Write out one header line
+ * @param fp File to write to
+ * @param pfxw Width of prefix string
+ * @param max Max width
+ * @param wraplen Column to wrap at
+ * @param pfx Prefix for header
+ * @param start Start of header line
+ * @param end End of header line
+ * @param flags Flags, e.g. #CH_DISPLAY
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int write_one_header(FILE *fp, int pfxw, int max, int wraplen, const char *pfx,
const char *start, const char *end, int flags)
{
/**
* mutt_write_one_header - Write one header line to a file
+ * @param fp File to write to
+ * @param tag Header key, e.g. "From"
+ * @param value Header value
+ * @param pfx Prefix for header
+ * @param wraplen Column to wrap at
+ * @param flags Flags, e.g. #CH_DISPLAY
+ * @retval 0 Success
+ * @retval -1 Failure
*
* split several headers into individual ones and call write_one_header
* for each one
return rc;
}
-/* Note: all RFC2047 encoding should be done outside of this routine, except
+/**
+ * mutt_rfc822_write_header - Write out one RFC822 header line
+ * @param fp File to write to
+ * @param env Envelope of email
+ * @param attach Attachment
+ * @param mode Mode, see notes below
+ * @param privacy If true, remove headers that might identify the user
+ * @retval 0 Success
+ * @retval -1 Failure
+ *
+ * Note: all RFC2047 encoding should be done outside of this routine, except
* for the "real name." This will allow this routine to be used more than
* once, if necessary.
*
* Likewise, all IDN processing should happen outside of this routine.
*
- * mode == 1 => "lite" mode (used for edit_headers)
+ * mode == 1 => "light" mode (used for edit_headers)
* mode == 0 => normal mode. write full header + MIME headers
* mode == -1 => write just the envelope info (used for postponing messages)
*
rfc2047_decode(&env->subject);
}
+/**
+ * bounce_message - Bounce an email message
+ * @param fp Handle of message
+ * @param h Header of email
+ * @param to Address to bounce to
+ * @param resent_from Address of new sender
+ * @param env_from Envelope of original sender
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int bounce_message(FILE *fp, struct Header *h, struct Address *to,
const char *resent_from, struct Address *env_from)
{
return rc;
}
+/**
+ * mutt_bounce_message - Bounce an email message
+ * @param fp Handle of message
+ * @param h Header of the email
+ * @param to Address to bounce to
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int mutt_bounce_message(FILE *fp, struct Header *h, struct Address *to)
{
const char *fqdn = mutt_fqdn(true);
/**
* mutt_write_multiple_fcc - Handle FCC with multiple, comma separated entries
+ * @param[in] path Path to mailboxes (comma separated)
+ * @param[in] hdr Header of the email
+ * @param[in] msgid Message id
+ * @param[in] post If true, postpone message
+ * @param[in] fcc fcc setting to save (postpone only)
+ * @param[out] finalpath Final path of email
+ * @retval 0 Success
+ * @retval -1 Failure
*/
int mutt_write_multiple_fcc(const char *path, struct Header *hdr, const char *msgid,
int post, char *fcc, char **finalpath)
return 0;
}
+/**
+ * mutt_write_fcc - Write email to FCC mailbox
+ * @param[in] path Path to mailbox
+ * @param[in] hdr Header of the email
+ * @param[in] msgid Message id
+ * @param[in] post If true, postpone message
+ * @param[in] fcc fcc setting to save (postpone only)
+ * @param[out] finalpath Final path of email
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int mutt_write_fcc(const char *path, struct Header *hdr, const char *msgid,
int post, char *fcc, char **finalpath)
{
mutt_debug(1, "%s: write failed.\n", tempfile);
mutt_file_fclose(&tempfp);
unlink(tempfile);
- mx_msg_commit(&f, msg); /* XXX - really? */
+ mx_msg_commit(&f, msg); /* XXX really? */
mx_msg_close(&f, &msg);
mx_mbox_close(&f, NULL);
goto done;
curs_set(1);
endwin(); /* just to be safe */
- /*
- * if sys_siglist is not defined, HAVE_DECL_SYS_SIGLIST will be set to 0
+ /* if sys_siglist is not defined, HAVE_DECL_SYS_SIGLIST will be set to 0
* so we must check it with #if and not #ifdef
*/
#if HAVE_DECL_SYS_SIGLIST
/**
* address_uses_unicode - Do any addresses use Unicode
+ * @param a Address list to check
* @retval true if any of the string of addresses use 8-bit characters
*/
static bool address_uses_unicode(const char *a)
/**
* addresses_use_unicode - Do any of a list of addresses use Unicode
+ * @param a Address list to check
* @retval true if any use 8-bit characters
*/
static bool addresses_use_unicode(const struct Address *a)
projects / neomutt / commitdiff