Scroll to navigation

pop3d(3tcl) Tcl POP3 Server Package pop3d(3tcl) 





NAME


pop3d - Tcl POP3 server implementation






SYNOPSIS


package require Tcl 8.5 9


package require pop3d ?1.2.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:



  

  
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:



  

  
After this call the server will listen for connections on its configured
      port.

  

  
After this call the server will stop listening for connections. This does
      not affect existing connections.

  

  
Destroys the server object. Currently open connections are handled
      depending on the chosen mode. The provided modes are:







  

  
Destroys the server immediately, and forcefully closes all currently open
      connections. This is the default mode.

  

  
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.







  

  
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.

  

  
Returns the current value of the specified option. This is an alias for
      the method cget. The options themselves are described in section
      Options.

  

  
Sets the specified option to the provided value. The options themselves
      are described in section Options.

  

  
Returns the current value of the specified option. The options themselves
      are described in section Options.

  

  
Returns a list containing the ids of all connections currently open.

  

  
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.



  

  
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.

  

  
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.

  

  
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.

  

  
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.



  

  
This method is given a username and has to return a boolean value
      telling whether or not the specified user exists.

  

  
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.



  

  
Deletes the messages whose numeric ids are contained in the msgList
      from the mailbox specified via 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.

  

  
This is the complementary method to lock, it revokes the lock on
      the specified mailbox.

  

  
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.

  

  
Determines the number of messages in the specified mailbox and returns
      this number.

  

  
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.


When proposing code changes, please provide unified diffs,
    i.e the output of diff -u.


Note further that attachments are strongly preferred over
    inlined patches. Attachments can be made by going to the Edit form of
    the ticket immediately after its creation, and then using the left-most
    button in the secondary navigation bar.






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>








  

    1.2.0
    tcllib