hook.h File Reference

Parse and execute user-defined hooks. More...

#include "config.h"
#include <stdint.h>
#include <stdio.h>
#include "mutt_commands.h"

Include dependency graph for hook.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	MUTT_HOOK_NO_FLAGS   0
	No flags are set. More...
#define	MUTT_FOLDER_HOOK   (1 << 0)
	folder-hook: when entering a mailbox More...
#define	MUTT_MBOX_HOOK   (1 << 1)
	mbox-hook: move messages after reading them More...
#define	MUTT_SEND_HOOK   (1 << 2)
	send-hook: when composing a new email More...
#define	MUTT_FCC_HOOK   (1 << 3)
	fcc-hook: to save outgoing email More...
#define	MUTT_SAVE_HOOK   (1 << 4)
	save-hook: set a default folder when saving an email More...
#define	MUTT_CHARSET_HOOK   (1 << 5)
	charset-hook: create a charset alias for malformed emails More...
#define	MUTT_ICONV_HOOK   (1 << 6)
	iconv-hook: create a system charset alias More...
#define	MUTT_MESSAGE_HOOK   (1 << 7)
	message-hook: run before displaying a message More...
#define	MUTT_CRYPT_HOOK   (1 << 8)
	crypt-hook: automatically select a PGP/SMIME key More...
#define	MUTT_ACCOUNT_HOOK   (1 << 9)
	account-hook: when changing between accounts More...
#define	MUTT_REPLY_HOOK   (1 << 10)
	reply-hook: when replying to an email More...
#define	MUTT_SEND2_HOOK   (1 << 11)
	send2-hook: when changing fields in the compose menu More...
#define	MUTT_OPEN_HOOK   (1 << 12)
	open-hook: to read a compressed mailbox More...
#define	MUTT_APPEND_HOOK   (1 << 13)
	append-hook: append to a compressed mailbox More...
#define	MUTT_CLOSE_HOOK   (1 << 14)
	close-hook: write to a compressed mailbox More...
#define	MUTT_IDXFMTHOOK   (1 << 15)
	index-format-hook: customise the format of the index More...
#define	MUTT_TIMEOUT_HOOK   (1 << 16)
	timeout-hook: run a command periodically More...
#define	MUTT_STARTUP_HOOK   (1 << 17)
	startup-hook: run when starting NeoMutt More...
#define	MUTT_SHUTDOWN_HOOK   (1 << 18)
	shutdown-hook: run when leaving NeoMutt More...
#define	MUTT_GLOBAL_HOOK   (1 << 19)
	Hooks which don't take a regex. More...

Typedefs
typedef uint32_t	HookFlags
	Flags for mutt_parse_hook(), e.g. MUTT_FOLDER_HOOK. More...

Functions
void	mutt_account_hook (const char *url)
	Perform an account hook. More...
void	mutt_crypt_hook (struct ListHead *list, struct Address *addr)
	Find crypto hooks for an Address. More...
void	mutt_default_save (char *path, size_t pathlen, struct Email *e)
	Find the default save path for an email. More...
void	mutt_delete_hooks (HookFlags type)
	Delete matching hooks. More...
char *	mutt_find_hook (HookFlags type, const char *pat)
	Find a matching hook. More...
void	mutt_folder_hook (const char *path, const char *desc)
	Perform a folder hook. More...
const char *	mutt_idxfmt_hook (const char *name, struct Mailbox *m, struct Email *e)
	Get index-format-hook format string. More...
void	mutt_message_hook (struct Mailbox *m, struct Email *e, HookFlags type)
	Perform a message hook. More...
enum CommandResult	mutt_parse_idxfmt_hook (struct Buffer *buf, struct Buffer *s, intptr_t data, struct Buffer *err)
	Parse the 'index-format-hook' command - Implements Command::parse() -. More...
enum CommandResult	mutt_parse_hook (struct Buffer *buf, struct Buffer *s, intptr_t data, struct Buffer *err)
	Parse the 'hook' family of commands - Implements Command::parse() -This is used by 'account-hook', 'append-hook' and many more. More...
