Provided by: tcllib_1.19-dfsg-2_all bug

NAME

       pop3d - Tcl POP3 server implementation

SYNOPSIS

       package require Tcl  8.3

       package require pop3d  ?1.1.0?

       ::pop3d::new ?serverName?

       serverName option ?arg arg ...?

       serverName up

       serverName down

       serverName destroy ?mode?

       serverName configure

       serverName configure -option

       serverName configure -option value...

       serverName cget -option

       serverName conn list

       serverName conn state id

       authCmd exists name

       authCmd lookup name

       storageCmd dele mbox msgList

       storageCmd lock mbox

       storageCmd unlock mbox

       storageCmd size mbox ?msgId?

       storageCmd stat mbox

       storageCmd get mbox msgId

_________________________________________________________________________________________________

DESCRIPTION

       ::pop3d::new ?serverName?
              This  command  creates  a  new  server object with an associated global Tcl command
              whose name is serverName.

       The command serverName may be used to invoke various operations on the server.  It has the
       following general form:

       serverName option ?arg arg ...?
              Option and the args determine the exact behavior of the command.

       A  pop3 server can be started on any port the caller has permission for from the operating
       system. The default port will be 110, which is the port defined by the standard  specified
       in  RFC 1939 (http://www.rfc-editor.org/rfc/rfc1939.txt).  After creating, configuring and
       starting a the server object will listen for and  accept  connections  on  that  port  and
       handle them according to the POP3 protocol.

       Note:  The  server  provided by this module will handle only the basic protocol by itself.
       For the higher levels of user authentication and handling of the actual  mailbox  contents
       callbacks will be invoked.

       The following commands are possible for server objects:

       serverName up
              After this call the server will listen for connections on its configured port.

       serverName down
              After  this  call  the  server  will  stop listening for connections. This does not
              affect existing connections.

       serverName destroy ?mode?
              Destroys the server object. Currently open connections are handled depending on the
              chosen mode.  The provided modes are:

              kill   Destroys  the  server  immediately, and forcefully closes all currently open
                     connections. This is the default mode.

              defer  Stops the server from accepting new connections and will actually destroy it
                     only  after  the  last  of  the currently open connections for the server is
                     closed.

       serverName configure
              Returns a list containing all options and their current values in a format suitable
              for  use  by the command array set. The options themselves are described in section
              Options.

       serverName configure -option
              Returns the current value of the specified option. This is an alias for the  method
              cget. The options themselves are described in section Options.

       serverName configure -option value...
              Sets  the  specified  option  to  the  provided  value.  The options themselves are
              described in section Options.

       serverName cget -option
              Returns the current value of the  specified  option.  The  options  themselves  are
              described in section Options.

       serverName conn list
              Returns a list containing the ids of all connections currently open.

       serverName conn state id
              Returns  a  list  suitable  for  [array set] containing the state of the connection
              referenced by id.

OPTIONS

       The following options are available to pop3 server objects.

       -port port
              Defines the port to listen on for new connections. Default is 110. This option is a
              bit special. If port is set to "0" the server, or rather the operating system, will
              select a free port on its own. When querying -port the id of this chosen port  will
              be  returned.  Changing  the  port  while  the server is up will neither change the
              returned value, nor will it change on which port the server is listening  on.  Only
              after resetting the server via a call to down followed by a call to up will the new
              port take effect. It is at that time that the value returned  when  querying  -port
              will change too.

       -auth command
              Defines a command prefix to call whenever the authentication of a user is required.
              If no such command is specified the server will reject  all  users.  The  interface
              which   has  to  be  provided  by  the  command  prefix  is  described  in  section
              Authentication.

       -storage command
              Defines a command prefix to call whenever  the  handling  of  mailbox  contents  is
              required.  If no such command is specified the server will claim that all mailboxes
              are empty. The interface which  has  to  be  provided  by  the  command  prefix  is
              described in section Mailboxes.

       -socket command
              Defines  a  command  prefix  to call for opening the listening socket.  This can be
              used to make the pop3 server listen on a SSL socket as provided by the tls package,
              see the command tls::socket.

AUTHENTICATION

       Here  we describe the interface which has to be provided by the authentication callback so
       that pop3 servers following the interface of this module are able to use it.

       authCmd exists name
              This method is given a username and has to return a boolean value  telling  whether
              or not the specified user exists.

       authCmd lookup name
              This method is given a username and has to return a two-element list containing the
              password for this user and a storage reference, in this order.

              The storage reference is passed unchanged to the  storage  callback,  see  sections
              Options  and  Mailboxes  for  either the option defining it and or the interface to
              provide, respectively.

MAILBOXES

       Here we describe the interface which has to be provided by the storage  callback  so  that
       pop3  servers following the interface of this module are able to use it. The mbox argument
       is the storage reference as returned by the lookup method of the  authentication  command,
       see section Authentication.

       storageCmd dele mbox msgList
              ]  Deletes  the  messages  whose  numeric ids are contained in the msgList from the
              mailbox specified via mbox.

       storageCmd lock mbox
              This method locks the specified mailbox for use  by  a  single  connection  to  the
              server.  This  is  necessary  to  prevent  havoc if several connections to the same
              mailbox are open. The complementary method is unlock. The command will return  true
              if the lock could be set successfully or false if not.

       storageCmd unlock mbox
              This  is  the  complementary  method  to lock, it revokes the lock on the specified
              mailbox.

       storageCmd size mbox ?msgId?
              Determines the size of the message specified through its id in msgId, in bytes, and
              returns  this  number. The command will return the size of the whole maildrop if no
              message id was specified.

       storageCmd stat mbox
              Determines the number of messages in the specified mailbox and returns this number.

       storageCmd get mbox msgId
              Returns a handle for the specified message. This handle is a mime  token  following
              the  interface described in the documentation of package mime. The pop3 server will
              use the functionality of the mime token to send the mail to the  requestor  at  the
              other end of a pop3 connection.

SECURE MAIL TRANSFER

       The  option  -socket (see Options) enables users of the package to override how the server
       opens its listening  socket.   The  envisioned  main  use  is  the  specification  of  the
       tls::socket command, see package tls, to secure the communication.

                package require tls
                tls::init \\
                   ...

                pop3d::new S -socket tls::socket
                ...

REFERENCES

       [1]    RFC 1939 [http://www.rfc-editor.org/rfc/rfc1939.txt]

       [2]    RFC 2449 [http://www.rfc-editor.org/rfc/rfc2449.txt]

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.   Please  report  such  in  the  category   pop3d   of   the   Tcllib   Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be  made  by going to the Edit form of the ticket immediately after its creation, and then
       using the left-most button in the secondary navigation bar.

KEYWORDS

       internet, network, pop3, protocol, rfc 1939, secure, ssl, tls

CATEGORY

       Networking

COPYRIGHT

       Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
       Copyright (c) 2005 Reinhard Max  <max@suse.de>