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>
