xenial (3) pop3d.3tcl.gz

Provided by: tcllib_1.17-dfsg-1_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.

KEYWORDS

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

CATEGORY

       Networking

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