enum CommandResult	mutt_parse_unhook (struct Buffer *buf, struct Buffer *s, intptr_t data, struct Buffer *err)
	Parse the 'unhook' command - Implements Command::parse() -. More...
void	mutt_select_fcc (struct Buffer *path, struct Email *e)
	Select the FCC path for an email. More...
void	mutt_startup_shutdown_hook (HookFlags type)
	Execute any startup/shutdown hooks. More...
void	mutt_timeout_hook (void)
	Execute any timeout hooks. More...

Detailed Description

Parse and execute user-defined hooks.

Authors

• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file hook.h.

Macro Definition Documentation

MUTT_HOOK_NO_FLAGS

#define MUTT_HOOK_NO_FLAGS   0

No flags are set.

Definition at line 38 of file hook.h.

MUTT_FOLDER_HOOK

#define MUTT_FOLDER_HOOK   (1 << 0)

folder-hook: when entering a mailbox

Definition at line 39 of file hook.h.

MUTT_MBOX_HOOK

#define MUTT_MBOX_HOOK   (1 << 1)

mbox-hook: move messages after reading them

Definition at line 40 of file hook.h.

MUTT_SEND_HOOK

#define MUTT_SEND_HOOK   (1 << 2)

send-hook: when composing a new email

Definition at line 41 of file hook.h.

MUTT_FCC_HOOK

#define MUTT_FCC_HOOK   (1 << 3)

fcc-hook: to save outgoing email

Definition at line 42 of file hook.h.

MUTT_SAVE_HOOK

#define MUTT_SAVE_HOOK   (1 << 4)

save-hook: set a default folder when saving an email

Definition at line 43 of file hook.h.

MUTT_CHARSET_HOOK

#define MUTT_CHARSET_HOOK   (1 << 5)

charset-hook: create a charset alias for malformed emails

Definition at line 44 of file hook.h.

MUTT_ICONV_HOOK

#define MUTT_ICONV_HOOK   (1 << 6)

iconv-hook: create a system charset alias

Definition at line 45 of file hook.h.

MUTT_MESSAGE_HOOK

#define MUTT_MESSAGE_HOOK   (1 << 7)

message-hook: run before displaying a message

Definition at line 46 of file hook.h.

MUTT_CRYPT_HOOK

#define MUTT_CRYPT_HOOK   (1 << 8)

crypt-hook: automatically select a PGP/SMIME key

Definition at line 47 of file hook.h.

MUTT_ACCOUNT_HOOK

#define MUTT_ACCOUNT_HOOK   (1 << 9)

account-hook: when changing between accounts

Definition at line 48 of file hook.h.

MUTT_REPLY_HOOK

#define MUTT_REPLY_HOOK   (1 << 10)

reply-hook: when replying to an email

Definition at line 49 of file hook.h.

MUTT_SEND2_HOOK

#define MUTT_SEND2_HOOK   (1 << 11)

send2-hook: when changing fields in the compose menu

Definition at line 50 of file hook.h.

MUTT_OPEN_HOOK

#define MUTT_OPEN_HOOK   (1 << 12)

open-hook: to read a compressed mailbox

Definition at line 52 of file hook.h.

MUTT_APPEND_HOOK

#define MUTT_APPEND_HOOK   (1 << 13)

append-hook: append to a compressed mailbox

Definition at line 53 of file hook.h.

MUTT_CLOSE_HOOK

#define MUTT_CLOSE_HOOK   (1 << 14)

close-hook: write to a compressed mailbox

Definition at line 54 of file hook.h.

MUTT_IDXFMTHOOK

#define MUTT_IDXFMTHOOK   (1 << 15)

index-format-hook: customise the format of the index

Definition at line 56 of file hook.h.

MUTT_TIMEOUT_HOOK

#define MUTT_TIMEOUT_HOOK   (1 << 16)

timeout-hook: run a command periodically

Definition at line 57 of file hook.h.

MUTT_STARTUP_HOOK

#define MUTT_STARTUP_HOOK   (1 << 17)

startup-hook: run when starting NeoMutt

Definition at line 58 of file hook.h.

MUTT_SHUTDOWN_HOOK

