1pop3d(n) Tcl POP3 Server Package pop3d(n)
2______________________________________________________________________________
6
8 pop3d - Tcl POP3 server implementation
9
11 package require Tcl 8.3
12 package require pop3d ?1.1.0?
14 ::pop3d::new ?serverName?
16 serverName option ?arg arg ...?
18 serverName up
20 serverName down
22 serverName destroy ?mode?
24 serverName configure
26 serverName configure -option
28 serverName configure -option value...
30 serverName cget -option
32 serverName conn list
34 serverName conn state id
36 authCmd exists name
38 authCmd lookup name
40 storageCmd dele mbox msgList
42 storageCmd lock mbox
44 storageCmd unlock mbox
46 storageCmd size mbox ?msgId?
48 storageCmd stat mbox
50 storageCmd get mbox msgId
52______________________________________________________________________________
54
56 ::pop3d::new ?serverName?
57 This command creates a new server object with an associated
58 global Tcl command whose name is serverName.
59 The command serverName may be used to invoke various operations on the
61 server. It has the following general form:
62 serverName option ?arg arg ...?
64 Option and the args determine the exact behavior of the command.
65 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 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 The following commands are possible for server objects:
78 serverName up
80 After this call the server will listen for connections on its
81 configured port.
82 serverName down
84 After this call the server will stop listening for connections.
85 This does not affect existing connections.
86 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 kill Destroys the server immediately, and forcefully closes
92 all currently open connections. This is the default mode.
93 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 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 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 serverName configure -option value...
109 Sets the specified option to the provided value. The options
110 themselves are described in section Options.
111 serverName cget -option
113 Returns the current value of the specified option. The options
114 themselves are described in section Options.
115 serverName conn list
117 Returns a list containing the ids of all connections currently
118 open.
119 serverName conn state id
121 Returns a list suitable for [array set] containing the state of
122 the connection referenced by id.
123
125 The following options are available to pop3 server objects.
126 -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 -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 -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 -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
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 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 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 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
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 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 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 storageCmd unlock mbox
195 This is the complementary method to lock, it revokes the lock on
196 the specified mailbox.
197 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 storageCmd stat mbox
205 Determines the number of messages in the specified mailbox and
206 returns this number.
207 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
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 package require tls
223 tls::init \
224 ...
225 pop3d::new S -socket tls::socket
227 ...
228
231 [1] RFC 1939 [http://www.rfc-editor.org/rfc/rfc1939.txt]
232 [2] RFC 2449 [http://www.rfc-editor.org/rfc/rfc2449.txt]
234
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 When proposing code changes, please provide unified diffs, i.e the out‐
243 put of diff -u.
244 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
251 internet, network, pop3, protocol, rfc 1939, secure, ssl, tls
252
254 Networking
255
257 Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
258 Copyright (c) 2005 Reinhard Max <max@suse.de>
259tcllib 1.1.0 pop3d(n)