1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
#ifndef foonewmailhfoo
#define foonewmailhfoo
/* $Id$ */
/***
This file is part of libnewmail
libnewmail is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
libnewmail is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with libnewmail; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA
***/
/** \mainpage
*
* For a brief explanation of libnewmail's purpose, have a look on <a href="../../README.html">the README file</a>. Thank you!
*
*/
/** \example easy.c
* A minimal example
*/
/** \example nmail.c
* This is an usage example for the simple, synchronous API of libnewmail
*/
/** \example nmail-async.c
* This is an usage example for the asynchronous API of libnewmail
*/
/** \example nm-spoolhack.c This is an example implementing a tool to
* emulate Unix mail spool stat() behaviour for a flag file to
* multiplex mail status information of libnewmail plugins.
*/
/** \file
*
* The public application interface of libnewmail. Applications
* linking to libnewmail should use only functions defined in this
* header file.
*/
#include <limits.h>
#include <oop.h>
/**
* Flags for a mail spool; specifies if a query on this spool will be
* executed synchronously or asynchronously. Local mailbox queries
* are probably executed synchronously, while networked queries are
* exectued asynchronously.
*/
enum nm_flags {
NM_FLAG_SYNCHRONOUS= 1, /**< The spool query won't block */
NM_FLAG_ASYNCHRONOUS = 2 /**< The spool query may block when not issued asynchronously */
};
/**
* An enumeration specifying a certain error
* condition. NM_ERROR_SYSTEM and NM_ERROR_EXPLANATION may be ORed
* logically with one of the other constants, to specifiy that system
* errno and/or the nm_explanation variable is in context with the
* error occured.
*/
enum nm_error {
NM_ERROR_SYSTEM = 256, /**< When this bit is set, errno is also set */
NM_ERROR_EXPLANATION = 512, /**< When this bit is set, nm_explanation is set */
NM_ERROR_SUCCESS = 0, /**< The query succeeded */
NM_ERROR_NOCONFIG = 1, /**< No configuration file was found for this spool */
NM_ERROR_INVPAR = 2, /**< An API function was called with corrupt parameters */
NM_ERROR_MEMORY = 3, /**< Failure while allocating memory */
NM_ERROR_INVNAME = 4, /**< Invalid name */
NM_ERROR_DLFAIL = 5, /**< Plugin could not be loaded (failure of dynamic loader) */
NM_ERROR_NOTIMPL = 6, /**< Function not implemented */
NM_ERROR_NOFILE = 7, /**< File not found */
NM_ERROR_FORK = 8, /**< Failure on fork() */
NM_ERROR_ALREADY = 9, /**< A query was submitted while the previous hasn't been terminated yet */
NM_ERROR_CONTEXT = 10, /**< Function called in wrong context */
NM_ERROR_INTERNAL = 11, /**< Internal error */
NM_ERROR_SERVFAIL = 12, /**< Server failed */
NM_ERROR_SERVNOTFOUND = 13, /**< Server not found */
};
/**
* Types of mail spool queries; A combination of these flags should be
* specified on a call to nm_query()
*/
enum nm_query {
NM_QUERY_CUR = 1, /**< Query the boolean availability of total (current) mails */
NM_QUERY_NEW = 2, /**< Query the boolean availabillty of unread mails */
NM_QUERY_NCUR = 4, /**< Query the numeric count of total (current) mails */
NM_QUERY_NNEW = 8 /**< Query the numeric count of unread mails */
};
/** Opaque structure encapsulating a handle on a mail spool A pointer
* to a structure of this type is returned by nm_open(). It should be
* freed with nm_close().
*/
struct nm_spool;
/** A structure describing a mail spool status.
*
*/
struct nm_status {
int cur; /**< The number of total mails available if the query was issued with NM_QUERY_NCUR or a boolean value if NM_QUERY_CUR was set. */
int new; /**< The number of unread mails available if the query was issued with NM_QUERY_NNEW or a boolean value if NM_QUERY_NEW was set. */
};
/** A structure for storing information about a mail spool. For usage with nm_info().
*/
struct nm_info {
char name[NAME_MAX]; /**< Name of the mailspool */
char path[PATH_MAX]; /**< Path to the configuration file */
char type[32]; /**< Textual representation of the mail spool type */
char text[128]; /**< Description of the mail spool */
enum nm_flags flags; /**< Flags describing the the mail spool */
};
/** A prototype for callback functions for enumerating configured
* mail spools with nm_list().
* @param spool A path to a configuration file
* @param user The user pointer specified on nm_list() invocation
*/
typedef void (*nm_enum_cb_t) (const char *spool, void*user);
/** A prototype for callback functions for asynchronous mail spool queries.
* @param s The mail spool belonging to this response
* @param status A pointer to a structure describing the mail spool status or NULL, if an error occured. In this case, nm_errno is set.
* @param user The user pointer specified on nm_query_submit() invocation
*/
typedef void (*nm_query_cb_t) (struct nm_spool *s, struct nm_status *status, void *user);
/** A pointer to a malloc() compatible function which is used by
* libnewmail for allocating memory. Initially set to libc's malloc().
*/
extern void* (*nm_malloc)(size_t);
/** A pointer to a realloc() compatible function which is used by
* libnewmail for reallocating memory. Initially set to libc's
* realloc().
*/
extern void* (*nm_realloc)(void *,size_t);
/** A pointer to a free() compatible function which is used by
* libnewmail for freeing memory. Initially set to libc's
* free().
*/
extern void (*nm_free)(void *);
/** A pointer to a textual string giving a terse explanation for the
* last failure. This is only valid when NM_ERROR_EXPLANATION is set
* in nm_errno.
*/
extern const char *nm_explanation;
/** A variable describing the last error occured. Only valid when the
* last API function call returned a failure.
*/
extern enum nm_error nm_errno;
/** Open the given mail spool configuration file and return a pointer
* to an opaque stracture used as handle to access the mail spool. The
* returned pointer should be freed with nm_close() when it is no
* longer needed.
* @param spool A path to a mail spool configuration file. If NULL an
* automatic detection of the mail spool location is tried.
* @return A pointer to a newly allocated spool handle or NULL on failure. In this case nm_errno is set.
*/
struct nm_spool* nm_open(const char *spool);
/** Free the given mail spool handle.
* @param s The spool handle to be freed
*/
void nm_close(struct nm_spool *s);
/** Issue a synchronous query for the specified mail spool. The
* function will block until the query succeeded or a failure is
* returned. Be aware that every query may use fork() to spawn a
* background process to execute the query.
* @param s The spool to be queried
* @param query The desired query type
* @param status A pointer to a structure which will be filled with the query response
* @return zero on success, negative on failure. In the latter case nm_errno is set.
*/
int nm_query(struct nm_spool *s, enum nm_query query, struct nm_status *status);
/** Issue an asynchronous query for the specified mail spool. The
* function will return immediately, however the callback cb is called
* when the query is finished. Be aware that every query may use fork() to spawn a
* background process to execute the query.
* @param s The spool to be queried
* @param query The desired query type
* @param oop The liboop oop_source which shall be used for asynchronous handling
* @param cb The callback function to be called when the query is finished.
* @param user An arbitrary pointer to be passed to cb
* @return zero on success, negative on failure. In the latter case nm_errno is set.
*/
int nm_query_submit(struct nm_spool *s, enum nm_query query, oop_source *oop, nm_query_cb_t cb, void *user);
/** Show an X11 configuration dialog for the specified mail spool -- Currently an NOOP
* This function will run an external configuration program for the specific mail spool eventually.
* @param s The spool the dialog should be shown for. NULL if a
* complete configuration dialog should be shown, with the possibility
* for the user to create new mail spool profiles.
* @return zero on success, negative on failure. In the latter case nm_errno is set.
*/
int nm_configure(struct nm_spool *s);
/** Fill a structure containing some information about the specified mail spool
* @param s The spool to be queried
* @param info A pointer to the information structure to be filled
* @return zero on success, negative on failure. In the latter case nm_errno is set.
*/
int nm_info(struct nm_spool *s, struct nm_info *info);
/** Enumerate all configured mail spools.
* @param cb A callback function called for every configured mail spool.
* @param user An arbitrary pointer to be passed to cb
* @return negative on failure, number of calls to cb invoked. If this
* is zero, no mail spool is configured, you probably should try a
* nm_open(NULL) next.
*/
int nm_list(nm_enum_cb_t cb, void *user);
/** Return a textual representation of the given error triplet.
* @param n A libnewmail error condition (e.g. nm_errno)
* @param e A libc error condition (e.g. errno)
* @param explanation A libnewmail error explanation (e.g. nm_explanation)
* @return A pointer to a string in static memory. The contents is
* overwritten on subsequent calls to nm_strerror() or nm_perror().
*/
const char *nm_strerror(enum nm_error n, int e, const char *explanation);
/** A similar function to libc's perror(). This function will show
* libnewmail error conditions however.
* @param s A string which will be concatenated with the error string
*/
void nm_perror(const char *s);
#endif
|
