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
142 returned 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
171 where <group> is the name of the newsgroup, <last> is the number
173 of the last known article currently in that newsgroup, <first>
174 is the number of the first article currently in the newsgroup,
175 and <p> is either 'y' or 'n' indicating whether posting to this
176 newsgroup is allowed ('y') or prohibited ('n').
177 The <first> and <last> fields will always be numeric. They may
179 have leading zeros. If the <last> field evaluates to less than
180 the <first> field, there are no articles currently on file in
181 the newsgroup.
182 nntpName listgroup ?group?
184 Query the server for a list of all the messages (message num‐
185 bers) in the group specified by the argument group or by the
186 current group if the group argument was not passed.
187 nntpName mode_reader
189 Query the server for its nntp 'MODE READER' response string.
190 nntpName newgroups since
192 Query the server for a list of all the new newsgroups created
193 since the time specified by the argument since. The argument
194 since can be any time string that is understood by clock scan.
195 The tcl list of newsgroups is returned in a similar form to the
196 list of groups returned by the nntpName list command. Each ele‐
197 ment of the list has the form:
198 group last first p
200 where <group> is the name of the newsgroup, <last> is the number
202 of the last known article currently in that newsgroup, <first>
203 is the number of the first article currently in the newsgroup,
204 and <p> is either 'y' or 'n' indicating whether posting to this
205 newsgroup is allowed ('y') or prohibited ('n').
206 nntpName newnews
208 Query the server for a list of new articles posted to the cur‐
209 rent group in the last day.
210 nntpName newnews since
212 Query the server for a list of new articles posted to the cur‐
213 rent group since the time specified by the argument since. The
214 argument since can be any time string that is understood by
215 clock scan.
216 nntpName newnews group ?since?
218 Query the server for a list of new articles posted to the group
219 specified by the argument group since the time specified by the
220 argument since (or in the past day if no since argument is
221 passed. The argument since can be any time string that is
222 understood by clock scan.
223 nntpName next
225 Sets the current article pointer to point to the next message
226 (if there is one) and returns the msgid of that message.
227 nntpName post article
229 Posts an article of the form specified in RFC 1036
230 (http://www.rfc-editor.org/rfc/rfc1036.txt, successor to RFC
231 850) to the current news group.
232 nntpName slave
234 Identifies a connection as being made from a slave nntp server.
235 This might be used to indicate that the connection is serving
236 multiple people and should be given priority. Actual use is
237 entirely implementation dependent and may vary from server to
238 server.
239 nntpName stat ?msgid?
241 The stat command is similar to the article command except that
242 no text is returned. When selecting by message number within a
243 group, the stat command serves to set the current article
244 pointer without sending text. The returned acknowledgment
245 response will contain the message-id, which may be of some
246 value. Using the stat command to select by message-id is valid
247 but of questionable value, since a selection by message-id does
248 NOT alter the "current article pointer"
249 nntpName quit
251 Gracefully close the connection after sending a NNTP QUIT com‐
252 mand down the socket.
253 nntpName xgtitle ?group_pattern?
255 Returns a tcl list where each element is of the form:
256 newsgroup description
258 If a group_pattern is specified then only newsgroups that match
260 the pattern will have their name and description returned.
261 nntpName xhdr field ?range?
263 Returns the specified header field value for the current message
264 or for a list of messages from the current group. field is the
265 title of a field in the header such as from, subject, date, etc.
266 If range is not specified or is "" then the current message is
267 queried. The command returns a list of elements where each ele‐
268 ment has the form of:
269 msgid value
271 Where msgid is the number of the message and value is the value
273 set for the queried field. The range argument can be in any of
274 the following forms:
275 "" The current message is queried.
277 msgid1-msgid2
279 All messages between msgid1 and msgid2 (including msgid1
280 and msgid2) are queried.
281 msgid1 msgid2
283 All messages between msgid1 and msgid2 (including msgid1
284 and msgid2) are queried.
285 nntpName xover ?range?
287 Returns header information for the current message or for a
288 range of messages from the current group. The information is
289 returned in a tcl list where each element is of the form:
290 msgid subject from date idstring bodysize headersize xref
292 If range is not specified or is "" then the current message is
294 queried. The range argument can be in any of the following
295 forms:
296 "" The current message is queried.
298 msgid1-msgid2
300 All messages between msgid1 and msgid2 (including msgid1
301 and msgid2) are queried.
302 msgid1 msgid2
304 All messages between msgid1 and msgid2 (including msgid1
305 and msgid2) are queried.
306 nntpName xpat field range ?pattern_list?
308 Returns the specified header field value for a specified message
309 or for a list of messages from the current group where the mes‐
310 sages match the pattern(s) given in the pattern_list. field is
311 the title of a field in the header such as from, subject, date,
312 etc. The information is returned in a tcl list where each ele‐
313 ment is of the form:
314 msgid value
316 Where msgid is the number of the message and value is the value
318 set for the queried field. The range argument can be in any of
319 the following forms:
320 msgid The message specified by msgid is queried.
322 msgid1-msgid2
324 All messages between msgid1 and msgid2 (including msgid1
325 and msgid2) are queried.
326 msgid1 msgid2
328 All messages between msgid1 and msgid2 (including msgid1
329 and msgid2) are queried.
330
332 A bigger example for posting a single article.
333 package require nntp
335 set n [nntp::nntp NNTP_SERVER]
336 $n post "From: USER@DOMAIN.EXT (USER_FULL)
337 Path: COMPUTERNAME!USERNAME
338 Newsgroups: alt.test
339 Subject: Tcl test post -ignore
340 Message-ID: <[pid][clock seconds]
341 @COMPUTERNAME>
342 Date: [clock format [clock seconds] -format "%a, %d %
343 b %y %H:%M:%S GMT" -gmt true]
344 Test message body"
346
349 news, nntp, nntpclient, rfc 1036, rfc 977
350nntp 1.5.1 nntp(n)