1pop3d(n)                    Tcl POP3 Server Package                   pop3d(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       pop3d - Tcl POP3 server implementation
9

SYNOPSIS

11       package require Tcl  8.3
12
13       package require pop3d  ?1.1.0?
14
15       ::pop3d::new ?serverName?
16
17       serverName option ?arg arg ...?
18
19       serverName up
20
21       serverName down
22
23       serverName destroy ?mode?
24
25       serverName configure
26
27       serverName configure -option
28
29       serverName configure -option value...
30
31       serverName cget -option
32
33       serverName conn list
34
35       serverName conn state id
36
37       authCmd exists name
38
39       authCmd lookup name
40
41       storageCmd dele mbox msgList
42
43       storageCmd lock mbox
44
45       storageCmd unlock mbox
46
47       storageCmd size mbox ?msgId?
48
49       storageCmd stat mbox
50
51       storageCmd get mbox msgId
52
53______________________________________________________________________________
54

DESCRIPTION

56       ::pop3d::new ?serverName?
57              This  command  creates  a  new  server object with an associated
58              global Tcl command whose name is serverName.
59
60       The command serverName may be used to invoke various operations on  the
61       server.  It has the following general form:
62
63       serverName option ?arg arg ...?
64              Option and the args determine the exact behavior of the command.
65
66       A  pop3 server can be started on any port the caller has permission for
67       from the operating system. The default port will be 110, which  is  the
68       port defined by the standard specified in RFC 1939 (http://www.rfc-edi
69       tor.org/rfc/rfc1939.txt).  After creating, configuring and  starting  a
70       the  server  object will listen for and accept connections on that port
71       and handle them according to the POP3 protocol.
72
73       Note: The server provided by this module will  handle  only  the  basic
74       protocol  by  itself.  For the higher levels of user authentication and
75       handling of the actual mailbox contents callbacks will be invoked.
76
77       The following commands are possible for server objects:
78
79       serverName up
80              After this call the server will listen for  connections  on  its
81              configured port.
82
83       serverName down
84              After  this call the server will stop listening for connections.
85              This does not affect existing connections.
86
87       serverName destroy ?mode?
88              Destroys the server object. Currently open connections are  han‐
89              dled depending on the chosen mode.  The provided modes are:
90
91              kill   Destroys  the  server  immediately, and forcefully closes
92                     all currently open connections. This is the default mode.
93
94              defer  Stops the server from accepting new connections and  will
95                     actually  destroy it only after the last of the currently
96                     open connections for the server is closed.
97
98       serverName configure
99              Returns a list containing all options and their  current  values
100              in  a  format suitable for use by the command array set. The op‐
101              tions themselves are described in section Options.
102
103       serverName configure -option
104              Returns the current value of the specified option.  This  is  an
105              alias  for the method cget. The options themselves are described
106              in section Options.
107
108       serverName configure -option value...
109              Sets the specified option to the  provided  value.  The  options
110              themselves are described in section Options.
111
112       serverName cget -option
113              Returns  the  current value of the specified option. The options
114              themselves are described in section Options.
115
116       serverName conn list
117              Returns a list containing the ids of all  connections  currently
118              open.
119
120       serverName conn state id
121              Returns  a list suitable for [array set] containing the state of
122              the connection referenced by id.
123

OPTIONS

125       The following options are available to pop3 server objects.
126
127       -port port
128              Defines the port to listen on for new  connections.  Default  is
129              110.  This  option  is  a bit special. If port is set to "0" the
130              server, or rather the operating system, will select a free  port
131              on  its own. When querying -port the id of this chosen port will
132              be returned. Changing the port while the server is up will  nei‐
133              ther change the returned value, nor will it change on which port
134              the server is listening on. Only after resetting the server  via
135              a  call  to down followed by a call to up will the new port take
136              effect. It is at that time that the value returned when querying
137              -port will change too.
138
139       -auth command
140              Defines  a command prefix to call whenever the authentication of
141              a user is required. If no such command is specified  the  server
142              will reject all users. The interface which has to be provided by
143              the command prefix is described in section Authentication.
144
145       -storage command
146              Defines a command prefix to call whenever the handling of  mail‐
147              box  contents  is  required. If no such command is specified the
148              server will claim that all mailboxes are  empty.  The  interface
149              which  has  to be provided by the command prefix is described in
150              section Mailboxes.
151
152       -socket command
153              Defines a command prefix  to  call  for  opening  the  listening
154              socket.   This  can  be used to make the pop3 server listen on a
155              SSL socket as provided by  the  tls  package,  see  the  command
156              tls::socket.
157

AUTHENTICATION

159       Here  we describe the interface which has to be provided by the authen‐
160       tication callback so that pop3 servers following the interface of  this
161       module are able to use it.
162
163       authCmd exists name
164              This  method  is  given  a  username and has to return a boolean
165              value telling whether or not the specified user exists.
166
167       authCmd lookup name
168              This method is given a username and has to return a  two-element
169              list  containing the password for this user and a storage refer‐
170              ence, in this order.
171
172              The storage reference is passed unchanged to the  storage  call‐
173              back,  see  sections Options and Mailboxes for either the option
174              defining it and or the interface to provide, respectively.
175

MAILBOXES

177       Here we describe the interface which has to be provided by the  storage
178       callback  so  that  pop3 servers following the interface of this module
179       are able to use it. The mbox argument is the storage reference  as  re‐
180       turned  by the lookup method of the authentication command, see section
181       Authentication.
182
183       storageCmd dele mbox msgList
184              Deletes the messages whose numeric ids are contained in the  ms‐
185              gList from the mailbox specified via mbox.
186
187       storageCmd lock mbox
188              This method locks the specified mailbox for use by a single con‐
189              nection to the server. This is necessary  to  prevent  havoc  if
190              several connections to the same mailbox are open. The complemen‐
191              tary method is unlock. The command will return true if the  lock
192              could be set successfully or false if not.
193
194       storageCmd unlock mbox
195              This is the complementary method to lock, it revokes the lock on
196              the specified mailbox.
197
198       storageCmd size mbox ?msgId?
199              Determines the size of the message specified through its  id  in
200              msgId,  in  bytes, and returns this number. The command will re‐
201              turn the size of the whole maildrop if no message id was  speci‐
202              fied.
203
204       storageCmd stat mbox
205              Determines  the  number of messages in the specified mailbox and
206              returns this number.
207
208       storageCmd get mbox msgId
209              Returns a handle for the specified message.  This  handle  is  a
210              mime  token  following the interface described in the documenta‐
211              tion of package mime. The pop3 server will use the functionality
212              of the mime token to send the mail to the requestor at the other
213              end of a pop3 connection.
214

SECURE MAIL TRANSFER

216       The option -socket (see Options) enables users of the package to  over‐
217       ride  how  the  server opens its listening socket.  The envisioned main
218       use is the specification of the tls::socket command, see  package  tls,
219       to secure the communication.
220
221
222                package require tls
223                tls::init \
224                   ...
225
226                pop3d::new S -socket tls::socket
227                ...
228
229

REFERENCES

231       [1]    RFC 1939 [http://www.rfc-editor.org/rfc/rfc1939.txt]
232
233       [2]    RFC 2449 [http://www.rfc-editor.org/rfc/rfc2449.txt]
234

BUGS, IDEAS, FEEDBACK

236       This  document,  and the package it describes, will undoubtedly contain
237       bugs and other problems.  Please report such in the category  pop3d  of
238       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
239       also report any ideas for enhancements you may have for either  package
240       and/or documentation.
241
242       When proposing code changes, please provide unified diffs, i.e the out‐
243       put of diff -u.
244
245       Note further that  attachments  are  strongly  preferred  over  inlined
246       patches.  Attachments  can  be  made  by  going to the Edit form of the
247       ticket immediately after its creation, and  then  using  the  left-most
248       button in the secondary navigation bar.
249

KEYWORDS

251       internet, network, pop3, protocol, rfc 1939, secure, ssl, tls
252

CATEGORY

254       Networking
255
257       Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
258       Copyright (c) 2005 Reinhard Max  <max@suse.de>
259
260
261
262
263tcllib                               1.1.0                            pop3d(n)
Impressum