1 2[//000000001]: # (pop3d \- Tcl POP3 Server Package) 3[//000000002]: # (Generated from file 'pop3d\.man' by tcllib/doctools with format 'markdown') 4[//000000003]: # (Copyright © 2002\-2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net>) 5[//000000004]: # (Copyright © 2005 Reinhard Max <max@suse\.de>) 6[//000000005]: # (pop3d\(n\) 1\.1\.0 tcllib "Tcl POP3 Server Package") 7 8<hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> | <a 9href="../../../toc.md">Table Of Contents</a> | <a 10href="../../../../index.md">Keyword Index</a> | <a 11href="../../../../toc0.md">Categories</a> | <a 12href="../../../../toc1.md">Modules</a> | <a 13href="../../../../toc2.md">Applications</a> ] <hr> 14 15# NAME 16 17pop3d \- Tcl POP3 server implementation 18 19# <a name='toc'></a>Table Of Contents 20 21 - [Table Of Contents](#toc) 22 23 - [Synopsis](#synopsis) 24 25 - [Description](#section1) 26 27 - [Options](#section2) 28 29 - [Authentication](#section3) 30 31 - [Mailboxes](#section4) 32 33 - [Secure mail transfer](#section5) 34 35 - [References](#section6) 36 37 - [Bugs, Ideas, Feedback](#section7) 38 39 - [Keywords](#keywords) 40 41 - [Category](#category) 42 43 - [Copyright](#copyright) 44 45# <a name='synopsis'></a>SYNOPSIS 46 47package require Tcl 8\.3 48package require pop3d ?1\.1\.0? 49 50[__::pop3d::new__ ?*serverName*?](#1) 51[__serverName__ *option* ?*arg arg \.\.\.*?](#2) 52[*serverName* __up__](#3) 53[*serverName* __down__](#4) 54[*serverName* __destroy__ ?*mode*?](#5) 55[*serverName* __configure__](#6) 56[*serverName* __configure__ *\-option*](#7) 57[*serverName* __configure__ *\-option value*\.\.\.](#8) 58[*serverName* __cget__ *\-option*](#9) 59[*serverName* __conn__ list](#10) 60[*serverName* __conn__ state *id*](#11) 61[*authCmd* __exists__ *name*](#12) 62[*authCmd* __lookup__ *name*](#13) 63[*storageCmd* __dele__ *mbox* *msgList*](#14) 64[*storageCmd* __lock__ *mbox*](#15) 65[*storageCmd* __unlock__ *mbox*](#16) 66[*storageCmd* __size__ *mbox* ?*msgId*?](#17) 67[*storageCmd* __stat__ *mbox*](#18) 68[*storageCmd* __get__ *mbox* *msgId*](#19) 69 70# <a name='description'></a>DESCRIPTION 71 72 - <a name='1'></a>__::pop3d::new__ ?*serverName*? 73 74 This command creates a new server object with an associated global Tcl 75 command whose name is *serverName*\. 76 77The command __serverName__ may be used to invoke various operations on the 78server\. It has the following general form: 79 80 - <a name='2'></a>__serverName__ *option* ?*arg arg \.\.\.*? 81 82 *Option* and the *arg*s determine the exact behavior of the command\. 83 84A pop3 server can be started on any port the caller has permission for from the 85operating system\. The default port will be 110, which is the port defined by the 86standard specified in RFC 1939 87\([http://www\.rfc\-editor\.org/rfc/rfc1939\.txt](http://www\.rfc\-editor\.org/rfc/rfc1939\.txt)\)\. 88After creating, configuring and starting a the server object will listen for and 89accept connections on that port and handle them according to the POP3 protocol\. 90 91*Note:* The server provided by this module will handle only the basic protocol 92by itself\. For the higher levels of user authentication and handling of the 93actual mailbox contents callbacks will be invoked\. 94 95The following commands are possible for server objects: 96 97 - <a name='3'></a>*serverName* __up__ 98 99 After this call the server will listen for connections on its configured 100 port\. 101 102 - <a name='4'></a>*serverName* __down__ 103 104 After this call the server will stop listening for connections\. This does 105 not affect existing connections\. 106 107 - <a name='5'></a>*serverName* __destroy__ ?*mode*? 108 109 Destroys the server object\. Currently open connections are handled depending 110 on the chosen mode\. The provided *mode*s are: 111 112 * __kill__ 113 114 Destroys the server immediately, and forcefully closes all currently 115 open connections\. This is the default mode\. 116 117 * __defer__ 118 119 Stops the server from accepting new connections and will actually 120 destroy it only after the last of the currently open connections for the 121 server is closed\. 122 123 - <a name='6'></a>*serverName* __configure__ 124 125 Returns a list containing all options and their current values in a format 126 suitable for use by the command __array set__\. The options themselves 127 are described in section [Options](#section2)\. 128 129 - <a name='7'></a>*serverName* __configure__ *\-option* 130 131 Returns the current value of the specified option\. This is an alias for the 132 method __cget__\. The options themselves are described in section 133 [Options](#section2)\. 134 135 - <a name='8'></a>*serverName* __configure__ *\-option value*\.\.\. 136 137 Sets the specified option to the provided value\. The options themselves are 138 described in section [Options](#section2)\. 139 140 - <a name='9'></a>*serverName* __cget__ *\-option* 141 142 Returns the current value of the specified option\. The options themselves 143 are described in section [Options](#section2)\. 144 145 - <a name='10'></a>*serverName* __conn__ list 146 147 Returns a list containing the ids of all connections currently open\. 148 149 - <a name='11'></a>*serverName* __conn__ state *id* 150 151 Returns a list suitable for \[__array set__\] containing the state of the 152 connection referenced by *id*\. 153 154# <a name='section2'></a>Options 155 156The following options are available to pop3 server objects\. 157 158 - __\-port__ *port* 159 160 Defines the *port* to listen on for new connections\. Default is 110\. This 161 option is a bit special\. If *port* is set to "0" the server, or rather the 162 operating system, will select a free port on its own\. When querying 163 __\-port__ the id of this chosen port will be returned\. Changing the port 164 while the server is up will neither change the returned value, nor will it 165 change on which port the server is listening on\. Only after resetting the 166 server via a call to __down__ followed by a call to __up__ will the 167 new port take effect\. It is at that time that the value returned when 168 querying __\-port__ will change too\. 169 170 - __\-auth__ *command* 171 172 Defines a *command* prefix to call whenever the authentication of a user 173 is required\. If no such command is specified the server will reject all 174 users\. The interface which has to be provided by the command prefix is 175 described in section [Authentication](#section3)\. 176 177 - __\-storage__ *command* 178 179 Defines a *command* prefix to call whenever the handling of mailbox 180 contents is required\. If no such command is specified the server will claim 181 that all mailboxes are empty\. The interface which has to be provided by the 182 command prefix is described in section [Mailboxes](#section4)\. 183 184 - __\-socket__ *command* 185 186 Defines a *command* prefix to call for opening the listening socket\. This 187 can be used to make the pop3 server listen on a SSL socket as provided by 188 the __[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__ package, see the command 189 __tls::socket__\. 190 191# <a name='section3'></a>Authentication 192 193Here we describe the interface which has to be provided by the authentication 194callback so that pop3 servers following the interface of this module are able to 195use it\. 196 197 - <a name='12'></a>*authCmd* __exists__ *name* 198 199 This method is given a user*name* and has to return a boolean value 200 telling whether or not the specified user exists\. 201 202 - <a name='13'></a>*authCmd* __lookup__ *name* 203 204 This method is given a user*name* and has to return a two\-element list 205 containing the password for this user and a storage reference, in this 206 order\. 207 208 The storage reference is passed unchanged to the storage callback, see 209 sections [Options](#section2) and [Mailboxes](#section4) for 210 either the option defining it and or the interface to provide, respectively\. 211 212# <a name='section4'></a>Mailboxes 213 214Here we describe the interface which has to be provided by the storage callback 215so that pop3 servers following the interface of this module are able to use it\. 216The *mbox* argument is the storage reference as returned by the __lookup__ 217method of the authentication command, see section 218[Authentication](#section3)\. 219 220 - <a name='14'></a>*storageCmd* __dele__ *mbox* *msgList* 221 222 Deletes the messages whose numeric ids are contained in the *msgList* from 223 the mailbox specified via *mbox*\. 224 225 - <a name='15'></a>*storageCmd* __lock__ *mbox* 226 227 This method locks the specified mailbox for use by a single connection to 228 the server\. This is necessary to prevent havoc if several connections to the 229 same mailbox are open\. The complementary method is __unlock__\. The 230 command will return true if the lock could be set successfully or false if 231 not\. 232 233 - <a name='16'></a>*storageCmd* __unlock__ *mbox* 234 235 This is the complementary method to __lock__, it revokes the lock on the 236 specified mailbox\. 237 238 - <a name='17'></a>*storageCmd* __size__ *mbox* ?*msgId*? 239 240 Determines the size of the message specified through its id in *msgId*, in 241 bytes, and returns this number\. The command will return the size of the 242 whole maildrop if no message id was specified\. 243 244 - <a name='18'></a>*storageCmd* __stat__ *mbox* 245 246 Determines the number of messages in the specified mailbox and returns this 247 number\. 248 249 - <a name='19'></a>*storageCmd* __get__ *mbox* *msgId* 250 251 Returns a handle for the specified message\. This handle is a mime token 252 following the interface described in the documentation of package 253 __[mime](\.\./mime/mime\.md)__\. The pop3 server will use the 254 functionality of the mime token to send the mail to the requestor at the 255 other end of a pop3 connection\. 256 257# <a name='section5'></a>Secure mail transfer 258 259The option __\-socket__ \(see [Options](#section2)\) enables users of the 260package to override how the server opens its listening socket\. The envisioned 261main use is the specification of the __tls::socket__ command, see package 262__[tls](\.\./\.\./\.\./\.\./index\.md\#tls)__, to secure the communication\. 263 264 package require tls 265 tls::init \ 266 ... 267 268 pop3d::new S -socket tls::socket 269 ... 270 271# <a name='section6'></a>References 272 273 1. [RFC 1939](http://www\.rfc\-editor\.org/rfc/rfc1939\.txt) 274 275 1. [RFC 2449](http://www\.rfc\-editor\.org/rfc/rfc2449\.txt) 276 277# <a name='section7'></a>Bugs, Ideas, Feedback 278 279This document, and the package it describes, will undoubtedly contain bugs and 280other problems\. Please report such in the category *pop3d* of the [Tcllib 281Trackers](http://core\.tcl\.tk/tcllib/reportlist)\. Please also report any ideas 282for enhancements you may have for either package and/or documentation\. 283 284When proposing code changes, please provide *unified diffs*, i\.e the output of 285__diff \-u__\. 286 287Note further that *attachments* are strongly preferred over inlined patches\. 288Attachments can be made by going to the __Edit__ form of the ticket 289immediately after its creation, and then using the left\-most button in the 290secondary navigation bar\. 291 292# <a name='keywords'></a>KEYWORDS 293 294[internet](\.\./\.\./\.\./\.\./index\.md\#internet), 295[network](\.\./\.\./\.\./\.\./index\.md\#network), 296[pop3](\.\./\.\./\.\./\.\./index\.md\#pop3), 297[protocol](\.\./\.\./\.\./\.\./index\.md\#protocol), [rfc 2981939](\.\./\.\./\.\./\.\./index\.md\#rfc\_1939), 299[secure](\.\./\.\./\.\./\.\./index\.md\#secure), [ssl](\.\./\.\./\.\./\.\./index\.md\#ssl), 300[tls](\.\./\.\./\.\./\.\./index\.md\#tls) 301 302# <a name='category'></a>CATEGORY 303 304Networking 305 306# <a name='copyright'></a>COPYRIGHT 307 308Copyright © 2002\-2009 Andreas Kupries <andreas\_kupries@users\.sourceforge\.net> 309Copyright © 2005 Reinhard Max <max@suse\.de> 310