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