


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.



pop3d                         1.1.0                             1





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


       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-edi-
       tor.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 han-
              dled 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.





pop3d                         1.1.0                             2





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


       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  nei-
              ther 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  mail-
              box  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 authen-
       tication callback so that pop3 servers following the interface of  this
       module are able to use it.





pop3d                         1.1.0                             3





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


       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 refer-
              ence, in this order.

              The storage reference is passed unchanged to the  storage  call-
              back,  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 sec-
       tion 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 con-
              nection to the server. This is necessary  to  prevent  havoc  if
              several connections to the same mailbox are open. The complemen-
              tary 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 spec-
              ified.

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





pop3d                         1.1.0                             4





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


SECURE MAIL TRANSFER
       The option -socket (see Options) enables users of the package to  over-
       ride  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://source-
       forge.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                             5


