 |
ActiveTcl User Guide
|
 |
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
pop3(n) 1.6 "Tcl POP3 Client Library"
pop3 - Tcl client for POP3 email protocol
package require Tcl 8.2
package require pop3 ?1.6?
The pop3 package provides a simple Tcl-only
client library for the POP3 email protocol as specified in RFC 1939
(http://www.rfc-editor.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.
- ::pop3::open
?-msex 0|1? ?-retr-mode
retr|list|slow? host username password ?port?
- Open a socket connection to the server specified by host, transmit 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
connecting 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 manner and falls back to
reading the message from the server line by line.
It should also be noted that the system checks upon the configured
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 message 1, then the first message in the queue is
message 2 (message index 1 is no longer valid). See the startIndex and endIndex descriptions
below.
- startIndex
- The startIndex may be an index of a specific
message starting with the index 1, or it have any of the following
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 message 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 parameter 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 message is returned.
- ::pop3::close chan
- Gracefully close the connect after sending a POP3 QUIT command
down the socket.
email , mail , pop , pop3 , rfc 1939