This is muint.info, produced by makeinfo version 4.5 from muint.texi.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* mailutils-int: (muint).  The internals of GNU Mailutils.
END-INFO-DIR-ENTRY

Published by the Free Software Foundation, 59 Temple Place - Suite 330
Boston, MA 02111-1307, USA

   Copyright (C) 2003 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being "A GNU Manual",
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled "GNU Free Documentation License".

   (a) The FSF's Back-Cover Text is: "You have freedom to copy and
modify this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development."

File: muint.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Scope of this Document
**********************

   This document describes the internals of the GNU Mailutils.  It
includes description of Mailutils' architecture, algorithms and data
structures. It is intended primarily for Mailutils developers and those
who wish to participate in the development of the package.

* Menu:

* Introduction::            Introduction to the Mailutils Architecture.
* Object Model::            The Mailutils Object Model.

Indices
* Concept Index::           Index of Concepts.


File: muint.info,  Node: Introduction,  Next: Object Model,  Prev: Top,  Up: Top

Introduction to the Mailutils Architecture.
*******************************************

   Mailutils is written in plain C using object-oriented approach. Each
part of the email message is represented as an object within the
Mailutils hierarchical structure. Such an object contains all the
information about the message part it represents and it provides all
the methods necessary for dealing with its data. All Mailutils objects
derive from the single root object. The object system is discussed in
further detail in chapter *Note Object Model::.


File: muint.info,  Node: Object Model,  Next: Concept Index,  Prev: Introduction,  Up: Top

Mailutils Object Model
**********************

   Mailutils is written in C, the language is widely supported on many
platforms and the ABI (Binary Interface) for linking objects with other
languages (like Guile, Java, ...) is well-defined.

   The C language does not provide support for object oriented
programming, but by using structures and pointers to function, it is
possible to provide a simple framework.

   Every Mailutils object has a corresponding C structure holding its
interface and specific data.  For example mu_object_t, is the root
object and all mailutils objects extends it:

     struct _mu_object;
     typedef struct _mu_object* mu_object_t;
     
     /* Defintion of the interface for mu_object */
     struct _mu_object_vtable
     {
       int  (*create)   (mu_object_t *object);
       void (*destroy)  (mu_object_t *object);
       void (*notify)   (mu_object_t object, int event, void *data);
     }
     
     struct _mu_object
     {
       struct _mu_object_vtable *vtable;
       int type;
     }

   The VTABLE is an array of pointers to function, it provides the
interface or the list of function for this object.  The library
provides wrapper to access the functions instead using the VTABLE
directly.

     int mu_object_notify(mu_object object, int event, void *data)
     {
       if (object == NULL || object->vtable == NULL
           || object->vtable->notify == NULL)
         return MU_ERR_NOT_SUPPORTED;
       return object->vtable->notify (object, event, data);
     }

   Instead of using macros or the vtable directly.
     #define mu_object_notify(o, evt, d)  ((o)->vtable->notify(o, evt, d))

Implementing an interface
=========================

   For a more concrete implementation, lets say we are implementing
some caching mailbox but we need to keep a better track of the objects
in our implementation.  We take the approach of simple reference
counting and extend the mu_object_t.

     #include <mailutils/sys/object.h>
     
     struct my_object;
     typedef struct refcount* refcount;
     
     struct refcount_vtable
     {
        struct _mu_object_vtable base;
        int (*increment)(refcount_t);
        int (*decrement)(refcount_t);
     }
     
     struct refcount
     {
       struct refcount_vtable * vtable;
       int count;
     }
     
     static int
     refcount_increment (mu_object_t obj)
     {
        refcount_t refcount = (refcount_t)obj;
        refcount->count++;
        return refcount->count;
     }
     
     static int
     refcount_decrement (mu_object_t obj)
     {
        refcount_t refcount = (refcount_t)obj;
        if (refcount->count > 0)
          refcount->count--;
        return refcount->count;
     }
     
     int
     my_mu_object_create (mu_object_t *pobject)
     {
        static struct refcount_vtable* vtable;
        refcount_t ref;
     
        if (object == NULL)
          return EINVAL;
     
        if (!vtable)
         {
           vtable = calloc(1, sizeof(*vtable));
           if (vtable == NULL)
             return ENOMEM;
           vtable->base.vtable = &_mu_object_vtable; // FIXME where can they get the base vtable
           vtable->increment = refcount_increment;
           vtable->decrement = refcount_decrement;
         }
     
        ref = malloc(sizeof *ref);
        ref->base = vtable;
        *pobject = &ref->base.vtable
        return 0;
     }

   The interface adds a `decrement' and `increment' to the `mu_object_t'
interface. Creating a `refcount_t' can be savely typecast to
`mu_object_t', for example:

     refcount_t ref;
     mu_object_t obj;
     refcount_create (&ref);
     
     /* send a notification to the listeners of an event.  */
     mu_object_notify ((mu_object_t)ref, 5, NULL)


File: muint.info,  Node: Concept Index,  Prev: Object Model,  Up: Top

Concept Index
*************

   This is a general index of all issues discussed in this manual

* Menu:

* Introduction:                          Introduction.



Tag Table:
Node: Top971
Node: Introduction1559
Node: Object Model2194
Node: Concept Index6044

End Tag Table
