---

newmail.h File Reference

The public application interface of libnewmail. More...

#include <limits.h>
#include <oop.h>

Go to the source code of this file.

Data Structures
struct	nm_info
	A structure for storing information about a mail spool. More...
struct	nm_status
	A structure describing a mail spool status. More...
Typedefs
typedef void(*	nm_enum_cb_t )(const char *spool, void *user)
	A prototype for callback functions for enumerating configured mail spools with nm_list().
typedef void(*	nm_query_cb_t )(struct nm_spool *s, struct nm_status *status, void *user)
	A prototype for callback functions for asynchronous mail spool queries.
Enumerations
enum	nm_flags { NM_FLAG_SYNCHRONOUS = 1, NM_FLAG_ASYNCHRONOUS = 2 }
	Flags for a mail spool; specifies if a query on this spool will be executed synchronously or asynchronously. More...
enum	nm_error {   NM_ERROR_SYSTEM = 256, NM_ERROR_EXPLANATION = 512, NM_ERROR_SUCCESS = 0, NM_ERROR_NOCONFIG = 1,   NM_ERROR_INVPAR = 2, NM_ERROR_MEMORY = 3, NM_ERROR_INVNAME = 4, NM_ERROR_DLFAIL = 5,   NM_ERROR_NOTIMPL = 6, NM_ERROR_NOFILE = 7, NM_ERROR_FORK = 8, NM_ERROR_ALREADY = 9,   NM_ERROR_CONTEXT = 10, NM_ERROR_INTERNAL = 11, NM_ERROR_SERVFAIL = 12, NM_ERROR_SERVNOTFOUND = 13 }
	An enumeration specifying a certain error condition. More...
enum	nm_query { NM_QUERY_CUR = 1, NM_QUERY_NEW = 2, NM_QUERY_NCUR = 4, NM_QUERY_NNEW = 8 }
	Types of mail spool queries; A combination of these flags should be specified on a call to nm_query(). More...
Functions
nm_spool *	nm_open (const char *spool)
	Open the given mail spool configuration file and return a pointer to an opaque stracture used as handle to access the mail spool.
void	nm_close (struct nm_spool *s)
	Free the given mail spool handle.
int	nm_query (struct nm_spool *s, enum nm_query query, struct nm_status *status)
	Issue a synchronous query for the specified mail spool.
int	nm_query_submit (struct nm_spool *s, enum nm_query query, oop_source *oop, nm_query_cb_t cb, void *user)
	Issue an asynchronous query for the specified mail spool.
int	nm_configure (struct nm_spool *s)
	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.
int	nm_info (struct nm_spool *s, struct nm_info *info)
	Fill a structure containing some information about the specified mail spool.
int	nm_list (nm_enum_cb_t cb, void *user)
	Enumerate all configured mail spools.
const char *	nm_strerror (enum nm_error n, int e, const char *explanation)
	Return a textual representation of the given error triplet.
void	nm_perror (const char *s)
	A similar function to libc's perror().
Variables
void *(*	nm_malloc )(size_t)
	A pointer to a malloc() compatible function which is used by libnewmail for allocating memory.
void *(*	nm_realloc )(void *, size_t)
	A pointer to a realloc() compatible function which is used by libnewmail for reallocating memory.
void(*	nm_free )(void *)
	A pointer to a free() compatible function which is used by libnewmail for freeing memory.
const char *	nm_explanation
	A pointer to a textual string giving a terse explanation for the last failure.
enum nm_error	nm_errno
	A variable describing the last error occured.

---

Detailed Description

The public application interface of libnewmail.

Applications linking to libnewmail should use only functions defined in this header file.

Definition in file newmail.h.

---

Typedef Documentation

typedef void(* nm_enum_cb_t)(const char *spool, void*user)

A prototype for callback functions for enumerating configured mail spools with nm_list(). Parameters: spool  A path to a configuration file user  The user pointer specified on nm_list() invocation Definition at line 137 of file newmail.h.

typedef void(* nm_query_cb_t)(struct nm_spool *s, struct nm_status *status, void *user)

A prototype for callback functions for asynchronous mail spool queries. Parameters: s  The mail spool belonging to this response status  A pointer to a structure describing the mail spool status or NULL, if an error occured. In this case, nm_errno is set. user  The user pointer specified on nm_query_submit() invocation Definition at line 144 of file newmail.h.

---

Enumeration Type Documentation

