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 start-
       ing 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  con-
		     nections 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 lis-
	      tening 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 MAIL-
	      BOXES.

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

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.

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

COPYRIGHT

       Copyright (c) 2002 Andreas Kupries <andreas_kupries@users.sourceforge.net>

pop3d								       1.1.0								  pop3d(n)