pop3d(n)                    Tcl POP3 Server Package                   pop3d(n)



______________________________________________________________________________

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


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 SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  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
       Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
       Copyright (c) 2005 Reinhard Max  <max@suse.de>




pop3d                                1.1.0                            pop3d(n)
