Mail Plugins
============

Typically plugins add hooks in their init() function by calling
'mail_storage_hooks_add()', and remove the hooks at deinit() with
'mail_storage_hooks_remove()'. Hooks that are currently supported:

 * mail_user_created: A new mail user was created. It doesn't yet have any
   namespaces.
 * mail_storage_created: A new mail storage was created. It's not connected to
   any namespaces/mailbox lists yet.
 * mailbox_list_created: A new mailbox list was created. It's not connected to
   any storages yet. Because of this, some internal virtual methods haven't
   been overridden by the storage yet, so plugins rarely want to use this hook.
   Instead they should use:
 * mail_namespace_storage_added: Storage was connected to its first
   namespace/mailbox list. This hook should usually be used if plugin wants to
   override mailbox_list's methods.
 * mail_namespaces_created: User's all namespaces have been created. This hook
   is called only per user at startup. More internal namespaces may be created
   later when using shared mailboxes.
 * mailbox_allocated: 'mailbox_alloc()' was called.
 * mailbox_opened: Mailbox (and its index) was actually opened, either
   explicitly with 'mailbox_open()' or implicitly by some other function.

Overriding methods
------------------

When the hook gets called, you usually want to override some method of the
created object. This is the easy part, for example:

---%<-------------------------------------------------------------------------
static void plugin_mailbox_allocated(struct mailbox *box)
..
        box->v.transaction_begin = plugin_transaction_begin;
---%<-------------------------------------------------------------------------

The problem is that once 'plugin_transaction_begin()' is called, it should call
the original 'transaction_begin()'. There may also be multiple plugins that
want to override the same method, so the idea is to just have each plugin call
the previous 'transaction_begin()'. The next problem is where do you save the
previous value? Most objects have a 'module_contexts' array for storing
per-plugin pointers for this purpose. There are several helper functions to
make setting and accessing them in a quite safe way.

Easiest way to set up the module context is to just copy&paste code from an
existing plugin that sets the same context. Here's some documentation about it
anyway:

First you start by creating register for the plugin. There are different
registers for different types of objects:

 * mail_user_module_register: For mail_user.
 * mailbox_list_module_register: For mailbox_list.
 * mail_storage_module_register: For mail_storage, mailbox, mailbox_transaction
   and mail_search.
 * mail_module_register: For mail.

We'll assume you want to use mail_storage_module_register:

---%<-------------------------------------------------------------------------
static MODULE_CONTEXT_DEFINE_INIT(plugin_storage_module,
&mail_storage_module_register);
---%<-------------------------------------------------------------------------

If you need to make it external, use:

---%<-------------------------------------------------------------------------
extern MODULE_CONTEXT_DEFINE(plugin_storage_module,
&mail_storage_module_register);
struct plugin_storage_module plugin_storage_module =
        MODULE_CONTEXT_INIT(&mail_storage_module_register);
---%<-------------------------------------------------------------------------

Next you'll need to allocate memory for the structure you want to place in the
context. If you only want to override some methods, you can use:

---%<-------------------------------------------------------------------------
union mailbox_module_context *mbox;
struct mailbox_vfuncs *v = box->vlast;

mbox = p_new(box->pool, union mailbox_module_context, 1);
mbox->super = *v;
box->vlast = &mbox->super;

v->transaction_begin = plugin_transaction_begin;
MODULE_CONTEXT_SET_SELF(box, plugin_storage_module, mbox);
---%<-------------------------------------------------------------------------

If you want to store some more plugin-specific data to the object instead of
just the super methods, you can do:

---%<-------------------------------------------------------------------------
struct plugin_mailbox {
        /* must be called module_ctx */
        union mailbox_module_context module_ctx;
};
/* .. */

struct plugin_mailbox *mbox;
struct mailbox_vfuncs *v = box->vlast;

mbox = p_new(box->pool, struct plugin_mailbox, 1);
mbox->module_ctx.super = *v;
box->vlast = &mbox->super;

v->transaction_begin = plugin_transaction_begin;
MODULE_CONTEXT_SET(box, plugin_storage_module, mbox);
---%<-------------------------------------------------------------------------

Note that when using union directly you use 'MODULE_CONTEXT_SET_SELF()', while
when it's inside a struct you use 'MODULE_CONTEXT_SET()'.

Once all this initialization is done, you can look up the module context with:

---%<-------------------------------------------------------------------------
#define PLUGIN_CONTEXT(obj) MODULE_CONTEXT(obj, plugin_storage_module)
/* .. */
struct plugin_mailbox *mbox = PLUGIN_CONTEXT(box);
---%<-------------------------------------------------------------------------

(Yes, this API seems a bit too difficult to use and could use a redesign.)

(This file was created from the wiki on 2017-05-11 04:42)