/**
* check_alias_name - Sanity-check an alias name
*
- * Only characters which are non-special to both the RFC 822 and the mutt
+ * Only characters which are non-special to both the RFC822 and the mutt
* configuration parser are permitted.
*/
int check_alias_name(const char *s, char *dest, size_t destlen)
/**
* mutt_addr_is_user - Does the address belong to the user
- * @return true if the given address belongs to the user
+ * @retval true if the given address belongs to the user
*/
bool mutt_addr_is_user(struct Address *addr)
{
/**
* mutt_compose_attachment - Create an attachment
- * @return
- * * 1 if require full screen redraw
- * * 0 otherwise
+ * @retval 1 if require full screen redraw
+ * @retval 0 otherwise
*/
int mutt_compose_attachment(struct Body *a)
{
/**
* mutt_edit_attachment - Edit an attachment
* @param a Email containing attachment
- * @return 1 if editor found, 0 if not
+ * @retval 1 if editor found
+ * @retval 0 if not
*
* Currently, this only works for send mode, as it assumes that the
* Body->filename actually contains the information. I'm not sure
* @param hdr Message header for the current message. Can be NULL
* @param idx Attachment
* @param idxlen Number of attachments
- * @return
- * * 0 if the viewer is run and exited succesfully
- * * -1 on error
- * * The return value of mutt_do_pager() when it is used
+ * @retval 0 If the viewer is run and exited succesfully
+ * @retval -1 Error
+ * @retval n Return value of mutt_do_pager() when it is used
*
* flag can be one of: #MUTT_MAILCAP, #MUTT_REGULAR, #MUTT_AS_TEXT
*
/**
* mutt_pipe_attachment - Pipe an attachment to a command
- * @return
- * * 1 on success
- * * 0 on error
+ * @retval 1 on success
+ * @retval 0 on error
*/
int mutt_pipe_attachment(FILE *fp, struct Body *b, const char *path, char *outfile)
{
/**
* mutt_save_attachment - Save an attachment
- * @return
- * * 0 on success
- * * -1 on error
+ * @retval 0 on success
+ * @retval -1 on error
*/
int mutt_save_attachment(FILE *fp, struct Body *m, char *path, int flags, struct Header *hdr)
{
/**
* mutt_decode_save_attachment - Decode, then save an attachment
- * @return 0 on success, -1 on error
+ * @retval 0 on success
+ * @retval -1 on error
*/
int mutt_decode_save_attachment(FILE *fp, struct Body *m, char *path, int displaying, int flags)
{
* @param cin Input buffer for the raw bytes
* @param len Length of the input buffer
* @param olen Length of the output buffer
- * @return The length of the string written to the output buffer
+ * @retval n Length of the string written to the output buffer
*
* This function performs base64 encoding. The resulting string is guaranteed
* to be null-terminated. The number of characters up to the terminating
* mutt_from_base64 - convert null-terminated base64 string to raw bytes
* @param out Output buffer for the raw bytes
* @param in Input buffer for the null-terminated base64-encoded string
- * @return The number of bytes written on success, -1 on error
+ * @retval n Number of bytes written on success
+ * @retval -1 on error
*
* This function performs base64 decoding. The resulting buffer is NOT
* null-terminated. If the input buffer contains invalid base64 characters,
* mutt_bcache_open - Open an Email-Body Cache
* @param account current mailbox' account (required)
* @param mailbox path to the mailbox of the account (optional)
- * @return NULL on failure
+ * @retval NULL on failure
*
* The driver using it is responsible for ensuring that hierarchies are
* separated by '/' (if it knows of such a concepts like mailboxes or
* mutt_bcache_get - Open a file in the Body Cache
* @param bcache Body Cache from mutt_bcache_open()
* @param id Per-mailbox unique identifier for the message
- * @return FILE* on success, NULL on failure
+ * @retval FILE* on success
+ * @retval NULL on failure
*/
FILE *mutt_bcache_get(struct BodyCache *bcache, const char *id);
* @param id Per-mailbox unique identifier for the message
* @param tmp Returned FILE* is in a temporary location
* If set, use mutt_bcache_commit to put it into place
- * @return FILE* on success, NULL on failure
+ * @retval FILE* on success
+ * @retval NULL on failure
*/
FILE *mutt_bcache_put(struct BodyCache *bcache, const char *id, int tmp);
* mutt_bcache_commit - Move a temporary file into the Body Cache
* @param bcache Body Cache from mutt_bcache_open()
* @param id Per-mailbox unique identifier for the message
- * @return 0 on success, -1 on failure
+ * @retval 0 on success
+ * @retval -1 on failure
*/
int mutt_bcache_commit(struct BodyCache *bcache, const char *id);
* mutt_bcache_del - Delete a file from the Body Cache
* @param bcache Body Cache from mutt_bcache_open()
* @param id Per-mailbox unique identifier for the message
- * @return 0 on success, -1 on failure
+ * @retval 0 on success
+ * @retval -1 on failure
*/
int mutt_bcache_del(struct BodyCache *bcache, const char *id);
* mutt_bcache_exists - Check if a file exists in the Body Cache
* @param bcache Body Cache from mutt_bcache_open()
* @param id Per-mailbox unique identifier for the message
- * @return 0 on success, -1 on failure
+ * @retval 0 on success
+ * @retval -1 on failure
*/
int mutt_bcache_exists(struct BodyCache *bcache, const char *id);
* @param bcache Body Cache from mutt_bcache_open()
* @param want_id Callback function called for each match
* @param data Data to pass to the callback function
- * @return -1 on failure, count (>=0) of matching items
+ * @retval -1 on failure
+ * @retval >=0 count of matching items
*
* This more or less "examines" the cache and calls a function with
* each id it finds if given.
#include "mutt_notmuch.h"
#endif
-static time_t BuffyTime = 0; /* last time we started checking for mail */
-static time_t BuffyStatsTime = 0; /* last time we check performed mail_check_stats */
-time_t BuffyDoneTime = 0; /* last time we knew for sure how much mail there was. */
-static short BuffyCount = 0; /* how many boxes with new mail */
-static short BuffyNotify = 0; /* # of unnotified new boxes */
+static time_t BuffyTime = 0; /**< last time we started checking for mail */
+static time_t BuffyStatsTime = 0; /**< last time we check performed mail_check_stats */
+time_t BuffyDoneTime = 0; /**< last time we knew for sure how much mail there was. */
+static short BuffyCount = 0; /**< how many boxes with new mail */
+static short BuffyNotify = 0; /**< # of unnotified new boxes */
/**
* fseek_last_message - Find the last message in the file
- * @return 0 on success, -1 if no message found
+ * @retval 0 on success
+ * @retval -1 if no message found
*/
static int fseek_last_message(FILE *f)
{
/**
* test_last_status_new - Is the last message new
- * @return 1 if the last message is new
+ * @retval 1 if the last message is new
*/
static int test_last_status_new(FILE *f)
{
* @param dir_name Path to mailbox
* @param check_new if true, check for new mail
* @param check_stats if true, count total, new, and flagged messages
- * @return 1 if the dir has new mail
+ * @retval 1 if the dir has new mail
*
* Checks the specified maildir subdir (cur or new) for new mail or mail counts.
*/
* buffy_maildir_check - Check for new mail in a maildir mailbox
* @param mailbox Mailbox to check
* @param check_stats if true, also count total, new, and flagged messages
- * @return 1 if the mailbox has new mail
+ * @retval 1 if the mailbox has new mail
*/
static int buffy_maildir_check(struct Buffy *mailbox, int check_stats)
{
* @param mailbox Mailbox to check
* @param sb stat(2) information about the mailbox
* @param check_stats if true, also count total, new, and flagged messages
- * @return 1 if the mailbox has new mail
+ * @retval 1 if the mailbox has new mail
*/
static int buffy_mbox_check(struct Buffy *mailbox, struct stat *sb, int check_stats)
{
void mutt_buffy_vfolder(char *s, size_t slen);
#endif
-extern time_t BuffyDoneTime; /* last time we knew for sure how much mail there was */
+extern time_t BuffyDoneTime; /**< last time we knew for sure how much mail there was */
struct Buffy *mutt_find_mailbox(const char *path);
void mutt_update_mailbox(struct Buffy *b);
-/* fixes up atime + mtime after mbox/mmdf mailbox was modified
- according to stat() info taken before a modification */
+/** fixes up atime + mtime after mbox/mmdf mailbox was modified
+ * according to stat() info taken before a modification */
void mutt_buffy_cleanup(const char *buf, struct stat *st);
-/* mark mailbox just left as already notified */
+/** mark mailbox just left as already notified */
void mutt_buffy_setnotified(const char *path);
int mh_buffy(struct Buffy *mailbox, int check_stats);
static const char *ExtPagerProgress = "all";
-/* The folder the user last saved to. Used by ci_save_message() */
+/** The folder the user last saved to. Used by ci_save_message() */
static char LastSaveFolder[_POSIX_PATH_MAX] = "";
int mutt_display_message(struct Header *cur)
char *err = NULL;
int rc;
- /* RfC 5322 mandates a From: header, so warn before bouncing
+ /* RFC5322 mandates a From: header, so warn before bouncing
* messages without one */
if (h)
{
if (!decrypt) /* If decode doesn't kick in for decrypt, */
{
- *chflags |= CH_DECODE; /* then decode RFC 2047 headers, */
+ *chflags |= CH_DECODE; /* then decode RFC2047 headers, */
if (option(OPTWEED))
{
/**
* mutt_save_message - Save an email
- * @return
- * * 0 if the copy/save was successful
- * * -1 on error/abort
+ * @retval 0 if the copy/save was successful
+ * @retval -1 on error/abort
*/
int mutt_save_message(struct Header *h, int delete, int decode, int decrypt)
{
* mutt_complete - Attempt to complete a partial pathname
* @param s Buffer containing pathname
* @param slen Buffer length
- * @return 0 if ok, -1 if no matches
+ * @retval 0 if ok
+ * @retval -1 if no matches
*
* Given a partial pathname, fill in as much of the rest of the path as is
* unique.
/**
* cum_attachs_size - Cumulative Attachments Size
* @param menu Menu listing attachments
- * @return Number of bytes in attachments
+ * @retval n Number of bytes in attachments
*
* Returns the total number of bytes used by the attachments in the attachment
* list _after_ content-transfer-encodings have been applied.
/**
* mutt_compose_menu - Allow the user to edit the message envelope
- * @return
- * * 1 Message should be postponed
- * * 0 Normal exit
- * * -1 Abort message
+ * @retval 1 Message should be postponed
+ * @retval 0 Normal exit
+ * @retval -1 Abort message
*/
int mutt_compose_menu(struct Header *msg, /* structure for new message */
char *fcc, /* where to save a copy of the message */
* lock_realpath - Try to lock the ctx->realpath
* @param ctx Mailbox to lock
* @param excl Lock exclusively?
- * @return
- * * 1: Success (locked or readonly)
- * * 0: Error (can't lock the file)
+ * @retval 1 Success (locked or readonly)
+ * @retval 0 Error (can't lock the file)
*
* Try to (exclusively) lock the mailbox. If we succeed, then we mark the
* mailbox as locked. If we fail, but we didn't want exclusive rights, then
/**
* setup_paths - Set the mailbox paths
* @param ctx Mailbox to modify
- * @return
- * * 0: Success
- * * -1: Error
+ * @retval 0 Success
+ * @retval -1 Error
*
* Save the compressed filename in ctx->realpath.
* Create a temporary filename and put its name in ctx->path.
/**
* get_size - Get the size of a file
* @param path File to measure
- * @return
- * * number: Size in bytes
- * * 0: On error
+ * @retval n Size in bytes
+ * @retval 0 On error
*/
static int get_size(const char *path)
{
/**
* find_hook - Find a hook to match a path
- * @param type Type of hook, e.g. MUTT_CLOSEHOOK
+ * @param type Type of hook, e.g. #MUTT_CLOSEHOOK
* @param path Filename to test
- * @return
- * * string: Matching hook command
- * * NULL: No matches
+ * @retval string Matching hook command
+ * @retval NULL No matches
*
* Each hook has a type and a pattern.
* Find a command that matches the type and path supplied. e.g.
* open-hook '\.gz$' "gzip -cd '%f' > '%t'"
*
* Call:
- * find_hook (MUTT_OPENHOOK, "myfile.gz");
+ * find_hook (#MUTT_OPENHOOK, "myfile.gz");
*/
static const char *find_hook(int type, const char *path)
{
/**
* set_compress_info - Find the compress hooks for a mailbox
* @param ctx Mailbox to examine
- * @return
- * * CompressInfo: Hook info for the mailbox's path
- * * NULL: On error
+ * @retval ptr CompressInfo Hook info for the mailbox's path
+ * @retval NULL On error
*
* When a mailbox is opened, we check if there are any matching hooks.
*/
/**
* escape_path - Escapes single quotes in a path for a command string
* @param src the path to escape
- * @return a pointer to the escaped string
+ * @retval ptr The escaped string
*/
static char *escape_path(char *src)
{
* @param elsestring Otherwise, display this string, UNUSED
* @param data Pointer to the mailbox Context
* @param flags Format flags, UNUSED
- * @return src (unchanged)
+ * @retval src (unchanged)
*
* cb_format_str is a callback function for mutt_expando_format. It understands
* two operators. '%f' : 'from' filename, '%t' : 'to' filename.
* @param ctx Mailbox to work with
* @param command Command string to execute
* @param progress Message to show the user
- * @return
- * * 1: Success
- * * 0: Failure
+ * @retval 1 Success
+ * @retval 0 Failure
*
* Run the supplied command, taking care of all the Mutt requirements,
* such as locking files and blocking signals.
* comp_open_append_mailbox - Open a compressed mailbox for appending
* @param ctx Mailbox to open
* @param flags e.g. Does the file already exist?
- * @return
- * * 0: Success
- * * -1: Failure
+ * @retval 0 Success
+ * @retval -1 Failure
*
* To append to a compressed mailbox we need an append-hook (or both open- and
* close-hooks).
/**
* comp_close_mailbox - Close a compressed mailbox
* @param ctx Mailbox to close
- * @return
- * * 0: Success
- * * -1: Failure
+ * @retval 0 Success
+ * @retval -1 Failure
*
* If the mailbox has been changed then re-compress the tmp file.
* Then delete the tmp file.
* comp_check_mailbox - Check for changes in the compressed file
* @param ctx Mailbox
* @param index_hint Currently selected mailbox
- * @return
- * * 0: Mailbox OK
- * * MUTT_REOPENED: The mailbox was closed and reopened
- * * -1: Mailbox bad
+ * @retval 0 Mailbox OK
+ * @retval #MUTT_REOPENED The mailbox was closed and reopened
+ * @retval -1 Mailbox bad
*
* If the compressed file changes in size but the mailbox hasn't been changed
* in Mutt, then we can close and reopen the mailbox.
/**
* mutt_comp_can_append - Can we append to this path?
* @param ctx Mailbox
- * @return
- * * true: Yes, we can append to the file
- * * false: No, appending isn't possible
+ * @retval true Yes, we can append to the file
+ * @retval false No, appending isn't possible
*
* To append to a file we can either use an 'append-hook' or a combination of
* 'open-hook' and 'close-hook'.
/**
* mutt_comp_can_read - Can we read from this file?
* @param path Pathname of file to be tested
- * @return
- * * true: Yes, we can read the file
- * * false: No, we cannot read the file
+ * @retval true Yes, we can read the file
+ * @retval false No, we cannot read the file
*
* Search for an 'open-hook' with a regex that matches the path.
*
* comp_sync_mailbox - Save changes to the compressed mailbox file
* @param ctx Mailbox to sync
* @param index_hint Currently selected mailbox
- * @return
- * * 0: Success
- * * -1: Failure
+ * @retval 0 Success
+ * @retval -1 Failure
*
* Changes in Mutt only affect the tmp file. Calling comp_sync_mailbox()
* will commit them to the compressed file.
/**
* mutt_comp_valid_command - Is this command string allowed?
* @param cmd Command string
- * @return
- * * 1: Valid command
- * * 0: "%f" and/or "%t" is missing
+ * @retval 1 Valid command
+ * @retval 0 "%f" and/or "%t" is missing
*
* A valid command string must have both "%f" (from file) and "%t" (to file).
* We don't check if we can actually run the command.
{
if (headers[x])
{
- /* We couldn't do the prefixing when reading because RFC 2047
+ /* We couldn't do the prefixing when reading because RFC2047
* decoding may have concatenated lines.
*/
* @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
+ * @retval 0 on success
+ * @retval -1 on error
*/
static int _mutt_append_message(struct Context *dest, FILE *fpin,
struct Context *src, struct Header *hdr,
/**
* copy_delete_attach - Copy a message, deleting marked attachments
- * @return
- * * 0 on success
- * * -1 on failure
+ * @retval 0 on success
+ * @retval -1 on failure
*
* This function copies a message body, while deleting _in_the_copy_
* any attachments which are marked for deletion.
* 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. */
+ * of course the Mutt way.
+ */
void mutt_need_hard_redraw(void)
{
keypad(stdscr, true);
* @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
+ * @retval n 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
* mutt_charlen - Count the bytes in a (multibyte) character
* @param[in] s String to be examined
* @param[out] width Number of screen columns the character would use
- * @return Number of bytes in the first (multibyte) character of input consumes
- * * < 0 ... conversion error
- * * = 0 ... end of input
- * * > 0 ... length (bytes)
+ * @retval n Number of bytes in the first (multibyte) character of input consumes
+ * @retval <0 Conversion error
+ * @retval =0 End of input
+ * @retval >0 Length (bytes)
*/
int mutt_charlen(const char *s, int *width)
{
/**
* mutt_strwidth - Measure a string's width in screen cells
* @param s String to be measured
- * @return Number of screen cells string would use
+ * @retval n Number of screen cells string would use
*/
int mutt_strwidth(const char *s)
{
/**
* is_leap_year_feb - Is it a leap year
* @param tm Date to be tested
- * @return true if it's a leap year
+ * @retval true if it's a leap year
*/
static int is_leap_year_feb(struct tm *tm)
{
* edit_one_message - Edit an email
* @param ctx Context
* @param cur Header of email
- * @return
- * * 1 Message not modified
- * * 0 Message edited successfully
- * * -1 Error
+ * @retval 1 Message not modified
+ * @retval 0 Message edited successfully
+ * @retval -1 Error
*/
static int edit_one_message(struct Context *ctx, struct Header *cur)
{
/**
* is_shell_char - Is character not typically part of a pathname
* @param ch Character to examine
- * @return 1 if the character is not typically part of a pathname
+ * @retval 1 if the character is not typically part of a pathname
*/
static inline int is_shell_char(wchar_t ch)
{
* @param buflen Buffer length
* @param col Initial cursor position
* @param flags Flags such as MUTT_FILE
- * @return 0 if input was given, -1 if abort
+ * @retval 0 if input was given
+ * @retval -1 if abort
*
* This function is for very basic input, currently used only by the
* built-in editor. It does not handle screen redrawing on resizes
* @param[out] files List of files selected
* @param[out] numfiles Number of files selected
* @param[out] state Current state (if function is called repeatedly)
- * @return
- * * 1 need to redraw the screen and call me again
- * * 0 if input was given
- * * -1 if abort.
+ * @retval 1 need to redraw the screen and call me again
+ * @retval 0 if input was given
+ * @retval -1 if abort
*/
int _mutt_enter_string(char *buf, size_t buflen, int col, int flags, int multiple,
char ***files, int *numfiles, struct EnterState *state)
* @param fdin If `in` is NULL and fdin is not -1 then fdin will be used as stdin for the command process
* @param fdout If `out` is NULL and fdout is not -1 then fdout will be used as stdout for the command process
* @param fderr If `error` is NULL and fderr is not -1 then fderr will be used as stderr for the command process
- * @return Pid of the created process or -1 on any error creating pipes or forking
+ * @retval n pid of the created process
+ * @retval -1 on any error creating pipes or forking
*
* This function provides multiple mechanisms to handle IO sharing for the
* command process. File streams are prioritized over file descriptors if
/**
* mutt_wait_filter - Wait for the exit of a process and return its status
* @param pid Process id of the process to wait for
- * @return Exit status of the process identified by pid or -1 in the event of an error
+ * @retval n Exit status of the process identified by pid
+ * @retval -1 Error
*/
int mutt_wait_filter(pid_t pid)
{
/**
* is_autoview - Should email body be filtered by mailcap
* @param b Email body
- * @return
- * * 1 body part should be filtered by a mailcap entry prior to viewing inline.
- * * 0 otherwise
+ * @retval 1 body part should be filtered by a mailcap entry prior to viewing inline
+ * @retval 0 otherwise
*/
static int is_autoview(struct Body *b)
{
/**
* mutt_can_decode - Will decoding the attachment produce any output
- * @return 1 if decoding the attachment will produce output
+ * @retval 1 if decoding the attachment will produce output
*/
int mutt_can_decode(struct Body *a)
{
* @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
+ * @retval -1 on error
+ * @retval >=0 on success, index into the hash table
*/
static int union_hash_insert(struct Hash *table, union HashKey key, void *data)
{
/**
* hcache_open_t - backend-specific routing to open the header cache database
* @param path The path to the database file
- * @return Pointer to backend-specific context on success, NULL otherwise
+ * @retval Pointer to backend-specific context on success
+ * @retval NULL otherwise
*
* The hcache_open function has the purpose of opening a backend-specific
* connection to the database file specified by the path parameter. Backends
* @param ctx The backend-specific context retrieved via hcache_open
* @param key A message identification string
* @param keylen The length of the string pointed to by key
- * @return Pointer to the message's headers on success, NULL otherwise
+ * @retval Pointer to the message's headers on success
+ * @retval NULL otherwise
*/
typedef void *(*hcache_fetch_t)(void *ctx, const char *key, size_t keylen);
* @param keylen The length of the string pointed to by key
* @param data The message headers data
* @param datalen The length of the string pointed to by data
- * @return 0 on success, a backend-specific error code otherwise
+ * @retval 0 on success
+ * @retval a backend-specific error code otherwise
*/
typedef int (*hcache_store_t)(void *ctx, const char *key, size_t keylen,
void *data, size_t datalen);
* @param ctx The backend-specific context retrieved via hcache_open
* @param key A message identification string
* @param keylen The length of the string pointed to by key
- * @return 0 on success, a backend-specific error code otherwise
+ * @retval 0 on success
+ * @retval a backend-specific error code otherwise
*/
typedef int (*hcache_delete_t)(void *ctx, const char *key, size_t keylen);
/**
* hcache_backend_t - backend-specific identification string
*
- * @return String describing the currently used hcache backend
+ * @retval String describing the currently used hcache backend
*/
typedef const char *(*hcache_backend_t)(void);
/**
* create_hcache_dir - Create parent dirs for the hcache database
* @param path Database filename
- * @return
- * * true Success
- * * false Failure (errno set)
+ * @retval true Success
+ * @retval false Failure (errno set)
*/
static bool create_hcache_dir(const char *path)
{
* @param path Base directory, from $header_cache
* @param folder Mailbox name (including protocol)
* @param namer Callback to generate database filename
- * @return Full pathname to the database (to be generated)
- * (path must be freed by the caller)
+ * @retval ptr Full pathname to the database (to be generated)
+ * (path must be freed by the caller)
*
* Generate the pathname for the hcache database, it will be of the form:
* BASE/FOLDER/NAME-SUFFIX
*
- * BASE : Base directory (@a path)
- * FOLDER: Mailbox name (@a folder)
- * NAME: Create by @a namer, or md5sum of @a folder
- * SUFFIX: Character set (if ICONV isn't being used)
+ * * BASE: Base directory (@a path)
+ * * FOLDER: Mailbox name (@a folder)
+ * * NAME: Create by @a namer, or md5sum of @a folder
+ * * SUFFIX: Character set (if ICONV isn't being used)
*
* This function will create any parent directories needed, so the caller just
* needs to create the database file.
* @param folder Name of the folder containing the messages
* @param namer Optional (might be NULL) client-specific function to form the
* final name of the hcache database file.
- * @return Pointer to a header_cache_t struct on success, NULL otherwise
+ * @retval Pointer to a header_cache_t struct on success
+ * @retval NULL otherwise
*/
header_cache_t *mutt_hcache_open(const char *path, const char *folder, hcache_namer_t namer);
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param key Message identification string
* @param keylen Length of the string pointed to by key
- * @return Pointer to the data if found and valid, NULL otherwise
+ * @retval Pointer to the data if found and valid
+ * @retval NULL otherwise
* @note This function performs a check on the validity of the data found by
* comparing it with the crc value of the header_cache_t structure.
* @note The returned pointer must be freed by calling mutt_hcache_free. This
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param key Message identification string
* @param keylen Length of the string pointed to by key
- * @return Pointer to the data if found, NULL otherwise
+ * @retval Pointer to the data if found
+ * @retval NULL otherwise
* @note This function does not perform any check on the validity of the data
* found.
* @note The returned pointer must be freed by calling mutt_hcache_free. This
/**
* mutt_hcache_restore - restore a Header from data retrieved from the cache
* @param d Data retrieved using mutt_hcache_fetch or mutt_hcache_fetch_raw
- * @return Pointer to the restored header (cannot be NULL)
+ * @retval Pointer to the restored header (cannot be NULL)
* @note The returned Header must be free'd by caller code with
- * mutt_free_header.
+ * mutt_free_header().
*/
struct Header *mutt_hcache_restore(const unsigned char *d);
/**
* mutt_hcache_store - store a Header along with a validity datum
- *
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param key Message identification string
* @param keylen Length of the string pointed to by key
* @param header Message header to store
* @param uidvalidity IMAP-specific UIDVALIDITY value, or 0 to use the current time
- * @return 0 on success, -1 otherwise
+ * @retval 0 on success
+ * @retval -1 otherwise
*/
int mutt_hcache_store(header_cache_t *h, const char *key, size_t keylen,
struct Header *header, unsigned int uidvalidity);
* @param keylen Length of the string pointed to by key
* @param data Payload to associate with key
* @param dlen Length of the buffer pointed to by the @a data parameter
- * @return 0 on success, -1 otherwise
+ * @retval 0 on success
+ * @retval -1 otherwise
*/
int mutt_hcache_store_raw(header_cache_t *h, const char *key, size_t keylen,
void *data, size_t dlen);
* @param h Pointer to the header_cache_t structure got by mutt_hcache_open
* @param key Message identification string
* @param keylen Length of the string pointed to by key
- * @return 0 on success, -1 otherwise
+ * @retval 0 on success
+ * @retval -1 otherwise
*/
int mutt_hcache_delete(header_cache_t *h, const char *key, size_t keylen);
/**
* mutt_hcache_backend_list - get a list of backend identification strings
- *
- * @return Comma separated string describing the compiled-in backends
+ * @retval Comma separated string describing the compiled-in backends
* @note The returned string must be free'd by the caller
*/
const char *mutt_hcache_backend_list(void);
/**
- * mutt_hcache_is_valid_backend
- *
+ * mutt_hcache_is_valid_backend - Is the string a valid hcache backend
* @param s String identifying a backend
- * @return 1 if s is recognized as a valid backend, 0 otherwise
+ * @retval 1 if s is recognized as a valid backend
+ * @retval 0 otherwise
*/
int mutt_hcache_is_valid_backend(const char *s);
#include "backend.h"
#include "lib.h"
-/* The maximum size of the database file (2GiB).
+/** The maximum size of the database file (2GiB).
* The file is mmap(2)'d into memory. */
const size_t LMDB_DB_SIZE = 2147483648;
* @param pfx Prefix string
* @param buf Buffer to store results
* @param buflen Buffer length
- * @return 1 Mailing list found, 0 No list found
+ * @retval 1 Mailing list found
+ * @retval 0 No list found
*
* Search for a mailing list in the list of addresses pointed to by adr.
* If one is found, print pfx and the name of the list into buf.
* @param buflen Buffer length
* @param flags Flags, e.g. MUTT_FORMAT_INDEX
* @param color Color, e.g. MT_COLOR_MESSAGE
- * @return Number of characters written
+ * @retval n Number of characters written
*
* The colors are stored as "magic" strings embedded in the text.
*/
* get_nth_wchar - Extract one char from a multi-byte table
* @param table Multi-byte table
* @param index Select this character
- * @return String pointer to the character
+ * @retval ptr String pointer to the character
*
* Extract one multi-byte character from a string table.
* If the index is invalid, then a space character will be returned.
/**
* make_from_prefix - Create a prefix for an author field
* @param disp Type of field
- * @return Prefix string (do not free it)
+ * @retval string Prefix string (do not free it)
*
* If $from_chars is set, pick an appropriate character from it.
* If not, use the default prefix: "To", "Cc", etc
/**
* 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
+ * @retval 0 User is not in list
+ * @retval 1 User is unique recipient
+ * @retval 2 User is in the TO list
+ * @retval 3 User is in the CC list
+ * @retval 4 User is originator
+ * @retval 5 Sent to a subscribed mailinglist
*/
static int user_is_recipient(struct Header *h)
{
* @param name String to be converted
* @param buf Buffer for the result
* @param buflen Size of the buffer
- * @return 1 on Success, 0 on Failure
+ * @retval 1 on Success
+ * @retval 0 on Failure
*
* Take a name, e.g. "John F. Kennedy" and reduce it to initials "JFK".
* The function saves the first character from each word. Words are delimited
imap_cmd_start(idata, "AUTHENTICATE CRAM-MD5");
- /* From RFC 2195:
+ /* From RFC2195:
* The data encoded in the first ready response contains a presumptively
* arbitrary string of random digits, a timestamp, and the fully-qualified
* primary host name of the server. The syntax of the unencoded form must
- * correspond to that of an RFC 822 'msg-id' [RFC822] as described in [POP3].
+ * correspond to that of an RFC822 'msg-id' [RFC822] as described in [POP3].
*/
do
rc = imap_cmd_step(idata);
mutt_debug(1, "Error releasing credentials\n");
/* send_token may contain a notification to the server to flush
- * credentials. RFC 1731 doesn't specify what to do, and since this
+ * credentials. RFC1731 doesn't specify what to do, and since this
* support is only for authentication, we'll assume the server knows
* enough to flush its own credentials */
gss_release_buffer(&min_stat, &send_token);
/**
* cmd_new - Create and queue a new command control block
* @param idata IMAP data
- * @return NULL if the pipeline is full
+ * @retval NULL if the pipeline is full
*/
static struct ImapCommand *cmd_new(struct ImapData *idata)
{
/**
* imap_code - Was the command successful
- * @return 1 if the command result was OK, or 0 if NO or BAD
+ * @param s IMAP command status
+ * @retval 1 if the command result was OK
+ * @retval 0 if NO or BAD
*/
int imap_code(const char *s)
{
* @param idata IMAP data
* @param cmdstr Command to execute
* @param flags Flags (see below)
- * @return
- * * 0 on success
- * * -1 on Failure
- * * -2 on OK Failure
+ * @retval 0 on success
+ * @retval -1 on Failure
+ * @retval -2 on OK Failure
*
* Also, handle untagged responses.
*
}
else
{
- /* RFC 2595 demands we recheck CAPABILITY after TLS completes. */
+ /* RFC2595 demands we recheck CAPABILITY after TLS completes. */
if (imap_exec(idata, "CAPABILITY", 0))
goto bail;
}
return 0;
}
-/* imap_set_flag: append str to flags if we currently have permission
- * according to aclbit */
+/**
+ * imap_set_flag - append str to flags if we currently have permission
+ *
+ * according to aclbit
+ */
static void imap_set_flag(struct ImapData *idata, int aclbit, int flag,
const char *str, char *flags, size_t flsize)
{
/**
* imap_has_flag - Does the flag exist in the list
- * @return boolean
+ * @retval boolean
*
* Do a caseless comparison of the flag against a flag list, return true if
* found or flag list has '\*'.
* 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. */
+ * 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)
{
* @param flag flag type on which to filter, e.g. MUTT_REPLIED
* @param changed include only changed messages in message set
* @param invert invert sense of flag, eg MUTT_READ matches unread messages
- * @return number of matched messages, or -1 on failure
+ * @retval n Number of matched messages
+ * @retval -1 Failure
*
* pre/post: commands are of the form "%s %s %s %s", tag, pre, message set, post
* Prepares commands for all messages matching conditions
/**
* compare_flags - Compare local flags against the server
- * @return 0 if mutt's flags match cached server flags
+ * @retval 0 if mutt's flags match cached server flags
*/
static bool compare_flags(struct Header *h)
{
* 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
+ * @retval 0 on success
+ * @retval -1 on error
*/
int imap_sync_mailbox(struct Context *ctx, int expunge)
{
* imap_check_mailbox - use the NOOP or IDLE command to poll for new mail
* @param ctx Context
* @param force Don't wait
- * @return
- * * MUTT_REOPENED mailbox has been externally modified
- * * MUTT_NEW_MAIL new mail has arrived!
- * * 0 no change
- * * -1 error
+ * @retval #MUTT_REOPENED mailbox has been externally modified
+ * @retval #MUTT_NEW_MAIL new mail has arrived
+ * @retval 0 no change
+ * @retval -1 error
*/
int imap_check_mailbox(struct Context *ctx, int force)
{
/**
* imap_status - Get the status of a mailbox
- * @return
- * * -1 on error
- * * >=0 count of messages in mailbox
+ * @retval -1 on error
+ * @retval >=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) */
+ * on the next call (for pipelining the postponed count)
+ */
int imap_status(char *path, int queue)
{
static int queued = 0;
* @param src Source buffer
* @param start Starting offset into string
* @param dlen Destination buffer length
- * @return Length of the common string
+ * @retval n Length of the common string
*
* Trim dest to the length of the longest prefix it shares with src.
*/
/**
* 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
+ * @retval -1 error
+ * @retval 0 success
+ * @retval 1 non-fatal error - try fetch/append
*/
int imap_fast_trash(struct Context *ctx, char *dest)
{
#define IMAP_LOG_PASS 5
/* IMAP command responses. Used in ImapCommand.state too */
-/* <tag> OK ... */
-#define IMAP_CMD_OK (0)
-/* <tag> BAD ... */
-#define IMAP_CMD_BAD (-1)
-/* <tag> NO ... */
-#define IMAP_CMD_NO (-2)
-/* * ... */
-#define IMAP_CMD_CONTINUE (1)
-/* + */
-#define IMAP_CMD_RESPOND (2)
-/* ImapCommand.state additions */
-#define IMAP_CMD_NEW (3)
+#define IMAP_CMD_OK (0) /**< <tag> OK ... */
+#define IMAP_CMD_BAD (-1) /**< <tag> BAD ... */
+#define IMAP_CMD_NO (-2) /**< <tag> NO ... */
+#define IMAP_CMD_CONTINUE (1) /**< \* ... */
+#define IMAP_CMD_RESPOND (2) /**< \+ */
+#define IMAP_CMD_NEW (3) /**< ImapCommand.state additions */
/* number of entries in the hash table */
#define IMAP_CACHE_LEN 10
IMAP4 = 0,
IMAP4REV1,
STATUS,
- ACL, /**< RFC 2086: IMAP4 ACL extension */
- NAMESPACE, /**< RFC 2342: IMAP4 Namespace */
- ACRAM_MD5, /**< RFC 2195: CRAM-MD5 authentication */
- AGSSAPI, /**< RFC 1731: GSSAPI authentication */
+ ACL, /**< RFC2086: IMAP4 ACL extension */
+ NAMESPACE, /**< RFC2342: IMAP4 Namespace */
+ ACRAM_MD5, /**< RFC2195: CRAM-MD5 authentication */
+ AGSSAPI, /**< RFC1731: GSSAPI authentication */
AUTH_ANON, /**< AUTH=ANONYMOUS */
- STARTTLS, /**< RFC 2595: STARTTLS */
+ STARTTLS, /**< RFC2595: STARTTLS */
LOGINDISABLED, /**< LOGINDISABLED */
- IDLE, /**< RFC 2177: IDLE */
+ IDLE, /**< RFC2177: IDLE */
SASL_IR, /**< SASL initial response draft */
- ENABLE, /**< RFC 5161 */
+ ENABLE, /**< RFC5161 */
X_GM_EXT1, /**< https://developers.google.com/gmail/imap/imap-extensions */
CAPMAX
* msg_parse_fetch - handle headers returned from header fetch
* @param h IMAP Header
* @param s Command string
- * @return
- * * 0 Success
- * * -1 String is corrupted
- * * -2 Fetch contains a body or header lines that still need to be parsed
+ * @retval 0 Success
+ * @retval -1 String is corrupted
+ * @retval -2 Fetch contains a body or header lines that still need to be parsed
*/
static int msg_parse_fetch(struct ImapHeader *h, char *s)
{
/**
* 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
+ * @retval 0 Success
+ * @retval -1 String is not a fetch response
+ * @retval -2 String is a corrupt fetch response
*
* Expects string beginning with * n FETCH.
*/
/**
* imap_copy_messages - Server COPY messages to another folder
- * @return
- * * -1 Error
- * * 0 Success
- * * 1 Non-fatal error - try fetch/append
+ * @retval -1 Error
+ * @retval 0 Success
+ * @retval 1 Non-fatal error - try fetch/append
*/
int imap_copy_messages(struct Context *ctx, struct Header *h, char *dest, int delete)
{
};
/**
- * utf7_to_utf8 - Convert the data (u7,u7len) from RFC 2060's UTF-7 to UTF-8
+ * utf7_to_utf8 - Convert the data (u7,u7len) from RFC2060'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
+ * store anything. RFC2060 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-).
*/
}
/**
- * utf8_to_utf7 - Convert the data (u8,u8len) from UTF-8 to RFC 2060's UTF-7
+ * utf8_to_utf7 - Convert the data (u8,u8len) from UTF-8 to RFC2060'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
* imap_expand_path - Canonicalise an IMAP path
* @param path Buffer containing path
* @param len Buffer length
- * @return
- * * 0 on success
- * * -1 on error
+ * @retval 0 on success
+ * @retval -1 on error
*
* IMAP implementation of mutt_expand_path. Rewrite an IMAP path in canonical
* and absolute form. The buffer is rewritten in place with the canonical IMAP
/**
* imap_new_idata - Allocate and initialise a new ImapData structure
- * @return NULL on failure (no mem)
+ * @retval NULL on failure (no mem)
*/
struct ImapData *imap_new_idata(void)
{
/**
* imap_get_literal_count - write number of bytes in an IMAP literal into bytes
- * @return 0 on success, -1 on failure
+ * @retval 0 on success
+ * @retval -1 on failure
*/
int imap_get_literal_count(const char *buf, long *bytes)
{
/**
* imap_make_date - format date in IMAP style: DD-MMM-YYYY HH:MM:SS +ZZzz
*
- * Caller should provide a buffer of IMAP_DATELEN bytes */
+ * Caller should provide a buffer of IMAP_DATELEN bytes
+ */
void imap_make_date(char *buf, time_t timestamp)
{
struct tm *tm = localtime(×tamp);
/**
* 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
+ * @retval -1 on error
+ * @retval >0 on success
*/
int mutt_option_index(const char *s)
{
* @param s Current line of the config file
* @param data data field from init.h:struct Command
* @param err Buffer for any error message
- * @return
- * * 1 Stop processing the current file
- * * -1 Failed
+ * @retval 1 Stop processing the current file
+ * @retval -1 Failed
*
* If the 'finish' command is found, we should stop reading the current file.
*/
* @param s Current line of the config file
* @param data data field from init.h:struct Command
* @param err Buffer for any error message
- * @return
- * * 0 Success
- * * -1 Failed
+ * @retval 0 Success
+ * @retval -1 Failed
*
* The 'ifdef' command allows conditional elements in the config file.
* If a given variable, function, command or compile-time symbol exists, then
* to_absolute_path - Convert relative filepath to an absolute path
* @param path Relative path
* @param reference Absolute path that \a path is relative to
- * @return true on success, false otherwise
+ * @retval true on success
+ * @retval false otherwise
*
* Use POSIX functions to convert a path to absolute, relatively to another path
* @note \a path should be at least of PATH_MAX length
* source_rc - Read an initialization file
* @param rcfile_path Path to initialization file
* @param err Buffer for error messages
- * @return <0 if mutt should pause to let the user know
+ * @retval <0 if mutt should pause to let the user know
*/
static int source_rc(const char *rcfile_path, struct Buffer *err)
{
* The creator of a mailto URL cannot expect the resolver of a URL to
* understand more than the "subject" and "body" headers. Clients that
* resolve mailto URLs into mail messages should be able to correctly
- * create RFC 822-compliant mail messages using the "subject" and "body"
+ * create RFC822-compliant mail messages using the "subject" and "body"
* headers.
*/
add_to_list(&MailtoAllow, "body");
** along with the body of your message.
** .pp
** Although the compose menu may have localized header labels, the
- ** labels passed to your editor will be standard RFC 2822 headers,
+ ** labels passed to your editor will be standard RFC2822 headers,
** (e.g. To:, Cc:, Subject:). Headers added in your editor must
- ** also be RFC 2822 headers, or one of the pseudo headers listed in
+ ** also be RFC2822 headers, or one of the pseudo headers listed in
** ``$edit-header''. Mutt will not understand localized header
** labels, just as it would not when parsing an actual email.
** .pp
/*
** .pp
** When \fIset\fP, Mutt will encode international domain names using
- ** IDN. Unset this if your SMTP server can handle newer (RFC 6531)
+ ** IDN. Unset this if your SMTP server can handle newer (RFC6531)
** UTF-8 encoded domains. (IDN only)
*/
#endif /* HAVE_LIBIDN */
/**
* 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
+ * @retval >0 Function to execute
+ * @retval #OP_NULL No function bound to key sequence
+ * @retval -1 Error occurred while reading input
+ * @retval -2 A timeout or sigwinch occurred
*/
int km_dokey(int menu)
{
* mutt_strchrnul - find first occurrence of character in string
* @param s Haystack
* @param c Needle
- * @return Pointer to the first occurrence if found or to the NULL character
+ * @retval ptr First occurrence if found or to the NULL character
*
* This function is like GNU's strchrnul, which is similar to the standard
* strchr function: it looks for the c character in the NULL-terminated string
* @param dirlen Directory length
* @param fname Filename
* @param fnamelen Filename length
- * @return NULL on error, pointer to \a dst on success
+ * @retval NULL Error
+ * @retval ptr Pointer to \a dst on success
*
* Write the concatenated pathname (dir + "/" + fname) into dst.
* The slash is omitted when dir or fname is of 0 length.
* mutt_inbox_cmp - do two folders share the same path and one is an inbox
* @param a First path
* @param b Second path
- * @return -1 if a is INBOX of b, 0 if none is INBOX, 1 if b is INBOX for a
+ * @retval -1 if a is INBOX of b
+ * @retval 0 if none is INBOX
+ * @retval 1 if b is INBOX for a
*
* This function compares two folder paths. It first looks for the position of
* the last common '/' character. If a valid position is found and it's not the
* mutt_mkdir - Recursively create directories
* @param path Directories to create
* @param mode Permissions for final directory
- * @return
- * * 0 Success
- * * -1 Error (errno set)
+ * @retval 0 Success
+ * @retval -1 Error (errno set)
*
* Create a directory, creating the parents if necessary. (like mkdir -p)
*
* @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
+ * @retval 0 on success
+ * @retval 1 on error
*/
int main(int argc, char **argv, char **env)
{
/**
* strict_addrcmp - Strictly compare two address list
- * @return 1 if address lists are strictly identical
+ * @retval 1 if address lists are strictly identical
*/
static int strict_addrcmp(const struct Address *a, const struct Address *b)
{
/**
* mbox_strict_cmp_headers - Strictly compare message headers
- * @return 1 if headers are strictly identical
+ * @retval 1 if headers are strictly identical
*/
int mbox_strict_cmp_headers(const struct Header *h1, const struct Header *h2)
{
* mbox_check_mailbox - Has mailbox changed on disk
* @param[in] ctx Context
* @param[out] index_hint Keep track of current index selection
- * @return
- * * #MUTT_REOPENED Mailbox has been reopened
- * * #MUTT_NEW_MAIL New mail has arrived
- * * #MUTT_LOCKED Couldn't lock the file
- * * 0 No change
- * * -1 Error
+ * @retval #MUTT_REOPENED Mailbox has been reopened
+ * @retval #MUTT_NEW_MAIL New mail has arrived
+ * @retval #MUTT_LOCKED Couldn't lock the file
+ * @retval 0 No change
+ * @retval -1 Error
*/
static int mbox_check_mailbox(struct Context *ctx, int *index_hint)
{
/**
* 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
+ * @retval true if the mailbox has at least 1 new messages (not old)
+ * @retval false otherwise
*/
static bool mbox_has_new(struct Context *ctx)
{
/**
* mbox_sync_mailbox - Sync a mailbox to disk
- * @return
- * * 0 Success
- * * -1 Failure
+ * @retval 0 Success
+ * @retval -1 Failure
*/
static int mbox_sync_mailbox(struct Context *ctx, int *index_hint)
{
/**
* mbox_check_empty - Is the mailbox empty
* @param path Path to mailbox
- * @return
- * * 1 mailbox is not empty
- * * 0 mailbox is empty
- * * -1 on error
+ * @retval 1 mailbox is not empty
+ * @retval 0 mailbox is empty
+ * @retval -1 on error
*/
int mbox_check_empty(const char *path)
{
* this program. If not, see <http://www.gnu.org/licenses/>.
*
* md5.c - Functions to compute MD5 message digest of files or memory blocks
- * according to the definition of MD5 in RFC 1321 from April 1992.
+ * according to the definition of MD5 in RFC1321 from April 1992.
*
* NOTE: The canonical source of this file is maintained with the GNU C
* Library. Bugs can be reported to bug-glibc@prep.ai.mit.edu.
#define BLOCKSIZE 4096
/* This array contains the bytes used to pad the buffer to the next
- 64-byte boundary. (RFC 1321, 3.1: Step 1) */
+ 64-byte boundary. (RFC1321, 3.1: Step 1) */
static const unsigned char fillbuf[64] = { 0x80, 0 /* , 0, 0, ... */ };
/**
* md5_init_ctx - Initialise the MD5 computation
*
- * (RFC 1321, 3.3: Step 3)
+ * (RFC1321, 3.3: Step 3)
*/
void md5_init_ctx(struct Md5Ctx *ctx)
{
/* These are the four functions used in the four steps of the MD5 algorithm
- and defined in the RFC 1321. The first function is a little bit optimized
+ and defined in the RFC1321. The first function is a little bit optimized
(as found in Colin Plumbs public domain implementation). */
/* #define FF(b, c, d) ((b & c) | (~b & d)) */
#define FF(b, c, d) (d ^ (b & (c ^ d)))
md5_uint32 C = ctx->C;
md5_uint32 D = ctx->D;
- /* First increment the byte count. RFC 1321 specifies the possible length of
+ /* First increment the byte count. RFC1321 specifies the possible length of
* the file up to 2^64 bits. Here we only compute the number of bytes. Do a
* double word increment. */
ctx->total[0] += len;
#define CYCLIC(w, s) (w = (w << s) | (w >> (32 - s)))
/* Before we start, one word to the strange constants.
- * They are defined in RFC 1321 as
+ * They are defined in RFC1321 as
* T[i] = (int) (4294967296.0 * fabs (sin (i))), i=1..64
* Here is an equivalent invocation using Perl:
* perl -e 'foreach(1..64){printf "0x%08x\n", int (4294967296 * abs (sin $_))}'
*/
/* Initialize structure containing state of computation.
- * (RFC 1321, 3.3: Step 3) */
+ * (RFC1321, 3.3: Step 3) */
void md5_init_ctx(struct Md5Ctx *ctx);
/* Starting with the result of former calls of this function (or the
/**
* mh_sequences_changed - Has the mailbox changed
* @param b Mailbox
- * @return
- * * 1 mh_sequences last modification time is more recent than the last visit to this mailbox
- * * 0 modification time is older
- * * -1 Error
+ * @retval 1 mh_sequences last modification time is more recent than the last visit to this mailbox
+ * @retval 0 modification time is older
+ * @retval -1 Error
*/
static int mh_sequences_changed(struct Buffy *b)
{
* mh_already_notified - Has the message changed
* @param b Mailbox
* @param msgno Message number
- * @return
- * * 1 Modification time on the message file is older than the last visit to this mailbox
- * * 0 Modification time on the message file is newer
- * * -1 Error
+ * @retval 1 Modification time on the message file is older than the last visit to this mailbox
+ * @retval 0 Modification time on the message file is newer
+ * @retval -1 Error
*/
static int mh_already_notified(struct Buffy *b, int msgno)
{
/**
* mh_valid_message - Is this a valid MH message filename
* @param s Pathname to examine
- * @return true name is valid, false name is invalid
+ * @retval true name is valid
+ * @retval false name is invalid
*
* Ignore the garbage files. A valid MH message consists of only
* digits. Deleted message get moved to a filename with a comma before
* mh_buffy - Check for new mail for a mh mailbox
* @param mailbox Mailbox to check
* @param check_stats Also count total, new, and flagged messages
- * @returns true if the mailbox has new mail
+ * @retval true if the mailbox has new mail
*/
int mh_buffy(struct Buffy *mailbox, int check_stats)
{
/**
* maildir_check_empty - Is the mailbox empty
* @param path Mailbox to check
- * @return
- * * 1 Mailbox is empty
- * * 0 Mailbox contains mail
- * * -1 Error
+ * @retval 1 Mailbox is empty
+ * @retval 0 Mailbox contains mail
+ * @retval -1 Error
*/
int maildir_check_empty(const char *path)
{
/**
* mh_check_empty - Is mailbox empty
* @param path Mailbox to check
- * @return
- * * 1 Mailbox is empty
- * * 0 Mailbox contains mail
- * * -1 Error
+ * @retval 1 Mailbox is empty
+ * @retval 0 Mailbox contains mail
+ * @retval -1 Error
*/
int mh_check_empty(const char *path)
{
* @param[in] url URI to parse
* @param[out] filename Save the filename
* @param[out] tags Save the list of tags
- * @return
- * * true Success
- * * false Error: Bad format
+ * @retval true Success
+ * @retval false Error Bad format
*
* Parse a NotMuch URI, such as:
* * notmuch:///path/to/db?query=tag:lkml&limit=1000
/**
* new_ctxdata - Create a new nm_ctxdata object from a query
* @param uri NotMuch query string
- * @return a new nm_ctxdata struct
+ * @retval ptr New nm_ctxdata struct
*
* A new nm_ctxdata struct is created, then the query is parsed and saved
* within it. This should be freed using free_ctxdata().
/**
* init_context - Add NotMuch data to the Context
* @param ctx A mailbox CONTEXT
- * @return
- * * 0 Success
- * * -1 Error: Bad format
+ * @retval 0 Success
+ * @retval -1 Error Bad format
*
* Create a new nm_ctxdata struct and add it CONTEXT::data.
* NotMuch-specific data will be stored in this struct.
/**
* query_window_check_timebase - Checks if a given timebase string is valid
* @param[in] timebase: string containing a time base
- * @return true if the given time base is valid
+ * @retval true if the given time base is valid
*
* This function returns whether a given timebase string is valid or not,
* which is used to validate the user settable configuration setting:
* @param[in] query vfolder search string
* @param[out] buf allocated string buffer to receive the modified search query
* @param[in] bufsz allocated maximum size of the buf string buffer
- * @return boolean value set to true if a transformed search query is available as
- * a string in buf, otherwise if the search query shall not be transformed.
+ * @retval true Transformed search query is available as a string in buf
+ * @retval false Search query shall not be transformed
*
* This is where the magic of windowed queries happens. Taking a vfolder search
* query string as parameter, it will use the following two user settings:
* get_query_string - builds the notmuch vfolder search string
* @param data internal notmuch context
* @param window if true enable application of the window on the search string
- * @return string containing a notmuch search query, or a NULL pointer
- * if none can be generated.
+ * @retval string Containing a notmuch search query
+ * @retval NULL If none can be generated
*
* This function parses the internal representation of a search, and returns
* a search query string ready to be fed to the notmuch API, given the search
/**
* db_trans_begin - Start a NotMuch database transaction
* @param data Header data
- * @return
- * * < 0 = error
- * * 1 = new transaction started
- * * 0 = already within transaction
+ * @retval <0 error
+ * @retval 1 new transaction started
+ * @retval 0 already within transaction
*/
static int db_trans_begin(struct NmCtxData *data)
{
/**
* is_longrun - Is NotMuch in the middle of a long-running transaction
* @param data Header data
- * @return true if it is
+ * @retval true if it is
*/
static int is_longrun(struct NmCtxData *data)
{
* get_database_mtime - Get the database modification time
* @param[in] data Struct holding database info
* @param[out] mtime Save the modification time
- * @return
- * * 0 Success (result in mtime)
- * * -1 Error
+ * @retval 0 Success (result in mtime)
+ * @retval -1 Error
*
* Get the "mtime" (modification time) of the database file.
* This is the time of the last update.
/**
* nm2mutt_message_id - converts notmuch message Id to mutt message Id
* @param id NotMuch ID to convert
- * @return Mutt message ID
+ * @retval string Mutt message ID
*
* Caller must free the Mutt Message ID
*/
* @param new_uri allocated string receiving the reformatted URI
* @param orig_uri original URI to be parsed
* @param new_uri_sz size of the allocated new_uri string
- * @return
- * * true if new_uri contains a normalized version of the query
- * * false if orig_uri contains an invalid query
+ * @retval true if new_uri contains a normalized version of the query
+ * @retval false if orig_uri contains an invalid query
*
* This function aims at making notmuch searches URI representations deterministic,
* so that when comparing two equivalent searches they will be the same. It works
/**
* nm_open_mailbox - Open a notmuch virtual mailbox
* @param ctx A mailbox CONTEXT
- * @return
- * * 0 Success
- * * -1 Error
+ * @retval 0 Success
+ * @retval -1 Error
*/
static int nm_open_mailbox(struct Context *ctx)
/**
* nm_close_mailbox - Close a notmuch virtual mailbox
* @param ctx A mailbox CONTEXT
- * @return
- * * 0 Success
- * * -1 Error
+ * @retval 0 Success
+ * @retval -1 Error
*/
static int nm_close_mailbox(struct Context *ctx)
{
* nm_check_mailbox - Check a notmuch mailbox for new mail
* @param ctx A mailbox CONTEXT
* @param index_hint Remeber our place in the index
- * @return
- * * -1 Error
- * * 0 QWQ
- * * #MUTT_NEW_MAIL - new mail has arrived
- * * #MUTT_REOPENED - mailbox closed and reopened
- * * #MUTT_FLAGS - QWQ
+ * @retval -1 Error
+ * @retval 0 Success
+ * @retval #MUTT_NEW_MAIL - new mail has arrived
+ * @retval #MUTT_REOPENED - mailbox closed and reopened
+ * @retval #MUTT_FLAGS - flags have changed
*/
static int nm_check_mailbox(struct Context *ctx, int *index_hint)
{
* @param ctx A mailbox CONTEXT
* @param msg Message to open
* @param msgno Index of message to open
- * @return
- * * 0 Success
- * * 1 Error
+ * @retval 0 Success
+ * @retval 1 Error
*/
static int nm_open_message(struct Context *ctx, struct Message *msg, int msgno)
{
* nm_close_message - Close a message
* @param ctx A mailbox CONTEXT
* @param msg Message to close
- * @return
- * * 0 Success
- * * 1 Error
+ * @retval 0 Success
+ * @retval 1 Error
*/
static int nm_close_message(struct Context *ctx, struct Message *msg)
{
* @param authz Authorization identity
* @param user Authentication identity (username)
* @param pass Password
- * @return The number of bytes written to buf
+ * @retval Number Bytes written to buf
*
* This function can be used to build a protocol-specific SASL Response message
* using the PLAIN mechanism. The protocol specific command is given in the cmd
/**
* 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
+ * @retval >0 There is data to read
+ * @retval 0 Read would block
+ * @retval -1 Connection doesn't support polling
*/
int mutt_socket_poll(struct Connection *conn)
{
* @param hostname Hostname
* @param idx Index into certificate list
* @param len Length of certificate list
- * @return 0 on failure, nonzero on success
+ * @retval 0 on failure
+ * @retval >0 on success
*/
static int tls_check_one_certificate(const gnutls_datum_t *certdata,
gnutls_certificate_status_t certstat,
/**
* mutt_matches_list - Is the string in the list
- * @return true if the header contained in "s" is in list "t"
+ * @retval true if the header contained in "s" is in list "t"
*/
bool mutt_matches_list(const char *s, struct List *t)
{
/**
* mutt_needs_mailcap - Does this type need a mailcap entry do display
* @param m Attachment body to be displayed
- * @return
- * * true Mutt requires a mailcap entry to display
- * * false otherwise
+ * @retval true Mutt requires a mailcap entry to display
+ * @retval false otherwise
*/
bool mutt_needs_mailcap(struct Body *m)
{
/**
* mutt_check_overwrite - Ask the user if overwriting is necessary
- * @return
- * * 0 on success
- * * -1 on abort
- * * 1 on error
+ * @retval 0 on success
+ * @retval -1 on abort
+ * @retval 1 on error
*/
int mutt_check_overwrite(const char *attname, const char *path, char *fname,
size_t flen, int *append, char **directory)
/**
* mutt_save_confirm - Ask the user to save
- * @return
- * * 0 if OK to proceed
- * * -1 to abort
- * * 1 to retry
+ * @retval 0 if OK to proceed
+ * @retval -1 to abort
+ * @retval 1 to retry
*/
int mutt_save_confirm(const char *s, struct stat *st)
{
* @param l List of spam patterns
* @param text Buffer to save match
* @param textsize Buffer length
- * @return true if \a s matches a pattern in \a l, false otherwise
+ * @retval true if \a s matches a pattern in \a l
+ * @retval false otherwise
*
* Match a string against the patterns defined by the 'spam' command and output
* the expanded format into `text` when there is a match. If textsize<=0, the
* @param type Type of XDG variable, e.g. #XDG_CONFIG_HOME
* @param buf Buffer to save path
* @param bufsize Buffer length
- * @return 1 if an entry was found that actually exists on disk and 0 otherwise
+ * @retval 1 if an entry was found that actually exists on disk and 0 otherwise
*
* Process an XDG environment variable or its fallback.
*/
* @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
+ * @retval 0 on success
+ * @retval -1 on failure
*/
int mx_lock_file(const char *path, int fd, int excl, int timeout)
{
* mx_sync_mailbox - Save changes to mailbox
* @param[in] ctx Context
* @param[out] index_hint Currently selected mailbox
- * @return 0 on success, -1 on error
+ * @retval 0 on success
+ * @retval -1 on error
*/
int mx_sync_mailbox(struct Context *ctx, int *index_hint)
{
* @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
+ * @retval ptr new Message
*/
struct Message *mx_open_new_message(struct Context *dest, struct Header *hdr, int flags)
{
/**
* mx_check_empty - Is the mailbox empty
* @param path Mailbox to check
- * @return
- * * 1 Mailbox is empty
- * * 0 Mailbox contains mail
- * * -1 Error
+ * @retval 1 Mailbox is empty
+ * @retval 0 Mailbox contains mail
+ * @retval -1 Error
*/
int mx_check_empty(const char *path)
{
state_attach_puts(tmp, s);
}
+/**
+ * crypt_forget_passphrase - Forget a passphrase and display a message
+ */
void crypt_forget_passphrase(void)
{
if ((WithCrypto & APPLICATION_PGP))
#endif
+/**
+ * crypt_valid_passphrase - Check that we have a usable passphrase, ask if not
+ */
int crypt_valid_passphrase(int flags)
{
int ret = 0;
return 0;
}
+/**
+ * crypt_query - Check out the type of encryption used
+ *
+ * Set the cached status values if there are any.
+ */
int crypt_query(struct Body *m)
{
int t = 0;
return t;
}
+/**
+ * crypt_write_signed - Write the message body/part
+ *
+ * Body/part A described by state S to the given TEMPFILE.
+ */
int crypt_write_signed(struct Body *a, struct State *s, const char *tempfile)
{
FILE *fp = NULL;
unset_option(OPTDONTHANDLEPGPKEYS);
}
+/**
+ * crypt_get_keys - Check we have all the keys we need
+ *
+ * Do a quick check to make sure that we can find all of the
+ * encryption keys if the user has requested this service.
+ * Return the list of keys in KEYLIST.
+ * If oppenc_mode is true, only keys that can be determined without
+ * prompting will be used.
+ */
int crypt_get_keys(struct Header *msg, char **keylist, int oppenc_mode)
{
struct Address *adrlist = NULL, *last = NULL;
/**
* crypt_get_fingerprint_or_id - Get the fingerprint or long key ID
+ * @param pphint Start of string to be passed to pgp_add_string_to_hints() or
+ * crypt_add_string_to_hints()
+ * @param ppl Start of long key ID if detected, else NULL
+ * @param pps Start of short key ID if detected, else NULL
+ * @retval string Copy of fingerprint, if any, stripped of all spaces
+ * Must be FREE'd by caller
+ * @retval NULL Otherwise
*
* Obtain pointers to fingerprint or short or long key ID, if any.
- * See ncrypt.h for details.
+ *
+ * Upon return, at most one of return, *ppl and *pps pointers is non-NULL,
+ * indicating the longest fingerprint or ID found, if any.
*/
const char *crypt_get_fingerprint_or_id(char *p, const char **pphint,
const char **ppl, const char **pps)
struct State;
void convert_to_7bit(struct Body *a);
-
-/* Print the current time. */
void crypt_current_time(struct State *s, char *app_name);
-
-/* Write the message body/part A described by state S to the given
- TEMPFILE. */
int crypt_write_signed(struct Body *a, struct State *s, const char *tempfile);
-
-/* Obtain pointers to fingerprint or short or long key ID, if any.
-
- Upon return, at most one of return, *ppl and *pps pointers is non-NULL,
- indicating the longest fingerprint or ID found, if any.
-
- Return: Copy of fingerprint, if any, stripped of all spaces, else NULL.
- Must be FREE'd by caller.
- *pphint Start of string to be passed to pgp_add_string_to_hints() or
- crypt_add_string_to_hints().
- *ppl Start of long key ID if detected, else NULL.
- *pps Start of short key ID if detected, else NULL. */
const char *crypt_get_fingerprint_or_id(char *p, const char **pphint,
const char **ppl, const char **pps);
-
-/* Check if a string contains a numerical key */
bool crypt_is_numerical_keyid(const char *s);
#endif /* _NCRYPT_CRYPT_H */
/**
* 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
+ * @retval true when s points to a digit or letter
*/
static int digit_or_letter(const unsigned char *s)
{
/**
* crypt_fpr_or_lkeyid - Find the fingerprint of a key
* @param k Key to examine
- * @return
- * * fingerprint if available
- * * otherwise returns the long keyid
+ * @retval string fingerprint if available
+ * @retval string otherwise the long keyid
*/
static const char *crypt_fpr_or_lkeyid(struct CryptKeyInfo *k)
{
/**
* crypt_key_is_valid - Is the key valid
- * @return true when key K is valid
+ * @retval true when key K is valid
*/
static bool crypt_key_is_valid(struct CryptKeyInfo *k)
{
/**
* crypt_id_is_strong - Is the key strong
- * @return true when validity of KEY is sufficient
+ * @retval true when validity of KEY is sufficient
*/
static int crypt_id_is_strong(struct CryptKeyInfo *key)
{
/**
* set_signer - Make sure that the correct signer is set
- * @return 0 on success
+ * @retval 0 on success
*/
static int set_signer(gpgme_ctx_t ctx, int for_smime)
{
{
if (use_smime)
{
- /* convert GPGME raw hash name to RFC 2633 format */
+ /* convert GPGME raw hash name to RFC2633 format */
snprintf(buf, buflen, "%s", algorithm_name);
ascii_strlower(buf);
}
else
{
- /* convert GPGME raw hash name to RFC 3156 format */
+ /* convert GPGME raw hash name to RFC3156 format */
snprintf(buf, buflen, "pgp-%s", algorithm_name);
ascii_strlower(buf + 4);
}
* 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
+ * @retval ptr new Body
+ * @retval NULL error
*/
static struct Body *sign_message(struct Body *a, int use_smime)
{
/**
* show_sig_summary - Show a signature summary
- * @return 1 if there is is a severe warning
+ * @retval 1 if there is is a severe warning
*
* Display the common attributes of the signature summary SUM.
*/
/**
* 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
+ * @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
/**
* pgp_gpgme_decrypt_mime - Decrypt a PGP/MIME message
- * @return 0 on success
+ * @retval 0 on success
*
* The message in FPIN and B and return a new body and the stream in CUR and
* FPOUT.
/**
* smime_gpgme_decrypt_mime - Decrypt a S/MIME message
- * @returns 0 on success
+ * @retval 0 on success
*
* The message in FPIN and B and return a new body and
* the stream in CUR and FPOUT.
* @param a String a
* @param n Maximum length to compare
* @param b String b
- * @return
- * * 0 Strings match
- * * -1 Strings differ
+ * @retval 0 Strings match
+ * @retval -1 Strings differ
*
* Check that \a b is a complete line containing \a a followed by either LF or
* CRLF.
/**
* find_keys - Find keys of the recipients of the message
- * @return NULL if any of the keys can not be found
+ * @retval 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.
/*
* Assume address is 'mailbox@domainname'.
* The mailbox part is case-sensitive,
- * the domainname is not. (RFC 2821)
+ * the domainname is not. (RFC2821)
*/
const char *tmp_email = uid->email + 1;
const char *tmp_sender = sender->mailbox;
void crypto_module_register(crypt_module_specs_t specs);
crypt_module_specs_t crypto_module_lookup(int identifier);
-/* If the crypto module identifier by IDENTIFIER has been registered,
+/** If the crypto module identifier by IDENTIFIER has been registered,
call its function FUNC. Do nothing else. This may be used as an
expression. */
#define CRYPT_MOD_CALL_CHECK(identifier, func) \
(crypto_module_lookup(APPLICATION_##identifier) && \
(crypto_module_lookup(APPLICATION_##identifier))->functions.func)
-/* Call the function FUNC in the crypto module identified by
+/** Call the function FUNC in the crypto module identified by
IDENTIFIER. This may be used as an expression. */
#define CRYPT_MOD_CALL(identifier, func) \
*(crypto_module_lookup(APPLICATION_##identifier))->functions.func
*/
/**
- * crypt_pgp_void_passphrase - Reset a PGP passphrase
+ * crypt_pgp_void_passphrase - Silently, reset a PGP passphrase
*/
void crypt_pgp_void_passphrase(void)
{
*/
/**
- * crypt_smime_void_passphrase - Reset an SMIME passphrase
+ * crypt_smime_void_passphrase - Silently, reset an SMIME passphrase
*/
void crypt_smime_void_passphrase(void)
{
struct Body;
struct State;
-/* Silently forget about a passphrase. */
void crypt_pgp_void_passphrase(void);
-
int crypt_pgp_valid_passphrase(void);
-
-/* fixme: needs documentation. */
struct Body *crypt_pgp_traditional_encryptsign(struct Body *a, int flags, char *keylist);
-
-/* 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. */
char *crypt_pgp_findkeys(struct Address *adrlist, int oppenc_mode);
-
-/* Create a new body with a PGP signed message from A. */
struct Body *crypt_pgp_sign_message(struct Body *a);
-
-/* 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);
-
-/* Invoke the PGP command to import a key. */
void crypt_pgp_invoke_import(const char *fname);
-
-/* fixme: needs documentation */
int crypt_pgp_verify_one(struct Body *sigbdy, struct State *s, const char *tempf);
-
void crypt_pgp_set_sender(const char *sender);
-/* Silently forget about a passphrase. */
void crypt_smime_void_passphrase(void);
-
int crypt_smime_valid_passphrase(void);
-
-/* Ask for an SMIME key. */
-
-/* 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. */
char *crypt_smime_findkeys(struct Address *adrlist, int oppenc_mode);
-
-/* fixme: Needs documentation. */
struct Body *crypt_smime_sign_message(struct Body *a);
-
-/* fixme: needs documentation. */
struct Body *crypt_smime_build_smime_entity(struct Body *a, char *certlist);
-
-/* Add a certificate and update index file (externally). */
void crypt_smime_invoke_import(char *infile, char *mailbox);
-
void crypt_smime_set_sender(const char *sender);
-
-/* fixme: needs documentation */
int crypt_smime_verify_one(struct Body *sigbdy, struct State *s, const char *tempf);
#endif /* _NCRYPT_CRYPTGLUE_H */
#define KEYFLAG_ABILITIES (KEYFLAG_CANSIGN | KEYFLAG_CANENCRYPT | KEYFLAG_PREFER_ENCRYPTION | KEYFLAG_PREFER_SIGNING)
/* Some prototypes -- old crypt.h. */
-
int mutt_protect(struct Header *msg, char *keylist);
-
int mutt_is_multipart_encrypted(struct Body *b);
-
int mutt_is_valid_multipart_pgp_encrypted(struct Body *b);
-
int mutt_is_malformed_multipart_pgp_encrypted(struct Body *b);
-
int mutt_is_multipart_signed(struct Body *b);
-
int mutt_is_application_pgp(struct Body *m);
-
int mutt_is_application_smime(struct Body *m);
-
int mutt_signed_handler(struct Body *a, struct State *s);
-
int mutt_parse_crypt_hdr(const char *p, int set_empty_signas, int crypt_app);
/* -- crypt.c -- */
-
-/* Check out the type of encryption used and set the cached status
- values if there are any. */
int crypt_query(struct Body *m);
-
-/* Fixme: To be documented. */
void crypt_extract_keys_from_messages(struct Header *h);
-
-/* Do a quick check to make sure that we can find all of the
- encryption keys if the user has requested this service.
- Return the list of keys in KEYLIST.
- If oppenc_mode is true, only keys that can be determined without
- prompting will be used. */
int crypt_get_keys(struct Header *msg, char **keylist, int oppenc_mode);
-
-/* Check if all recipients keys can be automatically determined.
- * Enable encryption if they can, otherwise disable encryption. */
void crypt_opportunistic_encrypt(struct Header *msg);
-
-/* Forget a passphrase and display a message. */
void crypt_forget_passphrase(void);
-
-/* Check that we have a usable passphrase, ask if not. */
int crypt_valid_passphrase(int flags);
/* -- cryptglue.c -- */
-
-/* Show a message that a backend will be invoked. */
void crypt_invoke_message(int type);
-
-/* Decrypt a PGP/MIME message. */
int crypt_pgp_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d);
-
-/* MIME handler for the application/pgp content-type. */
int crypt_pgp_application_pgp_handler(struct Body *m, struct State *s);
-
-/* MIME handler for an PGP/MIME encrypted message. */
int crypt_pgp_encrypted_handler(struct Body *a, struct State *s);
-
-/* fixme: needs documentation. */
void crypt_pgp_invoke_getkeys(struct Address *addr);
-
-/* Check for a traditional PGP message in body B. */
int crypt_pgp_check_traditional(FILE *fp, struct Body *b, int tagged_only);
-
-/* Generate a PGP public key attachment. */
struct Body *crypt_pgp_make_key_attachment(char *tempf);
-
int crypt_pgp_send_menu(struct Header *msg);
-
-/* fixme: needs documentation */
void crypt_pgp_extract_keys_from_attachment_list(FILE *fp, int tag, struct Body *top);
-
-/* Decrypt an S/MIME message. */
int crypt_smime_decrypt_mime(FILE *a, FILE **b, struct Body *c, struct Body **d);
-
-/* MIME handler for the application/smime content-type. */
int crypt_smime_application_smime_handler(struct Body *m, struct State *s);
-
-/* fixme: Needs documentation. */
void crypt_smime_getkeys(struct Envelope *env);
-
-/* Check that the sender matches. */
int crypt_smime_verify_sender(struct Header *h);
-
int crypt_smime_send_menu(struct Header *msg);
-
void crypt_init(void);
#endif /* _NCRYPT_NCRYPT_H */
void pgp_void_passphrase(void);
int pgp_valid_passphrase(void);
-/* private ? */
int pgp_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile);
struct Body *pgp_traditional_encryptsign(struct Body *a, int flags, char *keylist);
struct Body *pgp_encrypt_message(struct Body *a, char *keylist, int sign);
struct Address;
struct List;
-/* The PGP invocation interface - not really beautiful. */
+/* The PGP invocation interface */
void pgp_invoke_import(const char *fname);
void pgp_invoke_getkeys(struct Address *addr);
*/
enum PgpRing
{
- PGP_PUBRING,
- PGP_SECRING,
+ PGP_PUBRING, /**< Public keys */
+ PGP_SECRING, /**< Secret keys */
};
struct Body *pgp_make_key_attachment(char *tempf);
/**
* smime_find_keys - Find the keys of the recipients of a message
- * @return NULL if any of the keys can not be found
+ * @retval 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.
void smime_void_passphrase(void);
int smime_valid_passphrase(void);
-
int smime_decrypt_mime(FILE *fpin, FILE **fpout, struct Body *b, struct Body **cur);
-
int smime_application_smime_handler(struct Body *m, struct State *s);
-
struct Body *smime_sign_message(struct Body *a);
-
struct Body *smime_build_smime_entity(struct Body *a, char *certlist);
-
int smime_verify_one(struct Body *sigbdy, struct State *s, const char *tempfile);
-
int smime_verify_sender(struct Header *h);
-
void smime_getkeys(struct Envelope *env);
-
char *smime_find_keys(struct Address *adrlist, int oppenc_mode);
-
void smime_invoke_import(char *infile, char *mailbox);
-
int smime_send_menu(struct Header *msg);
#endif
/**
* nntp_newsrc_parse - Parse .newsrc file
* @param nserv NNTP server
- * @return
- * * 0 Not changed
- * * 1 Parsed
- * * -1 Error
+ * @retval 0 Not changed
+ * @retval 1 Parsed
+ * @retval -1 Error
*/
int nntp_newsrc_parse(struct NntpServer *nserv)
{
/**
* nntp_capabilities - Get capabilities
- * @return
- * * -1 Error, connection is closed
- * * 0 Mode is reader, capabilities setted up
- * * 1 Need to switch to reader mode
+ * @retval -1 Error, connection is closed
+ * @retval 0 Mode is reader, capabilities setted up
+ * @retval 1 Need to switch to reader mode
*/
static int nntp_capabilities(struct NntpServer *nserv)
{
/**
* 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)
+ * @retval 0 Success
+ * @retval 1 Bad response (answer in query buffer)
+ * @retval -1 Connection lost
+ * @retval -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:
* @param nntp_data NNTP data
* @param wildmat String to match
* @param msg Progress message
- * @return
- * * 0 Success
- * * 1 Bad response (answer in query buffer)
- * * -1 Connection lost
- * * -2 Error
+ * @retval 0 Success
+ * @retval 1 Bad response (answer in query buffer)
+ * @retval -1 Connection lost
+ * @retval -2 Error
*/
static int get_description(struct NntpData *nntp_data, char *wildmat, char *msg)
{
/**
* nntp_group_poll - Check newsgroup for new articles
- * @return
- * * 1 New articles found
- * * 0 No change
- * * -1 Lost connection
+ * @retval 1 New articles found
+ * @retval 0 No change
+ * @retval -1 Lost connection
*/
static int nntp_group_poll(struct NntpData *nntp_data, int update_stat)
{
/**
* 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
+ * @retval #MUTT_REOPENED Articles have been renumbered or removed from server
+ * @retval #MUTT_NEW_MAIL New articles found
+ * @retval 0 No change
+ * @retval -1 Lost connection
*
* Leave newsrc locked
*/
/**
* 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
+ * @retval #MUTT_REOPENED Articles have been renumbered or removed from server
+ * @retval #MUTT_NEW_MAIL New articles found
+ * @retval 0 No change
+ * @retval -1 Lost connection
*/
static int nntp_check_mailbox(struct Context *ctx, int *index_hint)
{
/**
* nntp_check_new_groups - Check for new groups/articles in subscribed groups
- * @return
- * * 1 New groups found
- * * 0 No new groups
- * * -1 Error
+ * @retval 1 New groups found
+ * @retval 0 No new groups
+ * @retval -1 Error
*/
int nntp_check_new_groups(struct NntpServer *nserv)
{
/**
* nntp_check_msgid - Fetch article by Message-ID
- * @return
- * * 0 Success
- * * 1 No such article
- * * -1 Error
+ * @retval 0 Success
+ * @retval 1 No such article
+ * @retval -1 Error
*/
int nntp_check_msgid(struct Context *ctx, const char *msgid)
{
* @param force_redraw Force a repaint
* @param search_re Regex to highlight
* @param pager_window Window to draw into
- * @return
- * * -1 EOF was reached
- * * 0 normal exit, line was not displayed
- * * >0 normal exit, line was displayed
+ * @retval -1 EOF was reached
+ * @retval 0 normal exit, line was not displayed
+ * @retval >0 normal exit, line was displayed
*
* flags:
* * #MUTT_SHOWFLAT, show characters (used for displaying help)
}
else if (ascii_strcasecmp(line + 1, "ist-Post") == 0)
{
- /* RFC 2369. FIXME: We should ignore whitespace, but don't. */
+ /* RFC2369. FIXME: We should ignore whitespace, but don't. */
if (strncmp(p, "NO", 2) != 0)
{
char *beg = NULL, *end = NULL;
* @param weed If this parameter is set and the user has activated the
* $weed option, honor the header weed list for user headers.
* Used for recall-message
- * @return newly allocated envelope structure
+ * @retval ptr Newly allocated envelope structure
*
* Caller should free the Envelope using mutt_free_envelope().
*/
hdr->content->encoding = ENC7BIT;
hdr->content->length = -1;
- /* RFC 2183 says this is arbitrary */
+ /* RFC2183 says this is arbitrary */
hdr->content->disposition = DISPINLINE;
}
}
/**
* 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!)
+ * @retval 1 if the cache value is set and has a true value
+ * @retval 0 otherwise (even if unset!)
*/
static int get_pattern_cache_value(int cache_entry)
{
/**
* top_of_thread - Find the first email in the current thread
* @param h Header of current email
- * @return
- * * MuttThread*: success, email found
- * * NULL: on error
+ * @retval ptr Success, email found
+ * @retval NULL On error
*/
static struct MuttThread *top_of_thread(struct Header *h)
{
/**
* mutt_limit_current_thread - Limit the email view to the current thread
* @param h Header of current email
- * @return
- * * true: Success
- * * false: Failure
+ * @retval true Success
+ * @retval false Failure
*/
bool mutt_limit_current_thread(struct Header *h)
{
* pop_read_header - Read header
* @param pop_data POP data
* @param h Email header
- * @return
- * * 0 Success
- * * -1 Connection lost,
- * * -2 Invalid command or execution error,
- * * -3 Error writing to tempfile
+ * @retval 0 Success
+ * @retval -1 Connection lost
+ * @retval -2 Invalid command or execution error
+ * @retval -3 Error writing to tempfile
*/
static int pop_read_header(struct PopData *pop_data, struct Header *h)
{
/**
* pop_fetch_headers - Read headers
* @param ctx Context
- * @return
- * * 0 Success
- * * -1 Connection lost,
- * * -2 Invalid command or execution error,
- * * -3 Error writing to tempfile
+ * @retval 0 Success
+ * @retval -1 Connection lost
+ * @retval -2 Invalid command or execution error
+ * @retval -3 Error writing to tempfile
*/
static int pop_fetch_headers(struct Context *ctx)
{
*/
enum PopStatus
{
- /* Status */
POP_NONE = 0,
POP_CONNECTED,
POP_DISCONNECTED,
/**
* pop_authenticate - Authenticate with a POP server
- * @return
- * * 0 Successful
- * * -1 Connection lost
- * * -2 Login failed
- * * -3 Authentication cancelled
-*/
+ * @retval 0 Successful
+ * @retval -1 Connection lost
+ * @retval -2 Login failed
+ * @retval -3 Authentication cancelled
+ */
int pop_authenticate(struct PopData *pop_data)
{
struct Account *acct = &pop_data->conn->account;
* pop_parse_path - Parse a POP mailbox name
* @param path Path to parse
* @param acct Account to store details
- * @return 0 success, -1 error
+ * @retval 0 success
+ * @retval -1 error
*
* Split a POP path into host, port, username and password
*/
* fetch_capa - Parse CAPA output
* @param line List of capabilities
* @param data POP data
- * @return 0 (always)
+ * @retval 0 (always)
*/
static int fetch_capa(char *line, void *data)
{
* fetch_auth - Fetch list of the authentication mechanisms
* @param line List of authentication methods
* @param data POP data
- * @return 0 (always)
+ * @retval 0 (always)
*/
static int fetch_auth(char *line, void *data)
{
* pop_capabilities - Get capabilities from a POP server
* @param pop_data POP data
* @param mode Initial capabilities
- * @return
- * * 0 Successful
- * * -1 Connection lost
- * * -2 Execution error
+ * @retval 0 Successful
+ * @retval -1 Connection lost
+ * @retval -2 Execution error
*/
static int pop_capabilities(struct PopData *pop_data, int mode)
{
/**
* pop_connect - Open connection
* @param pop_data POP data
- * @return
- * * 0 Successful
- * * -1 Connection lost
- * * -2 Invalid response
+ * @retval 0 Successful
+ * @retval -1 Connection lost
+ * @retval -2 Invalid response
*/
int pop_connect(struct PopData *pop_data)
{
/**
* pop_open_connection - Open connection and authenticate
* @param pop_data POP data
- * @return
- * * 0 Successful
- * * -1 Connection lost
- * * -2 Invalid command or execution error
- * * -3 Authentication cancelled
+ * @retval 0 Successful
+ * @retval -1 Connection lost
+ * @retval -2 Invalid command or execution error
+ * @retval -3 Authentication cancelled
*/
int pop_open_connection(struct PopData *pop_data)
{
* @param buf Buffer to send/store data
* @param buflen Buffer length
* @param msg Progress message
- * @return
- * * 0 Successful
- * * -1 Connection lost
- * * -2 Invalid command or execution error
+ * @retval 0 Successful
+ * @retval -1 Connection lost
+ * @retval -2 Invalid command or execution error
*/
int pop_query_d(struct PopData *pop_data, char *buf, size_t buflen, char *msg)
{
/**
* 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)
+ * @retval 0 Successful
+ * @retval -1 Connection lost
+ * @retval -2 Invalid command or execution error
+ * @retval -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.
* check_uidl - find message with this UIDL and set refno
* @param line String containing UIDL
* @param data POP data
- * @return 0 on success, -1 on error
+ * @retval 0 on success
+ * @retval -1 on error
*/
static int check_uidl(char *line, void *data)
{
/**
* pop_reconnect - reconnect and verify indexes if connection was lost
* @param ctx Context
- * @return 0 on success, -1 on error
+ * @retval 0 on success
+ * @retval -1 on error
*/
int pop_reconnect(struct Context *ctx)
{
* @param force
* * 0 Use a cached value if costly to get a fresh count (IMAP)
* * 1 Force check
- * @return Number of postponed messages
+ * @retval n Number of postponed messages
*/
int mutt_num_postponed(int force)
{
* which `hdr' is in reply to
* @param fcc fcc for the recalled message
* @param fcclen max length of fcc
- * @return
- * * -1 Error/no messages
- * * 0 Normal exit
- * * SENDREPLY Recalled message is a reply
+ * @retval -1 Error/no messages
+ * @retval 0 Normal exit
+ * @retval #SENDREPLY Recalled message is a reply
*/
int mutt_get_postponed(struct Context *ctx, struct Header *hdr,
struct Header **cur, char *fcc, size_t fcclen)
* @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
+ * @retval 0 on success
+ * @retval -1 on error
*/
int mutt_prepare_template(FILE *fp, struct Context *ctx, struct Header *newhdr,
struct Header *hdr, short resend)
* mutt_is_message_type - Determine if a mime type matches a message or not
* @param type Message type enum value
* @param subtype Message subtype
- * @return
- * * true Type is message/news or message/rfc822
- * * false Otherwise
+ * @retval true Type is message/news or message/rfc822
+ * @retval false Otherwise
*/
bool mutt_is_message_type(int type, const char *subtype)
{
/* one or more messages? */
p = (cur || count_tagged(idx, idxlen) == 1);
- /* RfC 5322 mandates a From: header, so warn before bouncing
+ /* RFC5322 mandates a From: header, so warn before bouncing
* messages without one */
if (cur)
{
/**
* @file
- * RFC 1524 Mailcap routines
+ * RFC1524 Mailcap routines
*
* @authors
* Copyright (C) 1996-2000,2003,2012 Michael R. Elkins <me@mutt.org>
}
/**
- * get_field - NUL terminate a rfc 1524 field
+ * get_field - NUL terminate a RFC1524 field
* @param s String to alter
- * @return start of next field or NULL
+ * @retval ptr Start of next field
+ * @retval NULL Error
*/
static char *get_field(char *s)
{
/**
* rfc1524_new_entry - Allocate memory for a new rfc1524 entry
- * @return Pointer to an un-initialized struct Rfc1524MailcapEntry
+ * @retval ptr An un-initialized struct Rfc1524MailcapEntry
*/
struct Rfc1524MailcapEntry *rfc1524_new_entry(void)
{
/**
* rfc1524_free_entry - Deallocate an struct Rfc1524MailcapEntry
- * @param entry Rfc1524MailcapEntry to deallocate.
+ * @param entry Rfc1524MailcapEntry to deallocate
*/
void rfc1524_free_entry(struct Rfc1524MailcapEntry **entry)
{
* @param type Text type in "type/subtype" format
* @param entry struct Rfc1524MailcapEntry to populate with results
* @param opt Type of mailcap entry to lookup
- * @return
- * * 1 on success. If *entry is not NULL it poplates it with the mailcap entry
- * * 0 if no matching entry is found
+ * @retval 1 on success. If *entry is not NULL it poplates it with the mailcap entry
+ * @retval 0 if no matching entry is found
*
* opt can be one of: #MUTT_EDIT, #MUTT_COMPOSE, #MUTT_PRINT, #MUTT_AUTOVIEW
*
* @param oldfile Original filename
* @param newfile Buffer for new filename
* @param nflen Buffer length
- * @return
- * * 0 if the left and right components of the oldfile and newfile match.
- * * 1 otherwise.
-
+ * @retval 0 if the left and right components of the oldfile and newfile match
+ * @retval 1 otherwise
+ *
* If there is no nametemplate, the stripped oldfile name is used as the
* template for newfile.
*
newfile[0] = 0;
- /* first, ignore leading path components.
- */
+ /* first, ignore leading path components */
if (nametemplate && (s = strrchr(nametemplate, '/')))
nametemplate = s + 1;
else /* oldfile && nametemplate */
{
/* first, compare everything left from the "%s"
- * (if there is one).
- */
+ * (if there is one). */
lmatch = true;
ps = 0;
/**
* @file
- * RFC 1524 Mailcap routines
+ * RFC1524 Mailcap routines
*
* @authors
* Copyright (C) 1996-2000 Michael R. Elkins <me@mutt.org>
/**
* @file
- * RFC 2047 MIME extensions routines
+ * RFC2047 MIME extensions routines
*
* @authors
* Copyright (C) 1996-2000,2010 Michael R. Elkins <me@mutt.org>
* @param tocode New encoding
* @param encoder Encoding function
* @param wlen Number of characters converted
- * @return 0 string could be converted >0 maximum that could be converted
+ * @retval 0 string could be converted >0 maximum that could be converted
*
* Return 0 if and set *encoder and *wlen if the data (d, dlen) could
* be converted to an encoded word of length *wlen using *encoder.
len_b = len + (((ob - buf1) + 2) / 3) * 4;
len_q = len + (ob - buf1) + 2 * count;
- /* Apparently RFC 1468 says to use B encoding for iso-2022-jp. */
+ /* Apparently RFC1468 says to use B encoding for iso-2022-jp. */
if (ascii_strcasecmp(tocode, "ISO-2022-JP") == 0)
len_q = ENCWORD_LEN_MAX + 1;
* @param fromcode Original encoding
* @param tocode New encoding
* @param encoder Encoding funtion
- * @return Length of the encoded word
+ * @retval n Length of the encoded word
*
* Encode the data (d, dlen) into s using the encoder.
*/
switch (count)
{
case 2:
- /* ignore language specification a la RFC 2231 */
+ /* ignore language specification a la RFC2231 */
t = pp1;
if ((t1 = memchr(pp, '*', t - pp)))
t = t1;
* 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,
+ * grammar in section 2 of RFC2047, 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)).
*/
/**
* @file
- * RFC 2047 MIME extensions routines
+ * RFC2047 MIME extensions routines
*
* @authors
* Copyright (C) 1996-2000 Michael R. Elkins <me@mutt.org>
/**
* @file
- * RFC 2231 MIME Charset routines
+ * RFC2231 MIME Charset routines
*
* @authors
* Copyright (C) 1999-2001 Thomas Roessler <roessler@does-not-exist.org>
/*
* Yet another MIME encoding for header data. This time, it's
- * parameters, specified in RFC 2231, and modeled after the
+ * parameters, specified in RFC2231, and modeled after the
* encoding used in URLs.
*
* Additionally, continuations and encoding are mixed in an, errrm,
if (!(s = strchr(p->attribute, '*')))
{
/*
- * Using RFC 2047 encoding in MIME parameters is explicitly
+ * Using RFC2047 encoding in MIME parameters is explicitly
* forbidden by that document. Nevertheless, it's being
* generated by some software, including certain Lotus Notes to
* Internet Gateways. So we actually decode it.
/**
* @file
- * RFC 2231 MIME Charset routines
+ * RFC2231 MIME Charset routines
*
* @authors
* Copyright (C) 1999-2000 Thomas Roessler <roessler@does-not-exist.org>
/**
* @file
- * RFC 3676 Format Flowed routines
+ * RFC3676 Format Flowed routines
*
* @authors
* Copyright (C) 2005 Andreas Krennmair <ak@synflood.at>
fst->spaces = 0;
}
+/**
+ * rfc3676_handler - body handler implementing RFC3676 for format=flowed
+ */
int rfc3676_handler(struct Body *a, struct State *s)
{
char *buf = NULL, *t = NULL;
newql = get_quote_level(buf);
/* end flowed paragraph (if we're within one) if quoting level
- * changes (should not but can happen, see RFC 3676, sec. 4.5.)
+ * changes (should not but can happen, see RFC3676, sec. 4.5.)
*/
if (newql != quotelevel)
flush_par(s, &fst);
/**
* @file
- * RFC 3676 Format Flowed routines
+ * RFC3676 Format Flowed routines
*
* @authors
* Copyright (C) 2005 Andreas Krennmair <ak@synflood.at>
struct Header;
struct State;
-/* body handler implementing RfC 3676 for format=flowed */
int rfc3676_handler(struct Body *a, struct State *s);
-
-/* this does the space-stuffing for RfC3676 style messages */
void rfc3676_space_stuff(struct Header *hdr);
#endif /* _MUTT_RFC3676_H */
/**
* @file
- * RFC 822 Email format routines
+ * RFC822 Email format routines
*
* @authors
* Copyright (C) 1996-2000 Michael R. Elkins <me@mutt.org>
/**
* @file
- * RFC 822 Email format routines
+ * RFC822 Email format routines
*
* @authors
* Copyright (C) 1996-2000 Michael R. Elkins <me@mutt.org>
* addrcmp - compare two e-mail addresses
* @param a Address 1
* @param b Address 2
- * @return true if they are equivalent
+ * @retval true if they are equivalent
*/
static bool addrcmp(struct Address *a, struct Address *b)
{
* @param flags compose mode
* @param ctx current mailbox
* @param cur current message
- * @return 0 on success, -1 on error
+ * @retval 0 on success
+ * @retval -1 on error
*/
static int generate_body(FILE *tempfp, struct Header *msg, int flags,
struct Context *ctx, struct Header *cur)
* @param tempfile file specified by -i or -H
* @param ctx current mailbox
* @param cur current message
- * @return
- *
- * * 0 Message was successfully sent
- * * -1 Message was aborted or an error occurred
- * * 1 Message was postponed
+ * @retval 0 Message was successfully sent
+ * @retval -1 Message was aborted or an error occurred
+ * @retval 1 Message was postponed
*/
int ci_send_message(int flags, struct Header *msg, char *tempfile,
struct Context *ctx, struct Header *cur)
* @param[in] tocodes List of target encodings
* @param[out] tocode Chosen encoding
* @param[in] info Encoding information
- * @return
- * * -1 Error, no conversion was possible
- * * >0 Success, number of bytes converted
+ * @retval -1 Error, no conversion was possible
+ * @retval >0 Success, number of bytes converted
*
* Find the best charset conversion of the file from fromcode into one
* of the tocodes. If successful, set *tocode and Content *info and
* mutt_lookup_mime_type - Find the MIME type for an attachment
* @param att Email with attachment
* @param path Path to attachment
- * @return MIME type, e.g. #TYPEIMAGE
+ * @retval n MIME type, e.g. #TYPEIMAGE
*
* Given a file at `path`, see if there is a registered MIME type.
* Returns the major MIME type, and copies the subtype to ``d''. First look
/**
* check_boundary - check for duplicate boundary
- * @return true if duplicate found
+ * @retval true if duplicate found
*/
static bool check_boundary(const char *boundary, struct Body *b)
{
* @param[in] elsestring Otherwise, display this string
* @param[in] data Pointer to our sidebar_entry
* @param[in] flags Format flags, e.g. MUTT_FORMAT_OPTIONAL
- * @return src (unchanged)
+ * @retval src (unchanged)
*
* cb_format_str is a callback function for mutt_expando_format. It understands
* six operators. '%B' : Mailbox name, '%F' : Number of flagged messages,
* cb_qsort_sbe - qsort callback to sort SBENTRYs
* @param a First SbEntry to compare
* @param b Second SbEntry to compare
- * @return
- * * -1: a precedes b
- * * 0: a and b are identical
- * * 1: b precedes a
+ * @retval -1 a precedes b
+ * @retval 0 a and b are identical
+ * @retval 1 b precedes a
*/
static int cb_qsort_sbe(const void *a, const void *b)
{
/**
* select_next - Selects the next unhidden mailbox
- * @return true: Success, false: Failure
+ * @retval true Success
+ * @retval false Failure
*/
static bool select_next(void)
{
/**
* select_next_new - Selects the next new mailbox
- * @return true: Success, false: Failure
+ * @retval true Success
+ * @retval false Failure
*
* Search down the list of mail folders for one containing new mail.
*/
/**
* select_prev - Selects the previous unhidden mailbox
- * @return true: Success, false: Failure
+ * @retval true Success
+ * @retval false Failure
*/
static bool select_prev(void)
{
/**
* select_prev_new - Selects the previous new mailbox
- * @return true: Success, false: Failure
+ * @retval true Success
+ * @retval false Failure
*
* Search up the list of mail folders for one containing new mail.
*/
/**
* select_page_down - Selects the first entry in the next page of mailboxes
- * @return true: Success, false: Failure
+ * @retval true Success
+ * @retval false Failure
*/
static int select_page_down(void)
{
/**
* select_page_up - Selects the last entry in the previous page of mailboxes
- * @return true: Success, false: Failure
+ * @retval true Success
+ * @retval false Failure
*/
static int select_page_up(void)
{
/**
* prepare_sidebar - Prepare the list of SBENTRYs for the sidebar display
* @param page_size The number of lines on a page
- * @return
- * * false: No, don't draw the sidebar
- * * true: Yes, draw the sidebar
+ * @retval false No, don't draw the sidebar
+ * @retval true Yes, draw the sidebar
*
* Before painting the sidebar, we determine which are visible, sort
* them and set up our page pointers.
* draw_divider - Draw a line between the sidebar and the rest of mutt
* @param num_rows Height of the Sidebar
* @param num_cols Width of the Sidebar
- * @return
- * * 0: Empty string
- * * n: Character occupies n screen columns
+ * @retval 0 Empty string
+ * @retval n Character occupies n screen columns
*
* Draw a divider using characters from the config option "sidebar_divider_char".
* This can be an ASCII or Unicode character.
* On the first run they'll be NULL, so we display the top of Mutt's list
* (Incoming).
*
- * TopBuffy - first visible mailbox
- * BotBuffy - last visible mailbox
- * OpnBuffy - mailbox shown in Mutt's Index Panel
- * HilBuffy - Unselected mailbox (the paging follows this)
+ * * TopBuffy - first visible mailbox
+ * * BotBuffy - last visible mailbox
+ * * OpnBuffy - mailbox shown in Mutt's Index Panel
+ * * HilBuffy - Unselected mailbox (the paging follows this)
*
* The entries are formatted using "sidebar_format" and may be abbreviated:
* "sidebar_short_path", indented: "sidebar_folder_indent",
/**
* mutt_sb_get_highlight - Get the Buffy that's highlighted in the sidebar
- * @return mailbox path
+ * @retval string Mailbox path
*
* Get the path of the mailbox that's highlighted in the sidebar.
*/
/**
* smtp_get_resp - Read a command response from the SMTP server
* @param conn SMTP connection
- * @return
- * * 0 Success (2xx code) or continue (354 code)
- * * -1 Write error, or any other response code
+ * @retval 0 Success (2xx code) or continue (354 code)
+ * @retval -1 Write error, or any other response code
*/
static int smtp_get_resp(struct Connection *conn)
{
/**
* address_uses_unicode - Do any addresses use Unicode
- * @return true if any of the string of addresses use 8-bit characters
+ * @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
- * @return true if any use 8-bit characters
+ * @retval true if any use 8-bit characters
*/
static bool addresses_use_unicode(const struct Address *a)
{
struct Address;
struct Context;
-#define SORT_DATE 1 /* the date the mail was sent. */
+#define SORT_DATE 1 /**< the date the mail was sent. */
#define SORT_SIZE 2
#define SORT_SUBJECT 3
-#define SORT_ALPHA 3 /* makedoc.c requires this */
+#define SORT_ALPHA 3 /**< makedoc.c requires this */
#define SORT_FROM 4
-#define SORT_ORDER 5 /* the order the messages appear in the mailbox. */
+#define SORT_ORDER 5 /**< the order the messages appear in the mailbox. */
#define SORT_THREADS 6
-#define SORT_RECEIVED 7 /* when the message were delivered locally */
+#define SORT_RECEIVED 7 /**< when the message were delivered locally */
#define SORT_TO 8
#define SORT_SCORE 9
#define SORT_ALIAS 10
* @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
+ * @retval n Index into the virtual email table
*/
int _mutt_aside_thread(struct Header *hdr, short dir, short subthreads)
{
/**
* rstrip_in_place - Strip a trailing carriage return
* @param s String to be modified
- * @return The modified string
+ * @retval string The modified string
*
* The string has its last carriage return set to NUL.
*/
/**
* feature_enabled - Test if a compile-time feature is enabled
* @param name Compile-time symbol of the feature
- * @return
- * * true: Feature enabled
- * * false: Feature not enabled, or not compiled in
+ * @retval true Feature enabled
+ * @retval false Feature not enabled, or not compiled in
*
* Many of the larger features of mutt can be disabled at compile time.
* They define a symbol and use ifdef's around their code.
projects / neomutt / commitdiff