1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin nntp n 1.5.1] 3[moddesc {Tcl NNTP Client Library}] 4[titledesc {Tcl client for the NNTP protocol}] 5[category Networking] 6[require Tcl 8.2] 7[require nntp [opt 0.2.1]] 8[description] 9 10The package [package nntp] provides a simple Tcl-only client library 11for the NNTP protocol. It works by opening the standard NNTP socket 12on the server, and then providing a Tcl API to access the NNTP 13protocol commands. All server errors are returned as Tcl errors 14(thrown) which must be caught with the Tcl [cmd catch] command. 15 16[section COMMANDS] 17 18[list_begin definitions] 19 20[call [cmd ::nntp::nntp] [opt [arg host]] [opt [arg port]] [opt [arg nntpName]]] 21 22The command opens a socket connection to the specified NNTP server and 23creates a new nntp object with an associated global Tcl command whose 24name is [arg nntpName]. This command may be used to access the various 25NNTP protocol commands for the new connection. The default [arg port] 26number is "119" and the default [arg host] is "news". These defaults 27can be overridden with the environment variables [var NNTPPORT] and 28[var NNTPHOST] respectively. 29 30[para] 31 32Some of the commands supported by this package are not part of the 33nntp rfc 977 ([uri http://www.rfc-editor.org/rfc/rfc977.txt]) and will 34not be available (or implemented) on all nntp servers. 35 36[para] 37 38The access command [arg nntpName] has the following general form: 39 40[list_begin definitions] 41 42[call [arg nntpName] [method method] [opt [arg "arg arg ..."]]] 43 44[arg Option] and the [arg arg]s determine the exact behavior of the 45command. 46 47[list_end] 48 49[call [arg nntpName] [method article] [opt [arg msgid]]] 50 51Query the server for article [arg msgid] from the current group. The article 52is returned as a valid tcl list which contains the headers, followed by 53a blank line, and then followed by the body of the article. Each element 54in the list is one line of the article. 55 56[call [arg nntpName] [method authinfo] [opt [arg user]] [opt [arg pass]]] 57 58Send authentication information (username and password) to the server. 59 60[call [arg nntpName] [method body] [opt [arg msgid]]] 61 62Query the server for the body of the article [arg msgid] from the current 63group. The body of the article is returned as a valid tcl list. Each element 64in the list is one line of the body of the article. 65 66[call [arg nntpName] [method configure]] 67[call [arg nntpName] [method configure] [arg option]] 68[call [arg nntpName] [method configure] [arg option] [arg value] ...] 69[call [arg nntpName] [method cget] [arg option]] 70 71Query and configure options of the nntp connection object. Currently 72only one option is supported, [option -binary]. When set articles are 73retrieved as binary data instead of text. The only methods affected by 74this are [method article] and [method body]. 75 76[para] 77 78One application of this option would be the download of articles 79containing yEnc encoded images. Although encoded the data is still 80mostly binary and retrieving it as text will corrupt the information. 81 82[para] 83 84See package [package yencode] for both encoder and decoder of such data. 85 86 87[call [arg nntpName] [method date]] 88 89Query the server for the servers current date. The date is returned in the 90format [emph YYYYMMDDHHMMSS]. 91 92[call [arg nntpName] [method group] [opt [arg group]]] 93 94Optionally set the current group, and retrieve information about the 95currently selected group. Returns the estimated number of articles in 96the group followed by the number of the first article in the group, followed 97by the last article in the group, followed by the name of the group. 98 99[call [arg nntpName] [method head] [opt [arg msgid]]] 100 101Query the server for the headers of the article [arg msgid] from the current 102group. The headers of the article are returned as a valid tcl list. Each element 103in the list is one line of the headers of the article. 104 105[call [arg nntpName] [method help]] 106 107Retrieves a list of the commands that are supported by the news server that 108is currently attached to. 109 110[call [arg nntpName] [method last]] 111 112Sets the current article pointer to point to the previous message (if there is 113one) and returns the msgid of that message. 114 115[call [arg nntpName] [method list]] 116 117Returns a tcl list of valid newsgroups and associated information. Each 118newsgroup is returned as an element in the tcl list with the following format: 119[example { 120 group last first p 121}] 122where <group> is the name of the newsgroup, <last> is the number of 123the last known article currently in that newsgroup, <first> is the 124number of the first article currently in the newsgroup, and <p> is 125either 'y' or 'n' indicating whether posting to this newsgroup is 126allowed ('y') or prohibited ('n'). 127[para] 128The <first> and <last> fields will always be numeric. They may have 129leading zeros. If the <last> field evaluates to less than the 130<first> field, there are no articles currently on file in the 131newsgroup. 132 133[call [arg nntpName] [method listgroup] [opt [arg group]]] 134 135Query the server for a list of all the messages (message numbers) in the 136group specified by the argument [arg group] or by the current group if 137the [arg group] argument was not passed. 138 139[call [arg nntpName] [method mode_reader]] 140 141Query the server for its nntp 'MODE READER' response string. 142 143[call [arg nntpName] [method newgroups] [arg since]] 144 145Query the server for a list of all the new newsgroups created since the time 146specified by the argument [arg since]. The argument [arg since] can be any 147time string that is understood by [cmd {clock scan}]. The tcl list of newsgroups 148is returned in a similar form to the list of groups returned by the 149[cmd {nntpName list}] command. Each element of the list has the form: 150 151[example { 152 group last first p 153}] 154where <group> is the name of the newsgroup, <last> is the number of 155the last known article currently in that newsgroup, <first> is the 156number of the first article currently in the newsgroup, and <p> is 157either 'y' or 'n' indicating whether posting to this newsgroup is 158allowed ('y') or prohibited ('n'). 159 160[call [arg nntpName] [method newnews]] 161 162Query the server for a list of new articles posted to the current group in the 163last day. 164 165[call [arg nntpName] [method newnews] [arg since]] 166 167Query the server for a list of new articles posted to the current group since 168the time specified by the argument [arg since]. The argument [arg since] can 169be any time string that is understood by [cmd {clock scan}]. 170 171[call [arg nntpName] [method newnews] [arg group] [opt [arg since]]] 172 173Query the server for a list of new articles posted to the group specified by 174the argument [arg group] since the time specified by the argument [arg since] 175(or in the past day if no [arg since] argument is passed. The argument 176[arg since] can be any time string that is understood by [cmd {clock scan}]. 177 178[call [arg nntpName] [method next]] 179 180Sets the current article pointer to point to the next message (if there is 181one) and returns the msgid of that message. 182 183[call [arg nntpName] [method post] [arg article]] 184 185Posts an article of the form specified in 186RFC 1036 ([uri http://www.rfc-editor.org/rfc/rfc1036.txt], successor 187to RFC 850) to the current news group. 188 189[call [arg nntpName] [method slave]] 190 191Identifies a connection as being made from a slave nntp server. This might 192be used to indicate that the connection is serving multiple people and should 193be given priority. Actual use is entirely implementation dependent and may 194vary from server to server. 195 196[call [arg nntpName] [method stat] [opt [arg msgid]]] 197 198The stat command is similar to the article command except that no 199text is returned. When selecting by message number within a group, 200the stat command serves to set the current article pointer without 201sending text. The returned acknowledgment response will contain the 202message-id, which may be of some value. Using the stat command to 203select by message-id is valid but of questionable value, since a 204selection by message-id does NOT alter the "current article pointer" 205 206[call [arg nntpName] [method quit]] 207 208Gracefully close the connection after sending a NNTP QUIT command down 209the socket. 210 211[call [arg nntpName] [method xgtitle] [opt [arg group_pattern]]] 212 213Returns a tcl list where each element is of the form: 214[example { 215newsgroup description 216}] 217If a [arg group_pattern] is specified then only newsgroups that match 218the pattern will have their name and description returned. 219 220[call [arg nntpName] [method xhdr] [arg field] [opt [arg range]]] 221 222Returns the specified header field value for the current message or for a 223list of messages from the current group. [arg field] is the title of a 224field in the header such as from, subject, date, etc. If [arg range] is 225not specified or is "" then the current message is queried. The command 226returns a list of elements where each element has the form of: 227[example { 228 msgid value 229}] 230Where msgid is the number of the message and value is the value set for the 231queried field. The [arg range] argument can be in any of the following forms: 232 233[list_begin definitions] 234 235[def [const {""}]] 236 237The current message is queried. 238 239[def [arg msgid1]-[arg msgid2]] 240 241All messages between [arg msgid1] and [arg msgid2] 242(including [arg msgid1] and [arg msgid2]) are queried. 243 244[def "[arg msgid1] [arg msgid2]"] 245 246All messages between [arg msgid1] and [arg msgid2] 247(including [arg msgid1] and [arg msgid2]) are queried. 248 249[list_end] 250 251 252[call [arg nntpName] [method xover] [opt [arg range]]] 253 254Returns header information for the current message or for a range of messages 255from the current group. The information is returned in a tcl list 256where each element is of the form: 257[example { 258 msgid subject from date idstring bodysize headersize xref 259}] 260If [arg range] is not specified or is "" then the current message is queried. 261The [arg range] argument can be in any of the following forms: 262 263[list_begin definitions] 264 265 266[def [const {""}]] 267 268The current message is queried. 269 270[def [arg msgid1]-[arg msgid2]] 271 272All messages between [arg msgid1] and [arg msgid2] 273(including [arg msgid1] and [arg msgid2]) are queried. 274 275[def "[arg msgid1] [arg msgid2]"] 276 277All messages between [arg msgid1] and [arg msgid2] 278(including [arg msgid1] and [arg msgid2]) are queried. 279 280[list_end] 281 282 283[call [arg nntpName] [method xpat] [arg field] [arg range] [opt [arg pattern_list]]] 284 285Returns the specified header field value for a specified message or for a 286list of messages from the current group where the messages match the 287pattern(s) given in the pattern_list. [arg field] is the title of a 288field in the header such as from, subject, date, etc. The information is 289returned in a tcl list where each element is of the form: 290[example { 291 msgid value 292}] 293Where msgid is the number of the message and value is the value set for the 294queried field. The [arg range] argument can be in any of the following forms: 295 296[list_begin definitions] 297 298[def [arg msgid]] 299 300The message specified by [arg msgid] is queried. 301 302[def [arg msgid1]-[arg msgid2]] 303 304All messages between [arg msgid1] and [arg msgid2] 305(including [arg msgid1] and [arg msgid2]) are queried. 306 307[def "[arg msgid1] [arg msgid2]"] 308 309All messages between [arg msgid1] and [arg msgid2] 310(including [arg msgid1] and [arg msgid2]) are queried. 311 312[list_end] 313[list_end] 314 315[section EXAMPLE] 316 317A bigger example for posting a single article. 318 319[para] 320[example { 321 package require nntp 322 set n [nntp::nntp NNTP_SERVER] 323 $n post "From: USER@DOMAIN.EXT (USER_FULL) 324 Path: COMPUTERNAME!USERNAME 325 Newsgroups: alt.test 326 Subject: Tcl test post -ignore 327 Message-ID: <[pid][clock seconds] 328 @COMPUTERNAME> 329 Date: [clock format [clock seconds] -format "%a, %d % 330 b %y %H:%M:%S GMT" -gmt true] 331 332 Test message body" 333}] 334 335[section {BUGS, IDEAS, FEEDBACK}] 336 337This document, and the package it describes, will undoubtedly contain 338bugs and other problems. 339 340Please report such in the category [emph nntp] of the 341[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 342 343Please also report any ideas for enhancements you may have for either 344package and/or documentation. 345 346 347[keywords news nntp nntpclient {rfc 1036} {rfc 977}] 348[manpage_end] 349