%% LyX 1.3 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[12pt,italian]{article}
\usepackage{bookman}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{a4wide}
\usepackage{fancyhdr}
\pagestyle{fancy}
\usepackage{array}
\usepackage{graphicx}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.


\usepackage{babel}
\makeatother

\include{macro-it}

\begin{document}
\thispagestyle{empty}

\vspace*{5cm}

\begin{flushright}\huge{FreePOPs Manual}

\vspace{-6mm}

\rule{15cm}{2mm}

\vspace{2mm}

\normalsize{Scritto da Enrico Tassi, Nicola Cocchiaro}

\vspace{1cm}

$Date: 2007/03/29 11:58:45 $

$Revision: 1.42 $

\end{flushright}

\vspace{\stretch{1}}

\hspace{\stretch{1}}Documento rilasciato sotto la licenza GNU/GPL.\hspace{\stretch{1}}

\pagebreak

\tableofcontents{}

\newpage


\section{Introduzione}

FreePOPs è un demone POP3 più un interprete LUA e alcune librerie
extra per il parsing di HTTP e HTML. Il suo scopo principale è tradurre
richieste POP3 locali in azioni HTTP remote per le webmail supportate,
ma in realtà è più flessibile di cosi': per esempio esiste un plugin
per leggere news da un sito web come se fossero messaggi in una mailbox.
Si può facilmente estendere FreePOPs al volo, senza neanche farlo
ripartire; si può aggiungere un plugin o modificarne uno esistente
semplicemente cambiando uno script, dato che i plugin sono scritti
in LUA e sono interpretati al volo.


