libmail - A mail handling library Code

.\" This file is part of libmail.
.\" 
.\"	(c) 2009 - Dimitris Mandalidis <mandas@users.sourceforge.net>
.\"
.\" libmail 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 3 of the License, or
.\" (at your option) any later version.
.\" 
.\" libmail 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 libmail.  If not, see <http://www.gnu.org/licenses/>.
.TH LIBMAIL_POP3 3 "2009-06-08" "version 0.3" "libmail - A mail handling library"
.SH NAME
pop3_check, pop3_authenticate, pop3_disconnect, pop3_connect - libmail's
POP3 protocol supporting functions
.SH SYNOPSIS
.nf
.B #include <libmail/libmail.h>
.B #include <libmail/pop3.h>
.sp
.BI "int pop3_connect(pop3_mailbox_t *" "server" );
.sp
.BI "int pop3_disconnect(pop3_mailbox_t *" "server" );
.sp
.BI "int pop3_authenticate(pop3_mailbox_t *" "server" );
.sp
.BI "int pop3_check(pop3_mailbox_t *" "server" ", int *" "n_new_messages" ", int *" "n_messages" );
.fi
.SH DESCRIPTION
All the above functions takes a pointer to 
.B pop3_mailbox_t 
structure which identify the server's configuration. More specifically 
.I pop3_mailbox_t 
is defined as follows :
.sp
.nf
	typedef struct libmail_remote_server_t {
		char hostname[HOST_NAME_MAX+1];
		char port[6];
		short inet_family;
		short use_secure;
		int sfd;
	} libmail_remote_server_t;

	typedef struct pop3_mailbox_t {
		libmail_remote_server_t server;	
		libmail_auth_t auth;
		char greeting[BUFSIZE+1];
	} pop3_mailbox_t;
.fi
.sp
The server's hostname and port are specified in
.I hostname
and
.I port
respectively while
.I inet_family
might be 
.BR "LIBMAIL_IPV4" " or " "LIBMAIL_IPV6"
to indicate IP protocol version.
.I use_secure
might be
.BR "LIBMAIL_USE_SECURE" " or " "LIBMAIL_USE_PLAIN"
to indicate if the session will be encrypted (if compiled with --enable-tls)
.I sfd
contains the socket file descriptor as returned by
.B pop3_connect()
(see below).
.I greeting
is the server's initial response which might be used for the APOP login
method.
.I auth
is a
.B libmail_auth_t
structure which is defined as follows :
.sp
.nf
	typedef struct libmail_auth_t {
		char username[BUFSIZE+1]; 
		char password[BUFSIZE+1]; 
		short auth_type;
	} libmail_auth_t;
.fi
.sp
.I username
and
.I password
contain the login credentials for the server and
.I auth_type
can be
.B AUTH_POP3_USERPASS 
for a USER/PASS login method, 
.B AUTH_POP3_APOP 
for the APOP login method (if compiled with --enable-apop) and
.B AUTH_POP3_SASL
for using a supported SASL authentication mechanism (if compile with --enable-sasl).
.sp
Although the function names are self-descriptive here is a short
description;
.B pop3_connect()
is used for the initial connection to the server, assigning a valid socket
file descriptor to
.IR server->sfd .
.B pop3_authenticate()
authenticates the user based on the info provided by
.IR server->auth .
.B pop3_check()
checks for messages filling the
.I n_messages
and
.I n_new_messages
with the number of total and new messages respectively.
.B pop3_disconnect()
disconnects the user from the server.
.SH "RETURN VALUE"
All four functions return
.B LIBMAIL_SUCCESS 
if they succeed. On error they return the following non-zero error codes :
.TP
.B LIBMAIL_SYSERROR
A system error occurred, errno defined in <errno.h> was set. Returned by
all four functions.
.TP
.B LIBMAIL_DNSERROR
The hostname specified in
.I server
was invalid resulting in "unresolved hostname"\-like error. Returned only by
.B pop3_connect().
.TP
.B LIBMAIL_SRVERROR
Returned by all. Indicates that the server responded with an "-ERR" to a
command.
.TP
.B LIBMAIL_POP3_UNSUPPORTED_APOP
Return by pop3_authenticate() when APOP authentication is requested by the
user side and the server doesn't support it.
.TP
.B LIBMAIL_POP3_INVALID_USER
Return by pop3_authenticate() when the supplied username is incorrect.
.B LIBMAIL_POP3_INVALID_PASSWORD
Return by pop3_authenticate() when the supplied password is incorrect.
.B LIBMAIL_POP3_MD5_ERROR
Return by pop3_authenticate() when the supplied MD5 digest to APOP
authentication mechanism is incorrect.
.B LIBMAIL_TLSERROR
Returned by all function indicating an error in TLS/SSL transaction context.
You can retrieve a short description about a specific error through libmail_strerror()
.SH "SEE ALSO"
.B RFC 1321, RFC 1939, RFC 2222, RFC 2822, RFC 4346 
.BR "libmail_strerror" "(3)"
.SH "BUGS"
Currently a real check for unread messages isn't implemented,
n_new_messages is always equal to n_messages after the call to
pop3_check().
.SH "AUTHOR"
Dimitris Mandalidis <mandas AT users DOT sourceforge DOT net>
.SH "EXAMPLES"
A short example on using libmail POP3 protocol support follows: 
.sp
.nf
#include <stdio.h>
#include <string.h>
#include <stdlib.h>

#include <libmail/libmail.h>
#include <libmail/pop3.h>
#include <libmail/error.h>

void pop3_test(void) {
	pop3_mailbox_t mailbox;
	int result;
	int n_new_messages, n_messages;

	strcpy(mailbox.server.hostname, "localhost");
	strcpy(mailbox.server.port, "110");
	mailbox.server.inet_family = LIBMAIL_IPV4;

	strcpy(mailbox.auth.username, "mailtest");
	strcpy(mailbox.auth.password, "foo");
	mailbox.auth.auth_type = AUTH_POP3_SASL;

	if ((result = pop3_connect(&mailbox)) != 0) {
		printf("ERROR: %s", libmail_strerror(result));
		exit(EXIT_FAILURE);	
	}
	if ((result = pop3_authenticate(&mailbox)) != 0) {
		printf("ERROR: %s", libmail_strerror(result));
		exit(EXIT_FAILURE);	
	}
	if ((result = pop3_check(&mailbox, &n_new_messages, &n_messages)) != 0) {
		printf("ERROR: %s", libmail_strerror(result));
		exit(EXIT_FAILURE);	
	}
	if ((result = pop3_disconnect(&mailbox)) != 0) {
		printf("ERROR: %s", libmail_strerror(result));
		exit(EXIT_FAILURE);	
   	} 
	printf("%d total messages and %d new messages", n_messages, n_new_messages);
	return; 
}
.fi