pop3(n) Tcl POP3 Client Library pop3(n)
NAME
pop3 - Tcl client for POP3 email protocol
SYNOPSIS
package require Tcl 8.2
package require pop3 ??1.6.1??
::::pop3::::open ?-msex 01? ?-retr-mode retrlistslow? host username
password ?port?
::::pop3::::config chan
::::pop3::::status chan
::::pop3::::last chan
::::pop3::::retrieve chan startIndex ?endIndex?
::::pop3::::delete chan startIndex ?endIndex?
::::pop3::::list chan ?msg?
::::pop3::::top chan msg n
::::pop3::::uidl chan ?msg?
::::pop3::::close chan
DESCRIPTION
The pop3 package provides a simple Tcl-only client library for the POP3
email protocol as specified in RFC 1939 (http://www.rfc-edi-
tor.org/rfc/rfc1939.txt). It works by opening the standard POP3 socket
on the server, transmitting the username and password, then providing a
Tcl API to access the POP3 protocol commands. All server errors are
returned as Tcl errors (thrown) which must be caught with the Tcl catch
command.
COMANDS
::::pop3::::open ?-msex 01? ?-retr-mode retrlistslow? host username
password ?port?
Open a socket connection to the server specified by host, trans-
mit the username and password as login information to the
server. The default port number is 110, which can be overridden
using the optional port argument. The return value is a channel
used by all of the other ::pop3 functions.
The command recognizes the options -msex and -retr-mode. The
first of them can be used to notify the package of the fact that
the server to talk to is an MS Exchange server (which has some
oddities we have to work around). The default is 0.
The retrieval mode determines how exactly messages are read from
the server. The allowed values are retr, list and slow. The
default is retr. See ::::pop3::::retrieve for more information.
::::pop3::::config chan
Returns the configuration of the pop3 connection identified by
the channel handle chan as a serialized array.
::::pop3::::status chan
Query the server for the status of the mail spool. The status
is returned as a list containing two elements, the first is the
number of email messages on the server and the second is the
size (in octets, 8 byte blocks) of the entire mail spool.
::::pop3::::last chan
Query the server for the last email message read from the spool.
This value includes all messages read from all clients connect-
ing to the login account. This command may not be supported by
the email server, in which case the server may return 0 or an
error.
::::pop3::::retrieve chan startIndex ?endIndex?
Retrieve a range of messages from the server. If the endIndex
is not specified, only one message will be retrieved. The
return value is a list containing each message as a separate
element. See the startIndex and endIndex descriptions below.
The retrieval mode determines how exactly messages are read from
the server. The mode retr assumes that the RETR command delivers
the size of the message as part of the command status and uses
this to read the message efficiently. In mode list RETR does not
deliver the size, but the LIST command does and we use this to
retrieve the message size before the actual retrieval, which can
then be done efficiently. In the last mode, slow, the system is
unable to obtain the size of the message to retrieve in any man-
ner and falls back to reading the message from the server line
by line.
It should also be noted that the system checks upon the config-
ured mode and falls back to the slower modes if the above
assumptions are not true.
::::pop3::::delete chan startIndex ?endIndex?
Delete a range of messages from the server. If the endIndex is
not specified, only one message will be deleted. Note, the
indices are not reordered on the server, so if you delete mes-
sage 1, then the first message in the queue is message 2 (mes-
sage index 1 is no longer valid). See the startIndex and endIn-
dex descriptions below.
startIndex
The startIndex may be an index of a specific message
starting with the index 1, or it have any of the follow-
ing values:
start This is a logical value for the first message in
the spool, equivalent to the value 1.
next The message immediately following the last message
read, see ::::pop3::::last.
end The most recent message in the spool (the end of
the spool). This is useful to retrieve only the
most recent message.
endIndex
The endIndex is an optional parameter and defaults to the
value "-1", which indicates to only retrieve the one mes-
sage specified by startIndex. If specified, it may be an
index of a specific message starting with the index "1",
or it may have any of the following values:
last The message is the last message read by a POP3
client, see ::::pop3::::last.
end The most recent message in the spool (the end of
the spool).
::::pop3::::list chan ?msg?
Returns the scan listing of the mailbox. If parameter msg is
given, then the listing only for that message is returned.
::::pop3::::top chan msg n
Optional POP3 command, not all servers may support this.
::::pop3::::top retrieves headers of a message, specified by parame-
ter msg, and number of n lines from the message body.
::::pop3::::uidl chan ?msg?
Optional POP3 command, not all servers may support this.
::::pop3::::uidl returns the uid listing of the mailbox. If the
parameter msg is specified, then the listing only for that mes-
sage is returned.
::::pop3::::close chan
Gracefully close the connect after sending a POP3 QUIT command
down the socket.
KEYWORDS
email, mail, pop, pop3, rfc 1939
pop3 1.6.1 pop3(n)
|
