home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _e34b1c832120ed490fb07f950c16c86b < prev    next >
Text File  |  2000-03-23  |  19KB  |  414 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Net::NNTP - NNTP Client class</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Net::NNTP - NNTP Client class</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#constructor">CONSTRUCTOR</A></LI>
  26.     <LI><A HREF="#methods">METHODS</A></LI>
  27.     <UL>
  28.  
  29.         <LI><A HREF="#extension methods">Extension methods</A></LI>
  30.     </UL>
  31.  
  32.     <LI><A HREF="#unsupported">UNSUPPORTED</A></LI>
  33.     <LI><A HREF="#definitions">DEFINITIONS</A></LI>
  34.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  35.     <LI><A HREF="#author">AUTHOR</A></LI>
  36.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  37. </UL>
  38. <!-- INDEX END -->
  39.  
  40. <HR>
  41. <P>
  42. <H1><A NAME="name">NAME</A></H1>
  43. <P>Net::NNTP - NNTP Client class</P>
  44. <P>
  45. <HR>
  46. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  47. <UL>
  48. <LI>Linux</LI>
  49. <LI>Solaris</LI>
  50. <LI>Windows</LI>
  51. </UL>
  52. <HR>
  53. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  54. <PRE>
  55.     use Net::NNTP;
  56. </PRE>
  57. <PRE>
  58.  
  59.     $nntp = Net::NNTP->new("some.host.name");
  60.     $nntp->quit;</PRE>
  61. <P>
  62. <HR>
  63. <H1><A NAME="description">DESCRIPTION</A></H1>
  64. <P><CODE>Net::NNTP</CODE> is a class implementing a simple NNTP client in Perl as described
  65. in RFC977. <CODE>Net::NNTP</CODE> inherits its communication methods from <CODE>Net::Cmd</CODE></P>
  66. <P>
  67. <HR>
  68. <H1><A NAME="constructor">CONSTRUCTOR</A></H1>
  69. <DL>
  70. <DT><STRONG><A NAME="item_new">new ( [ HOST ] [, OPTIONS ])</A></STRONG><BR>
  71. <DD>
  72. This is the constructor for a new Net::NNTP object. <CODE>HOST</CODE> is the
  73. name of the remote host to which a NNTP connection is required. If not
  74. given two environment variables are checked, first <CODE>NNTPSERVER</CODE> then
  75. <CODE>NEWSHOST</CODE>, then <CODE>Net::Config</CODE> is checked, and if a host is not found
  76. then <CODE>news</CODE> is used.
  77. <P><CODE>OPTIONS</CODE> are passed in a hash like fashion, using key and value pairs.
  78. Possible options are:</P>
  79. <P><STRONG>Timeout</STRONG> - Maximum time, in seconds, to wait for a response from the
  80. NNTP server, a value of zero will cause all IO operations to block.
  81. (default: 120)</P>
  82. <P><STRONG>Debug</STRONG> - Enable the printing of debugging information to STDERR</P>
  83. <P><STRONG>Reader</STRONG> - If the remote server is INN then initially the connection
  84. will be to nnrpd, by default <CODE>Net::NNTP</CODE> will issue a <CODE>MODE READER</CODE> command
  85. so that the remote server becomes innd. If the <CODE>Reader</CODE> option is given
  86. with a value of zero, then this command will not be sent and the
  87. connection will be left talking to nnrpd.</P>
  88. <P></P></DL>
  89. <P>
  90. <HR>
  91. <H1><A NAME="methods">METHODS</A></H1>
  92. <P>Unless otherwise stated all methods return either a <EM>true</EM> or <EM>false</EM>
  93. value, with <EM>true</EM> meaning that the operation was a success. When a method
  94. states that it returns a value, failure will be returned as <EM>undef</EM> or an
  95. empty list.</P>
  96. <DL>
  97. <DT><STRONG><A NAME="item_article">article ( [ MSGID|MSGNUM ] )</A></STRONG><BR>
  98. <DD>
  99. Retrieve the header, a blank line, then the body (text) of the
  100. specified article.
  101. <P>If no arguments are passed then the current article in the current
  102. newsgroup is returned.</P>
  103. <P><CODE>MSGNUM</CODE> is a numeric id of an article in the
  104. current newsgroup, and will change the current article pointer.
  105. <CODE>MSGID</CODE> is the message id of an article as
  106. shown in that article's header.  It is anticipated that the client
  107. will obtain the <CODE>MSGID</CODE> from a list provided by the <A HREF="#item_newnews"><CODE>newnews</CODE></A>
  108. command, from references contained within another article, or from
  109. the message-id provided in the response to some other commands.</P>
  110. <P>Returns a reference to an array containing the article.</P>
  111. <P></P>
  112. <DT><STRONG><A NAME="item_body">body ( [ MSGID|MSGNUM ] )</A></STRONG><BR>
  113. <DD>
  114. Retrieve the body (text) of the specified article.
  115. <P>Takes the same arguments as <A HREF="#item_article"><CODE>article</CODE></A></P>
  116. <P>Returns a reference to an array containing the body of the article.</P>
  117. <P></P>
  118. <DT><STRONG><A NAME="item_head">head ( [ MSGID|MSGNUM ] )</A></STRONG><BR>
  119. <DD>
  120. Retrieve the header of the specified article.
  121. <P>Takes the same arguments as <A HREF="#item_article"><CODE>article</CODE></A></P>
  122. <P>Returns a reference to an array containing the header of the article.</P>
  123. <P></P>
  124. <DT><STRONG><A NAME="item_nntpstat">nntpstat ( [ MSGID|MSGNUM ] )</A></STRONG><BR>
  125. <DD>
  126. The <A HREF="#item_nntpstat"><CODE>nntpstat</CODE></A> command is similar to the <A HREF="#item_article"><CODE>article</CODE></A> command except that no
  127. text is returned.  When selecting by message number within a group,
  128. the <A HREF="#item_nntpstat"><CODE>nntpstat</CODE></A> command serves to set the ``current article pointer'' without
  129. sending text.
  130. <P>Using the <A HREF="#item_nntpstat"><CODE>nntpstat</CODE></A> command to
  131. select by message-id is valid but of questionable value, since a
  132. selection by message-id does <STRONG>not</STRONG> alter the ``current article pointer''.</P>
  133. <P>Returns the message-id of the ``current article''.</P>
  134. <P></P>
  135. <DT><STRONG><A NAME="item_group">group ( [ GROUP ] )</A></STRONG><BR>
  136. <DD>
  137. Set and/or get the current group. If <CODE>GROUP</CODE> is not given then information
  138. is returned on the current group.
  139. <P>In a scalar context it returns the group name.</P>
  140. <P>In an array context the return value is a list containing, the number
  141. of articles in the group, the number of the first article, the number
  142. of the last article and the group name.</P>
  143. <P></P>
  144. <DT><STRONG><A NAME="item_ihave">ihave ( MSGID [, MESSAGE ])</A></STRONG><BR>
  145. <DD>
  146. The <A HREF="#item_ihave"><CODE>ihave</CODE></A> command informs the server that the client has an article
  147. whose id is <CODE>MSGID</CODE>.  If the server desires a copy of that
  148. article, and <CODE>MESSAGE</CODE> has been given the it will be sent.
  149. <P>Returns <EM>true</EM> if the server desires the article and <CODE>MESSAGE</CODE> was
  150. successfully sent,if specified.</P>
  151. <P>If <CODE>MESSAGE</CODE> is not specified then the message must be sent using the
  152. <CODE>datasend</CODE> and <CODE>dataend</CODE> methods from <A HREF="../../../site/lib/Net/Cmd.html">the Net::Cmd manpage</A></P>
  153. <P><CODE>MESSAGE</CODE> can be either an array of lines or a reference to an array.</P>
  154. <P></P>
  155. <DT><STRONG><A NAME="item_last">last ()</A></STRONG><BR>
  156. <DD>
  157. Set the ``current article pointer'' to the previous article in the current
  158. newsgroup.
  159. <P>Returns the message-id of the article.</P>
  160. <P></P>
  161. <DT><STRONG><A NAME="item_date">date ()</A></STRONG><BR>
  162. <DD>
  163. Returns the date on the remote server. This date will be in a UNIX time
  164. format (seconds since 1970)
  165. <P></P>
  166. <DT><STRONG><A NAME="item_postok">postok ()</A></STRONG><BR>
  167. <DD>
  168. <A HREF="#item_postok"><CODE>postok</CODE></A> will return <EM>true</EM> if the servers initial response indicated
  169. that it will allow posting.
  170. <P></P>
  171. <DT><STRONG><A NAME="item_authinfo">authinfo ( USER, PASS )</A></STRONG><BR>
  172. <DD>
  173. <DT><STRONG><A NAME="item_list">list ()</A></STRONG><BR>
  174. <DD>
  175. Obtain information about all the active newsgroups. The results is a reference
  176. to a hash where the key is a group name and each value is a reference to an
  177. array. The elements in this array are:- the first article number in the group,
  178. the last article number in the group and any information flags about the group.
  179. <P></P>
  180. <DT><STRONG><A NAME="item_newgroups">newgroups ( SINCE [, DISTRIBUTIONS ])</A></STRONG><BR>
  181. <DD>
  182. <CODE>SINCE</CODE> is a time value and <CODE>DISTRIBUTIONS</CODE> is either a distribution
  183. pattern or a reference to a list of distribution patterns.
  184. The result is the same as <A HREF="#item_list"><CODE>list</CODE></A>, but the
  185. groups return will be limited to those created after <CODE>SINCE</CODE> and, if
  186. specified, in one of the distribution areas in <CODE>DISTRIBUTIONS</CODE>.
  187. <P></P>
  188. <DT><STRONG><A NAME="item_newnews">newnews ( SINCE [, GROUPS [, DISTRIBUTIONS ]])</A></STRONG><BR>
  189. <DD>
  190. <CODE>SINCE</CODE> is a time value. <CODE>GROUPS</CODE> is either a group pattern or a reference
  191. to a list of group patterns. <CODE>DISTRIBUTIONS</CODE> is either a distribution
  192. pattern or a reference to a list of distribution patterns.
  193. <P>Returns a reference to a list which contains the message-ids of all news posted
  194. after <CODE>SINCE</CODE>, that are in a groups which matched <CODE>GROUPS</CODE> and a
  195. distribution which matches <CODE>DISTRIBUTIONS</CODE>.</P>
  196. <P></P>
  197. <DT><STRONG><A NAME="item_next">next ()</A></STRONG><BR>
  198. <DD>
  199. Set the ``current article pointer'' to the next article in the current
  200. newsgroup.
  201. <P>Returns the message-id of the article.</P>
  202. <P></P>
  203. <DT><STRONG><A NAME="item_post">post ( [ MESSAGE ] )</A></STRONG><BR>
  204. <DD>
  205. Post a new article to the news server. If <CODE>MESSAGE</CODE> is specified and posting
  206. is allowed then the message will be sent.
  207. <P>If <CODE>MESSAGE</CODE> is not specified then the message must be sent using the
  208. <CODE>datasend</CODE> and <CODE>dataend</CODE> methods from <A HREF="../../../site/lib/Net/Cmd.html">the Net::Cmd manpage</A></P>
  209. <P><CODE>MESSAGE</CODE> can be either an array of lines or a reference to an array.</P>
  210. <P></P>
  211. <DT><STRONG><A NAME="item_slave">slave ()</A></STRONG><BR>
  212. <DD>
  213. Tell the remote server that I am not a user client, but probably another
  214. news server.
  215. <P></P>
  216. <DT><STRONG><A NAME="item_quit">quit ()</A></STRONG><BR>
  217. <DD>
  218. Quit the remote server and close the socket connection.
  219. <P></P></DL>
  220. <P>
  221. <H2><A NAME="extension methods">Extension methods</A></H2>
  222. <P>These methods use commands that are not part of the RFC977 documentation. Some
  223. servers may not support all of them.</P>
  224. <DL>
  225. <DT><STRONG><A NAME="item_newsgroups">newsgroups ( [ PATTERN ] )</A></STRONG><BR>
  226. <DD>
  227. Returns a reference to a hash where the keys are all the group names which
  228. match <A HREF="#item_PATTERN"><CODE>PATTERN</CODE></A>, or all of the groups if no pattern is specified, and
  229. each value contains the description text for the group.
  230. <P></P>
  231. <DT><STRONG><A NAME="item_distributions">distributions ()</A></STRONG><BR>
  232. <DD>
  233. Returns a reference to a hash where the keys are all the possible
  234. distribution names and the values are the distribution descriptions.
  235. <P></P>
  236. <DT><STRONG><A NAME="item_subscriptions">subscriptions ()</A></STRONG><BR>
  237. <DD>
  238. Returns a reference to a list which contains a list of groups which
  239. are recommended for a new user to subscribe to.
  240. <P></P>
  241. <DT><STRONG><A NAME="item_overview_fmt">overview_fmt ()</A></STRONG><BR>
  242. <DD>
  243. Returns a reference to an array which contain the names of the fields returned
  244. by <A HREF="#item_xover"><CODE>xover</CODE></A>.
  245. <P></P>
  246. <DT><STRONG><A NAME="item_active_times">active_times ()</A></STRONG><BR>
  247. <DD>
  248. Returns a reference to a hash where the keys are the group names and each
  249. value is a reference to an array containing the time the groups was created
  250. and an identifier, possibly an Email address, of the creator.
  251. <P></P>
  252. <DT><STRONG><A NAME="item_active">active ( [ PATTERN ] )</A></STRONG><BR>
  253. <DD>
  254. Similar to <A HREF="#item_list"><CODE>list</CODE></A> but only active groups that match the pattern are returned.
  255. <A HREF="#item_PATTERN"><CODE>PATTERN</CODE></A> can be a group pattern.
  256. <P></P>
  257. <DT><STRONG><A NAME="item_xgtitle">xgtitle ( PATTERN )</A></STRONG><BR>
  258. <DD>
  259. Returns a reference to a hash where the keys are all the group names which
  260. match <A HREF="#item_PATTERN"><CODE>PATTERN</CODE></A> and each value is the description text for the group.
  261. <P></P>
  262. <DT><STRONG><A NAME="item_xhdr">xhdr ( HEADER, MESSAGE-SPEC )</A></STRONG><BR>
  263. <DD>
  264. Obtain the header field <CODE>HEADER</CODE> for all the messages specified.
  265. <P>The return value will be a reference
  266. to a hash where the keys are the message numbers and each value contains
  267. the text of the requested header for that message.</P>
  268. <P></P>
  269. <DT><STRONG><A NAME="item_xover">xover ( MESSAGE-SPEC )</A></STRONG><BR>
  270. <DD>
  271. The return value will be a reference
  272. to a hash where the keys are the message numbers and each value contains
  273. a reference to an array which contains the overview fields for that
  274. message.
  275. <P>The names of the fields can be obtained by calling <A HREF="#item_overview_fmt"><CODE>overview_fmt</CODE></A>.</P>
  276. <P></P>
  277. <DT><STRONG><A NAME="item_xpath">xpath ( MESSAGE-ID )</A></STRONG><BR>
  278. <DD>
  279. Returns the path name to the file on the server which contains the specified
  280. message.
  281. <P></P>
  282. <DT><STRONG><A NAME="item_xpat">xpat ( HEADER, PATTERN, MESSAGE-SPEC)</A></STRONG><BR>
  283. <DD>
  284. The result is the same as <A HREF="#item_xhdr"><CODE>xhdr</CODE></A> except the is will be restricted to
  285. headers where the text of the header matches <A HREF="#item_PATTERN"><CODE>PATTERN</CODE></A>
  286. <P></P>
  287. <DT><STRONG><A NAME="item_xrover">xrover</A></STRONG><BR>
  288. <DD>
  289. The XROVER command returns reference information for the <A HREF="#item_article"><CODE>article(s)</CODE></A>
  290. specified.
  291. <P>Returns a reference to a HASH where the keys are the message numbers and the
  292. values are the References: lines from the articles</P>
  293. <P></P>
  294. <DT><STRONG><A NAME="item_listgroup">listgroup ( [ GROUP ] )</A></STRONG><BR>
  295. <DD>
  296. Returns a reference to a list of all the active messages in <CODE>GROUP</CODE>, or
  297. the current group if <CODE>GROUP</CODE> is not specified.
  298. <P></P>
  299. <DT><STRONG><A NAME="item_reader">reader</A></STRONG><BR>
  300. <DD>
  301. Tell the server that you are a reader and not another server.
  302. <P>This is required by some servers. For example if you are connecting to
  303. an INN server and you have transfer permission your connection will
  304. be connected to the transfer daemon, not the NNTP daemon. Issuing
  305. this command will cause the transfer daemon to hand over control
  306. to the NNTP daemon.</P>
  307. <P>Some servers do not understand this command, but issuing it and ignoring
  308. the response is harmless.</P>
  309. <P></P></DL>
  310. <P>
  311. <HR>
  312. <H1><A NAME="unsupported">UNSUPPORTED</A></H1>
  313. <P>The following NNTP command are unsupported by the package, and there are
  314. no plans to do so.</P>
  315. <PRE>
  316.     AUTHINFO GENERIC
  317.     XTHREAD
  318.     XSEARCH
  319.     XINDEX</PRE>
  320. <P>
  321. <HR>
  322. <H1><A NAME="definitions">DEFINITIONS</A></H1>
  323. <DL>
  324. <DT><STRONG><A NAME="item_MESSAGE%2DSPEC">MESSAGE-SPEC</A></STRONG><BR>
  325. <DD>
  326. <A HREF="#item_MESSAGE%2DSPEC"><CODE>MESSAGE-SPEC</CODE></A> is either a single message-id, a single message number, or
  327. a reference to a list of two message numbers.
  328. <P>If <A HREF="#item_MESSAGE%2DSPEC"><CODE>MESSAGE-SPEC</CODE></A> is a reference to a list of two message numbers and the
  329. second number in a range is less than or equal to the first then the range
  330. represents all messages in the group after the first message number.</P>
  331. <P><STRONG>NOTE</STRONG> For compatibility reasons only with earlier versions of Net::NNTP
  332. a message spec can be passed as a list of two numbers, this is depreciated
  333. and a reference to the list should now be passed</P>
  334. <P></P>
  335. <DT><STRONG><A NAME="item_PATTERN">PATTERN</A></STRONG><BR>
  336. <DD>
  337. The <CODE>NNTP</CODE> protocol uses the <CODE>WILDMAT</CODE> format for patterns.
  338. The WILDMAT format was first developed by Rich Salz based on
  339. the format used in the UNIX ``find'' command to articulate
  340. file names. It was developed to provide a uniform mechanism
  341. for matching patterns in the same manner that the UNIX shell
  342. matches filenames.
  343. <P>Patterns are implicitly anchored at the
  344. beginning and end of each string when testing for a match.</P>
  345. <P>There are five pattern matching operations other than a strict
  346. one-to-one match between the pattern and the source to be
  347. checked for a match.</P>
  348. <P>The first is an asterisk <CODE>*</CODE> to match any sequence of zero or more
  349. characters.</P>
  350. <P>The second is a question mark <CODE>?</CODE> to match any single character. The
  351. third specifies a specific set of characters.</P>
  352. <P>The set is specified as a list of characters, or as a range of characters
  353. where the beginning and end of the range are separated by a minus (or dash)
  354. character, or as any combination of lists and ranges. The dash can
  355. also be included in the set as a character it if is the beginning
  356. or end of the set. This set is enclosed in square brackets. The
  357. close square bracket <CODE>]</CODE> may be used in a set if it is the first
  358. character in the set.</P>
  359. <P>The fourth operation is the same as the
  360. logical not of the third operation and is specified the same
  361. way as the third with the addition of a caret character <CODE>^</CODE> at
  362. the beginning of the test string just inside the open square
  363. bracket.</P>
  364. <P>The final operation uses the backslash character to
  365. invalidate the special meaning of the a open square bracket <CODE>[</CODE>,
  366. the asterisk, backslash or the question mark. Two backslashes in
  367. sequence will result in the evaluation of the backslash as a
  368. character with no special meaning.</P>
  369. <DL>
  370. <DT><STRONG><A NAME="item_Examples">Examples</A></STRONG><BR>
  371. <DD>
  372. <DT><STRONG><A NAME="item_%5B%5E%5D%2D%5D"><CODE>[^]-]</CODE></A></STRONG><BR>
  373. <DD>
  374. matches any single character other than a close square
  375. bracket or a minus sign/dash.
  376. <P></P>
  377. <LI>
  378. matches any string that ends with the string ``bdc''
  379. including the string ``bdc'' (without quotes).
  380. <P></P>
  381. <DT><STRONG><A NAME="item_%5B0%2D9a%2DzA%2DZ%5D"><CODE>[0-9a-zA-Z]</CODE></A></STRONG><BR>
  382. <DD>
  383. matches any single printable alphanumeric ASCII character.
  384. <P></P>
  385. <DT><STRONG><A NAME="item_a%3F%3Fd"><CODE>a??d</CODE></A></STRONG><BR>
  386. <DD>
  387. matches any four character string which begins
  388. with a and ends with d.
  389. <P></P></DL>
  390. </DL>
  391. <P>
  392. <HR>
  393. <H1><A NAME="see also">SEE ALSO</A></H1>
  394. <P><A HREF="../../../site/lib/Net/Cmd.html">the Net::Cmd manpage</A></P>
  395. <P>
  396. <HR>
  397. <H1><A NAME="author">AUTHOR</A></H1>
  398. <P>Graham Barr <<A HREF="mailto:gbarr@pobox.com">gbarr@pobox.com</A>></P>
  399. <P>
  400. <HR>
  401. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  402. <P>Copyright (c) 1995-1997 Graham Barr. All rights reserved.
  403. This program is free software; you can redistribute it and/or modify
  404. it under the same terms as Perl itself.</P>
  405. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  406. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  407. <STRONG><P CLASS=block> Net::NNTP - NNTP Client class</P></STRONG>
  408. </TD></TR>
  409. </TABLE>
  410.  
  411. </BODY>
  412.  
  413. </HTML>
  414.