pkg://icqmail-2.0a1.tar.gz:49734/icqmail-2.0a1/icqmail.man  downloads

.TH ICQMAIL 1 "Version 2.0a1"
.ds ]W January 2000
.SH NAME
icqmail \- ICQ->Email gateway
.SH SYNOPSIS
.ta 6n
\fBicqmail\fP 
[-f \fIcfg file\fP]
[-a \fIaliases file\fP]
[-s \fIscript file\fP]
[-l \fIlog file\fP]
[-d]
 
.br
.SH DESCRIPTION
The 
.I icqmail 
program acts as a simple ICQ->EMAIL gateway. It logs in to the ICQ
network, receives all messages for a specific user, and forwards them
to some email address.

.SH OPTIONS
.PP
.I icqmail\fP accepts following options:
.TP 8
.B \-d 
if specified, the program will detach itself from control teminal and work in 'daemon' mode. All error messages will go to syslog.
.TP 8
.B \-f \fP<\fIconfigutation file\fP>
Name of configuration file.
.TP 8
.B \-a \fP<\fIaliases file\fP>
Name of aliases file.
.TP 8
.B \-s \fP<\fIscript file\fP>
Name of script file.
.TP 8
.B \-l \fP<\fIlog file\fP>
Name of log file. All error output will be written to this file.

.SH CONFIGURATION FILE FORMAT
.PP
You need to create the configuration file. You can find a sample one
in the distribution named 'sample.cfg'. If value of some field contain
several words separated by spaces, it should be enclosed in double
quotes. Here is a list of allowed keywords:

.TP 8
.B Server          \fP
name of ICQ server host.
.TP 8
.B Port            \fP
port number of ICQ server.
.TP 8
.B UIN             \fP
your UIN.
.TP 8
.B Password        \fP
your password. Sorry it is stored in clear text.
.TP 8
.B ForwardTo       \fP
email address where all your messages are forwarded.
.TP 8
.B SmtpServer       \fP
name of you SMTP server host.
.TP 8
.B SendAsSubject         \fP
This option indicates that all ICQ messages should be delivered in Subject of email message. This is particulary useful when sending email to text pager. If this option is 'true', 'Subject' option will be disregarded. 
.
.TP 8
.B Subject         \fP
subject under which all ICQ messages will arrive to your mail box.
.TP 8
.B LogLevel        \fP
if this number is not 0 you will see some low level protocol messages on the screen. Useful for troubleshooting.
.TP 8
.B ReturnAddressSuffix \fP
this would be added after UIN in From: field of all messages.
.TP 8
.B Status \fP
This is ICQ of icqmail will switch to, after login. Should be one of the following: online, invisible, na, free_for_chat, occupied, away, dnd.
.TP 8
.B ReturnReceipt   \fP
specifies message that should be sent to sender after receiving a message.
.TP 8
.B NotifyOnConnect   \fP
Following is comma separated list of UINs which will be monitored.
once user logs in, email will be sent to you.
.TP 8
.B NotifyOnDisconnect   \fP
Following is comma separated list of UINs which will be monitored.
once user logs out, email will be sent to you.
.TP 8
.B NotifyOnStatusChange   \fP
Following is comma separated list of UINs which will be monitored.
once user change status, email will be sent to you.
.TP 8
.B LoginAttempts   \fP
This is number of attemps will be made to connect/login.
After icqmail fail to commect or login this number times in a row
it will exit.
.TP 8
.B MessageTemplate   \fP
Following template will be used to send regilar messages.
Macros: UIN, HOUR, MINUTE, DAY, MONTH, YEAR, TEXT.
Procedure: icqmail-new-message
.TP 8
.B URLTemplate   \fP
Following template will be used to send URLs.
Macros: UIN, HOUR, MINUTE, DAY, MONTH, YEAR, URL, DESCRIPTION.
Procedure: icqmail-new-URL
.TP 8
.B EmailMessageTemplate   \fP
Following template will be used to send email express messages.
Macros: UIN, HOUR, MINUTE, DAY, MONTH, YEAR, TEXT, NAME, EMAIL.
Procedure: icqmail-new-email-express
.TP 8
.B OnlineTemplate   \fP
Following template will be used to send user online notification.
Macros: USER, IP, REALIP, PORT, STATUS.
Procedure: icqmail-status-changed
.TP 8
.B OfflineTemplate   \fP
Following template will be used to send user offline notification.
Macros: USER.
Procedure: icqmail-status-changed
.TP 8
.B StatusChangeTemplate   \fP
Following template will be used to send user status change notification.
Macros: USER, STATUS.
Procedure: icqmail-status-changed
.TP 8
.B ContactsTemplate   \fP
Following template will be used to send contact lists.
Macros: UIN, HOUR, MINUTE, DAY, MONTH, YEAR, TOTAL, LIST.
Procedure: n/a
.TP 8
.B OneContactTemplate  \fP
Following template will be used format item of contact list.
Macros: SENDERUIN, NUMBER, UIN, NAME