\subsection{Situazioni d' uso}

FreePOPs può essere utile in molte situazioni, qui descriviamo le
più ovvie:

\begin{itemize}
\item Siete dietro un firewall che chiude la porta 110 ma volete comunque
leggere la posta elettronica e la webmail del vostro provider fa schifo.
\item Il vostro mail provider non vi permette di accedere alla mailbox con
il protocollo POP3 ma solo tramite il servizio di webmail.
\item Preferite usare la vostra mailbox invece di sfogliare le news di un
qualche sito.
\item Dovete sviluppare un server POP3 in meno di una settimana e volete
che sia ragionevolmente veloce e che non consumi molta memoria.
\item Non siete hacker del C, ma volete trarre beneficio da un frontend
ad un server POP3, veloce e scritto in C, ma non volete perdere un
mese a scrivere il backend in C. LUA è un linguaggio davvero semplice
e leggero, una settimana è abbastanza per impararlo e poterlo usare
in modo produttivo.
\end{itemize}

\subsection{Features}

FreePOPs è l' unico software che conosciamo con queste features:

\begin{itemize}
\item Server POP3 compliant con RFC (non con tutte le features, ma compliant).
\item Portabile (scritto in C e LUA il quale è scritto in C, quindi tutto
è scritto nel linguaggio più portabile del mondo).
\item Piccolo (in termini di risorse utilizzate) e ragionevolmente veloce.
\item Estremamente estendibile al volo mediante un linguaggio semplice e
potente.
\item Piuttosto documentato.
\item Rilasciato sotto la licenza GNU/GPL (questo significa che FreePOPs
è Software Libero).
\end{itemize}

\subsection{Plugin}

Questi sono i plugin correntemente inclusi in FreePOPs:

\begin{description}
\input{libero.lua.xml.b.it.xmltex}
\input{tin.lua.xml.b.it.xmltex}
\input{davmail.lua.xml.b.it.xmltex}
\input{popforward.lua.xml.b.it.xmltex}
\input{aggregator.lua.xml.b.it.xmltex}
\input{flatnuke.lua.xml.b.it.xmltex}
\input{kernel.lua.xml.b.it.xmltex}
\input{gmail.lua.xml.b.it.xmltex}
\input{yahoo.lua.xml.b.it.xmltex}
\input{squirrelmail.lua.xml.b.it.xmltex}
\input{hotmail.lua.xml.b.it.xmltex}
\input{aol.lua.xml.b.it.xmltex}
\input{netscape.lua.xml.b.it.xmltex}
\input{tre.lua.xml.b.it.xmltex}
\input{supereva.lua.xml.b.it.xmltex}
\input{mailcom.lua.xml.b.it.xmltex}
\input{mail2world.lua.xml.b.it.xmltex}
\input{juno.lua.xml.b.it.xmltex}
\input{fastmail.lua.xml.b.it.xmltex}
\input{criticalpath.lua.xml.b.it.xmltex}
\end{description}

\section{Storia}

FreePOPs non nasce dal nulla. Un progetto simile (solo nella situazione
d' uso principale) è LiberoPOPs. 

L' antenato di FreePOPs è completamente scritto in C per ragioni poco
interessanti. LiberoPOPs supporta {}``plugin'' ma in maniera più
statica e complessa. Il frontend al server POP3 potrebbe essere collegato
ad un backend scritto in C, questo significa che dovreste ricompilare
e far ripartire LiberoPOPs ogni volta che cambiate una riga in un
plugin. Un altro punto interessante è che LiberoPOPs era stato creato
dal nulla in un tempo molto breve (dovete essere Italiani e usare
un indirizzo di posta \texttt{@libero.it} per capire perché), ciò
vuol dire che era nato con molti bug e FIX-ME nel codice. 

Il progetto LiberoPOPs ebbe un rapido successo, perché tutti ne avevano
bisogno, quindi avevamo molti utenti. Nella filosofia della comunità
opensource (e anche di Linux) devi rilasciare il software frequentemente,
e questo è ciò che facevamo: rilasciavamo nuove versioni ogni due
giorni. Non avevamo a che fare con utenti Unix, né hacker, ma per
la maggior parte utenti Win32. Ad un certo punto capimmo che questi
erano pigri/stufi di aggiornare il software ogni due giorni. Il brutto
mondo Win insegna che il software si auto-aggiorna, si auto-installa
e probabilmente si auto-scrive. 

Cercammo di risolvere il problema tirando fuori dal motore in C la
maggior parte del codice che cambiava più spesso, ma questo era molto
difficile visto che il C non è pensato per questo genere di cose.
Una volta che LiberoPOPs si fu stabilizzato iniziammo a pensare a
come risolvere meglio la cosa. 

Un linguaggio di scripting/interpretato sembro' una buona scelta e
dopo una lunga ricerca in rete e nei newsgroup universitari trovai
LUA.. Questo non è il luogo per dire al mondo quanto sia bello questo
linguaggio quindi non ne parlerò oltre qui. Integrare l' interprete
LUA in LiberoPOPs non fu cosi' difficile e FreePOPs ne è il risultato.
Ora è davvero più facile scrivere/testare un plugin e (anche se non
è ancora implementato) un sistema di auto-aggiornamento è molto facile
da scrivere dato che non c'è bisogno di ricompilare il nucleo C in
quasi nessun caso.


\section{File di configurazione di FreePOPs}

FreePOPs non ha bisogno di una vera configurazione. La maggior parte
degli utenti non dovrebbe modificare il file di configurazione. Se
siete sviluppatori o utenti curiosi il file di configurazione è \texttt{config.lua},
che si trova nella directory del programma sotto Win32 o in  \texttt{/etc/freepops/}
in ambiente posix.

Più avanti vedremo come i plugin sono associati al dominio di un indirizzo
 di posta, e alcuni di questi plugin hanno alias per altri domini
per rendere  più facile la raccolta di news da alcuni siti. Leggete
la documentazione dei plugin per maggiori informazioni su di essi,
e  magari inviate una mail con il vostro nuovo alias se volete che
venga  integrato nella prossima versione di FreePOPs.

Dalla versione 0.0.11 il file \texttt{config.lua} ha una sezione policy.
In questa sezione potete escludere o accettare classi di indirizzi
mail. Questo può essere utile ad amministratori di rete.


\section{Parametri a riga di comando di FreePOPs}

La vera configurazione di FreePOPs viene impostata tramite argomenti
a riga  di comando. Questi sono descritti in dettaglio nelle pagine
del man in  ambienti Unix e qui di seguito. Tenete presente che in
condizioni d' uso normali non serve specificare niente per usare FreePOPs,
ma in caso di esigenze specifiche è bene fare riferimento a questo
elenco:

\begin{description}
\item [-p~<port>,~-\hspace{1mm}-port~<port>]Per default FreePOPs fa bind sulla porta
2000. Per modificare questo comportamento basta usare questo switch.
\item [-t~<num>,~-\hspace{1mm}-threads~<num>]FreePOPs può gestire connessioni multiple,
fino a \emph{num}. Il default è 5.
\item [-b~addr,~-\hspace{1mm}-bind~addr]Per fare bind su \emph{addr} invece che
INADDR\_ANY (0.0.0.0). \emph{addr} deve essere una stringa contenente
un indirizzo IPv4 nel formato {}``ddd.ddd.ddd.ddd'', o un nome host.
\item [-l~logfacility,~-\hspace{1mm}-logmode~logfacility]Può essere usato per specificare
il tipo di logging. \emph{logfacility} può essere {}``stdout'' per
standard output (il default), {}``syslog'' per usare un demone di
logging o un nome di file valido per avere un log su file.
\item [-d,~-\hspace{1mm}-daemonize]Sposta il processo in background rilasciando la tty
\item [-n,~-\hspace{1mm}-no-pid-file]Non crea il file contenente il pid del processo
in /var/run/.
\item [-P~<host>:<port>,~-\hspace{1mm}-proxy~<host>:<port>]Per dire a FreePOPs quale
è il vostro proxy HTTP. Se \emph{port} non è impostato viene usata
la porta 8080 di default.
\item [-A~<username>:<password>,~-\hspace{1mm}-auth~<username>:<password>]Si usa
per proxy con autenticazione, per specificare nome utente e password.
Va usato con \emph{-P} o la sua forma estesa.
\item [-u~name,~-\hspace{1mm}-useragent~name]Imposta lo useragent da usare nelle
connessioni HTTP. Il default è {}``Firefox/0.8''.
\item [-s~user.group,~-\hspace{1mm}-suid~user.group]Lascia i privilegi di root dopo
il bind. Se lanciato da utente normale non serve questa opzione.
\emph{(Non usato in Windows)}
\item [-k,~-\hspace{1mm}-kill]Termina il programma FreePOPs in esecuzione.
\emph{(Non usato in Windows)}
\item [-x~pluginfile,~-\hspace{1mm}-toxml~file]
Stampa la descrizione in XML del plugin o del modulo sullo standard output.
\item [-e~scriptfile~args...,~-\hspace{1mm}-execute~scriptfile~args...]
Esegue lo script in un interprete LUA dotato di tutte le librerie che
usa FreePOPs. Lo script deve definire una funzione main che prende in
input una table di stringhe (i parametri passati a freepopd dopo il
nome dello script) e deve ritornare un intero (che verr\`a poi
ritornato dall'interprete.
\item [-\hspace{1mm}-fpat~authtype,~-\hspace{1mm}-force-proxy-auth-type~authtype]
Per forzare l'utilizzo di un determinato metodo di autenticazione per
il proxy.
I valori accettati sono: ntlm, basic, digest e gss.
\item [-\hspace{1mm}-no-icon]
Per disattivare l'icona nella try bar di windows (solo per windows).
\item [-h,~-\hspace{1mm}-help]Stampa un messaggio di aiuto.
\item [-v,~-\hspace{1mm}-verbose,~-w,~-\hspace{1mm}-veryverbose]Questo dice a FreePOPs di loggare
alcune informazioni utili per  riportare bug.
\end{description}
In ambienti posix come Debian GNU/Linux potete avviare FreePOPs al
boot come  servizio standard. In questo caso gli switch a riga di
comando sono memorizzati in \texttt{/etc/default/freepops}, in alcuni
sistemi basati su rpm dovreste trovare lo stesso file con nome \texttt{/etc/sysconfig/freepops}.


\section{Configurazione del client email}

Per configurare il client email dovete cambiare le impostazioni del
server POP3. Solitamente dovrete usare \emph{localhost} come nome
del server POP3 e \emph{2000} come porta. Nel caso in cui installiate
FreePOPs in un altro computer della vostra LAN, dovreste usare il
nome di quell'host invece di localhost, mentre nel caso in cui abbiate
cambiato la porta di default con lo switch \texttt{-p} dovrete immettere
la stessa porta anche nel client email.. Dovete sempre usare come
nome utente l' indirizzo di posta completo, per esempio \texttt{qualcosa@libero.it}
invece che solo \texttt{qualcosa}. Questo è perché FreePOPs sceglie
il plugin da caricare guardando al nome utente che deve quindi contenere
tutte le informazioni. Più sotto presentiamo tutti i plugin e i loro
domini associati e mostriamo come sia possibile creare binding al
volo tra un indirizzo email e un dominio.


\subsection{Tutorial per Outlook Express}

Mostriamo qui come configurare Outlook Express in ambienti Windows
per l' uso con FreePOPs. Altri client si configurano più o meno allo
stesso modo.

\begin{itemize}
\item Dal menu \textbf{Strumenti} seleziona la voce \textbf{Account...}
(vedi \imageref{main})
\end{itemize}
\myincludegraphics{main}{!htp}{scale=0.8}

\begin{itemize}
\item Seleziona il tuo account e clicca su \textbf{Proprietà} (vedi
\imageref{settings})
\end{itemize}
\myincludegraphics{settings}{!htp}{scale=0.8}

\begin{itemize}
\item Nella linguetta \textbf{Server} metti in \textbf{Posta in arrivo}
il nome del computer su cui hai eseguito FreePOPs, solitamente \emph{localhost}.
Il \textbf{Nome account} deve essere il tuo indirizzo di mail completo,
seguito dal dominio al quale appartiene la tua email, ad esempio
\texttt{nomeutente@dominio.it} (vedi \imageref{server}).
\end{itemize}
\myincludegraphics{server}{!htp}{scale=0.8}

\begin{itemize}
\item Nella linguetta \textbf{Impostazioni avanzate} metti in \textbf{Posta
in arrivo} il numero di porta, che è \emph{2000} se hai seguito le
nostre impostazioni. \textbf{Deseleziona} \emph{Il server necessita
di una connessione protetta (SSL)} (vedi \imageref{advanced}).
\end{itemize}
\myincludegraphics{advanced}{!htp}{scale=0.8}


\subsection{Tutorial per Proxy}

FreePOPs è in grado di utilizzare proxy HTTP. Se non sapete cosa siano
oppure se nella vostra rete locale non ce n'è uno allora potete saltare
questa sezione in quanto le operazioni qui descritte saranno per voi
superflue.

Per utilizzare un proxy HTTP, FreePOPs supporta l' opzione \texttt{-P},
o l' equivalente opzione lunga \texttt{-{}-proxy}, per specificare
indirizzo e porta del proxy separati da : (due punti), ad esempio
\texttt{-P proxy.localnet.org:8080} oppure \texttt{-P 192.168.1.1}
sono esempi validi. Se non è specificato alcun numero di porta allora
sarà utilizzato \texttt{8080} come valore di default.

Se per utilizzare il proxy è necessaria un' autenticazione, usate anche
l' opzione \texttt{-A nomeutente:password}.

Ricordatevi che i valori specificati con l' opzione -P hanno la precedenza
su qualsiasi altro valore ottenuto dal sistema operativo utilizzato.

In ambienti POSIX è possibile impostare l' utilizzo di un proxy anche
attraverso opportune variabili d' ambiente.

Le variabili d' ambiente che saranno utilizzate sono, in ordine di
precedenza, \texttt{HTTP\_PROXY}, \texttt{http\_proxy}, \texttt{PROXY}
e \texttt{proxy}. 

L' implementazione corrente supporta vari metodi di autenticazione,
ma per alcuni e' necessaria la versione SSL di FreePOPs.


\subsection{Spam/AV tutorial}

Molti utenti, soprattutto della versione per Windows, utilizzano svariati
antivirus e software antispam che necessitano un minimo di configurazione.
Grazie alla collaborazione sul forum di LiberoPOPs tra gli sviluppatori
e gli utenti è stato realizzato questo tutorial che è valido anche
per FreePOPs.


\subsubsection{Norton AntiVirus, versione 2002 e successive}

È necessario mettere FreePOPs in ascolto sulla porta 110 per mezzo
dell'opzione \texttt{-p} e successivamente impostare il proprio client
email perché riceva la posta sulla porta 110. Per cambiare le opzioni
di FreePOPs, consultare le FAQ alla domanda \char`\"{}Come cambio
i parametri della riga di comando di FreePOPs?\char`\"{} 


\subsubsection{Avast! Antivirus}

Nel proprio client email, modificare il nome utente in questo modo:
\\
\texttt{indirizzo@email\#localhost:2000} Sempre all'interno delle
opzioni del proprio client email, impostare il numero di porta del
server POP3 a 110, invece che a 2000 come descritto nei precedenti
tutorial. 


\subsubsection{AVG Pro 7 Antivirus}

Nel proprio client email, modificare il numero di porta POP3 a 5300,
lasciare inalterati nome utente e server (\texttt{email@address} e
\texttt{localhost}). In AVG, entrare in \char`\"{}Proprietà > Servers
> Creare un Server di posta POP3 (server type)\char`\"{}, in connection
impostare Fixed host: 127.0.0.1:2000 e Local port: 5300 


\subsubsection{SpamHilator}

Configurare il proprio client email con i seguenti parametri: Server
POP3 (posta in entrata): localhost Porta server POP3: 110 Nome Utente:
\\
\texttt{localhost\&indirizzo@email\&2000 }


\subsubsection{Mailshield Desktop}

In Mailshield Desktop, scegliere \char`\"{}Edit mail account\char`\"{},
relativamente alla propria casella. In \char`\"{}Account name\char`\"{}
ed in \char`\"{}Email address\char`\"{} inserire il proprio indirizzo
email completo. Scegliere poi \char`\"{}Access\char`\"{}, in \char`\"{}type
of Email server\char`\"{} utilizzare \char`\"{}POP3 mail account\char`\"{},
mentre in \char`\"{}incoming mail server\char`\"{} immettere 127.0.0.1.
Può inoltre essere utile selezionare l'opzione \char`\"{}Use relaxed
timeouts whit this email server\char`\"{}. 


\subsubsection{K9}

Configurare il proprio client email inserendo 9999 come porta del
server POP3. Lasciare localhost come nome del server. Inserire poi
come nome utente \texttt{localhost/2000/indirizzo@email }


\subsubsection{SpamTerminator}

Configurare il proprio client email con i seguenti parametri: Server
POP3 (posta in entrata): \texttt{localhost} Porta server POP3: 8110
Nome Utente: \\
\texttt{indirizzo@email\#localhost} Avviare poi FreePOPs con l'opzione
-p 110. 


\subsubsection{SpamPal}

Configurare il proprio client email con i seguenti parametri: Server
POP3 (posta in entrata): \texttt{localhost} Porta server POP3: 110
Nome Utente: \\
\texttt{indirizzo@email@localhost:2000}


\subsection{LAN tutorial }


\subsubsection*{Come utilizzare FreePOPs come server in una rete di calcolatori (tutorial
orientato a Windows).}

La LAN è composta da due macchine (o più, ma da 2 a 100 è uguale).
Le macchine le chiameremo \emph{Sola} (il server) e \emph{Cucco} (il
client). FreePOPs parte su \emph{Sola} e lo lancio così: \\
\texttt{freepopsd.exe -b 0.0.0.0 -p 110} \texttt{}~\\
che significa che il servizio offerto da FreePOPs sarà offerto a tutti,
cioè FreePOPs si mette in ascolto su tutte le interfacce di rete.
E lo metto in ascolto alla porta standard per il POP3 (la 110). Non
è necessario, 2000 va bene, ma visto che è un server lo facciamo partire
sulla porta standard. Ora configuro il client di posta su Cucco. Come
server POP3 di posta scelgo \emph{Sola} e la porta nel caso la metto
a \emph{110}. Mettiamo che anche \emph{Sola} (anche se è un server)
abbia un monitor e che ci voglia leggere la posta. Qui il client di
posta lo configuro a \emph{localhost} e \emph{110}.

Fondamentale per la lan è il \texttt{-b 0.0.0.0} in quanto di default
su Windows FreePOPs parte con \texttt{-b 127.0.0.1} in modo che non
offra un servizio alla eventuale rete ma solo al pc stesso.


\section{Plugin}

Qui diamo una descrizione dettagliata di ogni plugin, ma prima di
iniziare spieghiamo la maniera generale di passare argomenti speciali
ai plugin (leggete la descrizione specifica di un plugin per sapere
quali argomenti esso accetta).


\subsection{Parametri}

Ogni plugin può ricevere parametri passati come aggiunta allo username.
Lo username seguente è per il plugin \texttt{popforward.lua}:\\
\texttt{gareuselesinge@mydomain.xx?host=pop.mydomain.xx\&port=110}\\
Dato che potreste usare qualche proxy antispam o altri programmi che
possono maneggiare il vostro username e potrebbero non gradire il
carattere \texttt{?} potete usare uno spazio al suo posto.
Tutti i caratteri seguenti che non siano lettere o numeri devono essere
scritti come \texttt{\%xx} dove \texttt{xx} \`e il codice esadecimale del
carattere corrispondente (esattamente come accade per le URL). Per semplicit\`a,
ogni carattere di spazio pu\`o essere sostituito con i carattere \texttt{+}
invece che con il corrispondente \texttt{\%20}. Ad esempio, se si vuole
assegnare il valore \texttt{"In Arrivo"} al parametro \texttt{folder} \`e
necessario scrivere \texttt{folder=In+Arrivo}.
Si veda l'Appendice per informazioni sui codici esadecimali dei vari caratteri.

Un altro modo di fare hacking dello username è con i binding dominio-plugin
fatti al volo. Potreste trovare utile dire: {}``Voglio usare il plugin
X per il dominio Y senza cambiare il file config.lua''. In questo
caso dovrete usare il nome del plugin (per esempio popforward.lua)
come nome di dominio e probabilmente dovrete passargli alcuni argomenti
usando la procedura descritta prima. Questo è un esempio:\\
\texttt{gareuselesinge@popforward.lua?host=pop.mymailsite.xx\&port=110}\\
Ricordate che in caso di uso di binding {}``al volo'' non ci saranno
argomenti di default, quindi \texttt{port=110} non può essere omesso,
come nell'esempio precedente.


\input{libero.lua.xml.it.xmltex}
\input{tin.lua.xml.it.xmltex}
\input{davmail.lua.xml.it.xmltex}
\input{popforward.lua.xml.it.xmltex}
\input{aggregator.lua.xml.it.xmltex}
Questa è la lista di alias per il plugin aggregator.\\
\\
\begin{tabular}{|l|l|}
\hline 
\texttt{\footnotesize aggregatordomain}&
{\footnotesize descrizione}\tabularnewline
\hline
\hline 
\texttt{\footnotesize freepops.rss.en}&
\multicolumn{1}{l|}{\texttt{\footnotesize http://www.freepops.org/} {\footnotesize news
(Inglese)}}\tabularnewline
\hline 
\texttt{\footnotesize freepops.rss.it}&
\texttt{\footnotesize http://www.freepops.org/} {\footnotesize news
(Italiano)}\tabularnewline
\hline 
\texttt{\footnotesize flatnuke.sf.net}&
\texttt{\footnotesize http://flatnuke.sourceforge.net/} {\footnotesize news
(Italiano)}\tabularnewline
\hline 
\texttt{\footnotesize ziobudda.net}&
\texttt{\footnotesize http://ziobudda.net/} {\footnotesize news (sia
Italiano che Inglese)}\tabularnewline
\hline 
\texttt{\footnotesize punto-informatico.it}&
\texttt{\footnotesize http://punto-informatico.it/} {\footnotesize news
(Italiano)}\tabularnewline
\hline 
\texttt{\footnotesize gaim.sf.net}&
\texttt{\footnotesize http://gaim.sourceforge.net/} {\footnotesize news
(Inglese)}\tabularnewline
\hline 
\texttt{\footnotesize linuxdevices.com}&
\texttt{\footnotesize http://linuxdevices.com/} {\footnotesize news
(Inglese)}\tabularnewline
\hline 
\texttt{\footnotesize securityfocus.com}&
\texttt{\footnotesize http://www.securityfocus.com/} {\footnotesize new
vulnerabilities (Inglese)}\tabularnewline
\hline 
\texttt{\footnotesize games.gamespot.com}&
\texttt{\footnotesize http://www.gamespot.com/} {\footnotesize computer
games news (Inglese)}\tabularnewline
\hline 
\texttt{\footnotesize news.gamespot.com}&
\texttt{\footnotesize http://www.gamespot.com/} {\footnotesize GameSpot
news (Inglese)}\tabularnewline
\hline 
\texttt{\footnotesize kerneltrap.org}&
\texttt{\footnotesize http://kerneltrap.org} {\footnotesize news (Inglese)}\tabularnewline
\hline 
\texttt{\footnotesize mozillaitalia.org}&
\texttt{\footnotesize http://www.mozillaitalia.org} {\footnotesize news
(Italiano)}\tabularnewline
\hline 
\texttt{\footnotesize linux.kerneltrap.org}&
\texttt{\footnotesize http://linux.kerneltrap.org} {\footnotesize news
(Inglese)}\tabularnewline
\hline
\texttt{\footnotesize linuxgazette.net}&
\texttt{\footnotesize http://linuxgazette.net} {\footnotesize news
(Inglese)}\tabularnewline
\hline
\end{tabular}


\input{flatnuke.lua.xml.it.xmltex}
Ci sono alcuni alias per siti FlatNuke,
vedi la documentazione del plugin aggregator per sapere cosa significa:\\
\\
\begin{tabular}{|l|l|}
\hline 
\texttt{\footnotesize aggregatordomain}&
{\footnotesize descrizione}\tabularnewline
\hline
\hline 
\texttt{\footnotesize freepops.en}&
\texttt{\footnotesize http://www.freepops.org/} {\footnotesize full
news (Inglese)}\tabularnewline
\hline 
\texttt{\footnotesize freepops.it}&
\texttt{\footnotesize http://www.freepops.org/} {\footnotesize full
news (Italiano)}\tabularnewline
\hline 
\texttt{\footnotesize flatnuke.it}&
\texttt{\footnotesize http://flatnuke.sourceforge.net/} {\footnotesize full
news (Italiano)}\tabularnewline
\hline
\end{tabular}

\input{kernel.lua.xml.it.xmltex}
\input{gmail.lua.xml.it.xmltex}
\input{yahoo.lua.xml.it.xmltex}
\input{squirrelmail.lua.xml.it.xmltex}
\input{hotmail.lua.xml.it.xmltex}
\input{aol.lua.xml.it.xmltex}
\input{netscape.lua.xml.it.xmltex}
\input{tre.lua.xml.it.xmltex}
\input{supereva.lua.xml.it.xmltex}
\input{mailcom.lua.xml.it.xmltex}
\input{mail2world.lua.xml.it.xmltex}
\input{juno.lua.xml.it.xmltex}
\input{fastmail.lua.xml.it.xmltex}
\input{criticalpath.lua.xml.it.xmltex}

\section{Creare un plugin}

Seguono due sezioni, la prima è una panoramica veloce su cosa un plugin
deve fare, la seconda è un tutorial più dettagliato. Prima di procedere
oltre suggeriamo di leggere un po' di documentazione alla  base della
scrittura dei plugin:

\begin{enumerate}
\item Dato che i plugin sono scritti in LUA dovete leggere almeno il tutorial
LUA (HTTP://lua-users.org/wiki/LuaTutorial); molte grazie a chi l'ha
scritto. LUA è un linguaggio di scripting piuttosto semplice, facile
da imparare,  e facile da leggere. Se siete interessati a questo linguaggio
dovreste leggere IL libro su LUA ({}``Programming in LUA'' di Roberto
Ierusalimschy HTTP://www.inf.puc-rio.br/\textasciitilde{}roberto/book/).
è davvero un buon libro, credetemi. Oggi il libro è stato pubblicato
on line http://www.lua.org/pil/
\item Visto che dobbiamo implementare un backend POP3 dovreste sapere cos'è
il POP3. La RFC 1939 è inclusa nella directory doc/ del pacchetto
dei sorgenti di FreePOPs, ma potete prelevarla anche dalla rete HTTP://www.ietf.org/rfc/rfc1939.txt.
\item Leggete attentamente questo tutorial, è lontano dall'essere ben fatto
ma è meglio di niente.
\item Il sito web contiene, nella sezione doc, un bel po' di documentazione
sui sorgenti. Dovreste tenere un web browser aperto alla pagina della
documentazione sui moduli LUA mentre scrivete un plugin.
\item Dopo aver creato un prototipo, dovreste leggere un plugin completo.
Il plugin libero.lua è davvero ben commentato, iniziate pure da li'.
\item Ricordate che questo software ha un forum ufficiale (HTTP://freepops.diludovico.it)
e degli autori a cui potete chiedere aiuto.
\item FreePOPs è distribuito sotto licenza GNU/GPL. Questo significa che
ogni software che fa uso del codice di FreePOPs deve essere rilasciato
sotto la stessa licenza. Questo include i plugin. Per maggiori informazioni
leggete il testo della licenza nel file \texttt{COPYING} incluso o
su HTTP://www.gnu.org/licenses/gpl.html.
\end{enumerate}

\subsection{Panoramica sui plugin}

Un plugin è essenzialmente un backend per un server POP3. I plugin
sono scritti in LUA%
\footnote{Il sito web del linguaggio è HTTP://www.lua.org%
} mentre il server POP3 è scritto in C. Qui esamineremo l' interfaccia
tra il nucleo C e i plugin LUA.


\subsection{L' interfaccia tra il nucleo C ed un plugin}

Come abbiamo spiegato prima il frontend POP3 in C deve essere collegato
ad un backend in LUA. L'interfaccia è molto semplice se conoscete
il protocollo POP3. Qui riassumiamo brevemente il significato, ma
la RFC 1939 (inclusa nella  directory \texttt{doc/} della distribuzione
dei sorgenti) è molto breve e facile da leggere. Come il vostro intuito
dovrebbe suggerirvi il client POP3 può richiedere che il server POP3
conosca qualcosa delle mail che sono nella mailbox e prima o poi prelevare/cancellare
dei messaggi. E questo è esattamente ciò che fa.

Il backend deve implementare tutti i comandi POP3 (come USER, PASS,
RETR, DELE, QUIT, LIST, ...) e deve restituire al frontend il risultato.
Diamo un semplice esempio di una sessione POP3 dalla RFC:

\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

     1  S: <wait for connection on TCP port 110>

     2  C: <open connection>

     3  S:    +OK POP3 server 

     4  C:    USER linux@kernel.org

     5  S:    +OK now insert the pasword

     6  C:    PASS gpl

     7  S:    +OK linux's maildrop has 2 messages (320 octets)

     8  C:    STAT

     9  S:    +OK 1 320

    10  C:    LIST

    11  S:    +OK 2 messages (320 octets)

    12  S:    1 320

    13  S:    .

    14  C:    RETR 1

    15  S:    +OK 120 octets

    16  S:    <the POP3 server sends message 1>

    17  S:    .

    18  C:    DELE 1

    19  S:    +OK message 1 deleted

    20  C:    QUIT

    21  S:    +OK dewey POP3 server signing off (maildrop empty)

    22  C:  <close connection>

    23  S:  <wait for next connection>

\end{verbatim}

\end{footnotesize}

In questa sessione il backend verrà chiamato per le righe 4, 6, 8,
10, 14, 18, 20 (tutte le righe \texttt{C:} ) e rispettivamente le
funzioni che implementano i comandi POP3 verranno chiamate in questo
modo

\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

    user(p,"linux@kernel.org")

    pass(p,"gpl")

    stat(p)

    list_all(p)

    retr(p,1)

    dele(p,1)

    quit_update(p)

\end{verbatim}

\end{footnotesize}

più tardi chiariremo cos'è p. Speriamo di toglierlo e renderlo implicito
per completa trasparenza. è facile capire che c'è un mapping 1-1 tra
i comandi POP3 e le chiamate a funzione del plugin. Potete vedere
un plugin come l'implementazione dell'interfaccia POP3.


\subsection{L'interfaccia tra un plugin e il nucleo C}

Prendiamo in esame la chiamata a \texttt{pass(p,''gpl'')}. Qui il
plugin dovrebbe autenticare l'utente (se c'è un qualche tipo di autenticazione)
e informare il nucleo C del risultato. Per ottenere questo ogni funzione
dei plugin deve restituire un flag di errore, per essere più precisi
uno di questi errori:\\


\begin{tabular}{|l|p{7cm}|}
\hline 
{\footnotesize Code}&
{\footnotesize Significato}\tabularnewline
\hline
\hline 
\texttt{\footnotesize POPSERVER\_ERR\_OK}&
{\footnotesize Nessun errore}\tabularnewline
\hline 
\texttt{\footnotesize POPSERVER\_ERR\_NETWORK}&
{\footnotesize Errore di rete}\tabularnewline
\hline 
\texttt{\footnotesize POPSERVER\_ERR\_AUTH}&
{\footnotesize Autenticazione fallita}\tabularnewline
\hline 
\texttt{\footnotesize POPSERVER\_ERR\_INTERNAL}&
{\footnotesize Errore interno, segnalate il bug}\tabularnewline
\hline 
\texttt{\footnotesize POPSERVER\_ERR\_NOMSG}&
{\footnotesize Il numero del messaggio è fuori range}\tabularnewline
\hline 
\texttt{\footnotesize POPSERVER\_ERR\_LOCKED}&
{\footnotesize Mailbox bloccata da altre sessioni}\tabularnewline
\hline 
\texttt{\footnotesize POPSERVER\_ERR\_EOF}&
\multicolumn{1}{l|}{{\footnotesize Fine trasmissione, usata nel popserver\_callback}}\tabularnewline
\hline 
\texttt{\footnotesize POPSERVER\_ERR\_TOOFAST}&
{\footnotesize Non è possibile riconnettersi al server ora, attendere
e riprovare}\tabularnewline
\hline 
\texttt{\footnotesize POPSERVER\_ERR\_UNKNOWN}&
{\footnotesize Non ho idea di che errore ho trovato}\tabularnewline
\hline
\end{tabular}\\
\\


Nel nostro caso i codici d'errore più appropriati sono \texttt{POPSERVER\_ERR\_AUTH}
e \texttt{POPSERVER\_ERR\_OK}. Questo è un caso semplice, in cui un
codice d'errore è abbastanza. Ora analizziamo il caso più complesso
della chiamata a \texttt{list\_all(p)}. Qui dobbiamo restituire un
codice d'errore come prima, ma dobbiamo anche informare il nucleo
C della grandezza di tutti i messaggi nella mailbox. Qui abbiamo bisogno
del parametro p passato ad ogni funzione del plugin (notate che tale
parametro potra' divenire implicito in futuro). \texttt{p} indica
la struttura dati che il C si aspetta venga riempita chiamando funzioni
appropriate come \texttt{set\_mailmessage\_size(p,num,size)} dove
num è il numero del messaggio e size è la grandezza in byte. Solitamente
è molto comune mettere insieme più funzioni. Per esempio quando guardate
la pagina di una webmail con la lista di messaggi conoscete il numero
dei messaggi, la loro grandezza e lo UIDL così che potete riempire
la struttura dati p con tutte le informazioni per LIST, STAT, UIDL. 

L'ultimo caso che esaminiamo è \texttt{retr(p,num,data)}. poiché un
messaggio di posta può essere molto grande, non è un modo elegante
di scaricare l'intero messaggio senza far sì che il client di posta
si lamenti per la morte del server. La soluzione è usare un callback.
Ogni volta che un plugin ha dei dati da mandare al client dovrebbe
chiamare la \texttt{popserver\_callback(buffer,data)}. \texttt{data}
è una struttura opaca che il popserver necessita per compiere il suo
lavoro (notate che questo parametro potrà venire rimosso per semplicità).
In alcuni casi, per esempio se sapete che il messaggio è piccolo o
state lavorando su una rete veloce, potete prelevare l'intero messaggio
e mandarlo, ma ricordate che questo consuma più memoria.


\subsection{L'arte di scrivere plugin (tutorial sui plugin)}

In questa sezione scriveremo un plugin passo passo, esaminando ogni
dettaglio importante. Non scriveremo un vero e completo plugin poiché
può diventare un pò difficile da seguire, ma creeremo una webmail
ad-hoc per i nostri scopi.


\subsubsection{(step 1) Lo scheletro}

La prima cosa che faremo sarà copiare il file \texttt{skeleton.lua}
in \texttt{foo.lua} (perché scriveremo il plugin per la webmail \emph{foo.xx}
, \emph{xx} sta per un dominio vero, ma non vogliamo menzionare alcun
sito qui...). Ora con il vostro editor migliore (suggeriamo vim su
Unix e scintilla per win32, visto che supportano il syntax highlighting
per LUA, ma qualsiasi altro editor di testo va bene) aprite \texttt{foo.lua}
e cambiate le prime righe aggiungendo il nome del plugin, la versione,
il vostro nome, il vostro indirizzo email e un breve commento, nei
posti appropriati.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- ************************************************************************** --

--  FreePOPs @--put domain here-- webmail interface

--

--  $Id: manual-it.tex,v 1.42 2007/03/29 11:58:45 gareuselesinge Exp $

--

--  Released under the GNU/GPL license

--  Written by --put Name here-- <--put email here-->

-- ************************************************************************** --



PLUGIN_VERSION = "--put version here--"

PLUGIN_NAME = "--put name here--"

\end{verbatim}

\end{footnotesize} Ora abbiamo un plugin vuoto, ma non è abbastanza per iniziare a farci
hacking. Dobbiamo aprire il file \texttt{config.lua} (nella distribuzione
win32 si trova nella directory principale, mentre nella distribuzione
Unix è in \texttt{/etc/freepops/}; altre copie di questo file possono
essere incluse nelle distribuzioni, ma sono copie di backup) e aggiungete
una riga come questa\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- foo plugin

freepops.MODULES_MAP["foo.xx"]      = {name="foo.lua"}

\end{verbatim}

\end{footnotesize} all'inizio del file. Prima di finire il primo passo dovreste provare
se il plugin viene correttamente attivato da FreePOPs quando necessario.
Per questo dovremo aggiungere alcune righe a \texttt{foo.lua}, in
particolare dovremo aggiungere un valore di ritorno di errore a \texttt{user()}.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- -------------------------------------------------------------------------- --

-- Must save the mailbox name

function user(pstate,username)

        return POPSERVER_ERR_AUTH

end

\end{verbatim}

\end{footnotesize} Ora la funzione user fallisce sempre, restituendo un errore di autenticazione.
Dovrete ora lanciare FreePOPs (se è già in esecuzione non è necessario
farlo ripartire) e lanciare telnet (sotto win32 dovreste aprire un
prompt DOS, sotto Unix avrete una shell) e digitate \texttt{telnet
localhost 2000} e poi digitate \texttt{user test@foo.xx}.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

tassi@garfield:~$ telnet localhost 2000

Trying 127.0.0.1...

Connected to garfield.

Escape character is '^]'.

+OK FreePOPs/0.0.10 pop3 server ready

user test@foo.xx

-ERR AUTH FAILED

Connection closed by foreign host.

\end{verbatim}

\end{footnotesize} Il server risponde chiudendo la connessione e stampando un messaggio
di autorizzazione fallita (va bene, dato che la funzione \texttt{user()}
del nostro plugin restituisce questo errore). Nel file standard error
(la console sotto Unix, il file \texttt{stderr.txt} sotto Windows)
vengono stampati i messaggi d'errore, non vi prestate attenzione per
ora.


\subsubsection{(step 2) Il login}

La procedura di login è la prima cosa da fare. Il protocollo POP3
ha due comandi per il login, \emph{user} e \emph{pass}. Prima il client
esegue uno user, poi dice al server la password. Come abbiamo già
visto nella panoramica questo significa che prima verrà eseguito \texttt{user()}
e poi \texttt{\emph{}}\texttt{pass()}. Questo è un esempio di login:\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

tassi@garfield:~$ telnet localhost 2000

Trying 127.0.0.1...

Connected to garfield.

Escape character is '^]'.

+OK FreePOPs/0.0.10 pop3 server ready

user test@foo.xx

+OK PLEASE ENTER PASSWORD

pass hello

-ERR AUTH FAILED

\end{verbatim}

\end{footnotesize} Se lanciate FreePOPs con il parametro \texttt{-w} dovreste leggere
questo sullo standard error/standard output:\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

freepops started with loglevel 2 on a little endian machine.

Cannot create pid file "/var/run/freepopsd.pid"

DBG(popserver.c, 162): [5118] ?? Ip address 0.0.0.0 real port 2000

DBG(popserver.c, 162): [5118] ?? Ip address 127.0.0.1 real port 2000

DBG(popserver.c, 162): [5118] -> +OK FreePOPs/0.0.10 pop3 server ready

DBG(popserver.c, 162): [5118] <- user test@foo.xx

DBG(log_lua.c,  83): (@src/lua/foo.lua, 37) : FreePOPs plugin 'Foo web mail' version '0.0.1' started!

*** the user wants to login as 'test@foo.xx'

DBG(popserver.c, 162): [5118] -> +OK PLEASE ENTER PASSWORD

DBG(popserver.c, 157): [5118] <- PASS *********

*** the user inserted 'hello' as the password for 'test@foo.xx'

DBG(popserver.c, 162): [5118] -> -ERR AUTH FAILED

AUTH FAILED

DBG(threads.c,  81): thread 0 will die

\end{verbatim}

\end{footnotesize}il plugin è stato modificato un pò per memorizzare i dati dell'utente
e stampare delle informazioni di debug. Questo è il plugin che ha
dato questo output:\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

foo_globals= {

username="nothing",

password="nothing"

}

-- -------------------------------------------------------------------------- --

-- Must save the mailbox name

function user(pstate,username)

foo_globals.username = username

print("*** the user wants to login as '"..username.."'")

return POPSERVER_ERR_OK

end

-- -------------------------------------------------------------------------- --

-- Must login

function pass(pstate,password)

foo_globals.password = password

print("*** the user inserted '"..password..

    "' as the password for '"..foo_globals.username.."'")

return POPSERVER_ERR_AUTH end

-- -------------------------------------------------------------------------- --

-- Must quit without updating

function quit(pstate)

return POPSERVER_ERR_OK

end

\end{verbatim}

\end{footnotesize}Qui vediamo delle importanti novità. Per prima cosa, la tabella \texttt{foo\_globals}
che contiene tutti i valori globali (valori che devono essere a disposizione
di chiamate a funzioni successive) di cui abbiamo bisogno. Per ora
ci abbiamo messo il nome utente e la password. La funzione\texttt{user()}
ora memorizza il nome utente passato nella tabella \texttt{foo\_globals}
e stampa qualcosa sullo standard output. La funzione \texttt{pass()}
allo stesso modo memorizza la password nella tabella globale e stampa
qualcosa. La funzione \texttt{quit()} restituisce semplicemente \texttt{POPSERVER\_ERR\_OK}
per far felice FreePOPs.

Ora che sappiamo come FreePOPs si comporterà durante il login dobbiamo
implementare il login nella webmail, ma prima decommentiamo alcune
righe nella funzione \texttt{init()} (chiamata alla partenza del plugin),
la quale carica il modulo \texttt{browser.lua} (il modulo usato per
fare login nella webmail). Ecco la pagina di login della webmail vista
con Mozilla e il codice sorgente della stessa pagina (con Mozilla
lo si vede con Ctrl-U, \imageref{login}).

\myincludegraphics{login}{!htp}{scale=0.8}

\begin{footnotesize}

\begin{verbatim}

<html>

<head>

<title>foo.xx webmail login</title>

</head>

<body style="background-color : grey; color : white">

<h1>Webmail login</h1>

<form name="webmail" method="post" action="http://localhost:3000/">

login: <input type="text" size="10" name="username"> <br>

password: <input type="password" size="10" name="password"> <br>

<input type="submit" value="login">

</form>

</body>

</html>

\end{verbatim}

\end{footnotesize}Abbiamo due campi di input, uno chiamato username e uno chiamato password.
Quando l'utente fa click su login il browser web eseguira' \texttt{POST}
sul \texttt{HTTP://localhost:3000/} contenuto del form (ho usato un
indirizzo locale per comodita', ma dovrebbe essere qualcosa come \texttt{HTTP://webmail.foo.xx/login.php}).
Questo è ciò che il browser invia:\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

POST / HTTP/1.1

Host: localhost:3000

User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040614 Firefox/0.8 Accept: */*

Accept-Language: en-us,en;q=0.5

Accept-Encoding: gzip,deflate

Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7

Keep-Alive: 300

Connection: keep-alive

Content-Type: application/x-www-form-urlencoded

Content-Length: 37



username=test%40foo.xx&password=hello

\end{verbatim}

\end{footnotesize} Non ci interessa la prima parte (l'header HTTP, visto che il modulo
browser se ne occuperà), bensì l'ultima, i dati inviati. poiché i
campi del form erano username e password, i dati inviati sono\texttt{}~\\
\texttt{username=test\%40.foo.xx\&password=hello}. Ora vogliamo riprodurre
la stessa richiesta HTTP con il nostro plugin. Questo è il semplice
codice che fara' proprio quello.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- -------------------------------------------------------------------------- --

-- Must login

function pass(pstate,password)

foo_globals.password = password



print("*** the user inserted '"..password..

     "' as the password for '"..foo_globals.username.."'")



-- create a new browser

local b = browser.new()



-- store the browser object in globals

foo_globals.browser = b



       -- create the data to post      

       local post_data = string.format("username=%s&password=%s",

               foo_globals.username,foo_globals.password)

       -- the uri to post to   

       local post_uri = "http://localhost:3000/"



       -- post it      

       local file,err = nil, nil       

  

       file,err = b:post_uri(post_uri,post_data)

       

       print("we received this webpage: ".. file)      

       return POPSERVER_ERR_AUTH 

end 

\end{verbatim}

\end{footnotesize} Prima creiamo un oggetto browser, poi mettiamo insieme \texttt{post\_uri}
e \texttt{post\_data} usando un semplice \texttt{string.format} (una
funzione simile a printf). E questa è la richiesta risultante\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

POST / HTTP/1.1 

User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040322 Firefox/0.8

Pragma: no-cache 

Accept: */* 

Host: localhost 

Content-Length: 35 

Content-Type: application/x-www-form-urlencoded



username=test@foo.xx&password=hello 

\end{verbatim}

\end{footnotesize}questo è essenzialmente come lo volevamo fare (dovremmo fare url-encode
dei post data con \texttt{curl.escape()}). Abbiamo salvato l'oggetto
browser sulla tabella globale, perché vogliamo usare lo stesso browser
tutte le volte.

Ora che abbiamo fatto login, vogliamo controllare la pagina risultante,
e magari estrarre un ID di sessione che useremo poi. Questo è il codice
per estrarre l'ID di sessione e la pagina HTML che abbiamo ricevuto
in risposta alla richiesta di login\linespread{0.5}

\begin{footnotesize}

\begin{verbatim} 

        ... come sopra qui ...

     

        print("we received this webpage: ".. file)

        

        -- search the session ID        

        local _,_,id = string.find(file,"session_id=(%w+)")



        if id == nil then               

               return POPSERVER_ERR_AUTH

        end



        foo_globals.session_id = id

        return POPSERVER_ERR_OK

end 

\end{verbatim}

\end{footnotesize} e questa è la pagina web restituita (vedi \imageref{logindone}).\\
\myincludegraphics{logindone}{!htp}{scale=0.8}\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

<html> 

<head> 

<title>foo.xx webmail</title> 

</head> 

<body style="background-color : grey; color : white"> 

<h1>Webmail - test@foo.xx</h1> 

Login done! click here to view the inbox folder. 

<a href="http://localhost:3000/inbox.php?session_id=ABCD1234">inbox</a> 

</body> 

</html>

\end{verbatim}

\end{footnotesize} Notate che abbiamo estratto l'ID di sessione usando \\
\texttt{string.find(file,''session\_id=(\%w+)'')}. Questa è una
funzione molto importante nella libreria LUA e, anche se è descritta
nel tutorial LUA su HTTP://lua-users.org, parleremo un po' di capture
anche qui. Guardiamo i sorgenti della pagina. Ci interessa la riga\emph{}\\
\texttt{<a href=\char`\"{}HTTP://localhost:3000/inbox.php?session\_id=ABCD1234\char`\"{}>inbox</a>}
\emph{}\\
che contiene il session\_id che vogliamo catturare. La nostra espressione
è \texttt{\emph{session\_id=(\%w+)}} che significa che vogliamo trovare
tutte le stringhe che iniziano con \texttt{session\_id=} e poi continuano
con uno o più caratteri alfanumerici. Siccome abbiamo scritto \texttt{\%w+}
tra parentesi tonde, intendiamo catturare il contenuto delle parentesi
(la parte alfanumerica). Così string.find restituirà tre valori, i
primi due sono ignorati (assegnati alla variabile dummy \texttt{\_})
mentre il terzo è la stringa catturata (nel nostro caso \texttt{ABCD1234}).
Il tutorial LUA su lua-users è molto ben fatto e su HTTP://sf.net/projects/lua-users
potete trovare il LUA short reference che è un riassunto di tutte
le funzioni standard LUA ed è anche un gran bel documento (mille grazie
a Enrico Colombini). Se vi piace molto LUA dovreste comprare IL libro
su LUA chiamato \emph{{}``Programming in Lua''} di Roberto Ierusalimschy
(consideratelo il K\&R per LUA).


\subsubsection{(step 3) Ottenere la lista dei messaggi}

Ora dovremo implementare la funzione \texttt{stat()}. La stat è probabilmente
la funzione più importante. Essa deve prelevare la lista dei messaggi
nella webmail, il loro UIDL e la loro grandezza. Nel nostro esempio
useremo il modulo mlex per tirare fuori le informazioni importanti
dalla pagina, ma potete usare il modulo per le stringhe di LUA per
fare la stessa cosa con i capture. Questa è la nostra pagina inbox
(vedi \imageref{inbox})\\
\myincludegraphics{inbox}{!htp}{scale=0.8}

e questo è il corpo HTML (solo i primi due messaggi sono riportati)\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

<h1>test@foo.xx - inbox (1/2)</h1> 

<form name="inbox" method="post" action="/delete.php"> 

<input type="hidden" name="session_id" value="ABCD1234"> 

<table> 

<tr><th>From</th><th>subject</th><th>size</th><th>date</th></tr> 

<tr>        

  <td><b>friend1@foo1.xx</b></td>         

  <td><b><a href="/read.php?session_id=ABCD1234&uidl=123">ok!</a></b></td>

  <td><b>20KB</b></td>

  <td><b>today</b></td>   

  <td><input type="checkbox" name="check_123"></td>

</tr> 

<tr>    

  <td>friend2@foo2.xx</td>        

  <td><a href="/read.php?session_id=ABCD1234&uidl=124">Re: hi!</a></td>  

  <td>12KB</td>   

  <td>yesterday</td>      

  <td><input type="checkbox" name="check_124"></td> 

</tr>

</table> 

<input type="submit" value="delete marked"> 

</form> 

<a href="/inbox.php?session_id=ABCD1234&page=2">go to next page</a> 

</body> 

\end{verbatim}

\end{footnotesize}Abbiamo prelevato l'HTML usando il browser e il metodo \texttt{get\_uri()}
(ricordate che la URI per l'inbox era nella pagina di login). Come
vedete i messaggi sono in una tabella, e tale tabella ha la stessa
struttura per ogni messaggio. Proprio questo è il posto in cui usare
mlex. Semplicemente, prendete tutto ciò che c'è tra \texttt{<tr>}
e \texttt{</tr>} di una riga di un messaggio e cancellate tutto tranne
i nomi dei i tag. Poi sostituite tutti gli spazi vuoti (chiameremo
spazio la stringa tra due tag) con un{}``\texttt{.{*}}''. Ecco cosa
abbiamo ottenuto (dovrebbe essere tutto sulla stessa riga, qui andiamo
a capo per mancanza di spazio) dal primo messaggio.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

.*<tr>.*<td>.*<b>.*</b>.*</td>.*<td>.*<b>.*<a>.*</a>.*</b>.*</td>.*

<td>.*<b>.*</b>.*</td>.*<td>.*<b>.*</b>.*</td>.*

<td>.*<input>.*</td>.*</tr>

\end{verbatim}

\end{footnotesize}Questa espressione è usata per fare match con la riga della tabella
che contiene informazioni sul messaggio. Ora copiate e incollate a
parte la riga e sostituite ogni spazio e ogni tag con O (la lettera,
non la cifra 0) o X. Mettete una X nei campi interessanti (nel nostro
esempio la grandezza e il tag input, che contiene lo UIDL del messaggio).\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

O<O>O<O>O<O>O<O>O<O>O<O>O<O>O<O>O<O>O<O>O<O>O

<O>O<O>X<O>O<O>O<O>O<O>O<O>O<O>O

<O>O<X>O<O>O<O>

\end{verbatim}

\end{footnotesize}Mentre la prima espressione verrà usata per fare match con la riga
della tabella, questa verrà usata per estrarre i campi importanti.
Questo codice lancia mlex sull'HTML e riempie la struttura dati popstate
con i dati catturati.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- -------------------------------------------------------------------------- -- 

-- Fill the number of messages and their size 

function stat(pstate)

      local file,err = nil, nil

      local b = foo_globals.browser

      file,err = b:get_uri("http://localhost:3000/inbox.php?session_id="..

              foo_globals.session_id)

      local e = ".*<tr>.*<td>.*<b>.*</b>.*</td>.*<td>.*<b>.*<a>"..               

              ".*</a>.*</b>.*</td>.*<td>.*<b>.*</b>.*</td>.*<td>.*"..                

              "<b>.*</b>.*</td>.*<td>.*<input>.*</td>.*</tr>"         

      local g = "O<O>O<O>O<O>O<O>O<O>O<O>O<O>O<O>O<O>O<O>O<O>O"..              

              "<O>O<O>X<O>O<O>O<O>O<O>O<O>O<O>O<O>O<X>O<O>O<O>"

      local x = mlex.match(file,e,g) 

      --debug print   

      x:print()



      set_popstate_nummesg(pstate,x:count())

      for i=1,x:count() do            

              local _,_,size = string.find(x:get(0,i-1),"(%d+)")

              local _,_,size_mult_k = string.find(x:get(0,i-1),"([Kk][Bb])") 
	      
	      local _,_,size_mult_m = string.find(x:get(0,i-1),"([Mm][Bb])")

              local _,_,uidl = string.find(x:get(1,i-1),"check_(%d+)")

           

              if size_mult_k ~= nil then

                     size = size * 1024

              end             

              if size_mult_m ~= nil then

                     size = size * 1024 * 1024

              end             

     

              set_mailmessage_size(pstate,i,size)                     

              set_mailmessage_uidl(pstate,i,uidl)

      end

 

      return POPSERVER_ERR_OK

end 

\end{verbatim}

\end{footnotesize}Il risultato di \texttt{x:print()} è il seguente\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

{'20KB','input type="checkbox" name="check_123"'}

\end{verbatim}

\end{footnotesize}e la sessione di telnet\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

+OK FreePOPs/0.0.11 pop3 server ready 

user test@foo.xx 

+OK PLEASE ENTER PASSWORD 

pass secret 

+OK ACCESS ALLOWED 

stat 

+OK 1 20480 

quit 

+OK BYE BYE, UPDATING 

\end{verbatim}

\end{footnotesize}Non abbiamo indicato come abbiamo aggiunto la riga \texttt{return}
\texttt{POPSERVER\_ERR\_OK} alla funzione \texttt{quit()}. Il codice
sorgente riportato sopra usa mlex per estrarre le due stringhe interessanti,
poi la scorre cercando la grandezza, il suo moltiplicatore e lo UIDL.
Di seguito imposta gli attributi dei messaggi. Potete vedere che abbiamo
processato solo il primo messaggio. Per processare gli altri dobbiamo
informare il modulo mlex che il tag  \texttt{<b>} è opzionale (potete
notare che solo il primo messaggio è in grassetto). Quindi cambiamo
le espressioni in\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

.*<tr>.*<td>[.*]{b}.*{/b}[.*]</td>.*<td>[.*]{b}.*<a>.*</a>.*{/b}[.*]</td>.*

<td>[.*]{b}.*{/b}[.*]</td>.*<td>[.*]{b}.*{/b}[.*]</td>.*

<td>.*<input>.*</td>.*</tr>

\end{verbatim}

\end{footnotesize}e\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

O<O>O<O>[O]{O}O{O}[O]<O>O<O>[O]{O}O<O>O<O>O{O}[O]<O>O

<O>[O]{O}X{O}[O]<O>O<O>[O]{O}O{O}[O]<O>O

<O>O<X>O<O>O<O>

\end{verbatim}

\end{footnotesize}Ora il comando stat risponde con \texttt{+OK 4 45056} e la stampa
di debug è \linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

{'20KB','input type="checkbox" name="check_123"'} 

{'12KB','input type="checkbox" name="check_124"'} 

{'10KB','input type="checkbox" name="check_125"'} 

{'2KB','input type="checkbox" name="check_126"'}

\end{verbatim}

\end{footnotesize}Ora abbiamo una vera e propria funzione stat che riempie la struttura
dati popstate con le informazioni di cui il server POP necessita per
rispondere ad una richiesta di stat. poiché le richieste list, uidl,
list\_all e uidl\_all possono essere soddisfatte con gli stessi dati,
useremo la funzione standard fornita dal modulo common.lua. Esso verrà
spiegato nel prossimo passo, ma dobbiamo aggiungere due righe importanti
alla funzione\texttt{stat()} per evitare una doppia chiamata.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

function stat(pstate) 

       if foo_globals.stat_done == true then return POPSERVER_ERR_OK end



       ... the same code here ...



       foo_globals.stat_done = true

       return POPSERVER_ERR_OK

end

\end{verbatim}

\end{footnotesize}

La funzione più importante è pronta, ma dobbiamo fare delle precisazioni.
Primo, mlex è molto comodo a volte, ma potreste trovare più utile
la libreria per le stringhe di LUA o la libreria regualerexp (espressioni
regolari estese posix) per raggiungere lo stesso scopo. Secondo, questa
implementazione si ferma alla prima pagina di inbox. Dovreste visitare
tutte le pagine di inbox, forse usando la funzione \texttt{do\_until()}
nella libreria  \texttt{support.lua} (che descriveremo brevemente
alla fine di questo tutorial). Terzo, non facciamo nessun controllo
degli errori. Per esempio la variabile file può essere nil e dobbiamo
controllare queste cose per fare un buon plugin.


\subsubsection{(step 4) Le funzioni comuni}

Il modulo comune ci dà alcune funzioni precotte che dipendono solo
da una \texttt{stat()} ben implementata (una stat che può essere chiamata
più di una volta). Ecco la nostra implementazione di queste funzioni\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- -------------------------------------------------------------------------- -- 

-- Fill msg uidl field 

function uidl(pstate,msg) return common.uidl(pstate,msg) end 



-- -------------------------------------------------------------------------- -- 

-- Fill all messages uidl field 

function uidl_all(pstate) return common.uidl_all(pstate) end 



-- -------------------------------------------------------------------------- -- 

-- Fill msg size 

function list(pstate,msg) return common.list(pstate,msg) end 



-- -------------------------------------------------------------------------- -- 

-- Fill all messages size 

function list_all(pstate) return common.list_all(pstate) end 



-- -------------------------------------------------------------------------- -- 

-- Unflag each message merked for deletion 

function rset(pstate) return common.rset(pstate) end



-- -------------------------------------------------------------------------- -- 

-- Mark msg for deletion 

function dele(pstate,msg) return common.dele(pstate,msg) end 



-- -------------------------------------------------------------------------- -- 

-- Do nothing 

function noop(pstate) return common.noop(pstate) end 



\end{verbatim}

\end{footnotesize}ma prima aggiungete il codice per caricare il modulo comune alla vostra
funzione \texttt{init()}.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

        ... the same code ..



        -- the common module    

        require("common")



        -- checks on globals    

        freepops.set_sanity_checks()    



        return POPSERVER_ERR_OK 

end 

\end{verbatim}

\end{footnotesize}


\subsubsection{(step 5) Cancellazione dei messaggi}

La cancellazione di un messaggio è solitamente un normale POST e un
esempio di \texttt{post\_data} è \texttt{session\_id=ABCD1234\&check\_124=on\&check\_126=on}.
Il codice segue\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- -------------------------------------------------------------------------- -- 

-- Update the mailbox status and quit 

function quit_update(pstate)

      -- we need the stat

      local st = stat(pstate)

      if st ~= POPSERVER_ERR_OK then return st end

         

      -- shorten names, not really important  

      local b = foo_globals.b         

      local post_uri = b:wherearewe() .. "/delete.php"        

      local session_id = foo_globals.session_id       

      local post_data = "session_id=" .. session_id .. "&"

    

      -- here we need the stat, we build the uri and we check if we   

      -- need to delete something     

    

      local delete_something = false; 

      for i=1,get_popstate_nummesg(pstate) do                 

             if get_mailmessage_flag(pstate,i,MAILMESSAGE_DELETE) then                                            
	     	post_data = post_data .. "check_" .. 

                        get_mailmessage_uidl(pstate,i).. "=on&"                             

                delete_something = true                 

             end     

      end

    

      if delete_something then                

             b:post_uri(post_uri,post_data)  

      end

    

      return POPSERVER_ERR_OK 

end 

\end{verbatim}

\end{footnotesize}Considerate che facciamo il POST solo se almeno un messaggio è segnato
per la cancellazione. Un'altra cosa importante da tenere a mente è
che fare un solo POST per tutti i messaggi è meglio che farne uno
per ognuno. Quando possibile dovreste ridurre il numero di richieste
HTTP al massimo dato che è qui che portiamo FreePOPs da lepre a tartaruga.


\subsubsection{(step 6) Scaricare messaggi}

Potrete chiedervi perché parliamo di questo argomento solo al punto
6, d'altronde avere la posta è probabilmente ciò che volete da un
plugin. Implementare la funzione \texttt{retr()} è di solito facile.
Dipende in realtà dalla webmail, ma qui parleremo del caso semplice,
mentre alla fine del tutorial vedrete come gestire webmail complesse.
Il caso base è quello in cui la webmail ha un pulsante per salvare
i messaggi, e il messaggio salvato è un file di testo semplice che
contiene sia l'header che il corpo del messaggio. Ci sono solo due
questioni interessanti in questo caso, e cioè quelle relativa ai messaggi
grandi al punto.

I messaggi grandi causano timeout. Sì, il modo più semplice di scaricare
un messaggio è chiamare \texttt{b:get\_uri()} e memorizzare il messaggio
in una variabile, poi mandarlo al client di posta con \texttt{popserver\_callback()}.
Ma pensate che una mail da 5MB, scaricata con una connessione DSL
da 640Kbps, alla piena velocità di 80KBps, impiega 64 secondi di download.
Questo significa che il vostro plugin non manderà dati al client di
posta per oltre un minuto, facendo sì che il client si disconnetta
da FreePOPS pensando che il server POP3 sia morto. Per cui, dobbiamo
mandare dati al client di posta appena possibile. Per questo abbiamo
la funzione \texttt{b:pipe\_uri()} che chiama un callback ogni volta
che ha dei dati freschi. Il codice seguente è la funzione di callback
factory, che crea un nuovo callback da passare al metodo \texttt{pipe\_uri}
del browser.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-------------------------------------------------------------------------------- 

-- The callback factory for retr 

-- 

function retr_cb(data)

        local a = stringhack.new() 

        return function(s,len)

                s = a:dothack(s).."\0"          

                popserver_callback(s,data)              

                return len,nil

        end

end 

\end{verbatim}

\end{footnotesize}Qui potete vedere che il callback usa \texttt{popserver\_callback()}
per passare dati al client di posta, ma prima di fare ciò manipola
i dati con lo stringhack. Ma questa è la seconda questione interessante.

Il protocollo POP3 deve terminare la risposta al comando retr con
una riga che contiene solo tre byte, {}``\texttt{.\textbackslash{}r\textbackslash{}n}''.
Ma che succede se una riga, dentro il corpo della mail, è un semplice
punto? Dobbiamo cambiarlo in {}``\texttt{..\textbackslash{}r\textbackslash{}n}''.
Non è cosi' difficile, una \texttt{string.gsub(s,''\textbackslash{}r\textbackslash{}n.\textbackslash{}r\textbackslash{}n'',''\textbackslash{}r\textbackslash{}n..\textbackslash{}r\textbackslash{}n'')}
è tutto ciò che ci serve... ma non nel caso dei callback. Il callback
di invio verrà chiamato con dati freschi, e più di una volta se la
mail è grande. E se il pattern cercato è troncato tra due chiamate
il metodo \texttt{string.gsub()} fallirà. Per questo il modulo stringhack
ci viene incontro. L'oggetto \texttt{a} vive fintantoché la funzione
di callback viene chiamata (vedi il tutorial LUA) e terrà a mente
che il pattern cercato può essere troncato.

Infine, il codice della \texttt{retr()}.\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- -------------------------------------------------------------------------- -- 

-- Get message msg, must call  

-- popserver_callback to send the data 

function retr(pstate,msg,pdata)          

        -- we need the stat

        local st = stat(pstate)

        if st ~= POPSERVER_ERR_OK then return st end 

    

        -- the callback

        local cb = retr_cb(data) 

     

        -- some local stuff

       local session_id = foo_globals.session_id

       local b = internal_state.b

       local uri = b:wherearewe() .. "/download.php?session_id="..session_id..

                "&message="..get_mailmessage_uidl(pstate,msg) 



        -- tell the browser to pipe the uri using cb

        local f,rc = b:pipe_uri(uri,cb)

        if not f then

                log.error_print("Asking for "..uri.."\n")

                log.error_print(rc.."\n")

                return POPSERVER_ERR_NETWORK

        end

end 

\end{verbatim}

\end{footnotesize}


\subsubsection{(step 7) Test}

Per fare un buon plugin ci vuole un sacco di testing. Dovreste cercare
beta tester presso il forum di FreePOPs (HTTP://freepops.diludovico.it)
e chiedere agli autori del software di includerlo nella distribuzione
principale. Dovreste anche leggere il contratto della webmail, controllare
se c'è qualcosa come {}``\emph{Non userò mai un server webmail->pop3
per leggere la mia posta}'' e inviare una copia agli autori del software.


\subsubsection{(step 8) La tanto anticipata parte finale del tutorial}

Ci sono un sacco di cose che abbiamo tralasciato.

\begin{description}
\item [La~multi-page~stat]è la vera buona implementazione per \texttt{stat()}.
Abbiamo detto sopra che la nostra implementazione elenca solo i messaggi
nella prima pagina. Il codice per il parsing e l'estrazione di informazioni
interessanti da una pagina è già scritto, ci serve solo una funzione
che controlli se siamo all'ultima pagina e se no cambi il valore di
una variabile \texttt{uri}. La variabile  \texttt{uri} in questione
sarà usata dalla funzione di prelevamento. In questo caso dovreste
usare il modulo di supporto con il ciclo do\_until. Questo è un semplice
esempio di \texttt{do\_until()} \linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- -------------------------------------------------------------------------- -- 

-- Fill the number of messages and their size 

function stat(pstate)

        ... some code as before ...



        -- this string will contain the uri to get. it may be updated by        

        -- the check_f function, see later      

        local uri = string.format(libero_string.first,popserver,session_id)



        -- The action for do_until      

        --      

        -- uses mlex to extract all the messages uidl and size  

        local function action_f (s)

                 -- calls match on the page s, with the mlexpressions

                 -- statE and statG              

                 local x = mlex.match(s,e,g)                 

               

                 -- the number of results                

                 local n = x:count()

                

                 if n == 0 then return true,nil end

 

                 -- this is not really needed since the structure                

                 -- grows automatically... maybe... don't remember now 

                 local nmesg_old = get_popstate_nummesg(pstate)

                 local nmesg = nmesg_old + n 

                 set_popstate_nummesg(pstate,nmesg)

      

                 -- gets all the results and puts them in the popstate structure                              for i = 1,n do                        

                         ... some code as before ...

 

                         set_mailmessage_size(pstate,i+nmesg_old,size)                     

                         set_mailmessage_uidl(pstate,i+nmesg_old,uidl)           

                 end     

                

                 return true,nil         

        end

        

        -- check must control if we are not in the last page and        

        -- eventually change uri to tell retrive_f the next page to retrive     

        local function check_f (s)              

                 local tmp1,tmp2 = string.find(s,next_check)              

                 if tmp1 ~= nil then                     

                          -- change retrive behaviour                     

                          uri = "--build the uri for the next page--"



                          -- continue the loop

                          return false       

                 else

                          return true

                 end

        end



        -- this is simple and uri-dependent

        local function retrive_f ()

                 local f,err = b:get_uri(uri)

                 if f == nil then 

                         return f,err

                 end

      

                 local _,_,c = string.find(f,"--timeout string--")

                 if c ~= nil then

                         internal_state.login_done = nil                                

                         session.remove(key())

                         local rc = libero_login()                       

                         if rc ~= POPSERVER_ERR_OK then                          

                                 return nil,"Session ended,unable to recover"                                         end             

                        

                         uri = "--uri for the first page--"      

                         return b:get_uri(uri)           

                  end     

               

                  return f,err    

        end



        -- initialize the data structure

        set_popstate_nummesg(pstate,0)

 

        -- do it        

        if not support.do_until(retrive_f,check_f,action_f) then

                  log.error_print("Stat failed\n")

                  session.remove(key())           

                  return POPSERVER_ERR_UNKNOWN    

        end

        

        -- save the computed values     

        internal_state["stat_done"] = true 

        return POPSERVER_ERR_OK 

end 

\end{verbatim}

\end{footnotesize}Le uniche cose strane sono la funzione di prelevamento e quel che
serve per salvare la sessione. Dato che le webmail a volte fanno timeout
dovreste controllare se la pagina prelevata sia valida o no, ed eventualmente
ritentare il login. Il salvataggio della sessione è la prossima questione.
\item [Salvare~la~sessione]è il modo per rendere FreePOPs davvero simile
ad un browser. ciò significa che la prossima volta che controllate
la posta FreePOPs ricaricherà semplicemente la pagina inbox senza
rifare il login. Per fare questo avete bisogno di una funzione \texttt{key()}
che crea un ID unico per ogni sessione\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-------------------------------------------------------------------------------- 

-- The key used to store session info 

-- 

-- This key must be unique for all webmails, since the session pool is one  

-- for all the webmails 

-- 

function key()

        return foo_globals.username .. foo_globals.password

end 

\end{verbatim}

\end{footnotesize}e una funzione di serializzazione  \texttt{foo\_globals}\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-------------------------------------------------------------------------------- 

-- Serialize the internal state 

-- 

-- serial.serialize is not enough powerful to correcly serialize the  

-- internal state. The field b is the problem. b is an object. This means 

-- that it is a table (and no problem for this) that has some field that are 

-- pointers to functions. this is the problem. there is no easy way for the  

-- serial module to know how to serialize this. so we call b:serialize  

-- method by hand hacking a bit on names 

-- 

function serialize_state()   

        internal_state.stat_done = false; 

        return serial.serialize("foo_globals",foo_globals) ..            

                internal_state.b:serialize("foo_globals.b") 

end 

\end{verbatim}

\end{footnotesize}Ora dovete dire a FreePOPs di salvare lo stato nella funzione \texttt{quit\_update()}
e caricarlo nella \texttt{pass()}. Questa è la nuova struttura \texttt{pass()}\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

function pass(pstate,password)  

        -- save the password

        internal_state.password = password



        -- eventually load session

        local s = session.load_lock(key())



        -- check if loaded properly

        if s ~= nil then

                 -- "\a" means locked

                 if s == "\a" then

                          log.say("Session for "..internal_state.name..

                              " is already locked\n")

                          return POPSERVER_ERR_LOCKED

                 end 

     

                 -- load the session

                 local c,err = loadstring(s)

                 if not c then

                          log.error_print("Unable to load saved session: "..err)

                          return foo_login()

                 end     

       

                 -- exec the code loaded from the session string

                 c()



                log.say("Session loaded for " .. internal_state.name .. "@" ..

                         internal_state.domain ..

                         "(" .. internal_state.session_id .. ")\n")      



                return POPSERVER_ERR_OK

        else

                -- call the login procedure

                return foo_login()

        end

end 

\end{verbatim}

\end{footnotesize}dove \texttt{foo\_login()} è la vecchia funzione \texttt{pass()} con
cambiamenti minori. Non dimenticate di chiamare \texttt{session.unlock(key())}
nella funzione \texttt{quit()}, perché dovrete rilasciare la sessione
in caso di fallimento (e  \texttt{quit()} viene chiamata qui) e salvare
la sessione in \texttt{quit\_update()}\linespread{0.5}

\begin{footnotesize}

\begin{verbatim}

-- save fails if it is already saved  

session.save(key(),serialize_state(),session.OVERWRITE)

-- unlock is useless if it have just been saved, but if we save

-- without overwriting the session must be unlocked manually

-- since it would fail instead overwriting

session.unlock(key()) 

\end{verbatim}

\end{footnotesize}
\item [La~funzione~top()]è piuttosto complessa. Non la descriveremo in
modo completo, ma suggeriamo di guardare il plugin  \texttt{libero.lua}
se il server web che vi manda i messaggi supporta il campo {}``\texttt{Range:}''
nelle richieste HTTP, o il plugin HTTP request field, o il plugin
\texttt{tin.lua} se il server deve essere interrotto in malo modo.
Ricordate che la \texttt{top()} ha bisogno che qualcuno conti le righe
e qui abbiamo di nuovo il modulo stringhack, che conta ed eventualmente
elimina delle righe.
\item [Il~javascript]è l'inferno delle webmail. I Javascript possono fare
qualsiasi cosa e dovrete leggerli per emulare ciò che fanno. Per esempio
potrebbero aggiungere alcuni cookie (e dovrete fare lo stesso a mano
con \texttt{b:add\_cookie()} come in tin.lua) oppure possono cambiare
alcuni campi di form (come nel codice  di bilanciamento del carico
in  \texttt{libero.lua}).
\item [I~cookie]sono abbastanza appetibili per noi, visto che il modulo
browser se ne occupa al posto nostro.
\item [I~file~standard]sono decisamente dipendenti dal sistema. Sotto
Windows dovrete costantemente guardare \texttt{stderr.txt} e \texttt{stdout.txt},
mentre sotto Unix dovrete solo lanciare FreePOPs con il parametro
\texttt{-w} e guardare la console.
\item [La~forza~bruta]si chiama Ethereal. A volte le cose non funzionano
nel modo giusto e l'unico modo per fare debug è attivare curl debugging
per vedere cosa fa FreePOPs (\texttt{b.curl:setopt(curl.OPT\_VERBOSE,1)})
e sniffare ciò che fa un vero browser con un tool come, appunto, Ethereal.
\item [Il~modo~open~source]è il modo migliore di avere software di buona
qualità. Questo significa che dovrete rilasciare molto spesso il vostro
plugin nella fase di sviluppo e interagire molto con i vostri tester.
Fidatevi, funziona, o leggete {}``\emph{The cathedral and the bazaar}''
di Eric Raymond.
\item [Il~modulo~mimer]è molto beta mentre scriviamo queste righe, ma
è ciò di cui avete bisogno se siete nel caso sfortunato di una webmail
che non ha un pulsante per salvare i messaggi. Il plugin \texttt{lycos.lua}
è un esempio di cosa può fare. La principale funzione interessante
è \texttt{mimer.pipe\_msg()} che prende un header di messaggio, il
testo del corpo (in html o testo semplice) e gli URI di alcuni attachment,
scaricati al volo, composti in una vera e propria mail che viene inoltrata
al client di posta.
\item [Parametri~per~i~moduli]possono venire passati dal file \texttt{config.lua}
o al volo usando \texttt{user@domain?param1=value1\&...\&paramN=valueN}
come descritto nel capitolo sui plugin. Per l'autore di plugin non
c'è differenza tra i due metodi. I parametri sono disponibili per
il plugin nella tabella \texttt{freepops.MODULE\_ARGS}.
\item [Regex~per~definire~i~domini~gestiti]sono supportate dalla 
version 0.0.29. I plugin ufficiali possono avere una riga nel
config.lua come questa
\begin{verbatim}
freepops.MODULES_MAP["foo2.*"]  = {

name="foo.lua",

regex = true -- enables the regex processing

}
\end{verbatim}
mentre i plugin non ufficiali possono dichiarare una lista di regex 
nel campo \texttt{PLUGIN\_REGEXES}. Per esempio
\begin{verbatim}
PLUGIN_REGEXES = {"@foo2.*", "@foo3.*", "@foo4[A-Z]*"}
\end{verbatim}

\end{description}

\section{Segnalare un bug}

Quando avete problemi o pensate di avere trovato un bug, vi preghiamo
di seguire alla lettera questo \emph{iter}:

\begin{enumerate}
\item Aggiornate alla versione più recente di FreePOPs.
\item Cercate di riprodurre il bug, se questo non è facilmente riproducibile
siamo sfortunati. Si può ancora tentare qualcosa, se il software è
andato in crash potreste compilarlo dai sorgenti, installare valgrind,
lanciare freepopsd con valgrind e sperare che i messaggi d'errore
siano interessanti.
\item Pulite i file di log
\item Lanciate FreePOPs con lo switch -w
\item Riproducete il bug
\item Inviate agli sviluppatori il log, più ogni altra informazione utile
come che tipo di sistema avete e come riprodurre il bug.
\end{enumerate}

\section{FAQ}


\subsection*{Come si configura FreePOPs?}

In condizioni d'uso normali FreePOPs non si configura, basta cambiare
le impostazioni del vostro client di posta come spiegato nel tutorial.
Per altri casi abbiamo fornito tutorial specifici. Ricordate di impostare
\emph{localhost} come server POP3 (se avete installato FreePOPs sul
computer da cui leggete la posta, altrimenti userete l'indirizzo IP
del computer dove è installato FreePOPs), \emph{2000} come porta (o
un'altra che avrete scelto all'esecuzione di FreePOPs con l'opzione
\emph{-p}) e di usare come nome utente il vostro indirizzo di posta
completo (nella forma \texttt{nomeutente@dominio.webmail}). \textbf{Non}
impostare l'uso di autenticazione per la connessione.

Se avete dei problemi, leggete pure i nostri tutorial. Se continuate
ad avere problemi, potete iscrivervi al forum su HTTP://freepops.diludovico.it
(molto frequentato) e descrivere il vostro problema.


\subsection*{FreePOPs si paga?}

FreePOPs è Free Software, è e rimarrà libero e gratuito. Lo potete
scaricare gratuitamente dal sito, ma se i quattro amici che l'hanno
creato vi stanno a cuore potete sempre inviargli una birretta chiedendo
il loro indirizzo via mail, o una piccola donazione (effettuabile
dal sito del progetto su SourceForge).


\subsection*{Ho installato e configurato correttamente FreePOPs, ma non riesco
comunque ad inviare messaggi, come posso fare?}

FreePOPs serve \textbf{solo} per ricevere la posta elettronica. Per
inviare messaggi dovete continuare ad utilizzare il server SMTP del
provider con il quale vi collegate ad Internet. In questo modo non
avrete nessun problema nell'invio di email. Per sapere a quale server
SMTP fare riferimento guardate il sito web del vostro provider o chiamate
il loro supporto tecnico.


\subsection*{Perderò la mia mail? Il programma è beta!}

Nessuno garantisce il software che produce, e nessuno si assume responsabilità,
tanto meno se il software non lo pagate. A noi pare abbastanza sicuro,
ma non possiamo garantire niente (nessun software è assolutamente
sicuro). Inoltre nessuno garantisce che il vostro client di mail funzioni
bene, quindi se usate quello...


\subsection*{Posso fare qualcosa per aiutare il progetto?}

Certo, i sorgenti sono disponibili. Mandateci pure patch e segnalateci
i problemi che incontrate.

Se il programma vi piace particolarmente potete anche contribuire
con una piccola donazione (effettuabile dal sito del progetto su SourceForge).

Quando volete segnalare un problema, assicuratevi prima che si verifichi
anche nell'ultima versione rilasciata del programma (se non è quella
che state usando). Consigliamo di disinstallare una vecchia versione
prima di installarne una nuova. Inoltre ricordatevi di includere:

\begin{itemize}
\item il numero della versione di FreePOPs che vi ha dato il problema
\item il sistema operativo su cui il problema si è presentato
\item il nome del client di posta che usi e se possibile il numero di versione
\item cosa più importante, il log di FreePOPs generato con l'opzione \textbf{-vv}
o \textbf{-w} (guardate sotto se non sapete dove si trova e/o come
aggiungere parametri alla riga di comando), controllando che non vi
siano riportati dati personali che non volete rendere noti ad altri
(gli autori del programma). Ma non preoccupatevi, la password non
è mai scritta nei log se non come una sequenza di nove (9) asterischi
(indipendentemente dalla sua reale lunghezza).
\end{itemize}

\subsection*{Dove si trova il log di FreePOPs?}

La posizione del log di FreePOPs dipende dal sistema operativo in
cui il programma viene eseguito. Su Linux, il log si trova in \emph{/var/log/freepops}
per default, o dove avete specificato con l'opzione \texttt{-l}. Su
Windows, il log (file log.txt) si trova nella cartella dove avete
installato FreePOPs o nel percorso da voi specificato se avete eseguito
FreePOPs con il parametro \texttt{-l}.

Prima di inviare il log assicuratevi che esso sia stato generato con
l'opzione \textbf{-vv} (o \textbf{-w}) che sta per {}``log verboso''.
Questi parametri da riga di comando producono un log molto più dettagliato
che ci permette di identificare più facilmente i problemi. Se necessario,
cancellate il file di log esistente e riavviate FreePOPs aggiungendo
uno di tali parametri alla riga di comando (guardate sotto): avrete
così un log {}``pulito'' che contiene solo la sessione fallita (se
l'errore è riproducibile). Come sopra, cancellate informazioni che
ritenete sensibili se non volete divulgarle.


\subsection*{Come cambio i parametri della riga di comando di FreePOPs?}

Su sistemi basati su Unix vi basta aggiungere i parametri che volete
al comando che usate per lanciare FreePOPs (forse da uno script).

Sui vari Windows avete due possibilità: dal menu Start -> Programmi
-> FreePOPs aprire la finestra delle proprietà del collegamento a
FreePOPs (con il tasto destro del mouse e selezionando dal menu che
apparirà la voce {}``Proprietà...'') e aggiungere i parametri nella
casella {}``Destinazione'' (in coda a X:\textbackslash{}Qualcosa\textbackslash{}freepopsd.exe);
oppure lanciare FreePOPs manualmente da una finestra DOS con i parametri
che volete (sempre specificandoli dopo il nome dell'eseguibile).

I parametri che vi servono dipendono dalle vostre esigenze. Leggete
l'apposita sezione del manuale per conoscerli tutti o lanciate \texttt{freepopsd
-h} (anche \texttt{man freepopsd} su Unix).

\begin{itemize}
\item Esempio Unix: \texttt{/usr/bin/freepopsd -P proxy:porta -A user:pass
-w -l logfile.txt}
\item Esempio Windows: \texttt{C:\textbackslash{}Programmi\textbackslash{}FreePOPs\textbackslash{}freepopsd.exe
-w}
\end{itemize}

\subsection*{Il mio {}``Antivirus'' di fiducia dice che in FreePOPs c'è un virus,
che devo fare?}

Smettere di usare quell'antivirus :-) A parte gli scherzi, FreePOPs
NON contiene virus, cavalli di troia, worm, formule per riti demoniaci,
piani segreti per il dominio del mondo né altro del genere. Se non
credete a noi, i sorgenti sono disponibili a tutti (il programma è
rilasciato sotto Licenza GNU GPL) e pensare di nascondere codice malevolo
alla luce del sole sarebbe quantomeno folle. Pertanto un qualsiasi
antivirus che rilevi problemi di questo tipo ha problemi di accuratezza,
eufemisticamente parlando.

Vero è che scaricare un eseguibile pre-compilato da una qualche fonte
sconosciuta è come andare in cerca di guai. I pacchetti pre-compilati
che trovate sulle pagine ufficiali del progetto (http://www.freepops.org)
provengono dai sorgenti che tutti possono vedere. Ciò che trovate
su siti vari di software gratuito o che scaricate tramite sistemi
di file sharing peer-to-peer, non può \emph{chiaramente} offrire alcuna
garanzia di sicurezza. Per cui usate un po' di buon senso. 


\section{Autori}

Questo manuale è stato scritto da Enrico Tassi \texttt{<gareuselesinge [at] users.sourceforge.net>}
e rivisto e tradotto da Nicola Cocchiaro \texttt{<ncocchiaro [at] users.sourceforge.net>}


\subsection{Sviluppatori}

\noindent FreePOPs è sviluppato da:

\begin{itemize}
\item Enico Tassi \texttt{<gareuselesinge [at] users.sourceforge.net>}
\item Alessio Caprari \texttt{<alessiofender [at] users.sourceforge.net>}
\item Nicola Cocchiaro \texttt{<ncocchiaro [at] users.sourceforge.net>}
\item Simone Vellei \texttt{<simone\_vellei [at] users.sourceforge.net>}
\end{itemize}
\noindent yahoo.lua, hotmail.lua, aol.lua, netscape.lua, mailcom.lua,
juno.lua, mail2world.lua, criticalpath.lua, fastmail.lua sono sviluppati da:

\begin{itemize}
\item Russell Schwager <\texttt{russells [at] despammed.com}> \\
\end{itemize}
\noindent gmail.lua è sviluppato da:

\begin{itemize}
\item Rami Kattan <\texttt{rkattan [at] gmail.com}> \\
HTTP://www.kattanweb.com/rami
\end{itemize}
\noindent squirrelmail.lua, tre.lua sono sviluppati da:

\begin{itemize}
\item Eddi De Pieri <\texttt{dpeddi [at] users.sourceforge.net}> \\
\end{itemize}
\noindent supereva.lua \`e sviluppato da:

\begin{itemize}
\item Andrea Dalle Molle <\texttt{Tund3r [at] fastwebnet.it}> \\
\end{itemize}
\noindent LiberoPOPs era sviluppato da:

\begin{itemize}
\item Enico Tassi \texttt{<gareuselesinge [at] users.sourceforge.net>}
\item Alessio Caprari \texttt{<alessiofender [at] users.sourceforge.net>}
\item Nicola Cocchiaro \texttt{<ncocchiaro [at] users.sourceforge.net>}
\item Simone Vellei \texttt{<simone\_vellei [at] users.sourceforge.net>}
\item Giacomo Tenaglia \texttt{<sonicsmith [at] users.sourceforge.net>}
\end{itemize}

\section{Ringraziamenti}

Ringraziamenti speciali vanno agli utenti che hanno testato il software,
agli hacker che hanno reso possibile avere un ambiente di sviluppo
affidabile e libero come il sistema Debian GNU/Linux.


\section*{Appendice}

Poiché la tabella ASCII è molto comune, non l'abbiamo inclusa qui.
Potete chiedere a google.
\end{document}
