.TH "newmail.h" 3 "23 Oct 2003" "libnewmail" \" -*- nroff -*- .ad l .nh .SH NAME newmail.h \- The public application interface of libnewmail. .SH SYNOPSIS .br .PP \fC#include \fP .br \fC#include \fP .br .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBnm_info\fP" .br .RI "\fIA structure for storing information about a mail spool.\fP" .ti -1c .RI "struct \fBnm_status\fP" .br .RI "\fIA structure describing a mail spool status.\fP" .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef void(* \fBnm_enum_cb_t\fP )(const char *spool, void *user)" .br .RI "\fIA prototype for callback functions for enumerating configured mail spools with \fBnm_list()\fP.\fP" .ti -1c .RI "typedef void(* \fBnm_query_cb_t\fP )(struct \fBnm_spool\fP *s, struct \fBnm_status\fP *status, void *user)" .br .RI "\fIA prototype for callback functions for asynchronous mail spool queries.\fP" .in -1c .SS "Enumerations" .in +1c .ti -1c .RI "enum \fBnm_flags\fP { \fBNM_FLAG_SYNCHRONOUS\fP = 1, \fBNM_FLAG_ASYNCHRONOUS\fP = 2 }" .br .RI "\fIFlags for a mail spool; specifies if a query on this spool will be executed synchronously or asynchronously.\fP" .ti -1c .RI "enum \fBnm_error\fP { \fBNM_ERROR_SYSTEM\fP = 256, \fBNM_ERROR_EXPLANATION\fP = 512, \fBNM_ERROR_SUCCESS\fP = 0, \fBNM_ERROR_NOCONFIG\fP = 1, \fBNM_ERROR_INVPAR\fP = 2, \fBNM_ERROR_MEMORY\fP = 3, \fBNM_ERROR_INVNAME\fP = 4, \fBNM_ERROR_DLFAIL\fP = 5, \fBNM_ERROR_NOTIMPL\fP = 6, \fBNM_ERROR_NOFILE\fP = 7, \fBNM_ERROR_FORK\fP = 8, \fBNM_ERROR_ALREADY\fP = 9, \fBNM_ERROR_CONTEXT\fP = 10, \fBNM_ERROR_INTERNAL\fP = 11, \fBNM_ERROR_SERVFAIL\fP = 12, \fBNM_ERROR_SERVNOTFOUND\fP = 13 }" .br .RI "\fIAn enumeration specifying a certain error condition.\fP" .ti -1c .RI "enum \fBnm_query\fP { \fBNM_QUERY_CUR\fP = 1, \fBNM_QUERY_NEW\fP = 2, \fBNM_QUERY_NCUR\fP = 4, \fBNM_QUERY_NNEW\fP = 8 }" .br .RI "\fITypes of mail spool queries; A combination of these flags should be specified on a call to \fBnm_query()\fP.\fP" .in -1c .SS "Functions" .in +1c .ti -1c .RI "\fBnm_spool\fP * \fBnm_open\fP (const char *spool)" .br .RI "\fIOpen the given mail spool configuration file and return a pointer to an opaque stracture used as handle to access the mail spool.\fP" .ti -1c .RI "void \fBnm_close\fP (struct \fBnm_spool\fP *s)" .br .RI "\fIFree the given mail spool handle.\fP" .ti -1c .RI "int \fBnm_query\fP (struct \fBnm_spool\fP *s, enum nm_query query, struct \fBnm_status\fP *status)" .br .RI "\fIIssue a synchronous query for the specified mail spool.\fP" .ti -1c .RI "int \fBnm_query_submit\fP (struct \fBnm_spool\fP *s, enum nm_query query, oop_source *oop, \fBnm_query_cb_t\fP cb, void *user)" .br .RI "\fIIssue an asynchronous query for the specified mail spool.\fP" .ti -1c .RI "int \fBnm_configure\fP (struct \fBnm_spool\fP *s)" .br .RI "\fIShow 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.\fP" .ti -1c .RI "int \fBnm_info\fP (struct \fBnm_spool\fP *s, struct nm_info *info)" .br .RI "\fIFill a structure containing some information about the specified mail spool.\fP" .ti -1c .RI "int \fBnm_list\fP (\fBnm_enum_cb_t\fP cb, void *user)" .br .RI "\fIEnumerate all configured mail spools.\fP" .ti -1c .RI "const char * \fBnm_strerror\fP (enum \fBnm_error\fP n, int e, const char *explanation)" .br .RI "\fIReturn a textual representation of the given error triplet.\fP" .ti -1c .RI "void \fBnm_perror\fP (const char *s)" .br .RI "\fIA similar function to libc's perror().\fP" .in -1c .SS "Variables" .in +1c .ti -1c .RI "void *(* \fBnm_malloc\fP )(size_t)" .br .RI "\fIA pointer to a malloc() compatible function which is used by libnewmail for allocating memory.\fP" .ti -1c .RI "void *(* \fBnm_realloc\fP )(void *, size_t)" .br .RI "\fIA pointer to a realloc() compatible function which is used by libnewmail for reallocating memory.\fP" .ti -1c .RI "void(* \fBnm_free\fP )(void *)" .br .RI "\fIA pointer to a free() compatible function which is used by libnewmail for freeing memory.\fP" .ti -1c .RI "const char * \fBnm_explanation\fP" .br .RI "\fIA pointer to a textual string giving a terse explanation for the last failure.\fP" .ti -1c .RI "enum \fBnm_error\fP \fBnm_errno\fP" .br .RI "\fIA variable describing the last error occured.\fP" .in -1c .SH "DETAILED DESCRIPTION" .PP The public application interface of libnewmail. .PP Applications linking to libnewmail should use only functions defined in this header file. .PP .PP Definition in file \fBnewmail.h\fP. .SH "TYPEDEF DOCUMENTATION" .PP .SS "typedef void(* nm_enum_cb_t)(const char *spool, void*user)" .PP A prototype for callback functions for enumerating configured mail spools with \fBnm_list()\fP. .PP \fBParameters: \fP .in +1c .TP \fB\fIspool\fP\fP A path to a configuration file .TP \fB\fIuser\fP\fP The user pointer specified on \fBnm_list()\fP invocation .PP Definition at line 137 of file newmail.h. .SS "typedef void(* nm_query_cb_t)(struct \fBnm_spool\fP *s, struct \fBnm_status\fP *status, void *user)" .PP A prototype for callback functions for asynchronous mail spool queries. .PP \fBParameters: \fP .in +1c .TP \fB\fIs\fP\fP The mail spool belonging to this response .TP \fB\fIstatus\fP\fP A pointer to a structure describing the mail spool status or NULL, if an error occured. In this case, nm_errno is set. .TP \fB\fIuser\fP\fP The user pointer specified on \fBnm_query_submit()\fP invocation .PP Definition at line 144 of file newmail.h. .SH "ENUMERATION TYPE DOCUMENTATION" .PP .SS "enum nm_error" .PP An enumeration specifying a certain error condition. .PP 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. .PP \fBEnumeration values: \fP .in +1c .TP \fB\fI\fINM_ERROR_SYSTEM\fP \fP\fP When this bit is set, errno is also set. .TP \fB\fI\fINM_ERROR_EXPLANATION\fP \fP\fP When this bit is set, nm_explanation is set. .TP \fB\fI\fINM_ERROR_SUCCESS\fP \fP\fP The query succeeded. .TP \fB\fI\fINM_ERROR_NOCONFIG\fP \fP\fP No configuration file was found for this spool. .TP \fB\fI\fINM_ERROR_INVPAR\fP \fP\fP An API function was called with corrupt parameters. .TP \fB\fI\fINM_ERROR_MEMORY\fP \fP\fP Failure while allocating memory. .TP \fB\fI\fINM_ERROR_INVNAME\fP \fP\fP Invalid name. .TP \fB\fI\fINM_ERROR_DLFAIL\fP \fP\fP Plugin could not be loaded (failure of dynamic loader). .TP \fB\fI\fINM_ERROR_NOTIMPL\fP \fP\fP Function not implemented. .TP \fB\fI\fINM_ERROR_NOFILE\fP \fP\fP File not found. .TP \fB\fI\fINM_ERROR_FORK\fP \fP\fP Failure on fork(). .TP \fB\fI\fINM_ERROR_ALREADY\fP \fP\fP A query was submitted while the previous hasn't been terminated yet. .TP \fB\fI\fINM_ERROR_CONTEXT\fP \fP\fP Function called in wrong context. .TP \fB\fI\fINM_ERROR_INTERNAL\fP \fP\fP Internal error. .TP \fB\fI\fINM_ERROR_SERVFAIL\fP \fP\fP Server failed. .TP \fB\fI\fINM_ERROR_SERVNOTFOUND\fP \fP\fP Server not found. .PP Definition at line 77 of file newmail.h. .SS "enum nm_flags" .PP Flags for a mail spool; specifies if a query on this spool will be executed synchronously or asynchronously. .PP Local mailbox queries are probably executed synchronously, while networked queries are exectued asynchronously. .PP \fBEnumeration values: \fP .in +1c .TP \fB\fI\fINM_FLAG_SYNCHRONOUS\fP \fP\fP The spool query won't block. .TP \fB\fI\fINM_FLAG_ASYNCHRONOUS\fP \fP\fP The spool query may block when not issued asynchronously. .PP Definition at line 65 of file newmail.h. .SS "enum nm_query" .PP Types of mail spool queries; A combination of these flags should be specified on a call to \fBnm_query()\fP. .PP \fBEnumeration values: \fP .in +1c .TP \fB\fI\fINM_QUERY_CUR\fP \fP\fP Query the boolean availability of total (current) mails. .TP \fB\fI\fINM_QUERY_NEW\fP \fP\fP Query the boolean availabillty of unread mails. .TP \fB\fI\fINM_QUERY_NCUR\fP \fP\fP Query the numeric count of total (current) mails. .TP \fB\fI\fINM_QUERY_NNEW\fP \fP\fP Query the numeric count of unread mails. .PP Definition at line 100 of file newmail.h. .SH "FUNCTION DOCUMENTATION" .PP .SS "void nm_close (struct \fBnm_spool\fP * s)" .PP Free the given mail spool handle. .PP \fBParameters: \fP .in +1c .TP \fB\fIs\fP\fP The spool handle to be freed .PP \fBExamples: \fP .in +1c \fBeasy.c\fP, \fBnm-spoolhack.c\fP, \fBnmail-async.c\fP, and \fBnmail.c\fP. .SS "int nm_configure (struct \fBnm_spool\fP * s)" .PP 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. .PP \fBParameters: \fP .in +1c .TP \fB\fIs\fP\fP 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. .PP \fBReturns: \fP .in +1c zero on success, negative on failure. In the latter case nm_errno is set. .SS "int nm_info (struct \fBnm_spool\fP * s, struct nm_info * info)" .PP Fill a structure containing some information about the specified mail spool. .PP \fBParameters: \fP .in +1c .TP \fB\fIs\fP\fP The spool to be queried .TP \fB\fIinfo\fP\fP A pointer to the information structure to be filled .PP \fBReturns: \fP .in +1c zero on success, negative on failure. In the latter case nm_errno is set. .PP \fBExamples: \fP .in +1c \fBnmail-async.c\fP, and \fBnmail.c\fP. .SS "int nm_list (\fBnm_enum_cb_t\fP cb, void * user)" .PP Enumerate all configured mail spools. .PP \fBParameters: \fP .in +1c .TP \fB\fIcb\fP\fP A callback function called for every configured mail spool. .TP \fB\fIuser\fP\fP An arbitrary pointer to be passed to cb .PP \fBReturns: \fP .in +1c 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. .PP \fBExamples: \fP .in +1c \fBnmail-async.c\fP, and \fBnmail.c\fP. .SS "struct \fBnm_spool\fP* nm_open (const char * spool)" .PP Open the given mail spool configuration file and return a pointer to an opaque stracture used as handle to access the mail spool. .PP The returned pointer should be freed with \fBnm_close()\fP when it is no longer needed. .PP \fBParameters: \fP .in +1c .TP \fB\fIspool\fP\fP A path to a mail spool configuration file. If NULL an automatic detection of the mail spool location is tried. .PP \fBReturns: \fP .in +1c A pointer to a newly allocated spool handle or NULL on failure. In this case nm_errno is set. .PP \fBExamples: \fP .in +1c \fBeasy.c\fP, \fBnm-spoolhack.c\fP, \fBnmail-async.c\fP, and \fBnmail.c\fP. .SS "void nm_perror (const char * s)" .PP A similar function to libc's perror(). .PP This function will show libnewmail error conditions however. .PP \fBParameters: \fP .in +1c .TP \fB\fIs\fP\fP A string which will be concatenated with the error string .PP \fBExamples: \fP .in +1c \fBnmail-async.c\fP, and \fBnmail.c\fP. .SS "int nm_query (struct \fBnm_spool\fP * s, enum nm_query query, struct \fBnm_status\fP * status)" .PP Issue a synchronous query for the specified mail spool. .PP 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. .PP \fBParameters: \fP .in +1c .TP \fB\fIs\fP\fP The spool to be queried .TP \fB\fIquery\fP\fP The desired query type .TP \fB\fIstatus\fP\fP A pointer to a structure which will be filled with the query response .PP \fBReturns: \fP .in +1c zero on success, negative on failure. In the latter case nm_errno is set. .PP \fBExamples: \fP .in +1c \fBeasy.c\fP, \fBnm-spoolhack.c\fP, and \fBnmail.c\fP. .SS "int nm_query_submit (struct \fBnm_spool\fP * s, enum nm_query query, oop_source * oop, \fBnm_query_cb_t\fP cb, void * user)" .PP Issue an asynchronous query for the specified mail spool. .PP 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. .PP \fBParameters: \fP .in +1c .TP \fB\fIs\fP\fP The spool to be queried .TP \fB\fIquery\fP\fP The desired query type .TP \fB\fIoop\fP\fP The liboop oop_source which shall be used for asynchronous handling .TP \fB\fIcb\fP\fP The callback function to be called when the query is finished. .TP \fB\fIuser\fP\fP An arbitrary pointer to be passed to cb .PP \fBReturns: \fP .in +1c zero on success, negative on failure. In the latter case nm_errno is set. .PP \fBExamples: \fP .in +1c \fBnmail-async.c\fP. .SS "const char* nm_strerror (enum \fBnm_error\fP n, int e, const char * explanation)" .PP Return a textual representation of the given error triplet. .PP \fBParameters: \fP .in +1c .TP \fB\fIn\fP\fP A libnewmail error condition (e.g. nm_errno) .TP \fB\fIe\fP\fP A libc error condition (e.g. errno) .TP \fB\fIexplanation\fP\fP A libnewmail error explanation (e.g. nm_explanation) .PP \fBReturns: \fP .in +1c A pointer to a string in static memory. The contents is overwritten on subsequent calls to \fBnm_strerror()\fP or \fBnm_perror()\fP. .PP \fBExamples: \fP .in +1c \fBeasy.c\fP, \fBnm-spoolhack.c\fP, \fBnmail-async.c\fP, and \fBnmail.c\fP. .SH "VARIABLE DOCUMENTATION" .PP .SS "enum \fBnm_error\fP nm_errno" .PP A variable describing the last error occured. .PP Only valid when the last API function call returned a failure. .PP Definition at line 172 of file newmail.h. .SS "const char* nm_explanation" .PP A pointer to a textual string giving a terse explanation for the last failure. .PP This is only valid when NM_ERROR_EXPLANATION is set in nm_errno. .PP Definition at line 167 of file newmail.h. .SS "void(* nm_free)(void *)" .PP A pointer to a free() compatible function which is used by libnewmail for freeing memory. .PP Initially set to libc's free(). .PP Definition at line 161 of file newmail.h. .SS "void*(* nm_malloc)(size_t)" .PP A pointer to a malloc() compatible function which is used by libnewmail for allocating memory. .PP Initially set to libc's malloc(). .PP Definition at line 149 of file newmail.h. .SS "void*(* nm_realloc)(void *,size_t)" .PP A pointer to a realloc() compatible function which is used by libnewmail for reallocating memory. .PP Initially set to libc's realloc(). .PP Definition at line 155 of file newmail.h. .SH "AUTHOR" .PP Generated automatically by Doxygen for libnewmail from the source code.