gears/sdk/api_localserver.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>LocalServer API</title>
  33     <link rel="stylesheet" type="text/css" href="gears.css" />
  34   </head>
  35
  36 <body>
  37
  38 <h1>LocalServer API</h1>
  39
  40 <div id="pagecontent">
  41
  42 <p>The LocalServer module allows a web application to cache and serve its HTTP
  43 resources locally, without a network connection.</p>
  44 <h3>Contents</h3>
  45 <ol class="toc">
  46   <li><a href="#overview">Overview</a></li>
  47   <li><a href="#example">Example</a>
  48   <li><a href="#classes">Classes
  49     </a>
  50     <ol>
  51       <li><a href="#LocalServer" >LocalServer</a></li>
  52       <li><a href="#ManagedResourceStore">ManagedResourceStore</a></li>
  53       <li><a href="#ResourceStore">ResourceStore</a></li>
  54       <li><a href="#FileSubmitter">FileSubmitter</a></li>
  55     </ol>
  56   </li>
  57   <li><a href="#manifest_file">Manifest file</a></li>
  58   <li><a href="#required_cookie">Cookies and the LocalServer</a></li>
  59   <li><a href="#filesystem_location">Location of cached files</a></li>
  60 </ol>
  61
  62
  63 <h2 id="overview">Overview</h2>
  64   <p>The LocalServer module is a specialized URL cache that the web application controls.
  65   Requests for URLs in the LocalServer's cache are intercepted and served
  66   locally from the user's disk.</p>
  67   <h4>Resource stores </h4>
  68   <p>A <em>resource store</em> is a container of URLs. Using the LocalServer module,
  69   applications can create any number of resource stores, and a resource store can contain any number of URLs.</p>
  70   <p>There are two types of resource stores:</p>
  71   <ul>
  72     <li><a href="#ResourceStore">ResourceStore</a> - for capturing ad-hoc URLs using JavaScript.
  73         The ResourceStore allows an application to capture user data files that need to be addressed with a URL,
  74         such as a PDF file or an image.</li>
  75     <li><a href="#ManagedResourceStore">ManagedResourceStore</a> - for capturing a related set of URLs that are
  76         declared in a <em>manifest file</em>, and are updated automatically.
  77         The ManagedResourceStore allows the set of resources needed to run a web application to be captured.</li>
  78   </ul>
  79   <p>For both types of stores, the set of URLs captured is explicitly controlled by the web application.</p>
  80
  81   <h4>Updating of cached resources</h4>
  82   <p>A key difference between the two types of stores is how resources are updated. The contents of a ManagedResourceStore are automatically
  83   updated whenever the version string in the store's manifest file changes. The ResourceStore's contents are never automatically
  84   updated, and are only updated explicitly by the application.</p>
  85   <p>Google Gears automatically updates ManagedResourceStores according to these rules:</p>
  86   <ul>
  87     <li><code>checkForUpdate()</code> is called each time  a resource contained in a ManagedResourceStore is requested and served locally, but no more often than once every 10 seconds.</li>
  88     <li>If the manifest file's <code>version</code> value has changed, the automatic update process runs. For further details, see <a href="#checkforupdate">checkForUpdate</a>. </li>
  89   </ul>
  90
  91   <h4>Local serving of cached resources</h4>
  92   <p>The LocalServer intercepts HTTP/HTTPS requests and serves them from the cache when all of these conditions are met:</p>
  93   <ul>
  94     <li>The URL is cached in a ResourceStore or ManagedResourceStore,</li>
  95     <li>The resource store's <code>enabled</code> attribute is set to true, and </li>
  96     <li>If the resource store has a  <code>requiredCookie</code> attribute,
  97         the request must have a cookie that matches. For further details read <a href="#required_cookie">Cookies and the LocalServer</a>.</li>
  98   </ul>
  99   <p>The LocalServer <em>always</em> serves a cached resource when the conditions are met, regardless of the network connection. The URLs contained in a store
 100   are eligible for local serving without requiring the application to open the  store.</p>
 101   <p>To disable local serving of stored resources and force URLs to be served using the regular network connection, the application can set
 102   the store's <code>enabled</code> attribute to false.</p>
 103   <p>&nbsp;</p>
 104
 105
 106
 107 <h2 id="example">Example</h2>
 108
 109 <pre><code>&lt;script type="text/javascript" src="<a href='tools.html#gears_init'>gears_init.js</a>"&gt;&lt;/script&gt;
 110 &lt;script type="text/javascript"&gt;
 111 var filesToCapture = [
 112   location.pathname,
 113   'gears_init.js'
 114 ];
 115 var localServer = google.gears.factory.create('beta.localserver');
 116 var store = localServer.createStore('test-store');
 117 function captureCallback(url, success, captureId) {
 118   alert(url + 'captured: ' + success ? 'success' : 'failure');
 119 }
 120 &lt;/script&gt;</code></pre>
 121
 122
 123 <h3 id="classes">Classes</h3>
 124   <pre><code><a href="#LocalServer" class="section">LocalServer class</a>
 125    boolean              <b>canServeLocally</b>(string url)
 126    ResourceStore        <b>createStore</b>(string name, [string requiredCookie])
 127    ResourceStore        <b>openStore</b>(string name, [string requiredCookie])
 128    void                 <b>removeStore</b>(string name, [string requiredCookie])
 129    ManagedResourceStore <b>createManagedStore</b>(string name, [string requiredCookie])
 130    ManagedResourceStore <b>openManagedStore</b>(string name, [string requiredCookie])
 131    void                 <b>removeManagedStore</b>(string name, [string requiredCookie])</code></pre>
 132
 133
 134   <pre><code><a href="#ManagedResourceStore">ManagedResourceStore class</a>
 135    readonly  attribute string  <b>name</b>
 136    readonly  attribute string  <b>requiredCookie</b>
 137    readwrite attribute boolean <b>enabled</b>
 138    readwrite attribute string  <b>manifestUrl</b>
 139    readonly  attribute int     <b>lastUpdateCheckTime</b>
 140    readonly  attribute int     <b>updateStatus</b>
 141    readonly  attribute string  <b>lastErrorMessage</b>
 142    readonly  attribute string  <b>currentVersion</b>
 143    event void <b>oncomplete</b>(Object details)
 144    event void <b>onerror</b>(Error error)
 145    event void <b>onprogress</b>(Object details)
 146    void <b>checkForUpdate</b>()</code></pre>
 147
 148   <pre><code><a href="#ResourceStore">ResourceStore class</a>
 149    readonly  attribute string  <b>name</b>
 150    readonly  attribute string  <b>requiredCookie</b>
 151    readwrite attribute boolean <b>enabled</b>
 152    int           <b>capture</b>(string urlOrUrlArray, completionCallback)
 153    void          <b>abortCapture</b>(int captureId)
 154    void          <b>remove</b>(string url)
 155    void          <b>rename</b>(string srcUrl, string destUrl)
 156    void          <b>copy</b>(string srcUrl, string destUrl)
 157    boolean       <b>isCaptured</b>(string url)
 158    void          <b>captureFile</b>(fileInputElement, url)
 159    string        <b>getCapturedFileName</b>(url)
 160    string        <b>getHeader</b>(string url, string name)
 161    string        <b>getAllHeaders</b>(string url)
 162    FileSubmitter <b>createFileSubmitter</b>()</code></pre>
 163
 164   <pre><code><a href="api_localserver.html#FileSubmitter">FileSubmitter class</a>
 165    void      <b>setFileInputElement</b>(htmlElement el, string url)</code></pre>
 166
 167   <p>
 168     <!------------------------------------------------------------->
 169     <!-- LocalServer                                             -->
 170     <!------------------------------------------------------------->
 171
 172     <br>
 173     <a name="LocalServer"></a>  </p>
 174   <h2>LocalServer class</h2>
 175
 176
 177   <p>The LocalServer is a factory and container for the set of
 178     ResourceStores and ManagedResourceStores your application creates and uses. Use resource stores to enable your JavaScript application to execute without a network connection. </p>
 179
 180   <p>To create a LocalServer object, use the Gears Factory as follows:</p>
 181
 182   <pre><code>&lt;script type="text/javascript" src="<a href='tools.html#gears_init'>gears_init.js</a>"&gt;&lt;/script&gt;
 183 &lt;script type="text/javascript"&gt;
 184 var localServer = google.gears.factory.create('beta.localserver');
 185 &lt;/script&gt;</code></pre>
 186
 187   <h4>Methods</h4>
 188   <table width="696">
 189     <tr class="odd">
 190       <th colspan="2"><div align="left"><code><strong>canServeLocally(string url)</strong></code></div></th>
 191     </tr>
 192     <tr class="odd">
 193       <td width="105">Return Value </td>
 194         <td width="579" >boolean</td>
 195     </tr>
 196     <tr class="odd">
 197       <td>Parameters</td>
 198         <td class="odd"><strong><code>url</code></strong> - relative or absolute URL that is from the same origin as the current page </td>
 199     </tr>
 200     <tr class="odd">
 201       <td>Exceptions</td>
 202         <td class="" >Throws an exception if the URL is not from the same origin
 203           as the current page.          </td>
 204     </tr>
 205     <tr class="odd">
 206       <td>Description</td>
 207         <td class="odd">
 208           Returns true if a request for the URL can be satisfied from any of the resource stores available,
 209           taking into account whether the containing store is enabled and if its requiredCookie matches.
 210         Relative URLs are interpreted according to the current page location.</td>
 211     </tr>
 212   </table>
 213   <table width="699">
 214     <tr class="odd">
 215       <th colspan="2"><div align="left"><code><strong>createStore(string name, [string requiredCookie])</strong></code></div></th>
 216     </tr>
 217     <tr class="odd">
 218       <td width="108">Return Value </td>
 219         <td width="579"><code>ResourceStore </code></td>
 220     </tr>
 221     <tr class="odd">
 222       <td>Parameters</td>
 223         <td><code>name</code>
 224                 - string identifying the store. <br />
 225             <code>requiredCookie</code> - optional.<br />
 226             The combination of name and requiredCookie (along with the domain) identify a unique store. <br />
 227           Expected cookie format is &quot;name=value&quot;. </td>
 228     </tr>
 229     <tr class="odd">
 230       <td>Exceptions</td>
 231         <td class="" >Throws a JavaScript exception if an errors occurs.</td>
 232     </tr>
 233     <tr class="odd">
 234       <td>Description</td>
 235         <td class="odd">Opens an existing ResourceStore or creates a new one if
 236       no such store exists.<br />
 237       <br />
 238       If a requiredCookie is given, creates a ResourceStore that requires the cookie to be present in the client in order to serve the contents from the store.
 239     </tr>
 240   </table>
 241   <table width="695">
 242     <tr class="odd">
 243       <th colspan="2"><div align="left"><code><strong>openStore(string name, [string requiredCookie])</strong></code></div></th>
 244     </tr>
 245     <tr class="odd">
 246       <td width="137">Return Value </td>
 247         <td width="546"><code>ResourceStore </code><br />
 248       <code>null</code> - if no such store exists</td>
 249     </tr>
 250     <tr class="odd">
 251       <td>Parameters</td>
 252         <td><code>name</code> - string identifying the store. <br />
 253   <code>requiredCookie</code> - optional.<br />
 254 The combination of name and requiredCookie (along with the domain) identify a unique store. <br />
 255 Expected cookie format is &quot;name=value&quot;.</td>
 256     </tr>
 257     <tr class="odd">
 258       <td>Exceptions</td>
 259         <td class="" > Throws a JavaScript exception if an errors occurs. </td>
 260     </tr>
 261     <tr class="odd">
 262       <td>Description</td>
 263       <td class="odd">Opens an existing ResourceStore or returns null if no such store exists. If the store was originally created with a requiredCookie, the same value must be provided in order to open this ResourceStore.
 264     </tr>
 265   </table>
 266   <table>
 267     <tr class="odd">
 268       <th colspan="2" width="100%"><div align="left"><code><strong> removeStore(string name, [string requiredCookie])</strong></code></div></th>
 269     </tr>
 270     <tr class="odd">
 271       <td width="113">Return Value </td>
 272         <td width="489" >void</td>
 273     </tr>
 274     <tr class="odd">
 275       <td>Parameters</td>
 276         <td><code>name</code> - string identifying the store. <br>
 277           <code>requiredCookie</code> - optional.<br />
 278           The combination of name and requiredCookie (along with the domain) identify a unique store. <br />
 279       Expected cookie format is &quot;name=value&quot;.</td>
 280     </tr>
 281     <tr class="odd">
 282       <td>Exceptions</td>
 283         <td class="" >Throws a JavaScript exception if an errors occurs.</td>
 284     </tr>
 285     <tr class="odd">
 286       <td>Description</td>
 287         <td class="odd">Removes a ResourceStore and deletes all of its contents. </td>
 288     </tr>
 289   </table>
 290   <table width="699">
 291     <tr class="odd">
 292       <th colspan="2"><div align="left"><code><strong>createManagedStore(string name, [string requiredCookie])</strong></code></div></th>
 293     </tr>
 294     <tr class="odd">
 295       <td width="125">Return Value </td>
 296         <td width="562"><code>ManagedResourceStore </code></td>
 297     </tr>
 298     <tr class="odd">
 299       <td>Parameters</td>
 300         <td><code>name</code> - string identifying the store.<br />
 301   <code>requiredCookie</code> - optional.<br />
 302   The combination of name and requiredCookie (along with the domain) identify a unique store. <br />
 303   Expected cookie format is &quot;name=value&quot;.</td>
 304     </tr>
 305     <tr class="odd">
 306       <td>Exceptions</td>
 307         <td class="" >Throws a JavaScript exception if an errors occurs.</td>
 308     </tr>
 309     <tr class="odd">
 310       <td>Description</td>
 311         <td class="odd">Opens an existing ManagedResourceStore or creates a new one if
 312       no such store exists.          </tr>
 313   </table>
 314   <table>
 315     <tr class="odd">
 316       <th colspan="2" width="100%"><div align="left"><code><strong>openManagedStore(string name, [string requiredCookie])</strong></code></div></th>
 317     </tr>
 318     <tr class="odd">
 319       <td width="113">Return Value </td>
 320         <td width="489"><code>ManagedResourceStore</code></td>
 321     </tr>
 322     <tr class="odd">
 323       <td>Parameters</td>
 324         <td><code>name</code>           - string identifying the store.<br />
 325 <code>requiredCookie</code> - optional.<br />
 326 The combination of name and requiredCookie (along with the domain) identify a unique store. <br />
 327 Expected cookie format is &quot;name=value&quot;.</td>
 328     </tr>
 329     <tr class="odd">
 330       <td>Exceptions</td>
 331         <td class="" > Throws a JavaScript exception if an errors occurs. </td>
 332     </tr>
 333     <tr class="odd">
 334       <td>Description</td>
 335       <td class="odd">Opens an existing ManagedResourceStore or returns null if no such store exists.          </tr>
 336   </table>
 337   <table width="699">
 338     <tr class="odd">
 339       <th colspan="2"><div align="left"><code><strong> removeManagedStore(string name, [string requiredCookie])</strong></code></div></th>
 340     </tr>
 341     <tr class="odd">
 342       <td width="129">Return Value </td>
 343         <td width="558" >void</td>
 344     </tr>
 345     <tr class="odd">
 346       <td>Parameters</td>
 347         <td><code>name</code> - string identifying the store.<br>
 348         <code>[requiredCookie]</code></td>
 349     </tr>
 350     <tr class="odd">
 351       <td>Exceptions</td>
 352         <td class="" >Throws a JavaScript exception if an errors occurs.</td>
 353     </tr>
 354     <tr class="odd">
 355       <td>Description</td>
 356         <td class="odd">Removes a ManagedResourceStore and all of its contained URLs
 357           from the local cache.          </td>
 358     </tr>
 359   </table>
 360 </ul>
 361
 362 <!------------------------------------------------------------->
 363 <!-- ManagedResourceStore                                    -->
 364 <!------------------------------------------------------------->
 365   <p><br>
 366     <a name="ManagedResourceStore"></a>  </p>
 367
 368
 369   <h2>ManagedResourceStore class </h2>
 370
 371
 372   <p>The ManagedResourceStore class is designed to cache a set of
 373     inter-dependent resources. For example, it can cache the set of resources required
 374     to bootstrap an application. The contents of a ManagedResourceStore are
 375     determined by the URLs listed in a <a href="#manifest_file">manifest file</a>. When all resources listed
 376     in the manifest have been captured, the LocalServer makes the set eligible
 377     for use. Periodically, the LocalServer checks for an updated manifest file. If the manifest file has been updated, LocalServer automatically downloads the updated set of resources.</p>
 378
 379
 380   <p>A ManagedResourceStore is a container of cached URLs. Each distinct ManagedResourceStore is uniquely identified by these attributes: </p>
 381
 382   <ul>
 383       <li><code>name</code> - a string identifying the store.<br>
 384         <i>Currently the name must consist  only of visible ASCII characters excluding the following:</i>
 385         <br><kbr>/ \ : * ? " &lt; &gt; | ; , </kbr><br>
 386         <i>Before finalization of the API we expect to remove this restriction.</i></li>
 387       <li><code>requiredCookie</code> - a cookie of the format &quot;name=value&quot; or null </li>
 388       <li><code>origin</code> - the scheme, domain, and port of the current page.</li>
 389   </ul>
 390
 391
 392   <p> An application can have many <code>ManagedResourceStores</code>.</p>
 393   <p>The ManagedResourceStores class requires a <em>manifest file</em> to define the URLs to store. The <a href="#manifest_file">manifest file</a> is described in detail, below. </p>
 394
 395   <h3>Attributes</h3>
 396   <table>
 397     <tr class="odd">
 398       <th width="158">Attribute</th>
 399         <th >Type</th>
 400         <th >Description</th>
 401     </tr>
 402     <tr class="odd">
 403       <td width="158"><strong>name</strong></td>
 404         <td width="109" >readonly attribute string</td>
 405         <td width="432" >The name of this managed resource store. </td>
 406     </tr>
 407     <tr class="odd">
 408       <td><strong><a name="MRScookie" id="MRScookie"></a>requiredCookie</strong></td>
 409         <td class="" >readonly attribute string </td>
 410         <td class="" >The cookie requirements of the store.<br>
 411         For further details see <a href="#required_cookie">Cookies and the LocalServer</a>.
 412         If empty, resources within this store are always served locally, provided the store is <code>enabled</code>.</td>
 413     </tr>
 414     <tr class="odd">
 415       <td><strong>enabled</strong></td>
 416         <td class="odd">readwrite attribute boolean </td>
 417         <td class="odd">Enables  local serving of URLs from this store when <code>enabled=true</code>. Disables local serving otherwise. </td>
 418     </tr>
 419     <tr class="odd">
 420       <td><strong>manifestUrl</strong></td>
 421         <td class="odd">readwrite attribute string </td>
 422         <td class="odd">The location of the manifest file.</td>
 423     </tr>
 424     <tr class="odd">
 425       <td><strong>lastUpdateCheckTime</strong></td>
 426         <td class="odd">readonly attribute int</td>
 427         <td class="odd">Time in second when the last update check
 428         occurred.</td>
 429     </tr>
 430     <tr class="odd">
 431       <td><strong>updateStatus</strong></td>
 432         <td class="odd">readonly attribute int</td>
 433         <td class="odd">
 434               Can be one of four values:
 435               <table class="noborders">
 436                 <tr>
 437                   <td><strong>0</strong>
 438                   <td>Update OK. An update task is not running. The last update task to run succeeded.
 439             <tr>
 440               <td><strong>1</strong>
 441               <td>Update checking. Gears is checking for a new manifest file.
 442             <tr>
 443               <td><strong>2</strong>
 444               <td>Update downloading. Gears is found a new manifest and is downloading the new resources.
 445             <tr>
 446               <td><strong>3</strong>
 447               <td>Update failed. An update task is not running. The last update task to run failed, and the error message is in the <code>lastErrorMessage</code> property.
 448        </table>
 449     </td>
 450     </tr>
 451     <tr class="odd">
 452       <td><strong> lastErrorMessage</strong> </td>
 453         <td class="odd">readonly attribute string</td>
 454         <td class="odd">When updateStatus is <strong>3</strong> (update failed), this property contains details about the error.</td>
 455     </tr>
 456     <tr class="odd">
 457       <td><strong>currentVersion</strong></td>
 458         <td class="odd">readonly attribute string </td>
 459         <td class="odd">The version of the set of resources that is currently being served locally, or empty string if no version is
 460               currently in use. This value reflects the <code>version</code> attribute from the manifest file only after all resources listed in the
 461         manifest file have been cached locally.</td>
 462     </tr>
 463   </table>
 464
 465
 466   <h3>Events</h3>
 467   <table>
 468     <tr class="odd">
 469       <th colspan="2"><code><strong>event void oncomplete(Object
 470         details)</strong></code></th>
 471     </tr>
 472     <tr class="odd">
 473       <td>Parameters</td>
 474       <td>
 475         <code>details</code> An object containing information about the update.
 476         Contains one property:
 477         <br>&nbsp; &nbsp; &bull; <code>String newVersion</code> - The new
 478         version of the ManagedResourceStore if the version changed. Otherwise,
 479         an empty string.
 480       </td>
 481     </tr>
 482     <tr class="odd">
 483       <td>Description</td>
 484       <td>
 485         <p>This event is fired when a ManagedResourceStore completes an
 486       update. Note that updates can be either started explicitly, by calling
 487       <code>checkForUpdate()</code>, or implicitly, when resources are
 488       served from the store.
 489         <p>An update may or may not result in a new version of the store. If
 490         a new version results, the <code>newVersion</code> property of the
 491         <code>details</code> object will contain the store's new version string.
 492       </td>
 493     </tr>
 494   </table>
 495
 496   <table>
 497     <tr class="odd">
 498       <th colspan="2"><code><strong>event void onerror(Error
 499         error)</strong></code></th>
 500     </tr>
 501     <tr class="odd">
 502       <td>Parameters</td>
 503       <td>
 504         <code>error</code> Contains details about the error that occured.
 505         Contains one property:
 506         <br>&nbsp; &nbsp; &bull; <code>String message</code> - The error
 507         message.
 508       </td>
 509     </tr>
 510     <tr class="odd">
 511       <td>Description</td>
 512       <td>This event is fired when a ManagedResourceStore update fails. Note
 513       that update failure may occur normally when an application is running
 514       offline, or if the server is down.</td>
 515     </tr>
 516   </table>
 517
 518   <table>
 519     <tr class="odd">
 520       <th colspan="2"><code><strong>event void onprogress(Object
 521         details)</strong></code></th>
 522     </tr>
 523     <tr class="odd">
 524       <td>Parameters</td>
 525       <td>
 526         <code>details</code> Contains information about the progress of a
 527         ManagedResourceStore update. Contains the following properties:
 528         <br>&nbsp; &nbsp; &bull; <code>Number filesComplete</code> - The number
 529         of files that have been captured so far in the current update.
 530         <br>&nbsp; &nbsp; &bull; <code>Number filesTotal</code> - The total
 531         number of files that need to be captured in the current update.
 532       </td>
 533     </tr>
 534     <tr class="odd">
 535       <td>Description</td>
 536       <td>This event is fired periodically during a ManagedResourceStore update.
 537       The <code>filesTotal</code> property contains the total number of files
 538       found in the manifest that need to be fetched. The
 539       <code>filesComplete</code> property contains the number of files that have
 540       been fetched so far. You can use this information to show progress
 541       information to the user.</td>
 542     </tr>
 543   </table>
 544
 545   <a name="checkforupdate" id="checkforupdate"></a>
 546   <h3>Methods</h3>
 547 <table>
 548   <tr class="odd">
 549     <th colspan="2"><div align="left"><code><strong>void checkForUpdate()</strong></code></div></th>
 550   </tr>
 551   <tr class="odd">
 552     <td width="91">Return Value </td>
 553     <td width="594" >void</td>
 554   </tr>
 555   <tr class="odd">
 556     <td >Parameters</td>
 557     <td class="odd">&nbsp;</td>
 558   </tr>
 559   <tr class="odd">
 560     <td >Exceptions</td>
 561     <td class="" >&nbsp;</td>
 562   </tr>
 563   <tr class="odd">
 564     <td >Description</td>
 565     <td class="odd"><p>Explicitly initiates an update task that runs asynchronously in the background, and returns immediately. <br />
 566     <p>An update task first issues a conditional GET of the manifest file from <code>manifestUrl</code>.
 567     If a response body is returned, the JSON data is parsed and the 'version' attribute is compared with
 568     the <code>currentVersion</code> property of the store. If they are different, the update task proceeds
 569     to GET each resource listed in the new manifest file. If the previous version contained a resource listed
 570     in the new version, the update task will issue an IfModifiedSince conditional request. While an update
 571     is in progress, resources from the previous version (if any) will continue to be served locally. After all
 572     resources have been downloaded, the <code>currentVersion</code> property will be updated to indicate
 573     that the new set of a resources are now being served locally and the previous version has been removed.
 574     <p>An additional HTTP header is added when Gears is capturing URLs<br>
 575       <code>X-Gears-Google: 1</code></p>
 576     <p>If an update task is interrupted in the middle, processing will resume where it left off the next time
 577     an update task for this store is initiated.</p>
 578     <p>Note that the manifest file's version string is compared for equality against the current known version string, and if a <em>different</em> version is found, downloads it. No other types of comparisons are performed on the version string. </p>
 579     <p>Update tasks are initiated automatically by Gears when resources stored in the ManagedResourceStore are requested and served. </p>    </td>
 580   </tr>
 581 </table>
 582 <p>&nbsp;</p>
 583 <p>&nbsp;</p>
 584 <ul>
 585   </li>
 586 </ul>
 587
 588 <br>
 589 <!------------------------------------------------------------->
 590 <!-- ResourceStore                                     -->
 591 <!------------------------------------------------------------->
 592 <a name="ResourceStore"></a>
 593 <h2>ResourceStore class </h2>
 594
 595 <p>A <code>ResourceStore</code> is a container of cached URLs.
 596 Each distinct <code>ResourceStores</code> is uniquely identified by three attributes:
 597 <ul>
 598   <li> <code>name</code> - a  string name identifying the ResourceStore<br>
 599         <i>Currently the name must consist  only of visible ASCII characters excluding the following:</i>
 600         <br><kbr>/ \ : * ? " &lt; &gt; | ; , </kbr><br>
 601         <i>Before finalization of the API we expect to remove this restriction.</i></li>
 602   <li><code>requiredCookie</code> - a cookie of the format &quot;name=value&quot; or null </li>
 603   <li><code>domain</code> -  the domain, protocol and port of the current page.</li>
 604   </ul>
 605 </p>
 606
 607  <p>There can be many <code>ResourceStores</code> in the system. </p>
 608  <p>
 609 A <code>ResourceStore</code> is populated with URLs explicitly through the use of the JavaScript API
 610 that this class provides.</p>
 611
 612   <h3>Attributes  </h3>
 613   <table width="647">
 614     <tr class="odd">
 615       <th width="123">Attribute</th>
 616       <th >Type</th>
 617       <th >Description</th>
 618     </tr>
 619     <tr class="odd">
 620       <td width="123"><strong>name</strong></td>
 621       <td width="126" >readonly attribute string</td>
 622       <td width="382" >The name of the store that you provided upon creating this object. </td>
 623     </tr>
 624     <tr class="odd">
 625       <td><strong>requiredCookie</strong></td>
 626       <td class="" >readonly attribute string </td>
 627       <td class="" >The cookie requirements of the store.
 628         For further details see <a href="#required_cookie">Cookies and the LocalServer</a>.<br>
 629         If requiredCookie is empty, then resources within this store are always served locally, provided the store is <code>enabled</code>.</td>
 630     </tr>
 631     <tr class="odd">
 632       <td><strong>enabled</strong></td>
 633       <td class="odd">readwrite attribute boolean </td>
 634       <td class="odd">Enables  local serving of URLs from this store when <code>enabled=true</code>. Disables local serving otherwise. </td>
 635     </tr>
 636   </table>
 637   <p>&nbsp;</p>
 638   <h3>Methods</h3>
 639   <table width="645">
 640     <tr class="odd">
 641       <th colspan="2"><div align="left"><code> <strong>capture(urlOrUrlArray, callback)</strong> </code></div></th>
 642     </tr>
 643     <tr class="odd">
 644       <td width="113">Return Value </td>
 645       <td width="489" >int</td>
 646     </tr>
 647     <tr class="odd">
 648       <td>Parameters</td>
 649       <td class="odd"><code>urlOrUrlArray</code><br />
 650         <br />
 651       <code>callback(string url, boolean success, int captureId)</code></td>
 652     </tr>
 653     <tr class="odd">
 654       <td>Exceptions</td>
 655       <td class="" >Throws an exception if any of the URLs is not from the same
 656       origin as the current page.</td>
 657     </tr>
 658     <tr class="odd">
 659       <td>Description</td>
 660       <td class="odd"><p>Initiates a capture task that runs asynchronously in the
 661       background, and returns immediately. The return value is a <code>captureId</code> which
 662       can be passed to <code>abortCapture</code> to cancel the task. <br />
 663       <br />
 664       Relative URLs are
 665       interpreted according to the current page's location. Upon completion of each URL the <code>callback</code> function is invoked.
 666       <p>An additional HTTP header is added when Gears is capturing  URLs<br><code>X-Gears-Google: 1</code></td>
 667     </tr>
 668   </table>
 669
 670   <table>
 671     <tr class="odd">
 672       <th colspan="2" width="100%"><div align="left"><code><strong> abortCapture(int captureId)</strong></code></div></th>
 673     </tr>
 674     <tr class="odd">
 675       <td width="113">Return Value </td>
 676       <td width="489" >void</td>
 677     </tr>
 678     <tr class="odd">
 679       <td>Parameters</td>
 680       <td class="odd"><code>captureId</code></td>
 681     </tr>
 682     <tr class="odd">
 683       <td>Exceptions</td>
 684       <td class="" >&nbsp;</td>
 685     </tr>
 686     <tr class="odd">
 687       <td>Description</td>
 688       <td class="odd">Aborts a capture task.</td>
 689     </tr>
 690   </table>
 691   <table width="648">
 692     <tr class="odd">
 693       <th colspan="2"><div align="left"><code> <strong> remove(string url)</strong></code></div></th>
 694     </tr>
 695     <tr class="odd">
 696       <td width="113">Return Value </td>
 697       <td width="489" >void</td>
 698     </tr>
 699     <tr class="odd">
 700       <td>Parameters</td>
 701       <td><code>url</code></td>
 702     </tr>
 703     <tr class="odd">
 704       <td>Exceptions</td>
 705       <td class="" >Throws an exception if URL is not from the same
 706       origin as the current page.</td>
 707     </tr>
 708     <tr class="odd">
 709       <td>Description</td>
 710       <td class="odd">Removes a cached URL from the store.</td>
 711     </tr>
 712   </table>
 713   <table width="651">
 714     <tr class="odd">
 715       <th colspan="2"><div align="left"><code><strong>rename(string srcUrl, string destUrl)</strong></code></div></th>
 716     </tr>
 717     <tr class="odd">
 718       <td width="131">Return Value </td>
 719       <td width="508" >void</td>
 720     </tr>
 721     <tr class="odd">
 722       <td>Parameters</td>
 723       <td><code>srcUrl</code> <br />
 724         <br />
 725       <code>destUrl</code></td>
 726     </tr>
 727     <tr class="odd">
 728       <td>Exceptions</td>
 729       <td class="" >Throws an exception if the source or destination URL is not from the same
 730       origin as the current page.</td>
 731     </tr>
 732     <tr class="odd">
 733       <td>Description</td>
 734       <td class="odd">Renames a  URL that is cached in the resource store. </td>
 735     </tr>
 736   </table>
 737   <table width="652">
 738     <tr class="odd">
 739       <th colspan="2"><div align="left"><code><strong>copy(string srcUrl, string destUrl)</strong></code></div></th>
 740     </tr>
 741     <tr class="odd">
 742       <td width="113">Return Value </td>
 743       <td width="489" >void</td>
 744     </tr>
 745     <tr class="odd">
 746       <td>Parameters</td>
 747       <td><code>srcUrl</code> <br />
 748         <br />
 749         <code>destUrl</code></td>
 750     </tr>
 751     <tr class="odd">
 752       <td>Exceptions</td>
 753       <td class="" >Throws an exception if the source or destination URL is not from the same
 754       origin as the current page.</td>
 755     </tr>
 756     <tr class="odd">
 757       <td>Description</td>
 758       <td class="odd">Copies a cached URL.</td>
 759     </tr>
 760   </table>
 761   <table>
 762     <tr class="odd">
 763       <th colspan="2" width="100%"><div align="left"><code><strong>isCaptured(string url)</strong></code></div></th>
 764     </tr>
 765     <tr class="odd">
 766       <td width="113">Return Value </td>
 767       <td width="489" >boolean</td>
 768     </tr>
 769     <tr class="odd">
 770       <td>Parameters</td>
 771       <td><code>url</code></td>
 772     </tr>
 773     <tr class="odd">
 774       <td>Exceptions</td>
 775       <td class="" >Throws an exception if the URL is not from the same
 776       origin as the current page.</td>
 777     </tr>
 778     <tr class="odd">
 779       <td>Description</td>
 780       <td class="odd">Returns true if the URL is cached in the store.</td>
 781     </tr>
 782   </table>
 783   <table>
 784     <tr class="odd">
 785       <th colspan="2" width="100%"><div align="left"><code><strong>captureFile(HtmlElement fileInputElement, string url)</strong></code></div></th>
 786     </tr>
 787     <tr class="odd">
 788       <td width="113">Return Value </td>
 789       <td width="489" >void</td>
 790     </tr>
 791     <tr class="odd">
 792       <td>Parameters</td>
 793       <td><code>fileInputElement</code><br/>
 794                        <br/>
 795                        <code>url</code></td>
 796     </tr>
 797     <tr class="odd">
 798       <td>Exceptions</td>
 799       <td class="" >Throws an exception if the URL is not from the same
 800       origin as the current page or if the file cannot be read.</td>
 801     </tr>
 802     <tr class="odd">
 803       <td>Description</td>
 804       <td class="odd">Captures the contents of the file indicated by the
 805         <code>fileInputElement</code> into the store and associates
 806         that content with the given URL. The <code>fileInputElement</code>
 807         argument must be a reference to an<code> &lt;input type=file&gt;</code>
 808         HTML element.</td>
 809     </tr>
 810   </table>
 811   <table>
 812     <tr class="odd">
 813       <th colspan="2" width="100%"><div align="left"><code><strong>getCapturedFileName(string url)</strong></code></div></th>
 814     </tr>
 815     <tr class="odd">
 816       <td width="113">Return Value </td>
 817       <td width="489" >string</td>
 818     </tr>
 819     <tr class="odd">
 820       <td>Parameters</td>
 821       <td><code>url</code></td>
 822     </tr>
 823     <tr class="odd">
 824       <td>Exceptions</td>
 825       <td class="" >Throws an exception if the <code>url</code> is not from the same
 826       origin as the current page.</td>
 827     </tr>
 828     <tr class="odd">
 829       <td>Description</td>
 830       <td class="odd">Returns the leaf file name associated with <code>url</code> that was previously captured by
 831       calling <code>captureFile</code>. Note that if <code>url</code> was captured by a method other than calling
 832       <code>captureFile</code> then an empty string will be returned and no exception will be thrown.</td>
 833     </tr>
 834   </table>
 835   <table>
 836     <tr class="odd">
 837       <th colspan="2" width="100%"><div align="left"><code><strong>getHeader(string url, string name)</strong></code></div></th>
 838     </tr>
 839     <tr class="odd">
 840       <td width="113">Return Value </td>
 841       <td width="489" >string</td>
 842     </tr>
 843     <tr class="odd">
 844       <td>Parameters</td>
 845       <td><code>url</code><br/><br/>
 846       <code>name</code> name of the header you want to retrieve, e.g. 'Content-Length'.</td>
 847     </tr>
 848     <tr class="odd">
 849       <td>Exceptions</td>
 850       <td class="" >Throws an exception if the <code>url</code> is not from the same
 851       origin as the current page.</td>
 852     </tr>
 853     <tr class="odd">
 854       <td>Description</td>
 855       <td width="489">Returns a specific HTTP header associated with the captured URL. </td>
 856     </tr>
 857   </table>
 858   <table>
 859     <tr class="odd">
 860       <th colspan="2" width="100%"><div align="left"><code><strong>getAllHeaders(string url)</strong></code></div></th>
 861     </tr>
 862     <tr class="odd">
 863       <td width="113">Return Value </td>
 864       <td width="489" >string</td>
 865     </tr>
 866     <tr class="odd">
 867       <td>Parameters</td>
 868       <td class="odd"><code>url</code></td>
 869     </tr>
 870     <tr class="odd">
 871       <td>Exceptions</td>
 872       <td class="" >Throws an exception if the <code>url</code> is not from the same
 873       origin as the current page.</td>
 874     </tr>
 875     <tr class="odd">
 876       <td>Description</td>
 877       <td width="489">Returns all HTTP headers associated with the captured <code>url</code>.</td>
 878     </tr>
 879   </table>
 880   <table>
 881     <tr class="odd">
 882       <th colspan="2" width="100%"><div align="left"><code><strong>createFileSubmitter()</strong></code></div></th>
 883     </tr>
 884     <tr class="odd">
 885       <td width="113">Return Value </td>
 886       <td width="489"><code>FileSubmitter</code></td>
 887     </tr>
 888     <tr class="odd">
 889       <td>Description</td>
 890       <td width="489">Returns a <code>FileSubmitter</code> object, which is used to submit URLs that are contained in this  store
 891       in HTML form submissions.</td>
 892     </tr>
 893   </table>
 894 <br>
 895
 896 <!------------------------------------------------------------->
 897 <!-- FileSubmitter                                           -->
 898 <!------------------------------------------------------------->
 899 <a name="FileSubmitter"></a>
 900 <h2>FileSubmitter class </h2>
 901 <p>The <code>FileSubmitter</code> object facilitates the submission of local files, that
 902   were previously captured using <code>ResourceStore.captureFile</code>, in
 903   multipart/form-data encoded form submissions. </p>
 904 <p>To create a <code>FileSubmitter</code>, call
 905   <code>ResourceStore.createFileSubmitter()</code>. The returned object allows only
 906   URLs contained in the originating resource store to be submitted. </p>
 907
 908   <h3>Methods</h3>
 909   <table>
 910     <tr class="odd">
 911       <th colspan="2" width="100%"><div align="left"><code><strong>setFileInputElement(htmlElement, url)</strong></code></div></th>
 912     </tr>
 913     <tr class="odd">
 914       <td width="113">Return Value </td>
 915       <td width="489"><code>void</code></td>
 916     </tr>
 917     <tr class="odd">
 918       <td>Parameters</td>
 919       <td><code>htmlElement</code><br/><br/>
 920                        <code>url</code></td>
 921     </tr>
 922     <tr class="odd">
 923       <td>Exceptions</td>
 924       <td class="" >Throws an exception if the URL is not from the same
 925       origin as the current page.</td>
 926     </tr>
 927     <tr class="odd">
 928       <td>Description</td>
 929       <td width="489"><p>Prepares the htmlElement to submit the file indicated by url. The htmlElement
 930       must be contained in an html form. When the form is submitted the file will be
 931       included as part of the resulting POST. The url is the captured resource's
 932       key in the originating Store. Relative URLs are interpreted according to the
 933       current page's location. The name attribute of htmlElement determines the
 934       parameter name associated with the uploaded file. </p>
 935       <p>Due to differences between Firefox and Internet Explorer, this method's
 936         behavior is browser specific. </p>
 937       <ul>
 938         <li> Firefox: The <code>htmlElement</code> must be a reference to an<code> &lt;input type=&quot;file&quot;&gt;</code>
 939           element. </li>
 940         <li> Internet Explorer: The <code>htmlElement</code> must NOT be a reference to an &lt;input&gt;
 941           of any type. </li>
 942       </ul></td>
 943     </tr>
 944   </table>
 945
 946   <pre><code>&lt;form method="POST" enctype="multipart/form-data" /&gt;
 947   &lt;input id="fileinput" type="file" name="formFieldName" /&gt;
 948   &lt;link id="iefileinput" name="formFieldName" /&gt;
 949 &lt;/form&gt;
 950
 951 &lt;script&gt;
 952   var fileSubmitter = store.createFileSubmitter();
 953   var htmlElement = isIE ? document.getElementById("iefileinput");
 954                          : document.getElementById("fileinput");
 955   fileSubmitter.setFileInputElement(htmlElement, urlOfStoredResource);
 956 &lt;/script&gt;</code></pre>
 957
 958 <!------------------------------------------------------------->
 959 <!-- Manifest File Format                                    -->
 960 <!------------------------------------------------------------->
 961   <p>&nbsp;</p>
 962   <a name="manifest_file" id="manifest_file"></a>
 963   <h2>Manifest File  </h2>
 964   <p>A manifest file lists all of the URLs to be captured by a ManagedResourceStore. It also contains the version  for the manifest file format, the version  of the contents of the manifest, and an optional redirection URL. </p>
 965   <p> Using the ManagedResourceStore requires that you create a manifest file.</p>
 966   <p>The manifest file and all the URLs listed in it must follow the &quot;same-origin policy&quot;, which means that all the URLs must originate from the same URI scheme, host, and port. See <a href="security.html">Gears and Security</a> for more information. </p>
 967   <p>An application can have any number of manifest files and ManagedResourceStores. You specify which manifest file to use when you create an instance of ManagedResourceStore.</p>
 968   <p>The manifest file is written in <a href="http://www.google.com/url?sa=D&amp;q=http://www.json.org">JavaScript Object Notation</a> (JSON) format.  </p>
 969   <p><strong>Sample manifest file</strong></p>
 970   <pre>{
 971   // version of the manifest file format
 972   &quot;betaManifestVersion&quot;: 1,
 973
 974   // version of the set of resources described in this manifest file
 975   &quot;version&quot;: &quot;my_version_string&quot;,
 976
 977   // optional
 978   // If the store specifies a requiredCookie, when a request would hit
 979   // an entry contained in the manifest except the requiredCookie is
 980   // not present, the local server responds with a redirect to this URL.
 981   &quot;redirectUrl&quot;:  &quot;login.html&quot;,
 982
 983   // URLs to be cached (URLs are given relative to the manifest URL)
 984   &quot;entries&quot;: [
 985       { &quot;url&quot;: &quot;main.html&quot;, &quot;src&quot;: &quot;main_offline.html&quot; },
 986       { &quot;url&quot;: &quot;.&quot;, &quot;redirect&quot;: &quot;main.html&quot; },
 987       { &quot;url&quot;: &quot;main.js&quot; }
 988       { &quot;url&quot;: &quot;formHandler.html&quot;, &quot;ignoreQuery&quot;: true },
 989     ]
 990 }</pre>
 991
 992     <h3>Contents of a manifest file </h3>
 993     <p>Manifest File JSON object: A single object contains the  attribute-value pairs described below.</p>
 994     <p>Note: All URLs can be provided as relative to the manifest file, or as fully-qualifed URIs. </p>
 995     <table>
 996       <tr class="odd">
 997         <th width="186"><div align="center" >Attribute</div></th>
 998                 <th width="208"><div align="center" >Value</div></th>
 999         <th width="336"><div align="center" >Notes</div></th>
