#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 the README file. 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
#include
/**
* 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