* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* IMAP login/authentication code */
+/**
+ * @page imap_auth IMAP authenticator multiplexor
+ *
+ * IMAP authenticator multiplexor
+ *
+ * | Function | Description
+ * | :------------------ | :-------------------------------------------------
+ * | imap_authenticate() | Authenticate to an IMAP server
+ */
#include "config.h"
#include <string.h>
#include "globals.h"
#include "protos.h"
+/**
+ * imap_authenticators - Accepted authentication methods
+ */
static const struct ImapAuth imap_authenticators[] = {
{ imap_auth_plain, "plain" },
#ifdef USE_SASL
/**
* imap_authenticate - Authenticate to an IMAP server
+ * @param idata Server data
+ * @retval num Result, e.g. #IMAP_AUTH_SUCCESS
*
* Attempt to authenticate using either user-specified authentication method if
* specified, or any.
/* common defs for authenticators. A good place to set up a generic callback
* system */
-#ifndef _MUTT_IMAP_AUTH_H
-#define _MUTT_IMAP_AUTH_H
+#ifndef _IMAP_AUTH_H
+#define _IMAP_AUTH_H
struct ImapData;
enum ImapAuthRes imap_auth_sasl(struct ImapData *idata, const char *method);
#endif
-#endif /* _MUTT_IMAP_AUTH_H */
+#endif /* _IMAP_AUTH_H */
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* IMAP login/authentication code */
+/**
+ * @page imap_auth_anon IMAP anonymous authentication method
+ *
+ * IMAP anonymous authentication method
+ *
+ * | Function | Description
+ * | :----------------- | :-------------------------------------------------
+ * | imap_auth_anon() | Authenticate anonymously
+ */
#include "config.h"
#include "imap_private.h"
/**
* imap_auth_anon - Authenticate anonymously
+ * @param idata Server data
+ * @param method Name of this authentication method
+ * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
*
* this is basically a stripped-down version of the cram-md5 method.
*/
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* IMAP login/authentication code */
+/**
+ * @page imap_auth_crap IMAP CRAM-MD5 authentication method
+ *
+ * IMAP CRAM-MD5 authentication method
+ *
+ * | Function | Description
+ * | :------------------- | :-------------------------------------------------
+ * | imap_auth_cram_md5() | Authenticate using CRAM-MD5
+ */
#include "config.h"
#include <stdio.h>
#define MD5_DIGEST_LEN 16
/**
- * hmac_md5 - hmac_md5: produce CRAM-MD5 challenge response
+ * hmac_md5 - produce CRAM-MD5 challenge response
+ * @param[in] password Password to encrypt
+ * @param[in] challenge Challenge from server
+ * @param[out] response Buffer for the response
*/
static void hmac_md5(const char *password, char *challenge, unsigned char *response)
{
}
/**
- * imap_auth_cram_md5 - imap_auth_cram_md5: AUTH=CRAM-MD5 support
+ * imap_auth_cram_md5 - Authenticate using CRAM-MD5
+ * @param idata Server data
+ * @param method Name of this authentication method
+ * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
*/
enum ImapAuthRes imap_auth_cram_md5(struct ImapData *idata, const char *method)
{
hmac_response[13], hmac_response[14], hmac_response[15]);
mutt_debug(2, "CRAM response: %s\n", obuf);
- /* XXX - ibuf must be long enough to store the base64 encoding of obuf,
- * plus the additional debris
- */
-
+ /* ibuf must be long enough to store the base64 encoding of obuf,
+ * plus the additional debris */
mutt_to_base64(ibuf, obuf, strlen(obuf), sizeof(ibuf) - 2);
safe_strcat(ibuf, sizeof(ibuf), "\r\n");
mutt_socket_write(idata->conn, ibuf);
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* GSS login/authentication code */
+/**
+ * @page imap_auth_gss IMAP GSS authentication method
+ *
+ * IMAP GSS authentication method
+ *
+ * | Function | Description
+ * | :----------------- | :-------------------------------------------------
+ * | imap_auth_gss() | GSS Authentication support
+ */
#include "config.h"
#include <netinet/in.h>
#define GSS_AUTH_P_NONE 1
#define GSS_AUTH_P_INTEGRITY 2
#define GSS_AUTH_P_PRIVACY 4
+
+/**
+ * print_gss_error - Print detailed error message to the debug log
+ * @param err_maj Error's major number
+ * @param err_min Error's minor number
+ */
static void print_gss_error(OM_uint32 err_maj, OM_uint32 err_min)
{
OM_uint32 maj_stat, min_stat;
/**
* imap_auth_gss - GSS Authentication support
+ * @param idata Server data
+ * @param method Name of this authentication method
+ * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
*/
enum ImapAuthRes imap_auth_gss(struct ImapData *idata, const char *method)
{
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* plain LOGIN support */
+/**
+ * @page imap_auth_login IMAP login authentication method
+ *
+ * IMAP login authentication method
+ *
+ * | Function | Description
+ * | :----------------- | :-------------------------------------------------
+ * | imap_auth_login() | Plain LOGIN support
+ */
#include "config.h"
#include <stdio.h>
/**
* imap_auth_login - Plain LOGIN support
+ * @param idata Server data
+ * @param method Name of this authentication method
+ * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
*/
enum ImapAuthRes imap_auth_login(struct ImapData *idata, const char *method)
{
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* SASL PLAIN support */
+/**
+ * @page imap_auth_plain IMAP plain authentication method
+ *
+ * IMAP plain authentication method
+ *
+ * | Function | Description
+ * | :----------------- | :-------------------------------------------------
+ * | imap_auth_plain() | SASL PLAIN support
+ */
#include "config.h"
#include "imap_private.h"
/**
* imap_auth_plain - SASL PLAIN support
+ * @param idata Server data
+ * @param method Name of this authentication method
+ * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
*/
enum ImapAuthRes imap_auth_plain(struct ImapData *idata, const char *method)
{
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* SASL login/authentication code */
+/**
+ * @page imap_auth_sasl IMAP SASL authentication method
+ *
+ * IMAP SASL authentication method
+ *
+ * | Function | Description
+ * | :----------------- | :-------------------------------------------------
+ * | imap_auth_sasl() | Default authenticator if available
+ */
#include "config.h"
#include <stddef.h>
/**
* imap_auth_sasl - Default authenticator if available
+ * @param idata Server data
+ * @param method Name of this authentication method
+ * @retval enum Result, e.g. #IMAP_AUTH_SUCCESS
*/
enum ImapAuthRes imap_auth_sasl(struct ImapData *idata, const char *method)
{
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* NeoMutt browser support routines */
+/**
+ * @page imap_browse Mailbox browser
+ *
+ * GUI select an IMAP mailbox from a list
+ *
+ * | Function | Description
+ * | :-------------------- | :-------------------------------------------------
+ * | imap_browse() | IMAP hook into the folder browser
+ * | imap_mailbox_create() | Create a new IMAP mailbox
+ * | imap_mailbox_rename() | Rename a mailbox
+ */
#include "config.h"
#ifdef ENABLE_NLS
/**
* add_folder - Format and add an IMAP folder to the browser
+ * @param delim Path delimiter
+ * @param folder Name of the folder
+ * @param noselect true if item isn't selectable
+ * @param noinferiors true if item has no children
+ * @param state Browser state to add to
+ * @param isparent true if item represents the parent folder
*
* The folder parameter should already be 'unmunged' via
* imap_unmunge_mbox_name().
FREE(&mx.mbox);
}
+/**
+ * browse_add_list_result - Add entries to the folder browser
+ * @param idata Server data
+ * @param cmd Command string from server
+ * @param state Browser state to add to
+ * @param isparent Is this a shortcut for the parent directory?
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int browse_add_list_result(struct ImapData *idata, const char *cmd,
struct BrowserState *state, short isparent)
{
/**
* imap_browse - IMAP hook into the folder browser
+ * @param path Current folder
+ * @param state BrowserState to populate
+ * @retval 0 Success
+ * @retval -1 Failure
*
* Fill out browser_state, given a current folder to browse
*/
/**
* imap_mailbox_create - Create a new IMAP mailbox
+ * @param folder Mailbox to create
+ * @retval 0 Success
+ * @retval -1 Failure
*
* Prompt for a new mailbox name, and try to create it
*/
return -1;
}
+/**
+ * imap_mailbox_rename - Rename a mailbox
+ * @param mailbox Mailbox to rename
+ * @retval 0 Success
+ * @retval -1 Failure
+ *
+ * The user will be prompted for a new name.
+ */
int imap_mailbox_rename(const char *mailbox)
{
struct ImapData *idata = NULL;
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* command.c: routines for sending commands to an IMAP server and parsing
- * responses */
+/**
+ * @page imap_command Send/receive commands to/from an IMAP server
+ *
+ * Send/receive commands to/from an IMAP server
+ *
+ * | Function | Description
+ * | :----------------- | :-------------------------------------------------
+ * | imap_cmd_finish() | Attempt to perform cleanup
+ * | imap_cmd_idle() | Enter the IDLE state
+ * | imap_cmd_start() | Given an IMAP command, send it to the server
+ * | imap_cmd_step() | Reads server responses from an IMAP command
+ * | imap_cmd_trailer() | Extra information after tagged command response if any
+ * | imap_code() | Was the command successful
+ * | imap_exec() | Execute a command and wait for the response from the server
+ */
#include "config.h"
#include <ctype.h>
#define IMAP_CMD_BUFSIZE 512
+/**
+ * Capabilities - Server capabilties strings that we understand
+ */
static const char *const Capabilities[] = {
"IMAP4", "IMAP4rev1", "STATUS", "ACL", "NAMESPACE",
"AUTH=CRAM-MD5", "AUTH=GSSAPI", "AUTH=ANONYMOUS", "STARTTLS", "LOGINDISABLED",
"IDLE", "SASL-IR", "X-GM-EXT1", "ENABLE", NULL,
};
-/* Gmail document one string but use another. Support both. */
-
/**
* struct CapabilityAlias - Alternative names for capabilities
*/
unsigned int value;
};
+/**
+ * CapabilityAliases - Alternate capability strings (for compatibility)
+ */
static struct CapabilityAlias CapabilityAliases[] = {
- { "X-GM-EXT-1", X_GM_EXT1 }, { NULL, 0 },
+ /* Gmail documents one string but use another. Support both. */
+ { "X-GM-EXT-1", X_GM_EXT1 },
+ { NULL, 0 },
};
+/**
+ * cmd_queue_full - Is the IMAP command queue full?
+ * @param idata Server data
+ * @retval true Queue is full
+ */
static bool cmd_queue_full(struct ImapData *idata)
{
if ((idata->nextcmd + 1) % idata->cmdslots == idata->lastcmd)
* cmd_new - Create and queue a new command control block
* @param idata IMAP data
* @retval NULL if the pipeline is full
+ * @retval ptr New command
*/
static struct ImapCommand *cmd_new(struct ImapData *idata)
{
/**
* cmd_queue - Add a IMAP command to the queue
+ * @param idata Server data
+ * @param cmdstr Command string
+ * @param flags Server flags, e.g. #IMAP_CMD_POLL
+ * @retval 0 Success
+ * @retval <0 Failure, e.g. #IMAP_CMD_BAD
*
* If the queue is full, attempts to drain it.
*/
/**
* cmd_handle_fatal - When ImapData is in fatal state, do what we can
+ * @param idata Server data
*/
static void cmd_handle_fatal(struct ImapData *idata)
{
}
}
+/**
+ * cmd_start - Start a new IMAP command
+ * @param idata Server data
+ * @param cmdstr Command string
+ * @param flags Command flags, e.g. #IMAP_CMD_QUEUE
+ * @retval 0 Success
+ * @retval <0 Failure, e.g. #IMAP_CMD_BAD
+ */
static int cmd_start(struct ImapData *idata, const char *cmdstr, int flags)
{
int rc;
/**
* cmd_status - parse response line for tagged OK/NO/BAD
+ * @param s Status string from server
+ * @retval 0 Success
+ * @retval <0 Failure, e.g. #IMAP_CMD_BAD
*/
static int cmd_status(const char *s)
{
/**
* cmd_parse_expunge - Parse expunge command
+ * @param idata Server data
+ * @param s String containing MSN of message to expunge
*
* cmd_parse_expunge: mark headers with new sequence ID and mark idata to be
* reopened at our earliest convenience
/**
* cmd_parse_fetch - Load fetch response into ImapData
+ * @param idata Server data
+ * @param s String containing MSN of message to fetch
*
* Currently only handles unanticipated FETCH responses, and only FLAGS data.
* We get these if another client has changed flags for a mailbox we've
/**
* cmd_parse_capability - set capability bits according to CAPABILITY response
+ * @param idata Server data
+ * @param s Command string with capabilities
*/
static void cmd_parse_capability(struct ImapData *idata, char *s)
{
}
}
+/**
+ * cmd_parse_list - Parse a server LIST command (list mailboxes)
+ * @param idata Server data
+ * @param s Command string with folder list
+ */
static void cmd_parse_list(struct ImapData *idata, char *s)
{
struct ImapList *list = NULL;
}
}
+/**
+ * cmd_parse_lsub - Parse a server LSUB (list subscribed mailboxes)
+ * @param idata Server data
+ * @param s Command string with folder list
+ */
static void cmd_parse_lsub(struct ImapData *idata, char *s)
{
char buf[STRING];
/**
* cmd_parse_myrights - Set rights bits according to MYRIGHTS response
+ * @param idata Server data
+ * @param s Command string with rights info
*/
static void cmd_parse_myrights(struct ImapData *idata, const char *s)
{
/**
* cmd_parse_search - store SEARCH response for later use
+ * @param idata Server data
+ * @param s Command string with search results
*/
static void cmd_parse_search(struct ImapData *idata, const char *s)
{
/**
* cmd_parse_status - Parse status from server
+ * @param idata Server data
+ * @param s Command string with status info
*
* first cut: just do buffy update. Later we may wish to cache all mailbox
* information, even that not desired by buffy
/**
* cmd_parse_enabled - Record what the server has enabled
+ * @param idata Server data
+ * @param s Command string containing acceptable encodings
*/
static void cmd_parse_enabled(struct ImapData *idata, const char *s)
{
/**
* cmd_handle_untagged - fallback parser for otherwise unhandled messages
+ * @param idata Server data
+ * @retval 0 Success
+ * @retval -1 Failure
*/
static int cmd_handle_untagged(struct ImapData *idata)
{
/**
* imap_cmd_start - Given an IMAP command, send it to the server
+ * @param idata Server data
+ * @param cmdstr Command string to send
+ * @retval 0 Success
+ * @retval <0 Failure, e.g. #IMAP_CMD_BAD
*
* If cmdstr is NULL, sends queued commands.
*/
/**
* imap_cmd_step - Reads server responses from an IMAP command
+ * @param idata Server data
+ * @retval 0 Success
+ * @retval <0 Failure, e.g. #IMAP_CMD_BAD
*
* detects tagged completion response, handles untagged messages, can read
* arbitrarily large strings (using malloc, so don't make it _too_ large!).
/**
* imap_code - Was the command successful
* @param s IMAP command status
- * @retval 1 if the command result was OK
- * @retval 0 if NO or BAD
+ * @retval 1 Command result was OK
+ * @retval 0 If NO or BAD
*/
bool imap_code(const char *s)
{
/**
* imap_cmd_trailer - Extra information after tagged command response if any
+ * @param idata Server data
+ * @retval ptr Extra command information (pointer into idata->buf)
+ * @retval "" Error (static string)
*/
const char *imap_cmd_trailer(struct ImapData *idata)
{
* @param idata IMAP data
* @param cmdstr Command to execute
* @param flags Flags (see below)
- * @retval 0 on success
- * @retval -1 on Failure
- * @retval -2 on OK Failure
+ * @retval 0 Success
+ * @retval -1 Failure
+ * @retval -2 OK Failure
*
* Also, handle untagged responses.
*
/**
* imap_cmd_finish - Attempt to perform cleanup
+ * @param idata Server data
*
* Attempts to perform cleanup (eg fetch new mail if detected, do expunge).
* Called automatically by imap_cmd_step(), but may be called at any time.
/**
* imap_cmd_idle - Enter the IDLE state
+ * @param idata Server data
+ * @retval 0 Success
+ * @retval <0 Failure, e.g. #IMAP_CMD_BAD
*/
int imap_cmd_idle(struct ImapData *idata)
{
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* Support for IMAP4rev1, with the occasional nod to IMAP 4. */
+/**
+ * @page imap_imap IMAP network mailbox
+ *
+ * Support for IMAP4rev1, with the occasional nod to IMAP 4.
+ *
+ * | Function | Description
+ * | :--------------------------- | :-------------------------------------------------
+ * | imap_access() | Check permissions on an IMAP mailbox
+ * | imap_buffy_check() | Check for new mail in subscribed folders
+ * | imap_check() | Check for new mail
+ * | imap_check_mailbox() | use the NOOP or IDLE command to poll for new mail
+ * | imap_close_connection() | Close an IMAP connection
+ * | imap_complete() | Try to complete an IMAP folder path
+ * | imap_conn_find() | Find an open IMAP connection
+ * | imap_create_mailbox() | Create a new mailbox
+ * | imap_delete_mailbox() | Delete a mailbox
+ * | imap_exec_msgset() | Prepare commands for all messages matching conditions
+ * | imap_expunge_mailbox() | Purge messages from the server
+ * | imap_fast_trash() | Use server COPY command to copy deleted messages to trash
+ * | imap_has_flag() | Does the flag exist in the list
+ * | imap_logout() | Gracefully log out of server
+ * | imap_logout_all() | close all open connections
+ * | imap_mboxcache_free() | Free the cached ImapStatus
+ * | imap_mboxcache_get() | Open an hcache for a mailbox
+ * | imap_open_connection() | Open an IMAP connection
+ * | imap_read_literal() | Read bytes bytes from server into file
+ * | imap_rename_mailbox() | Rename a mailbox
+ * | imap_search() | Find a matching mailbox
+ * | imap_status() | Get the status of a mailbox
+ * | imap_subscribe() | Subscribe to a mailbox
+ * | imap_sync_message_for_copy() | Update server to reflect the flags of a single message
+ *
+ * | Data | Description
+ * | :----------------- | :--------------------------------------------------
+ * | #mx_comp_ops | Mailbox callback functions
+ *
+ * | Function | Description
+ * | :-------------------------- | :-------------------------------------------------
+ * | imap_check_mailbox_reopen() | Check for new mail (reopen mailbox if necessary)
+ * | imap_close_mailbox() | Clean up IMAP data in Context
+ * | imap_commit_message_tags() | Add/Change/Remove flags from headers
+ * | imap_edit_message_tags() | Prompt and validate new messages tags
+ * | imap_open_mailbox() | Open an IMAP mailbox
+ * | imap_open_mailbox_append() | Open an IMAP mailbox to append
+ * | imap_open_new_message() | Open an IMAP message
+ * | imap_sync_mailbox() | Sync all the changes to the server
+ */
#include "config.h"
#include <ctype.h>
/**
* check_capabilities - Make sure we can log in to this server
+ * @param idata Server data
+ * @retval 0 Success
+ * @retval -1 Failure
*/
static int check_capabilities(struct ImapData *idata)
{
/**
* get_flags - Make a simple list out of a FLAGS response
+ * @param hflags List to store flags
+ * @param s String containing flags
+ * @retval ptr End of the flags
+ * @retval ptr NULL Failure
*
* return stream following FLAGS response
*/
}
/**
- * set_flag - append str to flags if we currently have permission
- *
- * according to aclbit
+ * set_flag - append str to flags if we currently have permission according to aclbit
+ * @param[in] idata Server data
+ * @param[in] aclbit Permissions, e.g. #MUTT_ACL_WRITE
+ * @param[in] flag Does the email have the flag set?
+ * @param[in] str Server flag name
+ * @param[out] flags Buffer for server command
+ * @param[in] flsize Length of buffer
*/
static void set_flag(struct ImapData *idata, int aclbit, int flag,
const char *str, char *flags, size_t flsize)
/**
* make_msg_set - Make a message set
+ * @param[in] idata Server data
+ * @param[in] buf Buffer to store message set
+ * @param[in] flag Flags to match, e.g. #MUTT_DELETED
+ * @param[in] changed Matched messages that have been altered
+ * @param[in] invert Flag matches should be inverted
+ * @param[out] pos Cursor used for multiple calls to this function
+ * @retval num Number of message in the set
*
- * Note: headers must be in SORT_ORDER. See imap_exec_msgset for args.
+ * Note: headers must be in SORT_ORDER. See imap_exec_msgset() for args.
* Pos is an opaque pointer a la strtok. It should be 0 at first call.
*/
static int make_msg_set(struct ImapData *idata, struct Buffer *buf, int flag,
/**
* compare_flags_for_copy - Compare local flags against the server
- * @retval 0 if neomutt's flags match cached server flags
- * EXCLUDING the deleted flag.
+ * @param h Header of email
+ * @retval true Flags have changed
+ * @retval false Flags match cached server flags
+ *
+ * The comparison of flags EXCLUDES the deleted flag.
*/
static bool compare_flags_for_copy(struct Header *h)
{
return false;
}
+/**
+ * sync_helper - Sync flag changes to the server
+ * @param idata Server data
+ * @param right ACL, e.g. #MUTT_ACL_DELETE
+ * @param flag Mutt flag, e.g. MUTT_DELETED
+ * @param name Name of server flag
+ * @retval >=0 Success, number of messages
+ * @retval -1 Failure
+ */
static int sync_helper(struct ImapData *idata, int right, int flag, const char *name)
{
int count = 0;
}
/**
- * get_mailbox - split path into (idata,mailbox name)
+ * get_mailbox - Split mailbox URI
+ * @param path Mailbox URI
+ * @param hidata Server data
+ * @param buf Buffer to store mailbox name
+ * @param blen Length of buffer
+ * @retval 0 Success
+ * @retval -1 Failure
+ *
+ * Split up a mailbox URI. The connection info is stored in the ImapData and
+ * the mailbox name is stored in buf.
*/
static int get_mailbox(const char *path, struct ImapData **hidata, char *buf, size_t blen)
{
/**
* do_search - Perform a search of messages
+ * @param search List of pattern to match
+ * @param allpats Must all patterns match?
+ * @retval num Number of patterns search that should be done server-side
*
- * returns number of patterns in the search that should be done server-side
- * (eg are full-text)
+ * Count the number of patterns that can be done by the server (are full-text).
*/
static int do_search(const struct Pattern *search, int allpats)
{
/**
* compile_search - Convert NeoMutt pattern to IMAP search
+ * @param ctx Context
+ * @param pat Pattern to convert
+ * @param buf Buffer for result
+ * @retval 0 Success
+ * @retval -1 Failure
*
* Convert neomutt Pattern to IMAP SEARCH command containing only elements
* that require full-text search (neomutt already has what it needs for most
/**
* complete_hosts - Look for completion matches for mailboxes
+ * @param dest Partial mailbox name to complete
+ * @param len Length of buffer
+ * @retval 0 Success
+ * @retval -1 Failure
*
* look for IMAP URLs to complete from defined mailboxes. Could be extended to
* complete over open connections and account/folder hooks too.
/**
* imap_access - Check permissions on an IMAP mailbox
+ * @param path Mailbox path
+ * @retval 0 Success
+ * @retval <0 Failure
*
* TODO: ACL checks. Right now we assume if it exists we can mess with it.
*/
return 0;
}
+/**
+ * imap_create_mailbox - Create a new mailbox
+ * @param idata Server data
+ * @param mailbox Mailbox to create
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_create_mailbox(struct ImapData *idata, char *mailbox)
{
char buf[LONG_STRING], mbox[LONG_STRING];
return 0;
}
+/**
+ * imap_rename_mailbox - Rename a mailbox
+ * @param idata Server data
+ * @param mx Existing mailbox
+ * @param newname New name for mailbox
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_rename_mailbox(struct ImapData *idata, struct ImapMbox *mx, const char *newname)
{
char oldmbox[LONG_STRING];
return 0;
}
+/**
+ * imap_delete_mailbox - Delete a mailbox
+ * @param ctx Context
+ * @param mx Mailbox to delete
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_delete_mailbox(struct Context *ctx, struct ImapMbox *mx)
{
char buf[LONG_STRING], mbox[LONG_STRING];
/**
* imap_read_literal - Read bytes bytes from server into file
+ * @param fp File handle for email file
+ * @param idata Server data
+ * @param bytes Number of bytes to read
+ * @param pbar Progress bar
+ * @retval 0 Success
+ * @retval -1 Failure
*
* Not explicitly buffered, relies on FILE buffering. NOTE: strips `\r` from
* `\r\n`. Apparently even literals use `\r\n`-terminated strings ?!
/**
* imap_expunge_mailbox - Purge messages from the server
+ * @param idata Server data
*
* Purge IMAP portion of expunged messages from the context. Must not be done
* while something has a handle on any headers (eg inside pager or editor).
/**
* imap_conn_find - Find an open IMAP connection
+ * @param account Account to search
+ * @param flags Flags, e.g. #MUTT_IMAP_CONN_NONEW
+ * @retval ptr Matching connection
+ * @retval NULL Failure
*
* Find an open IMAP connection matching account, or open a new one if none can
* be found.
return idata;
}
+/**
+ * imap_open_connection - Open an IMAP connection
+ * @param idata Server data
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_open_connection(struct ImapData *idata)
{
char buf[LONG_STRING];
return -1;
}
+/**
+ * imap_close_connection - Close an IMAP connection
+ * @param idata Server data
+ */
void imap_close_connection(struct ImapData *idata)
{
if (idata->state != IMAP_DISCONNECTED)
/**
* imap_logout - Gracefully log out of server
+ * @param idata Server data
*/
void imap_logout(struct ImapData **idata)
{
/**
* imap_has_flag - Does the flag exist in the list
- * @retval boolean
+ * @param flag_list List of server flags
+ * @param flag Flag to find
+ * @retval true Flag exists
*
* Do a caseless comparison of the flag against a flag list, return true if
* found or flag list has '\*'.
/**
* imap_sync_message_for_copy - Update server to reflect the flags of a single message
+ * @param[in] idata Server data
+ * @param[in] hdr Header of the email
+ * @param[in] cmd Buffer for the command string
+ * @param[out] err_continue Did the user force a continue?
+ * @retval 0 Success
+ * @retval -1 Failure
*
* Update the IMAP server to reflect the flags for a single message before
* performing a "UID COPY".
return imap_check(ctx->data, force);
}
+/**
+ * imap_check - Check for new mail
+ * @param idata Server data
+ * @param force Force a refresh
+ * @retval >0 Success, e.g. #MUTT_REOPENED
+ * @retval -1 Failure
+ */
int imap_check(struct ImapData *idata, int force)
{
/* overload keyboard timeout to avoid many mailbox checks in a row.
/**
* imap_buffy_check - Check for new mail in subscribed folders
+ * @param force Force an update
+ * @param check_stats Check for message stats too
+ * @retval num Number of mailboxes with new mail
+ * @retval 0 Failure
+ *
+ * @note Returns 0 on failure
*
* Given a list of mailboxes rather than called once for each so that it can
* batch the commands and save on round trips. Returns number of mailboxes with
/**
* imap_status - Get the status of a mailbox
- * @retval -1 on error
- * @retval >=0 count of messages in mailbox
+ * @param path Path of mailbox
+ * @param queue true if the command should be queued for the next call
+ * @retval -1 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)
+ * If queue is true, the command will be sent now and be expected to have been
+ * run on the next call (for pipelining the postponed count).
*/
int imap_status(char *path, int queue)
{
/**
* imap_mboxcache_get - Open an hcache for a mailbox
+ * @param idata Server data
+ * @param mbox Mailbox to cache
+ * @param create Should it be created if it doesn't exist?
+ * @retval ptr Stats of cached mailbox
+ * @retval ptr Stats of new cache entry
+ * @retval NULL Not in cache and create is false
*
* return cached mailbox stats or NULL if create is 0
*/
return status;
}
+/**
+ * imap_mboxcache_free - Free the cached ImapStatus
+ * @param idata Server data
+ */
void imap_mboxcache_free(struct ImapData *idata)
{
struct ImapStatus *status = NULL;
mutt_list_free(&idata->mboxcache);
}
+/**
+ * imap_search - Find a matching mailbox
+ * @param ctx Context
+ * @param pat Pattern to match
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_search(struct Context *ctx, const struct Pattern *pat)
{
struct Buffer buf;
return 0;
}
+/**
+ * imap_subscribe - Subscribe to a mailbox
+ * @param path Mailbox path
+ * @param subscribe True: subscribe, false: unsubscribe
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_subscribe(char *path, bool subscribe)
{
struct ImapData *idata = NULL;
/**
* imap_complete - Try to complete an IMAP folder path
+ * @param dest Buffer for result
+ * @param dlen Length of buffer
+ * @param path Partial mailbox name to complete
+ * @retval 0 Success
+ * @retval -1 Failure
*
* Given a partial IMAP folder path, return a string which adds as much to the
* path as is unique
/**
* imap_fast_trash - Use server COPY command to copy deleted messages to trash
- * @retval -1 error
- * @retval 0 success
- * @retval 1 non-fatal error - try fetch/append
+ * @param ctx Context
+ * @param dest Mailbox to move to
+ * @retval -1 Error
+ * @retval 0 Success
+ * @retval 1 Non-fatal error - try fetch/append
*/
int imap_fast_trash(struct Context *ctx, char *dest)
{
return rc < 0 ? -1 : rc;
}
+/**
+ * imap_open_mailbox - Open an IMAP mailbox
+ * @param ctx Context
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int imap_open_mailbox(struct Context *ctx)
{
struct ImapData *idata = NULL;
return -1;
}
+/**
+ * imap_open_mailbox_append - Open an IMAP mailbox to append
+ * @param ctx Context
+ * @param flags Mailbox flags (UNUSED)
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int imap_open_mailbox_append(struct Context *ctx, int flags)
{
struct ImapData *idata = NULL;
/**
* imap_close_mailbox - Clean up IMAP data in Context
+ * @param ctx Context
+ * @retval 0 Always
*/
-int imap_close_mailbox(struct Context *ctx)
+static int imap_close_mailbox(struct Context *ctx)
{
struct ImapData *idata = NULL;
return 0;
}
+/**
+ * imap_open_new_message - Open an IMAP message
+ * @param msg Message to open
+ * @param dest Context (UNUSED)
+ * @param hdr Header (UNUSED)
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int imap_open_new_message(struct Message *msg, struct Context *dest, struct Header *hdr)
{
char tmp[_POSIX_PATH_MAX];
return 0;
}
+/**
+ * imap_check_mailbox_reopen - Check for new mail (reopen mailbox if necessary)
+ * @param ctx Context
+ * @param index_hint Remeber our place in the index
+ * @retval >0 Success, e.g. #MUTT_REOPENED
+ * @retval -1 Failure
+ */
static int imap_check_mailbox_reopen(struct Context *ctx, int *index_hint)
{
int rc;
return rc;
}
-/*
+/**
* imap_sync_mailbox - Sync all the changes to the server
- * @param ctx the current context
+ * @param ctx Context
* @param expunge 0 or 1 - do expunge?
- * @retval 0 on success
- * @retval -1 on error
+ * @retval 0 Success
+ * @retval -1 Error
*/
int imap_sync_mailbox(struct Context *ctx, int expunge)
{
/**
* imap_edit_message_tags - Prompt and validate new messages tags
- *
- * @retval -1: error
- * @retval 0: no valid user input
- * @retval 1: buf set
+ * @param ctx Context
+ * @param tags Existing tags
+ * @param buf Buffer to store the tags
+ * @param buflen Length of buffer
+ * @retval -1 Error
+ * @retval 0 No valid user input
+ * @retval 1 Buf set
*/
static int imap_edit_message_tags(struct Context *ctx, const char *tags, char *buf, size_t buflen)
{
return 0;
}
+/**
+ * mx_comp_ops - Mailbox callback functions
+ */
struct MxOps mx_imap_ops = {
.open = imap_open_mailbox,
.open_append = imap_open_mailbox_append,
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-#ifndef _MUTT_IMAP_H
-#define _MUTT_IMAP_H
+/**
+ * @page imap IMAP Network Mailbox
+ *
+ * IMAP network mailbox
+ *
+ * -# @subpage imap_imap
+ * -# @subpage imap_auth_anon
+ * -# @subpage imap_auth
+ * -# @subpage imap_auth_crap
+ * -# @subpage imap_auth_gss
+ * -# @subpage imap_auth_login
+ * -# @subpage imap_auth_plain
+ * -# @subpage imap_auth_sasl
+ * -# @subpage imap_browse
+ * -# @subpage imap_command
+ * -# @subpage imap_message
+ * -# @subpage imap_utf7
+ * -# @subpage imap_util
+ */
+
+#ifndef _IMAP_IMAP_H
+#define _IMAP_IMAP_H
#include <stddef.h>
#include <sys/types.h>
int imap_check_mailbox(struct Context *ctx, int force);
int imap_delete_mailbox(struct Context *ctx, struct ImapMbox *mx);
int imap_sync_mailbox(struct Context *ctx, int expunge);
-int imap_close_mailbox(struct Context *ctx);
int imap_buffy_check(int force, int check_stats);
int imap_status(char *path, int queue);
int imap_search(struct Context *ctx, const struct Pattern *pat);
void imap_get_parent_path(char *output, const char *path, size_t olen);
void imap_clean_path(char *path, size_t plen);
-#endif /* _MUTT_IMAP_H */
+#endif /* _IMAP_IMAP_H */
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-#ifndef _MUTT_IMAP_PRIVATE_H
-#define _MUTT_IMAP_PRIVATE_H
+#ifndef _IMAP_PRIVATE_H
+#define _IMAP_PRIVATE_H
#include <stdbool.h>
#include <stdio.h>
#define imap_hcache_keylen mutt_strlen
#endif /* USE_HCACHE */
-#endif /* _MUTT_IMAP_PRIVATE_H */
+#endif /* _IMAP_PRIVATE_H */
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* message parsing/updating functions */
+/**
+ * @page imap_message Manage IMAP messages
+ *
+ * Manage IMAP messages
+ *
+ * | Function | Description
+ * | :---------------------- | :-------------------------------------------------
+ * | imap_append_message() | Write an email back to the server
+ * | imap_cache_clean() | Delete all the entries in the message cache
+ * | imap_cache_del() | Delete an email from the body cache
+ * | imap_close_message() | Close an email
+ * | imap_commit_message() | Save changes to an email
+ * | imap_copy_messages() | Server COPY messages to another folder
+ * | imap_fetch_message() | Fetch an email from an IMAP server
+ * | imap_free_header_data() | free ImapHeader structure
+ * | imap_read_headers() | Read headers from the server
+ * | imap_set_flags() | fill the message header according to the server flags
+ */
#include "config.h"
#include <ctype.h>
#include "hcache/hcache.h"
#endif
+/**
+ * new_header_data - Create a new ImapHeaderData
+ * @retval ptr New ImapHeaderData
+ */
static struct ImapHeaderData *new_header_data(void)
{
struct ImapHeaderData *d = safe_calloc(1, sizeof(struct ImapHeaderData));
return d;
}
+/**
+ * update_context - Cache the headers of all the emails
+ * @param idata Server data
+ * @param oldmsgcount Number of emails
+ */
static void update_context(struct ImapData *idata, int oldmsgcount)
{
struct Context *ctx = NULL;
}
}
+/**
+ * msg_cache_open - Open a message cache
+ * @param idata Server data
+ * @retval ptr Success, using existing cache
+ * @retval ptr Success, opened new cache
+ * @retval NULL Failure
+ */
static struct BodyCache *msg_cache_open(struct ImapData *idata)
{
char mailbox[_POSIX_PATH_MAX];
return mutt_bcache_open(&idata->conn->account, mailbox);
}
+/**
+ * msg_cache_get - Get the message cache entry for an email
+ * @param idata Server data
+ * @param h Email header
+ * @retval FILE* Success, handle of cache entry
+ * @retval NULL Failure
+ */
static FILE *msg_cache_get(struct ImapData *idata, struct Header *h)
{
char id[_POSIX_PATH_MAX];
return mutt_bcache_get(idata->bcache, id);
}
+/**
+ * msg_cache_put - Put an email into the message cache
+ * @param idata Server data
+ * @param h Email header
+ * @retval FILE* Success, handle of cache entry
+ * @retval NULL Failure
+ */
static FILE *msg_cache_put(struct ImapData *idata, struct Header *h)
{
char id[_POSIX_PATH_MAX];
return mutt_bcache_put(idata->bcache, id);
}
+/**
+ * msg_cache_commit - Add to the message cache
+ * @param idata Server data
+ * @param h Email header
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
static int msg_cache_commit(struct ImapData *idata, struct Header *h)
{
char id[_POSIX_PATH_MAX];
return mutt_bcache_commit(idata->bcache, id);
}
+/**
+ * msg_cache_clean_cb - Delete an entry from the message cache
+ * @param id ID of entry to delete
+ * @param bcache BodyCache
+ * @param data Server data
+ * @retval 0 Always
+ */
static int msg_cache_clean_cb(const char *id, struct BodyCache *bcache, void *data)
{
unsigned int uv, uid;
/**
* msg_parse_flags - read a FLAGS token into an ImapHeader
+ * @param h Header to store flags
+ * @param s Command string containing flags
+ * @retval ptr The end of flags string
+ * @retval NULL Failure
*/
static char *msg_parse_flags(struct ImapHeader *h, char *s)
{
}
/**
- * msg_fetch_header -import IMAP FETCH response into an ImapHeader.
+ * msg_fetch_header - import IMAP FETCH response into an ImapHeader
+ * @param ctx Context
+ * @param h ImapHeader
+ * @param buf Server string containing FETCH response
+ * @param fp Connection to server
* @retval 0 Success
* @retval -1 String is not a fetch response
* @retval -2 String is a corrupt fetch response
return rc;
}
+/**
+ * flush_buffer - Write data to a connection
+ * @param buf Buffer containing data
+ * @param len Length of buffer
+ * @param conn Network connection
+ */
static void flush_buffer(char *buf, size_t *len, struct Connection *conn)
{
buf[*len] = '\0';
*len = 0;
}
+/**
+ * alloc_msn_index - Create lookup table of MSN to Header
+ * @param idata Server data
+ * @param msn_count Number of MSNs in use
+ *
+ * Mapping from Message Sequence Number to Header
+ */
static void alloc_msn_index(struct ImapData *idata, unsigned int msn_count)
{
unsigned int new_size;
/**
* generate_seqset - Generate a sequence set
+ * @param b Buffer for the result
+ * @param idata Server data
+ * @param msn_begin First Message Sequence number
+ * @param msn_end Last Message Sequence number
*
* Generates a more complicated sequence set after using the header cache,
* in case there are missing MSNs in the middle.
}
}
-/* Sets server_changes to 1 if a change to a flag is made, or in the
+/**
+ * set_changed_flag - Have the flags of an email changed
+ * @param[in] ctx Context
+ * @param[in] h Email Header
+ * @param[in] local_changes Has the local mailbox been changed?
+ * @param[out] server_changes Set to 1 if the flag has changed
+ * @param[in] flag_name Flag to check, e.g. #MUTT_FLAG
+ * @param[in] old_hd_flag Old header flags
+ * @param[in] new_hd_flag New header flags
+ * @param[in] h_flag Email's value for flag_name
+ *
+ * Sets server_changes to 1 if a change to a flag is made, or in the
* case of local_changes, if a change to a flag _would_ have been
- * made. */
+ * made.
+ */
static void set_changed_flag(struct Context *ctx, struct Header *h,
int local_changes, int *server_changes, int flag_name,
int old_hd_flag, int new_hd_flag, int h_flag)
/**
* imap_read_headers - Read headers from the server
+ * @param idata Server data
+ * @param msn_begin First Message Sequence Number
+ * @param msn_end Last Message Sequence Number
+ * @retval num Last MSN
+ * @retval -1 Failure
*
* Changed to read many headers instead of just one. It will return the msn of
* the last message read. It will return a value other than msn_end if mail
return retval;
}
+/**
+ * imap_fetch_message - Fetch an email from an IMAP server
+ * @param ctx Context
+ * @param msg Message to fetch
+ * @param msgno Index into ctr->hdrs
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_fetch_message(struct Context *ctx, struct Message *msg, int msgno)
{
struct ImapData *idata = NULL;
return -1;
}
+/**
+ * imap_close_message - Close an email
+ * @param ctx Context
+ * @param msg Email info
+ * @retval 0 Success
+ * @retval EOF Failure, see errno
+ */
int imap_close_message(struct Context *ctx, struct Message *msg)
{
return safe_fclose(&msg->fp);
}
+/**
+ * imap_commit_message - Save changes to an email
+ * @param ctx Context
+ * @param msg Email info
+ * @retval 0 Success
+ * @retval EOF fclose() failured, see errno
+ * @retval -1 Failure
+ */
int imap_commit_message(struct Context *ctx, struct Message *msg)
{
int r = safe_fclose(&msg->fp);
return imap_append_message(ctx, msg);
}
+/**
+ * imap_append_message - Write an email back to the server
+ * @param ctx Context
+ * @param msg Message to save
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_append_message(struct Context *ctx, struct Message *msg)
{
struct ImapData *idata = NULL;
/**
* imap_copy_messages - Server COPY messages to another folder
+ * @param ctx Context
+ * @param h Header of the email
+ * @param dest Destination folder
+ * @param delete Delete the original?
* @retval -1 Error
* @retval 0 Success
* @retval 1 Non-fatal error - try fetch/append
return rc < 0 ? -1 : rc;
}
+/**
+ * imap_cache_del - Delete an email from the body cache
+ * @param idata Server data
+ * @param h Email header
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_cache_del(struct ImapData *idata, struct Header *h)
{
char id[_POSIX_PATH_MAX];
return mutt_bcache_del(idata->bcache, id);
}
+/**
+ * imap_cache_clean - Delete all the entries in the message cache
+ * @param idata Server data
+ * @retval 0 Always
+ */
int imap_cache_clean(struct ImapData *idata)
{
idata->bcache = msg_cache_open(idata);
/**
* imap_free_header_data - free ImapHeader structure
+ * @param data Header data to free
*/
void imap_free_header_data(struct ImapHeaderData **data)
{
/**
* imap_set_flags - fill the message header according to the server flags
+ * @param[in] idata Server data
+ * @param[in] h Email Header
+ * @param[in] s Command string
+ * @param[out] server_changes Flags have changed
+ * @retval ptr The end of flags string
+ * @retval NULL Failure
*
* Expects a flags line of the form "FLAGS (flag flag ...)"
- */
-
-/* imap_set_flags: fill out the message header according to the flags from
+ *
+ * imap_set_flags: fill out the message header according to the flags from
* the server. Expects a flags line of the form "FLAGS (flag flag ...)"
*
* Sets server_changes to 1 if a change to a flag is made, or in the
* case of h->changed, if a change to a flag _would_ have been
- * made. */
+ * made.
+ */
char *imap_set_flags(struct ImapData *idata, struct Header *h, char *s, int *server_changes)
{
struct Context *ctx = idata->ctx;
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-#ifndef _MUTT_IMAP_MESSAGE_H
-#define _MUTT_IMAP_MESSAGE_H
+#ifndef _IMAP_MESSAGE_H
+#define _IMAP_MESSAGE_H
#include <stdbool.h>
#include <time.h>
#define HEADER_DATA(ph) ((struct ImapHeaderData *) ((ph)->data))
-#endif /* _MUTT_IMAP_MESSAGE_H */
+#endif /* _IMAP_MESSAGE_H */
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
+/**
+ * @page imap_utf7 UTF-7 Manipulation
+ *
+ * Convert strings to/from utf7/utf8
+ *
+ * | Function | Description
+ * | :----------------- | :-------------------------------------------------
+ * | imap_utf_decode() | Decode email from UTF-8 to local charset
+ * | imap_utf_encode() | Encode email from local charset to UTF-8
+ */
+
#include "config.h"
#include <string.h>
#include "imap_private.h"
#include "globals.h"
// clang-format off
-/* This is very similar to the table in lib/lib_base64.c
+/**
+ * Index_64u - Lookup table for Base64 encoding/decoding
+ *
+ * This is very similar to the table in lib/lib_base64.c
* Encoding chars:
* utf7 A-Za-z0-9+,
* mime A-Za-z0-9+/
};
// clang-format on
+/**
+ * B64Chars - Characters of the Base64 encoding
+ */
static const char B64Chars[64] = {
'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M',
'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
};
/**
- * utf7_to_utf8 - Convert the data (u7,u7len) from RFC2060's UTF-7 to UTF-8
+ * utf7_to_utf8 - Convert data from RFC2060's UTF-7 to UTF-8
+ * @param[in] u7 UTF-7 data
+ * @param[in] u7len Length of UTF-7 data
+ * @param[out] u8 Save the UTF-8 data pointer
+ * @param[out] u8len Save the UTF-8 data length
+ * @retval ptr UTF-8 data
+ * @retval NULL Error
*
- * 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. 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-).
+ * 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-).
+ *
+ * @note The result is null-terminated.
+ * @note The caller must free() the returned data.
*/
static char *utf7_to_utf8(const char *u7, size_t u7len, char **u8, size_t *u8len)
{
}
/**
- * utf8_to_utf7 - Convert the data (u8,u8len) from UTF-8 to RFC2060's UTF-7
+ * utf8_to_utf7 - Convert data from UTF-8 to RFC2060's UTF-7
+ * @param[in] u8 UTF-8 data
+ * @param[in] u8len Length of UTF-8 data
+ * @param[out] u7 Save the UTF-7 data pointer
+ * @param[out] u7len Save the UTF-7 data length
+ * @retval ptr UTF-7 data
+ * @retval NULL Error
+ *
+ * Unicode characters above U+FFFF are replaced by U+FFFE.
*
- * The result is null-terminated and returned, and also stored in (*u7,*u7len)
- * if u7 or u7len is non-zero. Unicode characters above U+FFFF are replaced by
- * U+FFFE. If input data is invalid, return 0 and don't store anything.
+ * @note The result is null-terminated.
+ * @note The caller must free() the returned data.
*/
static char *utf8_to_utf7(const char *u8, size_t u8len, char **u7, size_t *u7len)
{
return NULL;
}
+/**
+ * imap_utf_encode - Encode email from local charset to UTF-8
+ * @param idata Server data
+ * @param s Email to convert
+ */
void imap_utf_encode(struct ImapData *idata, char **s)
{
if (Charset)
}
}
+/**
+ * imap_utf_decode - Decode email from UTF-8 to local charset
+ * @param[in] idata Server data
+ * @param[out] s Email to convert
+ */
void imap_utf_decode(struct ImapData *idata, char **s)
{
char *t = NULL;
* this program. If not, see <http://www.gnu.org/licenses/>.
*/
-/* general IMAP utility functions */
+/**
+ * @page imap_util IMAP helper functions
+ *
+ * IMAP helper functions
+ *
+ * | Function | Description
+ * | :----------------------- | :-------------------------------------------------
+ * | imap_account_match() | Compare two Accounts
+ * | imap_allow_reopen() | Allow re-opening a folder upon expunge
+ * | imap_cachepath() | Generate a cache path for a mailbox
+ * | imap_clean_path() | Cleans an IMAP path using imap_fix_path
+ * | imap_continue() | display a message and ask the user if they want to go on
+ * | imap_disallow_reopen() | Disallow re-opening a folder upon expunge
+ * | imap_error() | show an error and abort
+ * | imap_expand_path() | Canonicalise an IMAP path
+ * | imap_fix_path() | Fix up the imap path
+ * | imap_free_idata() | Release and clear storage in an ImapData structure
+ * | imap_get_literal_count() | write number of bytes in an IMAP literal into bytes
+ * | imap_get_parent() | Get an IMAP folder's parent
+ * | imap_get_parent_path() | Get the path of the parent folder
+ * | imap_get_qualifier() | Get the qualifier from a tagged response
+ * | imap_hcache_close() | Close the header cache
+ * | imap_hcache_del() | Delete an item from the header cache
+ * | imap_hcache_get() | Get a header cache entry by its UID
+ * | imap_hcache_namer() | Generate a filename for the header cache
+ * | imap_hcache_open() | Open a header cache
+ * | imap_hcache_put() | Add an entry to the header cache
+ * | imap_keepalive() | poll the current folder to keep the connection alive
+ * | imap_munge_mbox_name() | Quote awkward characters in a mailbox name
+ * | imap_mxcmp() | Compare mailbox names, giving priority to INBOX
+ * | imap_new_idata() | Allocate and initialise a new ImapData structure
+ * | imap_next_word() | Find where the next IMAP word begins
+ * | imap_parse_path() | Parse an IMAP mailbox name into name,host,port
+ * | imap_pretty_mailbox() | Prettify an IMAP mailbox name
+ * | imap_qualify_path() | Make an absolute IMAP folder target
+ * | imap_quote_string() | quote string according to IMAP rules
+ * | imap_unmunge_mbox_name() | Remove quoting from a mailbox name
+ * | imap_unquote_string() | equally stupid unquoting routine
+ * | imap_wait_keepalive() | Wait for a process to change state
+ */
#include "config.h"
#include <ctype.h>
* imap_expand_path - Canonicalise an IMAP path
* @param path Buffer containing path
* @param len Buffer length
- * @retval 0 on success
- * @retval -1 on error
+ * @retval 0 Success
+ * @retval -1 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_get_parent - Get an IMAP folder's parent
+ * @param output Buffer for the result
+ * @param mbox Mailbox whose parent is to be determined
+ * @param olen Length of the buffer
+ * @param delim Path delimiter
*/
void imap_get_parent(char *output, const char *mbox, size_t olen, char delim)
{
/**
* imap_get_parent_path - Get the path of the parent folder
+ * @param output Buffer for the result
+ * @param path Mailbox whose parent is to be determined
+ * @param olen Length of the buffer
*
* Provided an imap path, returns in output the parent directory if
* existent. Else returns the same path.
/**
* imap_clean_path - Cleans an IMAP path using imap_fix_path
+ * @param path Path to be cleaned
+ * @param plen Length of the buffer
*
* Does it in place.
*/
}
#ifdef USE_HCACHE
+/**
+ * imap_hcache_namer - Generate a filename for the header cache
+ * @param path Path for the header cache file
+ * @param dest Buffer for result
+ * @param dlen Length of buffer
+ * @retval num Number of chars written to dest
+ */
static int imap_hcache_namer(const char *path, char *dest, size_t dlen)
{
return snprintf(dest, dlen, "%s.hcache", path);
}
+/**
+ * imap_hcache_open - Open a header cache
+ * @param idata Server data
+ * @param path Path to the header cache
+ * @retval ptr HeaderCache
+ * @retval NULL Failure
+ */
header_cache_t *imap_hcache_open(struct ImapData *idata, const char *path)
{
struct ImapMbox mx;
return mutt_hcache_open(HeaderCache, cachepath, imap_hcache_namer);
}
+/**
+ * imap_hcache_close - Close the header cache
+ * @param idata Server data
+ */
void imap_hcache_close(struct ImapData *idata)
{
if (!idata->hcache)
idata->hcache = NULL;
}
+/**
+ * imap_hcache_get - Get a header cache entry by its UID
+ * @param idata Server data
+ * @param uid UID to find
+ * @retval ptr Email Header
+ * @retval NULL Failure
+ */
struct Header *imap_hcache_get(struct ImapData *idata, unsigned int uid)
{
char key[16];
return h;
}
+/**
+ * imap_hcache_put - Add an entry to the header cache
+ * @param idata Server data
+ * @param h Email Header
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_hcache_put(struct ImapData *idata, struct Header *h)
{
char key[16];
return mutt_hcache_store(idata->hcache, key, imap_hcache_keylen(key), h, idata->uid_validity);
}
+/**
+ * imap_hcache_del - Delete an item from the header cache
+ * @param idata Server data
+ * @param uid UID of entry to delete
+ * @retval 0 Success
+ * @retval -1 Failure
+ */
int imap_hcache_del(struct ImapData *idata, unsigned int uid)
{
char key[16];
/**
* imap_parse_path - Parse an IMAP mailbox name into name,host,port
+ * @param path Mailbox path to parse
+ * @param mx An IMAP mailbox
+ * @retval 0 Success
+ * @retval -1 Failure
*
* Given an IMAP mailbox name, return host, port and a path IMAP servers will
* recognize. mx.mbox is malloc'd, caller must free it
/**
* imap_mxcmp - Compare mailbox names, giving priority to INBOX
+ * @param mx1 First mailbox name
+ * @param mx2 Second mailbox name
+ * @retval <0 First mailbox precedes Second mailbox
+ * @retval 0 Mailboxes are the same
+ * @retval >0 Second mailbox precedes First mailbox
*
- * silly helper for mailbox name string comparisons, because of INBOX
+ * Like a normal sort function except that "INBOX" will be sorted to the
+ * beginning of the list.
*/
int imap_mxcmp(const char *mx1, const char *mx2)
{
/**
* imap_pretty_mailbox - Prettify an IMAP mailbox name
+ * @param path Mailbox name to be tidied
*
* Called by mutt_pretty_mailbox() to make IMAP paths look nice.
*/
FREE(&target.mbox);
}
-/* -- library functions -- */
-
/**
* imap_continue - display a message and ask the user if they want to go on
+ * @param msg Location of the error
+ * @param resp Message for user
+ * @retval num Result: #MUTT_YES, #MUTT_NO, #MUTT_ABORT
*/
int imap_continue(const char *msg, const char *resp)
{
/**
* imap_error - show an error and abort
+ * @param where Location of the error
+ * @param msg Message for user
*/
void imap_error(const char *where, const char *msg)
{
/**
* imap_new_idata - Allocate and initialise a new ImapData structure
* @retval NULL on failure (no mem)
+ * @retval ptr New ImapData
*/
struct ImapData *imap_new_idata(void)
{
/**
* imap_free_idata - Release and clear storage in an ImapData structure
+ * @param idata Server data
*/
void imap_free_idata(struct ImapData **idata)
{
/**
* imap_fix_path - Fix up the imap path
+ * @param idata Server data
+ * @param mailbox Mailbox path
+ * @param path Buffer for the result
+ * @param plen Length of buffer
+ * @retval ptr Fixed-up path
*
* This is necessary because the rest of neomutt assumes a hierarchy delimiter of
* '/', which is not necessarily true in IMAP. Additionally, the filesystem
return path;
}
+/**
+ * imap_cachepath - Generate a cache path for a mailbox
+ * @param idata Server data
+ * @param mailbox Mailbox name
+ * @param dest Buffer to store cache path
+ * @param dlen Length of buffer
+ */
void imap_cachepath(struct ImapData *idata, const char *mailbox, char *dest, size_t dlen)
{
char *s = NULL;
/**
* imap_get_literal_count - write number of bytes in an IMAP literal into bytes
- * @retval 0 on success
- * @retval -1 on failure
+ * @param[in] buf Number as a string
+ * @param[out] bytes Resulting number
+ * @retval 0 Success
+ * @retval -1 Failure
*/
int imap_get_literal_count(const char *buf, long *bytes)
{
/**
* imap_get_qualifier - Get the qualifier from a tagged response
+ * @param buf Command string to process
+ * @retval ptr Start of the qualifier
*
- * In a tagged response, skip tag and status for the qualifier message. Used by
- * imap_copy_message for TRYCREATE
+ * In a tagged response, skip tag and status for the qualifier message.
+ * Used by imap_copy_message for TRYCREATE
*/
char *imap_get_qualifier(char *buf)
{
}
/**
- * imap_next_word - return index into string where next IMAP word begins
+ * imap_next_word - Find where the next IMAP word begins
+ * @param s Command string to process
+ * @retval ptr Next IMAP word
*/
char *imap_next_word(char *s)
{
/**
* imap_qualify_path - Make an absolute IMAP folder target
+ * @param dest Buffer for the result
+ * @param len Length of buffer
+ * @param mx Imap mailbox
+ * @param path Path relative to the mailbox
*
* given ImapMbox and relative path.
*/
/**
* imap_quote_string - quote string according to IMAP rules
+ * @param dest Buffer for the result
+ * @param dlen Length of the buffer
+ * @param src String to be quoted
*
* Surround string with quotes, escape " and \ with backslash
*/
/**
* imap_unquote_string - equally stupid unquoting routine
+ * @param s String to be unquoted
*/
void imap_unquote_string(char *s)
{
}
/**
- * imap_munge_mbox_name - Quoting and UTF-7 conversion
+ * imap_munge_mbox_name - Quote awkward characters in a mailbox name
+ * @param idata Server data
+ * @param dest Buffer to store safe mailbox name
+ * @param dlen Length of buffer
+ * @param src Mailbox name
*/
void imap_munge_mbox_name(struct ImapData *idata, char *dest, size_t dlen, const char *src)
{
FREE(&buf);
}
+/**
+ * imap_unmunge_mbox_name - Remove quoting from a mailbox name
+ * @param idata Server data
+ * @param s Mailbox name
+ *
+ * The string will be altered in-place.
+ */
void imap_unmunge_mbox_name(struct ImapData *idata, char *s)
{
char *buf = NULL;
FREE(&buf);
}
-/*
- * Imap keepalive: poll the current folder to keep the
- * connection alive.
+/**
+ * alrm_handler - Dummy signal handler (ignore a signal)
+ * @param sig Signal number
*/
-
static void alrm_handler(int sig)
{
/* empty */
}
+/**
+ * imap_keepalive - poll the current folder to keep the connection alive
+ */
void imap_keepalive(void)
{
struct Connection *conn = NULL;
}
}
+/**
+ * imap_wait_keepalive - Wait for a process to change state
+ * @param pid Process ID to listen to
+ * @retval num 'wstatus' from waitpid()
+ */
int imap_wait_keepalive(pid_t pid)
{
struct sigaction oldalrm;
}
/**
- * imap_allow_reopen - Allow/disallow re-opening a folder upon expunge
+ * imap_allow_reopen - Allow re-opening a folder upon expunge
+ * @param ctx Context
*/
void imap_allow_reopen(struct Context *ctx)
{
idata->reopen |= IMAP_REOPEN_ALLOW;
}
+/**
+ * imap_disallow_reopen - Disallow re-opening a folder upon expunge
+ * @param ctx Context
+ */
void imap_disallow_reopen(struct Context *ctx)
{
struct ImapData *idata = NULL;
idata->reopen &= ~IMAP_REOPEN_ALLOW;
}
+/**
+ * imap_account_match - Compare two Accounts
+ * @param a1 First Account
+ * @param a2 Second Account
+ * @retval true Accounts match
+ */
int imap_account_match(const struct Account *a1, const struct Account *a2)
{
struct ImapData *a1_idata = imap_conn_find(a1, MUTT_IMAP_CONN_NONEW);
projects / neomutt / commitdiff