.SH TEMPLATES
.PP
Format of the messages sent to the user could be customized editing
templated files. Each template file whill be used to form email
message sent to user. File might contain free form text with
macros. Text will be transferred intact, while macros would be
replaced by their values.  If 'SendAsSubject' option is set, all line
feeds in template will be replaced by spaces. All unresolved macros
will be removed from text.

Each macro name should be in format '$NAME'. If you need
to use dollar sign in template text, you must quote
it with backslash.

.SH SCRIPTING
.PP
Sometimes users want to implement non-standard processing of ICQ
messages. To simplify this task I added support for scripting. As
scripting language icqmail uses GUILE (Project GNU's extension
language). If you specified script file location on startup it will be
loaded, and special procedures will be called for different events
happenning, like receiving messages, or user status changes. Each
procedure takes only one parameter - alist of macros names and values
(with same names as used in templates). Each procedure can return #t,
meaning that no further processing of this message is required, or #f,
meaning that messages should be processing in regular manner.

Special procedure 'icqmail-cfg-file-loaded' is called after
configuration file is loaded. Single parameter is contents of cfg file
as alist.

Script file template is included in icqmail distribution under 
name 'sample.scm'.

.SH ALIASES
.PP
Aliases file allows you to make messages from ICQmail more
meaningul. Entries are located one per line and separated by spaces.
First field is sender ICQ number. Second field is user real name
(enclose in double quotation marks if name contains tabs or
spaces). Third field is optional and contains email address. For all
messages from this ICQ number, email will be generated with this given
user name in From field.  If email address was specified, Reply-To
header will be added to generated message with this address. Empty
lines and comment lines (starting from '#' character) are
ignored. 

Sample aliases file is included in icqmail distribution under the name 'aliases.cfg'.

.PP
.SH RETURN VALUES

.TP 8
.B 0   \fP
normal exit
.TP 8
.B 1   \fP
wrong arguments
.TP 8
.B 2   \fP
error loading/parsing cfg file
.TP 8
.B 8   \fP
connection to server lost
.TP 8
.B 16   \fP
user interrupt with SIGINT.

.SH BUGS
It was reported that some systems (e.g. Solaris 2.5) do not have function 
vsnprintf. In such case icqmail will use vsprintf instead, but this could 
cause buffer overflow problem. 

Due to the bug in current version of icqlib (0.1.3) URLs sending does
not seems to work.

This man page needs to be rewritten for clarity and language.

.SH FILES

sample.cfg, 
aliases.cfg, 
sample.scm,
contacts_template.txt,
offline_template.txt,
status_change_template.txt,
email_template.txt,
one_contact_template.txt,
url_template.txt,
message_template.txt,
online_template.txt

.TP8
.PP
.SH SEE ALSO
.PP
http://www.crocodile.org/software.html\,
ftp://www.crocodile.org/pub/,
http://www.icq.com/,
http://kicq.sourceforge.net/icqlib.html,
http://www.gnu.org/software/guile/guile.html

.SH AUTHOR
.PP
Vadim Zaliva <lord@crocodile.org>

.SH CONTRIBUTORS
.PP
Mooneer Salem <mooneer@earthlink.net>,
Andrey Arhipov <andy@paco.net>