enum nm_error

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. Enumeration values: NM_ERROR_SYSTEM  When this bit is set, errno is also set. NM_ERROR_EXPLANATION  When this bit is set, nm_explanation is set. NM_ERROR_SUCCESS  The query succeeded. NM_ERROR_NOCONFIG  No configuration file was found for this spool. NM_ERROR_INVPAR  An API function was called with corrupt parameters. NM_ERROR_MEMORY  Failure while allocating memory. NM_ERROR_INVNAME  Invalid name. NM_ERROR_DLFAIL  Plugin could not be loaded (failure of dynamic loader). NM_ERROR_NOTIMPL  Function not implemented. NM_ERROR_NOFILE  File not found. NM_ERROR_FORK  Failure on fork(). NM_ERROR_ALREADY  A query was submitted while the previous hasn't been terminated yet. NM_ERROR_CONTEXT  Function called in wrong context. NM_ERROR_INTERNAL  Internal error. NM_ERROR_SERVFAIL  Server failed. NM_ERROR_SERVNOTFOUND  Server not found. Definition at line 77 of file newmail.h.

enum nm_flags

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. Enumeration values: NM_FLAG_SYNCHRONOUS  The spool query won't block. NM_FLAG_ASYNCHRONOUS  The spool query may block when not issued asynchronously. Definition at line 65 of file newmail.h.

enum nm_query

Types of mail spool queries; A combination of these flags should be specified on a call to nm_query(). Enumeration values: NM_QUERY_CUR  Query the boolean availability of total (current) mails. NM_QUERY_NEW  Query the boolean availabillty of unread mails. NM_QUERY_NCUR  Query the numeric count of total (current) mails. NM_QUERY_NNEW  Query the numeric count of unread mails. Definition at line 100 of file newmail.h.

---

Function Documentation

void nm_close (  struct nm_spool *    s )

Free the given mail spool handle. Parameters: s  The spool handle to be freed Examples: easy.c, nm-spoolhack.c, nmail-async.c, and nmail.c.

int nm_configure (  struct nm_spool *    s )

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. Parameters: 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. Returns: 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 )

Fill a structure containing some information about the specified mail spool. Parameters: s  The spool to be queried info  A pointer to the information structure to be filled Returns: zero on success, negative on failure. In the latter case nm_errno is set. Examples: nmail-async.c, and nmail.c.

int nm_list (  nm_enum_cb_t    cb, void *    user )

Enumerate all configured mail spools. Parameters: cb  A callback function called for every configured mail spool. user  An arbitrary pointer to be passed to cb Returns: 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. Examples: nmail-async.c, and nmail.c.

struct nm_spool* nm_open (  const char *    spool )

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. Parameters: spool  A path to a mail spool configuration file. If NULL an automatic detection of the mail spool location is tried. Returns: A pointer to a newly allocated spool handle or NULL on failure. In this case nm_errno is set. Examples: easy.c, nm-spoolhack.c, nmail-async.c, and nmail.c.

void nm_perror (  const char *    s )

A similar function to libc's perror(). This function will show libnewmail error conditions however. Parameters: s  A string which will be concatenated with the error string Examples: nmail-async.c, and nmail.c.

int nm_query (  struct nm_spool *    s, enum nm_query    query, struct nm_status *    status )

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. Parameters: s  The spool to be queried query  The desired query type status  A pointer to a structure which will be filled with the query response Returns: zero on success, negative on failure. In the latter case nm_errno is set. Examples: easy.c, nm-spoolhack.c, and nmail.c.

int nm_query_submit (  struct nm_spool *    s, enum nm_query    query, oop_source *    oop, nm_query_cb_t    cb, void *    user )

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. Parameters: s  The spool to be queried query  The desired query type oop  The liboop oop_source which shall be used for asynchronous handling cb  The callback function to be called when the query is finished. user  An arbitrary pointer to be passed to cb Returns: zero on success, negative on failure. In the latter case nm_errno is set. Examples: nmail-async.c.

const char* nm_strerror (  enum nm_error    n, int    e, const char *    explanation )

Return a textual representation of the given error triplet. Parameters: n  A libnewmail error condition (e.g. nm_errno) e  A libc error condition (e.g. errno) explanation  A libnewmail error explanation (e.g. nm_explanation) Returns: A pointer to a string in static memory. The contents is overwritten on subsequent calls to nm_strerror() or nm_perror(). Examples: easy.c, nm-spoolhack.c, nmail-async.c, and nmail.c.

---

Variable Documentation

enum nm_error nm_errno

A variable describing the last error occured. Only valid when the last API function call returned a failure. Definition at line 172 of file newmail.h.

const char* nm_explanation

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. Definition at line 167 of file newmail.h.

void(* nm_free)(void *)

A pointer to a free() compatible function which is used by libnewmail for freeing memory. Initially set to libc's free(). Definition at line 161 of file newmail.h.

void*(* nm_malloc)(size_t)

A pointer to a malloc() compatible function which is used by libnewmail for allocating memory. Initially set to libc's malloc(). Definition at line 149 of file newmail.h.

void*(* nm_realloc)(void *,size_t)

A pointer to a realloc() compatible function which is used by libnewmail for reallocating memory. Initially set to libc's realloc(). Definition at line 155 of file newmail.h.

---