home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _daa6079b63a23f82396c6639e9080228 < prev    next >
Text File  |  2000-03-23  |  8KB  |  193 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>HTTP::Response - Class encapsulating HTTP Responses</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> HTTP::Response - Class encapsulating HTTP Responses</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="#copyright">COPYRIGHT</A></LI>
  26. </UL>
  27. <!-- INDEX END -->
  28.  
  29. <HR>
  30. <P>
  31. <H1><A NAME="name">NAME</A></H1>
  32. <P>HTTP::Response - Class encapsulating HTTP Responses</P>
  33. <P>
  34. <HR>
  35. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  36. <UL>
  37. <LI>Linux</LI>
  38. <LI>Solaris</LI>
  39. <LI>Windows</LI>
  40. </UL>
  41. <HR>
  42. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  43. <PRE>
  44.  require HTTP::Response;</PRE>
  45. <P>
  46. <HR>
  47. <H1><A NAME="description">DESCRIPTION</A></H1>
  48. <P>The <CODE>HTTP::Response</CODE> class encapsulates HTTP style responses.  A
  49. response consists of a response line, some headers, and (potentially
  50. empty) content. Note that the LWP library also uses HTTP style
  51. responses for non-HTTP protocol schemes.</P>
  52. <P>Instances of this class are usually created and returned by the
  53. <A HREF="#item_request"><CODE>request()</CODE></A> method of an <CODE>LWP::UserAgent</CODE> object:</P>
  54. <PRE>
  55.  #...
  56.  $response = $ua->request($request)
  57.  if ($response->is_success) {
  58.      print $response->content;
  59.  } else {
  60.      print $response->error_as_HTML;
  61.  }</PRE>
  62. <P><CODE>HTTP::Response</CODE> is a subclass of <CODE>HTTP::Message</CODE> and therefore
  63. inherits its methods.  The inherited methods most often used are header(),
  64. push_header(), remove_header(), headers_as_string(), and content().
  65. The header convenience methods are also available.  See
  66. <A HREF="../../../site/lib/HTTP/Message.html">the HTTP::Message manpage</A> for details.</P>
  67. <P>The following additional methods are available:</P>
  68. <DL>
  69. <DT><STRONG><A NAME="item_new">$r = HTTP::Response->new($rc, [$msg, [$header, [$content]]])</A></STRONG><BR>
  70. <DD>
  71. Constructs a new <CODE>HTTP::Response</CODE> object describing a response with
  72. response code <CODE>$rc</CODE> and optional message <CODE>$msg</CODE>.  The message is a
  73. short human readable single line string that explains the response
  74. code.
  75. <P></P>
  76. <DT><STRONG><A NAME="item_code">$r-><CODE>code([$code])</CODE></A></STRONG><BR>
  77. <DD>
  78. <DT><STRONG><A NAME="item_message">$r-><CODE>message([$message])</CODE></A></STRONG><BR>
  79. <DD>
  80. <DT><STRONG><A NAME="item_request">$r-><CODE>request([$request])</CODE></A></STRONG><BR>
  81. <DD>
  82. <DT><STRONG><A NAME="item_previous">$r-><CODE>previous([$previousResponse])</CODE></A></STRONG><BR>
  83. <DD>
  84. These methods provide public access to the object attributes.  The
  85. first two contain respectively the response code and the message
  86. of the response.
  87. <P>The request attribute is a reference the request that caused this
  88. response.  It does not have to be the same request as passed to the
  89. $ua-><A HREF="#item_request"><CODE>request()</CODE></A> method, because there might have been redirects and
  90. authorization retries in between.</P>
  91. <P>The previous attribute is used to link together chains of responses.
  92. You get chains of responses if the first response is redirect or
  93. unauthorized.</P>
  94. <P></P>
  95. <DT><STRONG><A NAME="item_status_line">$r->status_line</A></STRONG><BR>
  96. <DD>
  97. Returns the string ``<code> <message>''.  If the message attribute
  98. is not set then the official name of <code> (see <A HREF="../../../site/lib/HTTP/Status.html">the HTTP::Status manpage</A>)
  99. is substituted.
  100. <P></P>
  101. <DT><STRONG><A NAME="item_base">$r->base</A></STRONG><BR>
  102. <DD>
  103. Returns the base URL for this response.  The return value will be a
  104. reference to a URI object.
  105. <P>The base URL is obtained from one the following sources (in priority
  106. order):</P>
  107. <OL>
  108. <LI>
  109. Embedded in the document content, for instance <BASE HREF=``...''>
  110. in HTML documents.
  111. <P></P>
  112. <LI>
  113. A ``Content-Base:'' or a ``Content-Location:'' header in the response.
  114. <P>For backwards compatability with older HTTP implementations we will
  115. also look for the ``Base:'' header.</P>
  116. <P></P>
  117. <LI>
  118. The URL used to request this response. This might not be the original
  119. URL that was passed to $ua-><A HREF="#item_request"><CODE>request()</CODE></A> method, because we might have
  120. received some redirect responses first.
  121. <P></P></OL>
  122. <P>When the LWP protocol modules produce the HTTP::Response object, then
  123. any base URL embedded in the document (step 1) will already have
  124. initialized the ``Content-Base:'' header. This means that this method
  125. only performs the last 2 steps (the content is not always available
  126. either).</P>
  127. <DT><STRONG><A NAME="item_as_string">$r->as_string</A></STRONG><BR>
  128. <DD>
  129. Returns a textual representation of the response.  Mainly
  130. useful for debugging purposes. It takes no arguments.
  131. <P></P>
  132. <DT><STRONG><A NAME="item_is_info">$r->is_info</A></STRONG><BR>
  133. <DD>
  134. <DT><STRONG><A NAME="item_is_success">$r->is_success</A></STRONG><BR>
  135. <DD>
  136. <DT><STRONG><A NAME="item_is_redirect">$r->is_redirect</A></STRONG><BR>
  137. <DD>
  138. <DT><STRONG><A NAME="item_is_error">$r->is_error</A></STRONG><BR>
  139. <DD>
  140. These methods indicate if the response was informational, sucessful, a
  141. redirection, or an error.
  142. <P></P>
  143. <DT><STRONG><A NAME="item_error_as_HTML">$r-><CODE>error_as_HTML()</CODE></A></STRONG><BR>
  144. <DD>
  145. Returns a string containing a complete HTML document indicating what
  146. error occurred.  This method should only be called when $r->is_error
  147. is TRUE.
  148. <P></P>
  149. <DT><STRONG><A NAME="item_current_age">$r->current_age</A></STRONG><BR>
  150. <DD>
  151. Calculates the ``current age'' of the response as
  152. specified by <draft-ietf-http-v11-spec-07> section 13.2.3.  The
  153. age of a response is the time since it was sent by the origin server.
  154. The returned value is a number representing the age in seconds.
  155. <P></P>
  156. <DT><STRONG><A NAME="item_freshness_lifetime">$r->freshness_lifetime</A></STRONG><BR>
  157. <DD>
  158. Calculates the ``freshness lifetime'' of the response
  159. as specified by <draft-ietf-http-v11-spec-07> section 13.2.4.  The
  160. ``freshness lifetime'' is the length of time between the generation of a
  161. response and its expiration time.  The returned value is a number
  162. representing the freshness lifetime in seconds.
  163. <P>If the response does not contain an ``Expires'' or a ``Cache-Control''
  164. header, then this function will apply some simple heuristic based on
  165. 'Last-Modified' to determine a suitable lifetime.</P>
  166. <P></P>
  167. <DT><STRONG><A NAME="item_is_fresh">$r->is_fresh</A></STRONG><BR>
  168. <DD>
  169. Returns TRUE if the response is fresh, based on the values of
  170. <A HREF="#item_freshness_lifetime"><CODE>freshness_lifetime()</CODE></A> and current_age().  If the response is no longer
  171. fresh, then it has to be refetched or revalidated by the origin
  172. server.
  173. <P></P>
  174. <DT><STRONG><A NAME="item_fresh_until">$r->fresh_until</A></STRONG><BR>
  175. <DD>
  176. Returns the time when this entiy is no longer fresh.
  177. <P></P></DL>
  178. <P>
  179. <HR>
  180. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  181. <P>Copyright 1995-1997 Gisle Aas.</P>
  182. <P>This library is free software; you can redistribute it and/or
  183. modify it under the same terms as Perl itself.</P>
  184. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  185. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  186. <STRONG><P CLASS=block> HTTP::Response - Class encapsulating HTTP Responses</P></STRONG>
  187. </TD></TR>
  188. </TABLE>
  189.  
  190. </BODY>
  191.  
  192. </HTML>
  193.