Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

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.7?

       ::pop3::open  ?-msex  0|1?  ?-retr-mode retr|list|slow? ?-socketcmd cmdprefix? 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-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.

API
       ::pop3::open ?-msex 0|1? ?-retr-mode retr|list|slow? ?-socketcmd cmdprefix?  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 three options

              -msex boolean
                     Setting  this  option  tells  the  package  that  the server we are talking to is an MS
                     Exchange server (which has some oddities we have to work around). The default is False.

              -retr-mode retr|list|slow
                     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.

              -socketcmd cmdprefix
                     This  option  allows the user to overide the use of the builtin socket command with any
                     API-compatible command. The envisioned main use is the securing of the  new  connection
                     via  SSL,  through  the  specification of the command tls::socket. This command is spe-cially specially
                     cially recognized as well, changing the default port of the connection to 995.

       ::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 contain-ing containing
              ing 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 mes-sages messages
              sages read from all clients connecting to the login account.  This command  may  not  be  sup-ported supported
              ported 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 mes-sage message
              sage will be retrieved.  The return value is a list containing each message as a separate ele-ment. element.
              ment.  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  mes-sage message
              sage  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 fol-lowing following
                     lowing 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.


SECURE MAIL TRANSFER
       A  pop3 connection can be secured with SSL/TLS by requiring the package TLS and then using the option
       -socketcmd of the command pop3::open to force the use of the tls::socket  command  when  opening  the
       connection.

            package require tls
            tls::init -cafile /path/to/ca/cert -keyfile ...

            # Create secured pop3 channel
            pop3::open -socketcmd tls::socket \\
                 $thehost $theuser $thepassword

            ...


BUGS, IDEAS, FEEDBACK
       This  document,  and  the  package  it  describes,  will undoubtedly contain bugs and other problems.
       Please  report  such  in  the   category   pop3   of   the   Tcllib   SF   Trackers   [http://source -
       forge.net/tracker/? group_id=12883].   Please  also report any ideas for enhancements you may have for
       either package and/or documentation.

KEYWORDS
       email, mail, pop, pop3, rfc 1939, secure, ssl, tls

CATEGORY
       Networking



pop3                                                 1.7                                             pop3(n)