gears/sdk/api_httprequest.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
   2
   3 <!--
   4 Copyright 2007, Google Inc.
   5
   6 Redistribution and use in source and binary forms, with or without
   7 modification, are permitted provided that the following conditions are met:
   8
   9  1. Redistributions of source code must retain the above copyright notice,
  10     this list of conditions and the following disclaimer.
  11  2. Redistributions in binary form must reproduce the above copyright notice,
  12     this list of conditions and the following disclaimer in the documentation
  13     and/or other materials provided with the distribution.
  14  3. Neither the name of Google Inc. nor the names of its contributors may be
  15     used to endorse or promote products derived from this software without
  16     specific prior written permission.
  17
  18 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
  19 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  20 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
  21 EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  23 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  24 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  25 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  26 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  27 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 -->
  29
  30 <html>
  31   <head>
  32     <title>HttpRequest Module API</title>
  33     <link rel="stylesheet" type="text/css" href="gears.css" />
  34   </head>
  35
  36 <body>
  37
  38 <h1>HttpRequest Module API</h1>
  39
  40 <div id="pagecontent">
  41
  42 <p>The HttpRequest module implements a subset of the
  43    <a href="http://www.w3.org/TR/XMLHttpRequest/">W3C XmlHttpRequest
  44    specification</a>, and makes it available in both workers and the
  45    main HTML page.</p>
  46
  47 <h3>Contents</h3>
  48 <ol class="toc">
  49   <li><a href="#overview">Overview</a></li>
  50   <li><a href="#example">Example</a></li>
  51   <li><a href="#HttpRequest">HttpRequest class</a></li>
  52 </ol>
  53
  54 <a name="overview"></a><h2>Overview</h2>
  55   <p>Since the browser's XmlHttpRequest object is not available in the context of
  56      a worker, Gears provides its own HttpRequest object to fill that need. Gears HttpRequest
  57      provides most of the features of XmlHttpRequest except for the ability to access the response
  58      as an XML DOM object and the ability to send a request synchronously.
  59   </p>
  60
  61 <a name="example"></a><h2>Example</h2>
  62
  63 <pre><code>&lt;script type="text/javascript" src="<a href='tools.html#gears_init'>gears_init.js</a>"&gt;&lt;/script&gt;
  64 &lt;script type="text/javascript"&gt;
  65 var request = google.gears.factory.create('beta.httprequest');
  66 request.open('GET', '/index.html');
  67 request.onreadystatechange = function() {
  68   if (request.readyState == 4) {
  69     console.write(request.responseText);
  70   }
  71 };
  72 request.send();
  73 &lt;/script&gt;</code></pre>
  74
  75 <!-- ########## Class Reference ########## -->
  76
  77 <br>
  78 <a name="HttpRequest"></a>
  79 <h2>HttpRequest class</h2>
  80
  81 <pre><code>void     <b>open</b>(method, url)
  82 void     <b>setRequestHeader</b>(name, value)
  83 void     <b>send</b>([postData])
  84 void     <b>abort</b>()
  85 string   <b>getResponseHeader</b>(name)
  86 string   <b>getAllResponseHeaders</b>()
  87 callback <b>onreadystatechange</b>
  88 readonly attribute int <b>readyState</b>
  89 readonly attribute string <b>responseText</b>
  90 readonly attribute int    <b>status</b>
  91 readonly attribute string <b>statusText</b> </code></pre>
  92
  93 <!-- ########## Methods ########## -->
  94 <h3>Methods</h3>
  95 <table>
  96   <tr class="odd">
  97     <th colspan="2"><div align="left"><code>abort()</code></div></th>
  98     </tr>
  99   <tr class="odd">
 100     <td width="113">Return value: </td>
 101     <td width="489" ><code>void</code></td>
 102     </tr>
 103   <tr class="odd">
 104     <td>Description:</td>
 105     <td class="odd">
 106         Cancels the request.
 107     </td>
 108   </tr>
 109 </table>
 110 <table>
 111   <tr class="odd">
 112     <th colspan="2"><div align="left"><code>getAllResponseHeaders()</code></div></th>
 113     </tr>
 114   <tr class="odd">
 115     <td width="113">Return value: </td>
 116     <td width="489"><code>string</code></td>
 117     </tr>
 118   <tr class="odd">
 119     <td>Description:</td>
 120     <td class="odd">
 121         Returns a string containing the entire set of HTTP headers in the server response.
 122     </td>
 123   </tr>
 124 </table>
 125 <table>
 126   <tr class="odd">
 127     <th colspan="2"><div align="left"><code>getResponseHeader(headerName)</code></div></th>
 128     </tr>
 129   <tr class="odd">
 130     <td width="113">Return value: </td>
 131     <td width="489"><code>string</code></td>
 132     </tr>
 133   <tr class="odd">
 134       <td>Parameters:</td>
 135       <td class="odd">
 136           <code>headerName</code>
 137       </td>
 138     </tr>
 139   <tr class="odd">
 140     <td>Description:</td>
 141     <td class="odd">
 142         Returns the value of a specific HTTP header in the server response.
 143     </td>
 144   </tr>
 145 </table>
 146 <table>
 147   <tr class="odd">
 148     <th colspan="2"><div align="left"><code>open(method, url)</code></div></th>
 149     </tr>
 150   <tr class="odd">
 151     <td width="113">Return value: </td>
 152     <td width="489"><code>void</code></td>
 153     </tr>
 154   <tr class="odd">
 155     <td>Parameters:</td>
 156     <td class="odd">
 157         <code>method</code><br/>
 158         <code>url</code>
 159     </td>
 160   </tr>
 161   <tr class="odd">
 162     <td>Description:</td>
 163     <td class="odd">
 164         Specifies the method and URL of a request.
 165         <p>The method parameter can have a value of "GET", "POST", "HEAD" or another HTTP method listed in the W3C specification.</p>
 166         <p>The URL parameter may be either a relative or complete URL and must be from the same origin as the current context.</p>
 167     </td>
 168   </tr>
 169 </table>
 170 <table>
 171   <tr class="odd">
 172     <th colspan="2"><div align="left"><code>send([postData])</code></div></th>
 173     </tr>
 174   <tr class="odd">
 175     <td width="113">Return value: </td>
 176     <td width="489"><code>void</code></td>
 177     </tr>
 178   <tr class="odd">
 179     <td>Parameters:</td>
 180     <td class="odd">
 181         <code>postData</code> - an optional string to be sent as the body of a POST or PUT request.<br/>
 182     </td>
 183   </tr>
 184   <tr class="odd">
 185     <td>Description:</td>
 186     <td class="odd">
 187         Sends the request.
 188     </td>
 189   </tr>
 190 </table>
 191 <table>
 192   <tr class="odd">
 193     <th colspan="2"><div align="left"><code>setRequestHeader(name, value)</code></div></th>
 194     </tr>
 195   <tr class="odd">
 196     <td width="113">Return value: </td>
 197     <td width="489"><code>void</code></td>
 198     </tr>
 199   <tr class="odd">
 200     <td>Parameters:</td>
 201     <td class="odd">
 202         <code>name</code> - the HTTP header to set<br/>
 203         <code>value</code> - the value of the header<br/>
 204     </td>
 205   </tr>
 206   <tr class="odd">
 207     <td>Description:</td>
 208     <td class="odd">
 209         Adds the header to the set of HTTP headers to be sent.
 210     </td>
 211   </tr>
 212 </table>
 213
 214 <!-- ########## Events ########## -->
 215 <h3>Event Handler</h3>
 216 <table>
 217   <tr class="odd">
 218     <th colspan="2"><div align="left"><code>callback onreadystatechange()</code></div></th>
 219     </tr>
 220   <tr class="odd">
 221     <td width="113">Description: </td>
 222     <td width="489">An event handler that fires at every state change and repeatedly as new responseText data becomes available while the request is in the Interactive state.</td>
 223     </tr>
 224 </table>
 225
 226 <!-- ########## Attributes ########## -->
 227 <h3>Attributes</h3>
 228   <table>
 229     <tr class="odd">
 230       <th width="158">Attribute</th>
 231       <th >Type</th>
 232       <th >Description</th>
 233     </tr>
 234     <tr class="odd">
 235       <td width="158"><strong>readyState</strong></td>
 236         <td width="109" >readonly int</td>
 237         <td width="432" > Returns the state of the object:
 238                 <table class="noborders">
 239                   <tr>
 240                     <td><strong>0</strong></td>
 241                     <td>Uninitialized</td>
 242             </tr>
 243             <tr>
 244               <td><strong>1</strong></td>
 245               <td>Open</td>
 246             </tr>
 247             <tr>
 248               <td><strong>2</strong></td>
 249               <td>Sent</td>
 250             </tr>
 251             <tr>
 252               <td><strong>3</strong></td>
 253               <td>Interactive</td>
 254             </tr>
 255             <tr>
 256               <td><strong>4</strong></td>
 257               <td>Complete</td>
 258           </table>
 259         </td>
 260     </tr>
 261     <tr class="odd">
 262       <td><strong>responseText</strong></td>
 263         <td class="" >readonly string </td>
 264         <td class="" >Returns the response body as a string. This property can be read when the request is in the Interactive or Complete state.</td>
 265     </tr>
 266     <tr class="odd">
 267       <td><strong>status</strong></td>
 268         <td class="odd">readonly int</td>
 269         <td class="odd">Returns the status as a number (e.g. 404 for "Not Found" or 200 for "OK"). This property can be read when the request is in the Interactive or Complete state.</td>
 270     </tr>
 271     <tr class="odd">
 272       <td><strong>statusText</strong></td>
 273         <td class="odd">readonly string </td>
 274         <td class="odd">Returns the status as a string (e.g. "Not Found" or "OK"). This property can be read when the request is in the Interactive or Complete state.</td>
 275     </tr>
 276   </table>
 277
 278 </div>
 279 </body>
 280 </html>