Skip to content

John McEleney / mailutils

Go to a project
Toggle navigation
Toggle navigation pinning
Commit d232a467 d232a4677cd0b69cd5bb763eaf1325d7dfc8dda3 by Sergey Poznyakoff
Options

Minor changes. 

* doc/texinfo/mailutils.texi: Update.
* doc/texinfo/rendition.texi: Rewrite.
1 parent 843523b0
Inline Side-by-side
Showing 3 changed files with 47 additions and 174 deletions
......@@ -37,6 +37,7 @@
* mail: (mailutils)mail. Send and Receive Mail.
* maidag: (mailutils)maidag. A General-Purpose Mail Delivery Agent.
* messages: (mailutils)messages. Count Messages in a Mailbox.
* movemail: (mailutils)movemail. Move Mail between Mailboxes.
* pop3d: (mailutils)pop3d. POP3 Daemon.
* readmsg: (mailutils)readmsg. Extract Messages from a Folder.
* sieve: (mailutils)sieve. Mail Filtering Utility.
......
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2010,
@c 2011 Free Software Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************
@chapter 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:
@smallexample
struct _mu_object;
typedef struct _mu_object* mu_object_t;
/* Definition 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;
@}
@end smallexample
The @var{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 @var{vtable} directly.
@smallexample
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);
@}
@end smallexample
Instead of using macros or the vtable directly.
@smallexample
#define mu_object_notify(o, evt, d) ((o)->vtable->notify(o, evt, d))
@end smallexample
@section Implementing an Interface
@comment ***********************************************************
@comment This is not a very good/useful example, we should do one using
@comment header or message, something usefully that would clarify the concepts
@comment better and at the same could be reuse in code by clients.
@comment
@comment For example mime_t "extends" message_t, this is a good example
@comment since you can consider a mime_t as a message_t but with extra functions.
@comment ***********************************************************
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.
@smallexample
#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;
@}
@end smallexample
The interface adds a @code{decrement} and @code{increment} to the @code{mu_object_t}
interface. Creating a @code{refcount_t} can be savely typecast to @code{mu_object_t},
for example:
@smallexample
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)
@end smallexample
@c Let's use the concept of 'renditions' by Fra@,{c}ois Pinard
@c I extended it by adding a FIXME_FOOTNOTE variable, which controls
@c whether FIXME information should be placed in footnotes or
@c inlined.
@c This file is part of GNU Mailutils.
@c Copyright (C) 2001, 2002, 2003, 2004, 2006, 2007, 2009, 2010, 2011
@c Free Software Foundation, Inc.
@c
@c GNU Mailutils is free software; you can redistribute it and/or
@c modify it under the terms of the GNU General Public License as
@c published by the Free Software Foundation; either version 3, or (at
@c your option) any later version.
@c
@c GNU Mailutils is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
@c General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with GNU Mailutils. If not, see
@c <http://www.gnu.org/licenses/>.
@c This file implements Fra@,{c}ois Pinard's concept of 'renditions'.
@c ======================================================================
@c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
......@@ -39,9 +54,9 @@
@macro WRITEME
@ifclear PUBLISH
@quotation
@emph{This node is to be written.}
@end quotation
@cartouche
@center @emph{@strong{Editor's note:} This node is to be written.}
@end cartouche
@end ifclear
@end macro
......@@ -49,10 +64,10 @@
@macro UNREVISED
@ifclear PUBLISH
@quotation
(@emph{The information in this node may be obsolete or otherwise inaccurate.}
This message will disappear, once this node revised.)
@end quotation
@cartouche
@emph{Editor's note:} The information in this node may be obsolete or
otherwise inaccurate. This message will disappear, once this node revised.
@end cartouche
@end ifclear
@end macro
......@@ -60,35 +75,39 @@ This message will disappear, once this node revised.)
@macro FIXME{string}
@ifset PROOF
@ifset PROOF_FOOTNOTED
@footnote{@strong{FIXME:} \string\}
@end ifset
@ifclear PROOF_FOOTNOTED
@sp 1
@cartouche
@strong{<FIXME>} \string\ @strong{</>}
@strong{Editor's note:} \string\
@end cartouche
@end ifclear
@end ifset
@w{}
@end macro
@macro deadlink{}
(@strong{Editor's note: dangling link})
@end macro
@macro FIXME-ref{string}
@macro FIXMEREF{text,string}
@ifset PROOF
@strong{<REF>} \string\ @strong{</>}
@html
\text\ <span class="deadlink">\string\</span>
@end html
@ifnothtml
\text\ @i{\string\}
@end ifnothtml
@deadlink{}
@end ifset
@w{}
@end macro
@macro FIXME-ref{string}
@FIXMEREF{,\string\}
@end macro
@macro FIXME-pxref{string}
@ifset PROOF
@strong{<PXREF>} \string\ @strong{</>}
@end ifset
@FIXMEREF{see,\string\}
@end macro
@macro FIXME-xref{string}
@ifset PROOF
@strong{<XREF>} \string\ @strong{</>}
@end ifset
@FIXMEREF{See,\string\}
@end macro
......