Manual Pages for UNIX Darwin command on man pop3

pop3(n) Tcl POP3 Client Library pop3(n)

NAME

pop3 - Tcl client for POP3 email protocol

SYNOPSIS

package require TTccll 88..22 package require ppoopp33 ??11..66..11??

::::ppoopp33::::ooppeenn ?-mmsseexx 0|1? ?-rreettrr-mmooddee retr|list|slow? host username

password ?port? ::::ppoopp33::::ccoonnffiigg chan ::::ppoopp33::::ssttaattuuss chan ::::ppoopp33::::llaasstt chan ::::ppoopp33::::rreettrriieevvee chan startIndex ?endIndex? ::::ppoopp33::::ddeelleettee chan startIndex ?endIndex? ::::ppoopp33::::lliisstt chan ?msg? ::::ppoopp33::::ttoopp chan msg n ::::ppoopp33::::uuiiddll chan ?msg? ::::ppoopp33::::cclloossee chan

DESCRIPTION

The ppoopp33 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 ccaattcchh command. CCOOMMMMAANNDDSS

::::ppoopp33::::ooppeenn ?-mmsseexx 0|1? ?-rreettrr-mmooddee retr|list|slow? 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 -mmsseexx and -rreettrr-mmooddee. 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 rreettrr, lliisstt and ssllooww. The default is rreettrr. See ::::ppoopp33::::rreettrriieevvee for more information. ::::ppoopp33::::ccoonnffiigg chan

Returns the configuration of the pop3 connection identified by

the channel handle chan as a serialized array. ::::ppoopp33::::ssttaattuuss 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. ::::ppoopp33::::llaasstt 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. ::::ppoopp33::::rreettrriieevvee 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 rreettrr 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 lliisstt 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, ssllooww, 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. ::::ppoopp33::::ddeelleettee 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: ssttaarrtt This is a logical value for the first message in the spool, equivalent to the value 1. nneexxtt The message immediately following the last message read, see ::::ppoopp33::::llaasstt. eenndd 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: llaasstt The message is the last message read by a POP3 client, see ::::ppoopp33::::llaasstt. eenndd The most recent message in the spool (the end of the spool). ::::ppoopp33::::lliisstt chan ?msg? Returns the scan listing of the mailbox. If parameter msg is given, then the listing only for that message is returned. ::::ppoopp33::::ttoopp chan msg n Optional POP3 command, not all servers may support this.

::::ppoopp33::::ttoopp retrieves headers of a message, specified by parame-

ter msg, and number of n lines from the message body. ::::ppoopp33::::uuiiddll chan ?msg? Optional POP3 command, not all servers may support this. ::::ppoopp33::::uuiiddll returns the uid listing of the mailbox. If the

parameter msg is specified, then the listing only for that mes-

sage is returned. ::::ppoopp33::::cclloossee chan Gracefully close the connect after sending a POP3 QUIT command down the socket. KKEEYYWWOORRDDSS