1nntp(n) Tcl NNTP Client Library nntp(n)
2______________________________________________________________________________
6
8 nntp - Tcl client for the NNTP protocol
9
11 package require Tcl 8.2
12 package require nntp ?0.2.1?
14 ::nntp::nntp ?host? ?port? ?nntpName?
16 nntpName method ?arg arg ...?
18 nntpName article ?msgid?
20 nntpName authinfo ?user? ?pass?
22 nntpName body ?msgid?
24 nntpName configure
26 nntpName configure option
28 nntpName configure option value ...
30 nntpName cget option
32 nntpName date
34 nntpName group ?group?
36 nntpName head ?msgid?
38 nntpName help
40 nntpName last
42 nntpName list
44 nntpName listgroup ?group?
46 nntpName mode_reader
48 nntpName newgroups since
50 nntpName newnews
52 nntpName newnews since
54 nntpName newnews group ?since?
56 nntpName next
58 nntpName post article
60 nntpName slave
62 nntpName stat ?msgid?
64 nntpName quit
66 nntpName xgtitle ?group_pattern?
68 nntpName xhdr field ?range?
70 nntpName xover ?range?
72 nntpName xpat field range ?pattern_list?
74______________________________________________________________________________
76
78 The package nntp provides a simple Tcl-only client library for the NNTP
79 protocol. It works by opening the standard NNTP socket on the server,
80 and then providing a Tcl API to access the NNTP protocol commands. All
81 server errors are returned as Tcl errors (thrown) which must be caught
82 with the Tcl catch command.
83
85 ::nntp::nntp ?host? ?port? ?nntpName?
86 The command opens a socket connection to the specified NNTP
87 server and creates a new nntp object with an associated global
88 Tcl command whose name is nntpName. This command may be used to
89 access the various NNTP protocol commands for the new connec‐
90 tion. The default port number is "119" and the default host is
91 "news". These defaults can be overridden with the environment
92 variables NNTPPORT and NNTPHOST respectively.
93 Some of the commands supported by this package are not part of
95 the nntp rfc 977 (http://www.rfc-editor.org/rfc/rfc977.txt) and
96 will not be available (or implemented) on all nntp servers.
97 The access command nntpName has the following general form:
99 nntpName method ?arg arg ...?
101 Option and the args determine the exact behavior of the
102 command.
103 nntpName article ?msgid?
105 Query the server for article msgid from the current group. The
106 article is returned as a valid tcl list which contains the head‐
107 ers, followed by a blank line, and then followed by the body of
108 the article. Each element in the list is one line of the arti‐
109 cle.
110 nntpName authinfo ?user? ?pass?
112 Send authentication information (username and password) to the
113 server.
114 nntpName body ?msgid?
116 Query the server for the body of the article msgid from the cur‐
117 rent group. The body of the article is returned as a valid tcl
118 list. Each element in the list is one line of the body of the
119 article.
120 nntpName configure
122 nntpName configure option
124 nntpName configure option value ...
126 nntpName cget option
128 Query and configure options of the nntp connection object. Cur‐
129 rently only one option is supported, -binary. When set articles
130 are retrieved as binary data instead of text. The only methods
131 affected by this are article and body.
132 One application of this option would be the download of articles
134 containing yEnc encoded images. Although encoded the data is
135 still mostly binary and retrieving it as text will corrupt the
136 information.
137 See package yencode for both encoder and decoder of such data.
139 nntpName date
141 Query the server for the servers current date. The date is re‐
142 turned in the format YYYYMMDDHHMMSS.
143 nntpName group ?group?
145 Optionally set the current group, and retrieve information about
146 the currently selected group. Returns the estimated number of
147 articles in the group followed by the number of the first arti‐
148 cle in the group, followed by the last article in the group,
149 followed by the name of the group.
150 nntpName head ?msgid?
152 Query the server for the headers of the article msgid from the
153 current group. The headers of the article are returned as a
154 valid tcl list. Each element in the list is one line of the
155 headers of the article.
156 nntpName help
158 Retrieves a list of the commands that are supported by the news
159 server that is currently attached to.
160 nntpName last
162 Sets the current article pointer to point to the previous mes‐
163 sage (if there is one) and returns the msgid of that message.
164 nntpName list
166 Returns a tcl list of valid newsgroups and associated informa‐
167 tion. Each newsgroup is returned as an element in the tcl list
168 with the following format:
169 group last first p
172 where <group> is the name of the newsgroup, <last> is the number
175 of the last known article currently in that newsgroup, <first>
176 is the number of the first article currently in the newsgroup,
177 and <p> is either 'y' or 'n' indicating whether posting to this
178 newsgroup is allowed ('y') or prohibited ('n').
179 The <first> and <last> fields will always be numeric. They may
181 have leading zeros. If the <last> field evaluates to less than
182 the <first> field, there are no articles currently on file in
183 the newsgroup.
184 nntpName listgroup ?group?
186 Query the server for a list of all the messages (message num‐
187 bers) in the group specified by the argument group or by the
188 current group if the group argument was not passed.
189 nntpName mode_reader
191 Query the server for its nntp 'MODE READER' response string.
192 nntpName newgroups since
194 Query the server for a list of all the new newsgroups created
195 since the time specified by the argument since. The argument
196 since can be any time string that is understood by clock scan.
197 The tcl list of newsgroups is returned in a similar form to the
198 list of groups returned by the nntpName list command. Each ele‐
199 ment of the list has the form:
200 group last first p
203 where <group> is the name of the newsgroup, <last> is the number
206 of the last known article currently in that newsgroup, <first>
207 is the number of the first article currently in the newsgroup,
208 and <p> is either 'y' or 'n' indicating whether posting to this
209 newsgroup is allowed ('y') or prohibited ('n').
210 nntpName newnews
212 Query the server for a list of new articles posted to the cur‐
213 rent group in the last day.
214 nntpName newnews since
216 Query the server for a list of new articles posted to the cur‐
217 rent group since the time specified by the argument since. The
218 argument since can be any time string that is understood by
219 clock scan.
220 nntpName newnews group ?since?
222 Query the server for a list of new articles posted to the group
223 specified by the argument group since the time specified by the
224 argument since (or in the past day if no since argument is
225 passed. The argument since can be any time string that is un‐
226 derstood by clock scan.
227 nntpName next
229 Sets the current article pointer to point to the next message
230 (if there is one) and returns the msgid of that message.
231 nntpName post article
233 Posts an article of the form specified in RFC 1036
234 (http://www.rfc-editor.org/rfc/rfc1036.txt, successor to RFC
235 850) to the current news group.
236 nntpName slave
238 Identifies a connection as being made from a slave nntp server.
239 This might be used to indicate that the connection is serving
240 multiple people and should be given priority. Actual use is en‐
241 tirely implementation dependent and may vary from server to
242 server.
243 nntpName stat ?msgid?
245 The stat command is similar to the article command except that
246 no text is returned. When selecting by message number within a
247 group, the stat command serves to set the current article
248 pointer without sending text. The returned acknowledgment re‐
249 sponse will contain the message-id, which may be of some value.
250 Using the stat command to select by message-id is valid but of
251 questionable value, since a selection by message-id does NOT al‐
252 ter the "current article pointer"
253 nntpName quit
255 Gracefully close the connection after sending a NNTP QUIT com‐
256 mand down the socket.
257 nntpName xgtitle ?group_pattern?
259 Returns a tcl list where each element is of the form:
260 newsgroup description
263 If a group_pattern is specified then only newsgroups that match
266 the pattern will have their name and description returned.
267 nntpName xhdr field ?range?
269 Returns the specified header field value for the current message
270 or for a list of messages from the current group. field is the
271 title of a field in the header such as from, subject, date, etc.
272 If range is not specified or is "" then the current message is
273 queried. The command returns a list of elements where each ele‐
274 ment has the form of:
275 msgid value
278 Where msgid is the number of the message and value is the value
281 set for the queried field. The range argument can be in any of
282 the following forms:
283 "" The current message is queried.
285 msgid1-msgid2
287 All messages between msgid1 and msgid2 (including msgid1
288 and msgid2) are queried.
289 msgid1 msgid2
291 All messages between msgid1 and msgid2 (including msgid1
292 and msgid2) are queried.
293 nntpName xover ?range?
295 Returns header information for the current message or for a
296 range of messages from the current group. The information is
297 returned in a tcl list where each element is of the form:
298 msgid subject from date idstring bodysize headersize xref
301 If range is not specified or is "" then the current message is
304 queried. The range argument can be in any of the following
305 forms:
306 "" The current message is queried.
308 msgid1-msgid2
310 All messages between msgid1 and msgid2 (including msgid1
311 and msgid2) are queried.
312 msgid1 msgid2
314 All messages between msgid1 and msgid2 (including msgid1
315 and msgid2) are queried.
316 nntpName xpat field range ?pattern_list?
318 Returns the specified header field value for a specified message
319 or for a list of messages from the current group where the mes‐
320 sages match the pattern(s) given in the pattern_list. field is
321 the title of a field in the header such as from, subject, date,
322 etc. The information is returned in a tcl list where each ele‐
323 ment is of the form:
324 msgid value
327 Where msgid is the number of the message and value is the value
330 set for the queried field. The range argument can be in any of
331 the following forms:
332 msgid The message specified by msgid is queried.
334 msgid1-msgid2
336 All messages between msgid1 and msgid2 (including msgid1
337 and msgid2) are queried.
338 msgid1 msgid2
340 All messages between msgid1 and msgid2 (including msgid1
341 and msgid2) are queried.
342
344 A bigger example for posting a single article.
345 package require nntp
347 set n [nntp::nntp NNTP_SERVER]
348 $n post "From: USER@DOMAIN.EXT (USER_FULL)
349 Path: COMPUTERNAME!USERNAME
350 Newsgroups: alt.test
351 Subject: Tcl test post -ignore
352 Message-ID: <[pid][clock seconds]
353 @COMPUTERNAME>
354 Date: [clock format [clock seconds] -format "%a, %d %
355 b %y %H:%M:%S GMT" -gmt true]
356 Test message body"
358
361 This document, and the package it describes, will undoubtedly contain
362 bugs and other problems. Please report such in the category nntp of
363 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
364 also report any ideas for enhancements you may have for either package
365 and/or documentation.
366 When proposing code changes, please provide unified diffs, i.e the out‐
368 put of diff -u.
369 Note further that attachments are strongly preferred over inlined
371 patches. Attachments can be made by going to the Edit form of the
372 ticket immediately after its creation, and then using the left-most
373 button in the secondary navigation bar.
374
376 news, nntp, nntpclient, rfc 1036, rfc 977
377
379 Networking
380tcllib 1.5.1 nntp(n)