1[comment {-*- tcl -*-}] 2[manpage_begin pop3d n 1.1.0] 3[copyright {2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>}] 4[copyright {2005 Reinhard Max <max@suse.de>}] 5[moddesc {Tcl POP3 Server Package}] 6[titledesc {Tcl POP3 server implementation}] 7[category Networking] 8[keywords pop3 internet network protocol {rfc 1939} ssl tls secure] 9[require Tcl 8.3] 10[require pop3d [opt 1.1.0]] 11[description] 12[para] 13 14[list_begin definitions] 15 16[call [cmd ::pop3d::new] [opt [arg serverName]]] 17 18This command creates a new server object with an associated global Tcl 19command whose name is [arg serverName]. 20 21[list_end] 22 23The command [cmd serverName] may be used to invoke various operations 24on the server. It has the following general form: 25 26[list_begin definitions] 27[call [cmd serverName] [arg option] [opt [arg "arg arg ..."]]] 28 29[arg Option] and the [arg arg]s determine the exact behavior of the 30command. 31 32[list_end] 33 34[para] 35 36A pop3 server can be started on any port the caller has permission for 37from the operating system. The default port will be 110, which is the 38port defined by the standard specified in 39RFC 1939 ([uri http://www.rfc-editor.org/rfc/rfc1939.txt]). 40 41After creating, configuring and starting a the server object will 42listen for and accept connections on that port and handle them 43according to the POP3 protocol. 44 45[para] 46 47[emph Note:] The server provided by this module will handle only the 48basic protocol by itself. For the higher levels of user authentication 49and handling of the actual mailbox contents callbacks will be invoked. 50 51[para] 52 53The following commands are possible for server objects: 54 55[list_begin definitions] 56 57[call [arg serverName] [method up]] 58 59After this call the server will listen for connections on its configured port. 60 61[call [arg serverName] [method down]] 62 63After this call the server will stop listening for connections. This 64does not affect existing connections. 65 66[call [arg serverName] [method destroy] [opt [arg mode]]] 67 68Destroys the server object. Currently open connections are handled 69depending on the chosen mode. 70 71The provided [arg mode]s are: 72 73[list_begin definitions] 74 75[def [const kill]] 76 77Destroys the server immediately, and forcefully closes all currently 78open connections. This is the default mode. 79 80[def [const defer]] 81 82Stops the server from accepting new connections and will actually 83destroy it only after the last of the currently open connections for 84the server is closed. 85 86[list_end] 87 88[call [arg serverName] [method configure]] 89 90Returns a list containing all options and their current values in a 91format suitable for use by the command [cmd {array set}]. The options 92themselves are described in section [sectref Options]. 93 94[call [arg serverName] [method configure] [arg -option]] 95 96Returns the current value of the specified option. This is an alias 97for the method [method cget]. The options themselves are described in 98section [sectref Options]. 99 100[call [arg serverName] [method configure] [arg {-option value}]...] 101 102Sets the specified option to the provided value. The options 103themselves are described in section [sectref Options]. 104 105[call [arg serverName] [method cget] [arg -option]] 106 107Returns the current value of the specified option. The options 108themselves are described in section [sectref Options]. 109 110[call [arg serverName] [method conn] list] 111 112Returns a list containing the ids of all connections currently open. 113 114[call [arg serverName] [method conn] state [arg id]] 115 116Returns a list suitable for [lb][cmd {array set}][rb] containing the 117state of the connection referenced by [arg id]. 118 119[list_end] 120 121[section Options] 122 123The following options are available to pop3 server objects. 124 125[list_begin definitions] 126 127[def "[option -port] [arg port]"] 128 129Defines the [arg port] to listen on for new connections. Default is 130110. This option is a bit special. If [arg port] is set to "0" the 131server, or rather the operating system, will select a free port on its 132own. When querying [option -port] the id of this chosen port will be 133returned. Changing the port while the server is up will neither change 134the returned value, nor will it change on which port the server is 135listening on. Only after resetting the server via a call to 136 137[method down] followed by a call to [method up] will the new port take 138effect. It is at that time that the value returned when querying 139[option -port] will change too. 140 141[def "[option -auth] [arg command]"] 142 143Defines a [arg command] prefix to call whenever the authentication of 144a user is required. If no such command is specified the server will 145reject all users. The interface which has to be provided by the 146command prefix is described in section [sectref Authentication]. 147 148[def "[option -storage] [arg command]"] 149 150Defines a [arg command] prefix to call whenever the handling of 151mailbox contents is required. If no such command is specified the 152server will claim that all mailboxes are empty. The interface which 153has to be provided by the command prefix is described in section 154[sectref Mailboxes]. 155 156[def "[option -socket] [arg command]"] 157 158Defines a [arg command] prefix to call for opening the listening socket. 159This can be used to make the pop3 server listen on a SSL socket 160as provided by the [package tls] package, see the command [cmd tls::socket]. 161 162[list_end] 163 164[section Authentication] 165 166Here we describe the interface which has to be provided by the 167authentication callback so that pop3 servers following the interface 168of this module are able to use it. 169 170[list_begin definitions] 171 172[call [arg authCmd] [method exists] [arg name]] 173 174This method is given a user[arg name] and has to return a boolean 175value telling whether or not the specified user exists. 176 177[call [arg authCmd] [method lookup] [arg name]] 178 179This method is given a user[arg name] and has to return a two-element 180list containing the password for this user and a storage reference, in 181this order. 182 183[para] 184 185The storage reference is passed unchanged to the storage callback, see 186sections [sectref Options] and [sectref Mailboxes] for either the 187option defining it and or the interface to provide, respectively. 188 189[list_end] 190 191[section Mailboxes] 192 193Here we describe the interface which has to be provided by the storage 194callback so that pop3 servers following the interface of this module 195are able to use it. The [arg mbox] argument is the storage reference 196as returned by the [method lookup] method of the authentication 197command, see section [sectref Authentication]. 198 199[list_begin definitions] 200 201[call [arg storageCmd] [method dele] [arg mbox] [arg msgList]]] 202 203Deletes the messages whose numeric ids are contained in the 204[arg msgList] from the mailbox specified via [arg mbox]. 205 206[call [arg storageCmd] [method lock] [arg mbox]] 207 208This method locks the specified mailbox for use by a single connection 209to the server. This is necessary to prevent havoc if several 210connections to the same mailbox are open. The complementary method is 211[method unlock]. The command will return true if the lock could be set 212successfully or false if not. 213 214[call [arg storageCmd] [method unlock] [arg mbox]] 215 216This is the complementary method to [method lock], it revokes the lock 217on the specified mailbox. 218 219[call [arg storageCmd] [method size] [arg mbox] [opt [arg msgId]]] 220 221Determines the size of the message specified through its id in 222[arg msgId], in bytes, and returns this number. The command will 223return the size of the whole maildrop if no message id was specified. 224 225[call [arg storageCmd] [method stat] [arg mbox]] 226 227Determines the number of messages in the specified mailbox and returns 228this number. 229 230[call [arg storageCmd] [method get] [arg mbox] [arg msgId]] 231 232Returns a handle for the specified message. This handle is a mime 233token following the interface described in the documentation of 234package [package mime]. The pop3 server will use the functionality of 235the mime token to send the mail to the requestor at the other end of a 236pop3 connection. 237 238[list_end] 239 240[section {Secure mail transfer}] 241 242The option [option -socket] (see [sectref Options]) enables users of 243the package to override how the server opens its listening socket. 244 245The envisioned main use is the specification of the [cmd tls::socket] 246command, see package [package tls], to secure the communication. 247 248[example { 249 package require tls 250 tls::init \\ 251 ... 252 253 pop3d::new S -socket tls::socket 254 ... 255}] 256 257 258[vset CATEGORY pop3d] 259[include ../doctools2base/include/feedback.inc] 260[manpage_end] 261