diff options
Diffstat (limited to 'src/newmail.h')
| -rw-r--r-- | src/newmail.h | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/src/newmail.h b/src/newmail.h new file mode 100644 index 0000000..109a87d --- /dev/null +++ b/src/newmail.h @@ -0,0 +1,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, const 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, const 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 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, const 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, const 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 |