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 @@ ...@@ -37,6 +37,7 @@
37 * mail: (mailutils)mail. Send and Receive Mail. 37 * mail: (mailutils)mail. Send and Receive Mail.
38 * maidag: (mailutils)maidag. A General-Purpose Mail Delivery Agent. 38 * maidag: (mailutils)maidag. A General-Purpose Mail Delivery Agent.
39 * messages: (mailutils)messages. Count Messages in a Mailbox. 39 * messages: (mailutils)messages. Count Messages in a Mailbox.
40 * movemail: (mailutils)movemail. Move Mail between Mailboxes.
40 * pop3d: (mailutils)pop3d. POP3 Daemon. 41 * pop3d: (mailutils)pop3d. POP3 Daemon.
41 * readmsg: (mailutils)readmsg. Extract Messages from a Folder. 42 * readmsg: (mailutils)readmsg. Extract Messages from a Folder.
42 * sieve: (mailutils)sieve. Mail Filtering Utility. 43 * sieve: (mailutils)sieve. Mail Filtering Utility.
......
1 @c This is part of the GNU Mailutils manual.
2 @c Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2010,
3 @c 2011 Free Software Foundation, Inc.
4 @c See file mailutils.texi for copying conditions.
5 @comment *******************************************************************
6
7 @chapter Mailutils Object Model
8 Mailutils is written in C, the language is widely supported on
9 many platforms and the ABI (Binary Interface) for linking objects
10 with other languages (like Guile, Java, ...) is well-defined.
11
12 The C language does not provide support for object oriented programming,
13 but by using structures and pointers to function, it is possible to provide
14 a simple framework.
15
16 Every Mailutils object has a corresponding C structure holding its interface
17 and specific data. For example mu_object_t, is the root object and all mailutils objects
18 extends it:
19
20 @smallexample
21 struct _mu_object;
22 typedef struct _mu_object* mu_object_t;
23
24 /* Definition of the interface for mu_object */
25 struct _mu_object_vtable
26 @{
27 int (*create) (mu_object_t *object);
28 void (*destroy) (mu_object_t *object);
29 void (*notify) (mu_object_t object, int event, void *data);
30 @}
31
32 struct _mu_object
33 @{
34 struct _mu_object_vtable *vtable;
35 int type;
36 @}
37 @end smallexample
38
39 The @var{vtable} is an array of pointers to function, it provides the interface
40 or the list of function for this object. The library provides wrapper to
41 access the functions instead using the @var{vtable} directly.
42
43 @smallexample
44 int mu_object_notify(mu_object object, int event, void *data)
45 @{
46 if (object == NULL || object->vtable == NULL
47 || object->vtable->notify == NULL)
48 return MU_ERR_NOT_SUPPORTED;
49 return object->vtable->notify (object, event, data);
50 @}
51 @end smallexample
52
53 Instead of using macros or the vtable directly.
54 @smallexample
55 #define mu_object_notify(o, evt, d) ((o)->vtable->notify(o, evt, d))
56 @end smallexample
57
58 @section Implementing an Interface
59
60 @comment ***********************************************************
61 @comment This is not a very good/useful example, we should do one using
62 @comment header or message, something usefully that would clarify the concepts
63 @comment better and at the same could be reuse in code by clients.
64 @comment
65 @comment For example mime_t "extends" message_t, this is a good example
66 @comment since you can consider a mime_t as a message_t but with extra functions.
67 @comment ***********************************************************
68
69 For a more concrete implementation, lets say we are implementing some caching mailbox
70 but we need to keep a better track of the objects in our implementation.
71 We take the approach of simple reference counting and extend the mu_object_t.
72
73 @smallexample
74 #include <mailutils/sys/object.h>
75
76 struct my_object;
77 typedef struct refcount* refcount;
78
79 struct refcount_vtable
80 @{
81 struct _mu_object_vtable base;
82 int (*increment)(refcount_t);
83 int (*decrement)(refcount_t);
84 @}
85
86 struct refcount
87 @{
88 struct refcount_vtable * vtable;
89 int count;
90 @}
91
92 static int
93 refcount_increment (mu_object_t obj)
94 @{
95 refcount_t refcount = (refcount_t)obj;
96 refcount->count++;
97 return refcount->count;
98 @}
99
100 static int
101 refcount_decrement (mu_object_t obj)
102 @{
103 refcount_t refcount = (refcount_t)obj;
104 if (refcount->count > 0)
105 refcount->count--;
106 return refcount->count;
107 @}
108
109 int
110 my_mu_object_create (mu_object_t *pobject)
111 @{
112 static struct refcount_vtable* vtable;
113 refcount_t ref;
114
115 if (object == NULL)
116 return EINVAL;
117
118 if (!vtable)
119 @{
120 vtable = calloc(1, sizeof(*vtable));
121 if (vtable == NULL)
122 return ENOMEM;
123 vtable->base.vtable = &_mu_object_vtable; // FIXME where can they get the base vtable
124 vtable->increment = refcount_increment;
125 vtable->decrement = refcount_decrement;
126 @}
127
128 ref = malloc(sizeof *ref);
129 ref->base = vtable;
130 *pobject = &ref->base.vtable
131 return 0;
132 @}
133 @end smallexample
134
135 The interface adds a @code{decrement} and @code{increment} to the @code{mu_object_t}
136 interface. Creating a @code{refcount_t} can be savely typecast to @code{mu_object_t},
137 for example:
138
139 @smallexample
140 refcount_t ref;
141 mu_object_t obj;
142 refcount_create (&ref);
143
144 /* send a notification to the listeners of an event. */
145 mu_object_notify ((mu_object_t)ref, 5, NULL)
146
147 @end smallexample
1 @c Let's use the concept of 'renditions' by Fra@,{c}ois Pinard 1 @c This file is part of GNU Mailutils.
2 @c I extended it by adding a FIXME_FOOTNOTE variable, which controls 2 @c Copyright (C) 2001, 2002, 2003, 2004, 2006, 2007, 2009, 2010, 2011
3 @c whether FIXME information should be placed in footnotes or 3 @c Free Software Foundation, Inc.
4 @c inlined. 4 @c
5 @c GNU Mailutils is free software; you can redistribute it and/or
6 @c modify it under the terms of the GNU General Public License as
7 @c published by the Free Software Foundation; either version 3, or (at
8 @c your option) any later version.
9 @c
10 @c GNU Mailutils is distributed in the hope that it will be useful, but
11 @c WITHOUT ANY WARRANTY; without even the implied warranty of
12 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 @c General Public License for more details.
14 @c
15 @c You should have received a copy of the GNU General Public License
16 @c along with GNU Mailutils. If not, see
17 @c <http://www.gnu.org/licenses/>.
18
19 @c This file implements Fra@,{c}ois Pinard's concept of 'renditions'.
5 20
6 @c ====================================================================== 21 @c ======================================================================
7 @c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF, 22 @c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
...@@ -39,9 +54,9 @@ ...@@ -39,9 +54,9 @@
39 54
40 @macro WRITEME 55 @macro WRITEME
41 @ifclear PUBLISH 56 @ifclear PUBLISH
42 @quotation 57 @cartouche
43 @emph{This node is to be written.} 58 @center @emph{@strong{Editor's note:} This node is to be written.}
44 @end quotation 59 @end cartouche
45 @end ifclear 60 @end ifclear
46 @end macro 61 @end macro
47 62
...@@ -49,10 +64,10 @@ ...@@ -49,10 +64,10 @@
49 64
50 @macro UNREVISED 65 @macro UNREVISED
51 @ifclear PUBLISH 66 @ifclear PUBLISH
52 @quotation 67 @cartouche
53 (@emph{The information in this node may be obsolete or otherwise inaccurate.} 68 @emph{Editor's note:} The information in this node may be obsolete or
54 This message will disappear, once this node revised.) 69 otherwise inaccurate. This message will disappear, once this node revised.
55 @end quotation 70 @end cartouche
56 @end ifclear 71 @end ifclear
57 @end macro 72 @end macro
58 73
...@@ -60,35 +75,39 @@ This message will disappear, once this node revised.) ...@@ -60,35 +75,39 @@ This message will disappear, once this node revised.)
60 75
61 @macro FIXME{string} 76 @macro FIXME{string}
62 @ifset PROOF 77 @ifset PROOF
63 @ifset PROOF_FOOTNOTED 78 @sp 1
64 @footnote{@strong{FIXME:} \string\}
65 @end ifset
66 @ifclear PROOF_FOOTNOTED
67 @cartouche 79 @cartouche
68 @strong{<FIXME>} \string\ @strong{</>} 80 @strong{Editor's note:} \string\
69 @end cartouche 81 @end cartouche
70 @end ifclear
71 @end ifset 82 @end ifset
83 @w{}
84 @end macro
72 85
86 @macro deadlink{}
87 (@strong{Editor's note: dangling link})
73 @end macro 88 @end macro
74 89
75 @macro FIXME-ref{string} 90 @macro FIXMEREF{text,string}
76 @ifset PROOF 91 @ifset PROOF
77 @strong{<REF>} \string\ @strong{</>} 92 @html
93 \text\ <span class="deadlink">\string\</span>
94 @end html
95 @ifnothtml
96 \text\ @i{\string\}
97 @end ifnothtml
98 @deadlink{}
78 @end ifset 99 @end ifset
100 @w{}
101 @end macro
79 102
103 @macro FIXME-ref{string}
104 @FIXMEREF{,\string\}
80 @end macro 105 @end macro
81 106
82 @macro FIXME-pxref{string} 107 @macro FIXME-pxref{string}
83 @ifset PROOF 108 @FIXMEREF{see,\string\}
84 @strong{<PXREF>} \string\ @strong{</>}
85 @end ifset
86
87 @end macro 109 @end macro
88 110
89 @macro FIXME-xref{string} 111 @macro FIXME-xref{string}
90 @ifset PROOF 112 @FIXMEREF{See,\string\}
91 @strong{<XREF>} \string\ @strong{</>}
92 @end ifset
93
94 @end macro 113 @end macro
......