gears/sdk/api_factory.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>Factory API</title>
  33     <link rel="stylesheet" type="text/css" href="gears.css" />
  34   </head>
  35
  36 <body>
  37
  38 <h1>Factory API</h1>
  39
  40 <div id="pagecontent">
  41
  42 <p>The Factory class is used to instantiate all other Google Gears
  43 objects. Using the <code>create</code> method, an
  44 application specifies the interface version it uses.</p>
  45
  46 <p>Use <a href='tools.html#gears_init'>gears_init.js</a> in your
  47 application for the easiest way to create a Factory object.  The
  48 script defines <code>google.gears.factory</code> to refer to a Factory
  49 object.</p>
  50
  51
  52 <p><a name="factoryclass" id="factoryclass"></a></p>
  53
  54 <h2 id="Factory">Factory class</h2>
  55
  56 <pre><code>Object  <b>create</b>(className, classVersion)
  57 string  <b>getBuildInfo</b>()
  58 boolean <b>getPermission</b>(siteName, imageUrl, extraMessage)
  59 readonly attribute boolean <b>hasPermission</b>
  60 readonly attribute string <b>version</b>
  61 </code></pre>
  62
  63
  64 <p>Code Example:</p>
  65 <pre><code>// gears_init.js defines google.gears.factory.
  66 &lt;script type="text/javascript" src="<a href='tools.html#gears_init'>gears_init.js</a>"&gt;&lt;/script&gt;
  67 &lt;script type="text/javascript"&gt;
  68
  69 // Check whether Google Gears is installed.
  70 if (window.google && google.gears) {
  71   // Instantiate Gears objects
  72   var db = google.gears.factory.create('beta.database');
  73   db.open();
  74 }
  75 &lt;/script&gt;</code></pre>
  76
  77 <h3>Methods</h3>
  78
  79 <table>
  80   <tr class="odd">
  81     <th colspan="2"><code>Object create(className, classVersion)</code></th>
  82   </tr>
  83   <tr class="odd">
  84     <td width="113">Summary:</td>
  85     <td width="550" class="odd">Creates a Gears object of the given class.</td>
  86   </tr>
  87   <tr class="odd">
  88     <td>Parameters:</td>
  89     <td class="odd">
  90       <code>className</code>
  91       - Type of object to create.
  92       <br>
  93       <code>classVersion</code>
  94       - Optional. If the value does not exist, <code>'1.0'</code> is assumed.
  95         (To see if the machine has the minimum version of Gears you require, use
  96         <code>factory.version</code> instead.)
  97       </td>
  98   </tr>
  99   <tr class="odd">
 100     <td>Return value:</td>
 101     <td class="odd">The new object.</td>
 102   </tr>
 103   <tr class="odd">
 104     <td>Details:</td>
 105     <td class="odd">
 106       An exception is thrown if the given <code>className</code> is not
 107       recognized.
 108       <p>
 109       The supported class names are:
 110       <table width="79%" border="0" cellpadding="0" cellspacing="0">
 111         <tr>
 112           <th width="177">className</th>
 113           <th width="216">Google Gears class created</th>
 114         </tr>
 115         <tr>
 116           <td class="code">beta.database</td>
 117           <td><a href="api_database.html">Database</a></td>
 118         </tr>
 119         <tr>
 120           <td class="code">beta.desktop</td>
 121           <td><a href="api_desktop.html">Desktop</a></td>
 122         </tr>
 123         <tr>
 124           <td class="code">beta.httprequest</td>
 125           <td><a href="api_httprequest.html">HttpRequest</a></td>
 126         </tr>
 127         <tr>
 128           <td class="code">beta.localserver</td>
 129           <td><a href="api_localserver.html">LocalServer</a></td>
 130         </tr>
 131         <tr>
 132           <td class="code">beta.timer</td>
 133           <td><a href="api_timer.html">Timer</a></td>
 134         </tr>
 135         <tr>
 136           <td class="code">beta.workerpool</td>
 137           <td><a href="api_workerpool.html">WorkerPool</a></td>
 138         </tr>
 139       </table>
 140     </td>
 141   </tr>
 142 </table>
 143
 144 <table>
 145   <tr class="odd">
 146     <th colspan="2"><code>string getBuildInfo()</code></th>
 147   </tr>
 148   <tr class="odd">
 149     <td width="113">Summary:</td>
 150     <td width="550" class="odd">Returns a description of the build of Gears installed.</td>
 151   </tr>
 152   <tr class="odd">
 153     <td>Return value:</td>
 154     <td class="odd">The build description string.</td>
 155   </tr>
 156   <tr class="odd">
 157     <td>Details:</td>
 158     <td class="odd">This string is purely informational.  Application developers
 159       should not rely on the format of data returned.  The contents and layout
 160       may change over time.
 161     </td>
 162   </tr>
 163 </table>
 164
 165 <table>
 166   <tr class="odd">
 167     <th colspan="2"><code>boolean getPermission(siteName, imageUrl, extraMessage)</code></th>
 168   </tr>
 169   <tr class="odd">
 170     <td width="113">Summary:</td>
 171     <td width="550" class="odd">Lets a site manually trigger the Gears security dialog, optionally with UI customizations.</td>
 172   </tr>
 173   <tr class="odd">
 174     <td>Parameters:</td>
 175     <td class="odd">
 176       <code>siteName</code>
 177       - Friendly name of the site requesting permission.
 178       <br>
 179       <code>imageUrl</code>
 180       - URL of a .png file to display in the dialog.
 181       <br>
 182       <code>extraMessage</code>
 183       - Site-specific text to display to users in the security dialog.
 184       </td>
 185   </tr>
 186   <tr class="odd">
 187     <td>Return value:</td>
 188     <td class="odd">Indicates whether the site has permission to use Gears.</td>
 189   </tr>
 190   <tr class="odd">
 191     <td>Details:</td>
 192     <td class="odd">It is always safe to call this function; it will return
 193     immediately if the site already has permission to use Gears.
 194     <br><br>
 195     All arguments are required, but an empty string can be passed for any value
 196     a site does not wish to use.
 197     </td>
 198   </tr>
 199 </table>
 200
 201 <h3>Attributes</h3>
 202
 203 <table>
 204   <tr class="odd">
 205     <th width="113">Attribute</th>
 206     <th width="113">Type</th>
 207     <th width="437">Description</th>
 208   </tr>
 209   <tr class="odd">
 210     <td><code><b>version</b></code></td>
 211     <td>readonly string</td>
 212     <td>Returns the version of Gears installed, as a string of the form <code>Major.Minor.Build.Patch</code> (e.g., '0.10.2.0').
 213   </tr>
 214   <tr class="odd">
 215     <td><code><b>hasPermission</b></code></td>
 216     <td>readonly boolean</td>
 217     <td>Returns true if the site already has permission to use Gears.
 218   </tr>
 219 </table>
 220
 221 <br>
 222
 223
 224 </div>
 225 </body>
 226 </html>