History

MAPIStore 1.0 backend.backend structure

This structure is required to proper backend registration. It holds the following parameters:

  • backend.name: the name of the backend
  • backend.description: A short description for the backend
  • backend.namespace: the namespace used to reference this backend
  • backend.init: a pointer on the function to call for initialization
  • backend.list_contexts:
  • backend.create_context: a pointer on the function to call to create a mapistore context
  • backend.create_root_folder:

Deleting context

You will notice there is no function to delete a context explicitly within the backend. This is because the mapistore interface deletes a backend on its own by free'ing the memory context used by this backend.

However, backend's developers are required to allocate their internal data with the memory context passed during create_context and associate a talloc destructor function. If additional operations need to be performed such as close a file descriptor, socket or call the language specific memory release system (garbage collector, pool etc.)

When mapistore will delete the context (free up memory), the hierarchy will automatically be processed and the destructor function for the backend will be called. This is in this internal function that you need to implement actions such as close (fd, socket) etc.

To create a talloc destructor, call the following function:

talloc_set_destructor((void *)context, (int (*)(void *))destructor_fct);

In this example context is the structure allocated with the memory context passed in parameter of the create_context function. An example of the destructor function would looks like:

static int desctructor_fct(void *data)
{
    /* perform operations to clean-up everything properly */

   return 0;
}

backend.init function

This is the function called right after the backend is registered (mapistore_backend_register). This function will be executed each time mapistore_init function is called from the calling application.

In the context of OpenChange server and Samba forked model, it means the backend would be called each time a new instance of the server is created.
To keep init only called once in the server's lifetime, it is required to use a static variable within mapistore_init_backend which value changes when backend gets initialized the first time.

The init function is used to initialize your backend with data (or environment) it will need all along mapistore's lifetime. It is a one-time operation and is generally used to:
  • open a connection to a remote system
  • load a virtual machine

It results in having a static structure, local to the backend's file which is used along calls to access an environment or file descriptor.
It prevents from having to open or load a virtual machine or open a connection to a system each time a context is created.

backend.list_contexts function

This function is part of the auto-provisioning process available in OpenChange 1.0. It is called by OpenChange server to query the MAPIStore URI for the backend available for specified user. Its prototype uses the following parameters:
  • const char *module_name: the name of the backend. For C backend, this parameter is pretty much useless. However it is required when your backend implements gateway to other languages such as the C-Python gateway.
  • const char *username: the Samba username for which MAPIStore URI has to be retrieved
  • struct tdb_wrap *: a pointer to the wrapped TDB database (sort of hash table) which associates for all folder/messages an Exchange specific folder and message identifier to a mapistore URI.
  • TALLOC_CTX * Pointer to the memory context used for this backend. This is the memory context you need to use to allocate memory for the mapistore_contexts_list to return
  • struct mapistore_contexts_list **: Pointer of Pointer on a double chained list of mapistore contexts list information to return

backend.create_context function

This is the function called when we are creating a context (see Contexts subsection). Its prototype uses the following parameters:
  • TALLOC_CTX * Pointer to the memory context used for this backend. This is the memory context you need to use to allocate memory for your specific backend's context structure and for which you may want to set a destructor.
  • struct mapistore_connection_info * Pointer to a data structure holding information about the incoming user and wrapping structures such as the mapistore_context structure pointer. It is needed for a backend for example to register messages on its own.
  • struct tdb_wrap * Pointer to a wrapped TDB database (sort of hash table) which associates for all folder/messages an Exchange specific folder and message identifier to a mapistore URI.
  • const char *uri Pointer to the URI for this context
  • void **context_object Pointer to a context object to return and which the backend uses to associate backend's specific information on the context.

backend.create_root_folder function