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-03-23" "version 0.2" "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_server_t *" "server" );
.sp
.BI "int pop3_disconnect(pop3_server_t *" "server" );
.sp
.BI "int pop3_authenticate(pop3_server_t *" "server" );
.sp
.BI "int pop3_check(pop3_server_t *" "server" ", int *" "n_new_messages" ", int *" "n_messages" );
.fi
.SH DESCRIPTION
All the above functions takes a pointer to 
.B pop3_server_t 
structure which identify the server's configuration. More specifically 
.I pop3_server_t 
is defined as follows :
.sp
.nf
	typedef struct pop3_server_t {
		char hostname[HOST_NAME_MAX+1];
		char port[6];
		short ai_family;
		int sfd;
		pop3_auth_t auth;
		char greeting[POP3_MAX_RESPONSE+1];
	} pop3_server_t;
.fi
.sp
The server's hostname and port are specified in
.I hostname
and
.I port
respectively while
.I ai_family
might be 
.BR "IPV4" " or " "IPV6"
to indicate IP protocol version. 
.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 pop3_auth_t
structure which is defined as follows :
.sp
.nf
	typedef struct pop3_auth_t {
		char username[POP3_MAX_COMMAND+1]; 
		char password[POP3_MAX_COMMAND+1]; 
		short auth_type;
	} pop3_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 and
.B AUTH_POP3_SASL
for using a supported SASL authentication mechanism.
.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
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, 
.BR "libmail_strerror" "(3)"
.SH "AUTHOR"
Dimitris Mandalidis <mandas AT users DOT sourceforge DOT net>
.SH "EXAMPLES"
For convenience, 
.B endpeer_t 
and
.B server_t 
are defined as follows:
.sp
.nf
typedef union server_t {
	pop3_server_t pop3_server;
	imap4_server_t imap4_server;
	mbox_server_t local_mbox;
} server_t;

typedef struct endpeer_t {
	time_t last_checked_on;
	short protocol;
	int n_messages;
	int n_new_messages;
	server_t server; 
} endpeer_t;
.fi
.sp
However they will never be used by libmail as arguments of return values of
functions. A short example on using libmail POP3 protocol support follows: 
.sp
.nf
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <limits.h>
#include <time.h>

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

int check_for_messages(endpeer_t *endpeer) {
	int status;

	if ((status = pop3_connect(&endpeer->server.pop3_server)) != 0)
		return status;
	if ((status = pop3_authenticate(&endpeer->server.pop3_server)) != 0)
		return status;
	if ((status = pop3_check(&endpeer->server.pop3_server, &endpeer->n_new_messages, &endpeer->n_messages)) != 0)
		return status;
	endpeer->last_checked_on = time(NULL);
	if ((status = pop3_disconnect(&endpeer->server.pop3_server)) != 0)
		return status;
	return 0;
}

void pop3_test(void) {
	endpeer_t endpeer;
	pop3_server_t pop3_server;
	strcpy(pop3_server.hostname, "localhost");
	strcpy(pop3_server.port, "110");
	pop3_server.ai_family = IPV4;
	endpeer.protocol = POP3_PROTO;

	strcpy(pop3_server.auth.username, "mailtest");
	strcpy(pop3_server.auth.password, "foo");
	pop3_server.auth.auth_type = AUTH_POP3_APOP;
	pop3_server.ai_family = IPV4;

	endpeer.server.pop3_server = pop3_server;

	if (check_for_messages(&endpeer) != 0) {
        printf("ERROR");
        exit(EXIT_FAILURE);
    }
    printf("%d total messages and %d new messages", endpeer.n_messages, endpeer.n_new_messages);
	return; 
}
.fi