#define MUTT_SHUTDOWN_HOOK   (1 << 18)

shutdown-hook: run when leaving NeoMutt

Definition at line 59 of file hook.h.

MUTT_GLOBAL_HOOK

#define MUTT_GLOBAL_HOOK   (1 << 19)

Hooks which don't take a regex.

Definition at line 60 of file hook.h.

Typedef Documentation

HookFlags

typedef uint32_t HookFlags

Flags for mutt_parse_hook(), e.g. MUTT_FOLDER_HOOK.

Definition at line 35 of file hook.h.

Function Documentation

mutt_account_hook()

void mutt_account_hook

(

const char *

url

)

Perform an account hook.

Parameters

url	Account URL to match

Definition at line 782 of file hook.c.

{
  /* parsing commands with URLs in an account hook can cause a recursive
   * call. We just skip processing if this occurs. Typically such commands
   * belong in a folder-hook -- perhaps we should warn the user. */
  static bool inhook = false;
  if (inhook)
    return;

  struct Hook *hook = NULL;
  struct Buffer *err = mutt_buffer_pool_get();

  TAILQ_FOREACH(hook, &Hooks, entries)
  {
    if (!(hook->command && (hook->type & MUTT_ACCOUNT_HOOK)))
      continue;

    if (mutt_regex_match(&hook->regex, url))
    {
      inhook = true;
      mutt_debug(LL_DEBUG1, "account-hook '%s' matches '%s'\n", hook->regex.pattern, url);
      mutt_debug(LL_DEBUG5, "    %s\n", hook->command);

      if (mutt_parse_rc_line(hook->command, err) == MUTT_CMD_ERROR)
      {
        mutt_error("%s", mutt_buffer_string(err));
        mutt_buffer_pool_release(&err);

        inhook = false;
        goto done;
      }

      inhook = false;
    }
  }
done:
  mutt_buffer_pool_release(&err);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_crypt_hook()

void mutt_crypt_hook	(	struct ListHead *	list,
		struct Address *	addr
	)

Find crypto hooks for an Address.

Parameters

[out]	list	List of keys
[in]	addr	Address to match

The crypt-hook associates keys with addresses.

Definition at line 773 of file hook.c.

{
  list_hook(list, addr->mailbox, MUTT_CRYPT_HOOK);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_default_save()

void mutt_default_save	(	char *	path,
		size_t	pathlen,
		struct Email *	e
	)

Find the default save path for an email.

Parameters

path	Buffer for the path
pathlen	Length of buffer
e	Email

Definition at line 677 of file hook.c.

{
  *path = '\0';
  if (addr_hook(path, pathlen, MUTT_SAVE_HOOK, ctx_mailbox(Context), e) == 0)
    return;

  struct Envelope *env = e->env;
  const struct Address *from = TAILQ_FIRST(&env->from);
  const struct Address *reply_to = TAILQ_FIRST(&env->reply_to);
  const struct Address *to = TAILQ_FIRST(&env->to);
  const struct Address *cc = TAILQ_FIRST(&env->cc);
  const struct Address *addr = NULL;
  bool from_me = mutt_addr_is_user(from);

  if (!from_me && reply_to && reply_to->mailbox)
    addr = reply_to;
  else if (!from_me && from && from->mailbox)
    addr = from;
  else if (to && to->mailbox)
    addr = to;
  else if (cc && cc->mailbox)
    addr = cc;
  else
    addr = NULL;
  if (addr)
  {
    struct Buffer *tmp = mutt_buffer_pool_get();
    mutt_safe_path(tmp, addr);
    snprintf(path, pathlen, "=%s", mutt_buffer_string(tmp));
    mutt_buffer_pool_release(&tmp);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_delete_hooks()

void mutt_delete_hooks

(

HookFlags

type

)

Delete matching hooks.

Parameters

type	Hook type to delete, see HookFlags

If 0 is passed, all the hooks will be deleted.

Definition at line 328 of file hook.c.

{
  struct Hook *h = NULL;
  struct Hook *tmp = NULL;

  TAILQ_FOREACH_SAFE(h, &Hooks, entries, tmp)
  {
    if ((type == MUTT_HOOK_NO_FLAGS) || (type == h->type))
    {
      TAILQ_REMOVE(&Hooks, h, entries);
      delete_hook(h);
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_find_hook()

char* mutt_find_hook	(	HookFlags	type,
		const char *	pat
	)

Find a matching hook.

Parameters

type	Hook type, see HookFlags
pat	Pattern to match

Return values

ptr	Command string

Note

The returned string must not be freed.

Definition at line 577 of file hook.c.

{
  struct Hook *tmp = NULL;

  TAILQ_FOREACH(tmp, &Hooks, entries)
  {
    if (tmp->type & type)
    {
      if (mutt_regex_match(&tmp->regex, pat))
        return tmp->command;
    }
  }
  return NULL;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_folder_hook()

void mutt_folder_hook	(	const char *	path,
		const char *	desc
	)

Perform a folder hook.

Parameters

path	Path to potentially match
desc	Description to potentially match

Definition at line 529 of file hook.c.

{
  if (!path && !desc)
    return;

  struct Hook *hook = NULL;
  struct Buffer *err = mutt_buffer_pool_get();

  current_hook_type = MUTT_FOLDER_HOOK;

  TAILQ_FOREACH(hook, &Hooks, entries)
  {
    if (!hook->command)
      continue;

    if (!(hook->type & MUTT_FOLDER_HOOK))
      continue;

    const char *match = NULL;
    if (mutt_regex_match(&hook->regex, path))
      match = path;
    else if (mutt_regex_match(&hook->regex, desc))
      match = desc;

    if (match)
    {
      mutt_debug(LL_DEBUG1, "folder-hook '%s' matches '%s'\n", hook->regex.pattern, match);
      mutt_debug(LL_DEBUG5, "    %s\n", hook->command);
      if (mutt_parse_rc_line(hook->command, err) == MUTT_CMD_ERROR)
      {
        mutt_error("%s", mutt_buffer_string(err));
        break;
      }
    }
  }
  mutt_buffer_pool_release(&err);

  current_hook_type = MUTT_HOOK_NO_FLAGS;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_idxfmt_hook()

const char* mutt_idxfmt_hook	(	const char *	name,
		struct Mailbox *	m,
		struct Email *	e
	)

Get index-format-hook format string.

Parameters

name	Hook name
m	Mailbox
e	Email

Return values

ptr	printf(3)-like format string
NULL	No matching hook

Definition at line 893 of file hook.c.

{
  if (!IdxFmtHooks)
    return NULL;

  struct HookList *hl = mutt_hash_find(IdxFmtHooks, name);
  if (!hl)
    return NULL;

  current_hook_type = MUTT_IDXFMTHOOK;

  struct PatternCache cache = { 0 };
  const char *fmtstring = NULL;
  struct Hook *hook = NULL;

  TAILQ_FOREACH(hook, hl, entries)
  {
    struct Pattern *pat = SLIST_FIRST(hook->pattern);
    if ((mutt_pattern_exec(pat, 0, m, e, &cache) > 0) ^ hook->regex.pat_not)
    {
      fmtstring = hook->command;
      break;
    }
  }

  current_hook_type = MUTT_HOOK_NO_FLAGS;

  return fmtstring;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_message_hook()

void mutt_message_hook	(	struct Mailbox *	m,
		struct Email *	e,
		HookFlags	type
	)

Perform a message hook.

Parameters

m	Mailbox Context
e	Email
type	Hook type, see HookFlags

Definition at line 598 of file hook.c.

{
  struct Hook *hook = NULL;
  struct PatternCache cache = { 0 };
  struct Buffer *err = mutt_buffer_pool_get();

  current_hook_type = type;

  TAILQ_FOREACH(hook, &Hooks, entries)
  {
    if (!hook->command)
      continue;

    if (hook->type & type)
    {
      if ((mutt_pattern_exec(SLIST_FIRST(hook->pattern), 0, m, e, &cache) > 0) ^
          hook->regex.pat_not)
      {
        if (mutt_parse_rc_line(hook->command, err) == MUTT_CMD_ERROR)
        {
          mutt_error("%s", mutt_buffer_string(err));
          current_hook_type = MUTT_HOOK_NO_FLAGS;
          mutt_buffer_pool_release(&err);

          return;
        }
        /* Executing arbitrary commands could affect the pattern results,
         * so the cache has to be wiped */
        memset(&cache, 0, sizeof(cache));
      }
    }
  }
  mutt_buffer_pool_release(&err);

  current_hook_type = MUTT_HOOK_NO_FLAGS;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_select_fcc()

void mutt_select_fcc	(	struct Buffer *	path,
		struct Email *	e
	)

Select the FCC path for an email.

Parameters

path	Buffer for the path
e	Email

Definition at line 715 of file hook.c.

{
  mutt_buffer_alloc(path, PATH_MAX);

  if (addr_hook(path->data, path->dsize, MUTT_FCC_HOOK, NULL, e) != 0)
  {
    const struct Address *to = TAILQ_FIRST(&e->env->to);
    const struct Address *cc = TAILQ_FIRST(&e->env->cc);
    const struct Address *bcc = TAILQ_FIRST(&e->env->bcc);
    const bool c_save_name = cs_subset_bool(NeoMutt->sub, "save_name");
    const bool c_force_name = cs_subset_bool(NeoMutt->sub, "force_name");
    const char *const c_record = cs_subset_string(NeoMutt->sub, "record");
    if ((c_save_name || c_force_name) && (to || cc || bcc))
    {
      const struct Address *addr = to ? to : (cc ? cc : bcc);
      struct Buffer *buf = mutt_buffer_pool_get();
      mutt_safe_path(buf, addr);
      const char *const c_folder = cs_subset_string(NeoMutt->sub, "folder");
      mutt_buffer_concat_path(path, NONULL(c_folder), mutt_buffer_string(buf));
      mutt_buffer_pool_release(&buf);
      if (!c_force_name && (mx_access(mutt_buffer_string(path), W_OK) != 0))
        mutt_buffer_strcpy(path, c_record);
    }
    else
      mutt_buffer_strcpy(path, c_record);
  }
  else
    mutt_buffer_fix_dptr(path);

  mutt_buffer_pretty_mailbox(path);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_startup_shutdown_hook()

void mutt_startup_shutdown_hook

(

HookFlags

type

)

Execute any startup/shutdown hooks.

Parameters

type	Hook type: MUTT_STARTUP_HOOK or MUTT_SHUTDOWN_HOOK

The user can configure hooks to be run on startup/shutdown. This function finds all the matching hooks and executes them.

Definition at line 863 of file hook.c.

{
  struct Hook *hook = NULL;
  struct Buffer err = mutt_buffer_make(0);
  char buf[256];

  err.data = buf;
  err.dsize = sizeof(buf);

  TAILQ_FOREACH(hook, &Hooks, entries)
  {
    if (!(hook->command && (hook->type & type)))
      continue;

    if (mutt_parse_rc_line(hook->command, &err) == MUTT_CMD_ERROR)
    {
      mutt_error("%s", err.data);
      mutt_buffer_reset(&err);
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_timeout_hook()

void mutt_timeout_hook

(

void

)

Execute any timeout hooks.

The user can configure hooks to be run on timeout. This function finds all the matching hooks and executes them.

Definition at line 827 of file hook.c.

{
  struct Hook *hook = NULL;
  struct Buffer err;
  char buf[256];

  mutt_buffer_init(&err);
  err.data = buf;
  err.dsize = sizeof(buf);

  TAILQ_FOREACH(hook, &Hooks, entries)
  {
    if (!(hook->command && (hook->type & MUTT_TIMEOUT_HOOK)))
      continue;

    if (mutt_parse_rc_line(hook->command, &err) == MUTT_CMD_ERROR)
    {
      mutt_error("%s", err.data);
      mutt_buffer_reset(&err);

      /* The hooks should be independent of each other, so even though this on
       * failed, we'll carry on with the others. */
    }
  }

  /* Delete temporary attachment files */
  mutt_unlink_temp_attachments();
}

Here is the call graph for this function:

Here is the caller graph for this function: