Provided by: tcllib_1.17-dfsg-1_all 
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
Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
Copyright (c) 2005 Reinhard Max <max@suse.de>