1000       </tr>
1001       <tr class="odd">
1002         <td width="186"><code>&quot;betaManifestVersion&quot;</code></td>
1003         <td width="208"><code>1</code></td>
1004         <td width="336" >Required. Represents the version of the manifest file format itself. The manifest file is recognized only if this attribute and value appear and are correct. </td>
1005       </tr>
1006       <tr class="odd">
1007         <td><code>&quot;version&quot;</code></td>
1008         <td class="odd">string<strong></td>
1009         <td class="odd">Required. Represents the version, which you determine, of the manifest file's contents. This version is usually your application's version.
1010           <ul>
1011             <li>Version string is any  value determined by your application. </li>
1012             <li>String is case sensitive. </li>
1013             <li>Any change in the version string indicates to Gears that the manifest file has changed. </li>
1014         </ul></td>
1015       </tr>
1016       <tr class="odd">
1017         <td><code>&quot;redirectUrl&quot;</code></td>
1018         <td class="" >URL</td>
1019         <td class="" >Optional. The redirect URL is returned from the localServer if a &quot;<a href="#MRScookie">requiredCookie</a>&quot; is not present for the URL requested. </td>
1020       </tr>
1021       <tr class="odd">
1022         <td><code>&quot;entries&quot;</code></td>
1023         <td width="208">An array of URL resources,  in JavaScript object format. (See table below for details.) </td>
1024         <td width="336">Lists the URLs of all the resources to be captured for this manifest file. </td>
1025       </tr>
1026     </table>
1027     <p>&nbsp;</p>
1028     <p>The <code>&quot;entries&quot;</code> attribute in the manifest file is an array of URL resources,  in  JavaScript object format. The resource objects'  attribute-value pairs are described below.</p>
1029     <table>
1030       <tr class="odd">
1031         <th width="186"><div align="center" >Attribute</div></th>
1032         <th width="179"><div align="center" >Value</div></th>
1033         <th width="365"><div align="center" >Notes</div></th>
1034       </tr>
1035       <tr class="odd">
1036         <td width="186"><code>&quot;url&quot;</code></td>
1037         <td width="179"  >URL</td>
1038         <td width="365" >Required. A URL of a resource to be stored locally and served when <code>&quot;url&quot;</code> is requested locally. <br />
1039           <br />
1040         All URLs must follow the same-origin <a href="security.html">security</a> policy. </td>
1041       </tr>
1042       <tr class="odd">
1043         <td><code>&quot;src&quot;</code></td>
1044         <td class="odd">URL<strong></td>
1045         <td class="odd">Optional.
1046         If <code>&quot;src&quot;</code> is present, the given URL is fetched and
1047         served when <code>&quot;url&quot;</code> is requested locally.<br />
1048         <br />
1049         The<code>&quot;src&quot;</code> and <code>&quot;redirect&quot;</code> are mutually
1050       exclusive.</td>
1051       </tr>
1052       <tr class="odd">
1053         <td><code>&quot;redirect&quot;</code></td>
1054         <td class="" >URL</td>
1055         <td class="" >Optional. If  <code>&quot;redirect&quot;</code> is present, the
1056         local server responds with a 302 redirect to the given URL when <code>&quot;url&quot;</code> is
1057          requested locally.<br />
1058          <br />
1059          The<code>&quot;src&quot;</code> and <code>&quot;redirect&quot;</code> are mutually
1060       exclusive.</td>
1061       </tr>
1062       <tr class="odd">
1063         <td><code>&quot;ignoreQuery&quot;</code></td>
1064         <td width="179">boolean (default is <code>false</code>) </td>
1065         <td width="365">Optional. If the value is <code>true</code> the query string in the request URL is ignored when matching against this entry's URL.<br />
1066           <br/>
1067         For example, a request for <code>formHandler.html?name=value</code> can match the entries for the full URL including the query, or just the <code>formHandler.html</code> portion of the URL. <br />
1068         <br/>
1069         Note: An entry with an exact URL match takes precedence over a match found by ignoring the query string. </td>
1070       </tr>
1071     </table>
1072
1073 <!------------------------------------------------------------->
1074 <!-- Cookies and the LocalServer                             -->
1075 <!------------------------------------------------------------->
1076   <p>&nbsp;</p>
1077   <a name="required_cookie"></a>
1078   <h2>Cookies and the LocalServer</h2>
1079   <p>Both the <code>ResourceStore</code> and <code>ManagedResourceStore</code>
1080   support an optional <code>requiredCookie</code> attribute.
1081   This value causes LocalServer to examine cookies when
1082   deciding which resource to serve for a request. The attribute is used as follows:</p>
1083
1084   <table>
1085     <tr class="odd">
1086       <th><div align="center" >requiredCookie</div></th>
1087       <th width="100%"><div align="center" >Behavior</div></th>
1088     </tr>
1089     <tr class="odd">
1090       <td><code>&quot;foo=bar&quot;</code></td>
1091       <td>Serves the resource from the store if cookie <code>foo</code> is present in the request, and
1092         has the value <code>bar</code>.
1093       </td>
1094     </tr>
1095     <tr class="odd">
1096       <td><code>&quot;foo=;NONE;&quot;</code></td>
1097       <td class="odd">Serves the resource from the store if cookie <code>foo</code>
1098         is <b>not</b> present in the request.
1099       </td>
1100     </tr>
1101   </table>
1102
1103 <!------------------------------------------------------------->
1104 <!-- File system location                                    -->
1105 <!------------------------------------------------------------->
1106   <p>&nbsp;</p>
1107   <a name="filesystem_location"></a>
1108   <h2>Location of cached files</h2>
1109   <p>The LocalServer stores files that your application captures in a location determined by the browser and platform. </p>
1110   <p><strong>Windows Vista - Internet Explorer </strong></p>
1111   <p> Location: {FOLDERID_LocalAppDataLow}\Google\Google Gears for Internet Explorer<br />
1112     Example: C:\Users\Bob\AppData\LocalLow\Google\Google Gears for Internet Explorer</p>
1113   <p><strong>Windows Vista - Firefox </strong>- Files are stored in the user local profile directory. </p>
1114   <p>Location: C:\Users\&lt;username&gt;\AppData\Local\Mozilla\Firefox\Profiles\{profile}.default\Google Gears for Firefox <br />
1115     Example:  C:\Users\Bob\AppData\Local\Mozilla\Firefox\Profiles\uelib44s.default\Google Gears for Firefox  </p>
1116   <p><strong>Windows XP - Internet Explorer </strong>- Files are stored in the user local profile directory. </p>
1117   <p> Location: C:\Documents and Settings\&lt;username&gt;\Local Settings\Application Data\Google\Google Gears for Internet Explorer<br />
1118     Example: C:\Documents and Settings\Bob\Local Settings\Application Data\Google\Google Gears for Internet Explorer</p>
1119   <p><strong> Windows XP - Firefox </strong>- Files are stored in the user local profile directory. </p>
1120   <p>Location: C:\Documents and Settings\&lt;username&gt;\Local Settings\Application Data\Mozilla\Firefox\Profiles\{profile}\Google Gears for Firefox<br />
1121     Example: C:\Documents and Settings\Bob\Local Settings\Application Data\Mozilla\Firefox\Profiles\uelib44s.default\Google Gears for Firefox</p>
1122   <p><strong>Mac OS/X - Firefox </strong>- Files are stored in the user local profile directory. </p>
1123   <p>Location: Users/&lt;username&gt;/Library/Caches/Firefox/Profiles/{profile}.default/Google Gears for Firefox <br />
1124     Example: Users/Bob/Library/Caches/Firefox/Profiles/08ywpi3q.default/Google Gears for Firefox</p>
1125   <p><strong>Linux - Firefox </strong>- Files are stored in the user home directory.</p>
1126   <p>Location: ~<em>bob</em>/.mozilla/firefox/&lt;firefox's profile id&gt;/Google Gears for Firefox <br />
1127     Example: ~bob/.mozilla/firefox/08ywpi3q.default/Google Gears for Firefox </p>
1128
1129
1130 </div>
1131 </body>
1132 </html>