home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _4c1ea67396ec8f4c25ca3ff3c9160db3 < prev    next >
Text File  |  2000-03-23  |  6KB  |  144 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>LWP::Protocol - Base class for LWP protocols</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> LWP::Protocol - Base class for LWP protocols</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="#see also">SEE ALSO</A></LI>
  26.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  27. </UL>
  28. <!-- INDEX END -->
  29.  
  30. <HR>
  31. <P>
  32. <H1><A NAME="name">NAME</A></H1>
  33. <P>LWP::Protocol - Base class for LWP protocols</P>
  34. <P>
  35. <HR>
  36. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  37. <UL>
  38. <LI>Linux</LI>
  39. <LI>Solaris</LI>
  40. <LI>Windows</LI>
  41. </UL>
  42. <HR>
  43. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  44. <PRE>
  45.  package LWP::Protocol::foo;
  46.  require LWP::Protocol;
  47.  @ISA=qw(LWP::Protocol);</PRE>
  48. <P>
  49. <HR>
  50. <H1><A NAME="description">DESCRIPTION</A></H1>
  51. <P>This class is used a the base class for all protocol implementations
  52. supported by the LWP library.</P>
  53. <P>When creating an instance of this class using
  54. <A HREF="#item_create"><CODE>LWP::Protocol::create($url)</CODE></A>, and you get an initialised subclass
  55. appropriate for that access method. In other words, the
  56. LWP::Protocol::create() function calls the constructor for one of its
  57. subclasses.</P>
  58. <P>All derived LWP::Protocol classes need to override the <A HREF="#item_request"><CODE>request()</CODE></A>
  59. method which is used to service a request. The overridden method can
  60. make use of the <A HREF="#item_collect"><CODE>collect()</CODE></A> function to collect together chunks of data
  61. as it is received.</P>
  62. <P>The following methods and functions are provided:</P>
  63. <DL>
  64. <DT><STRONG><A NAME="item_new">$prot = LWP::Protocol-><CODE>new()</CODE></A></STRONG><BR>
  65. <DD>
  66. The LWP::Protocol constructor is inherited by subclasses. As this is a
  67. virtual base class this method should <STRONG>not</STRONG> be called directly.
  68. <P></P>
  69. <DT><STRONG><A NAME="item_create">$prot = LWP::Protocol::create($url)</A></STRONG><BR>
  70. <DD>
  71. Create an object of the class implementing the protocol to handle the
  72. given scheme. This is a function, not a method. It is more an object
  73. factory than a constructor. This is the function user agents should
  74. use to access protocols.
  75. <P></P>
  76. <DT><STRONG><A NAME="item_implementor">$class = LWP::Protocol::implementor($scheme, [$class])</A></STRONG><BR>
  77. <DD>
  78. Get and/or set implementor class for a scheme.  Returns '' if the
  79. specified scheme is not supported.
  80. <P></P>
  81. <DT><STRONG><A NAME="item_request">$prot-><CODE>request(...)</CODE></A></STRONG><BR>
  82. <DD>
  83. <PRE>
  84.  $response = $protocol->request($request, $proxy, undef);
  85.  $response = $protocol->request($request, $proxy, '/tmp/sss');
  86.  $response = $protocol->request($request, $proxy, \&callback, 1024);</PRE>
  87. <P>Dispactches a request over the protocol, and returns a response
  88. object. This method needs to be overridden in subclasses.  Referer to
  89. <A HREF="../../../site/lib/LWP/UserAgent.html">the LWP::UserAgent manpage</A> for description of the arguments.</P>
  90. <DT><STRONG><A NAME="item_timeout">$prot-><CODE>timeout($seconds)</CODE></A></STRONG><BR>
  91. <DD>
  92. Get and set the timeout value in seconds
  93. <P></P>
  94. <DT><STRONG><A NAME="item_parse_head">$prot-><CODE>parse_head($yesno)</CODE></A></STRONG><BR>
  95. <DD>
  96. Should we initialize response headers from the <head> section of HTML
  97. documents.
  98. <P></P>
  99. <DT><STRONG><A NAME="item_collect">$prot->collect($arg, $response, $collector)</A></STRONG><BR>
  100. <DD>
  101. Called to collect the content of a request, and process it
  102. appropriately into a scalar, file, or by calling a callback.  If $arg
  103. is undefined, then the content is stored within the $response.  If
  104. $arg is a simple scalar, then $arg is interpreted as a file name and
  105. the content is written to this file.  If $arg is a reference to a
  106. routine, then content is passed to this routine.
  107. <P>The $collector is a routine that will be called and which is
  108. reponsible for returning pieces (as ref to scalar) of the content to
  109. process.  The $collector signals EOF by returning a reference to an
  110. empty sting.</P>
  111. <P>The return value from <A HREF="#item_collect"><CODE>collect()</CODE></A> is the $response object reference.</P>
  112. <P><STRONG>Note:</STRONG> We will only use the callback or file argument if
  113. $response->is_success().  This avoids sendig content data for
  114. redirects and authentization responses to the callback which would be
  115. confusing.</P>
  116. <P></P>
  117. <DT><STRONG><A NAME="item_collect_once">$prot->collect_once($arg, $response, $content)</A></STRONG><BR>
  118. <DD>
  119. Can be called when the whole response content is available as
  120. $content.  This will invoke <A HREF="#item_collect"><CODE>collect()</CODE></A> with a collector callback that
  121. returns a reference to $content the first time and an empty string the
  122. next.
  123. <P></P></DL>
  124. <P>
  125. <HR>
  126. <H1><A NAME="see also">SEE ALSO</A></H1>
  127. <P>Inspect the <EM>LWP/Protocol/file.pm</EM> and <EM>LWP/Protocol/http.pm</EM> files
  128. for examples of usage.</P>
  129. <P>
  130. <HR>
  131. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  132. <P>Copyright 1995-1997 Gisle Aas.</P>
  133. <P>This library is free software; you can redistribute it and/or
  134. modify it under the same terms as Perl itself.</P>
  135. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  136. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  137. <STRONG><P CLASS=block> LWP::Protocol - Base class for LWP protocols</P></STRONG>
  138. </TD></TR>
  139. </TABLE>
  140.  
  141. </BODY>
  142.  
  143. </HTML>
  144.