Listed below are several possible causes for the connection error you're receiving. Please determine which of these causes may be applicable to you and follow the instructions to resolve the problem.
If you're using other firewall software, please visit that program's website for specific instructions to add applications to the exceptions list.
If you continue to have difficulties with BITS, make sure you have write access to the following folder:
C:\Documents and Settings\All Users\Application Data\Microsoft\Network\Downloader\
To determine if you have write access, right-click the folder and choose "Properties." If you see an empty box next to "Read-only" in the "General tab," you do have write access. If you see a checkmark or a green box, click the box until it's empty and click "OK." If you're unable to click the box, please speak with your system administrator.
Occasionally you may wish to know if Gears is installed on a particular computer. For example, you may wish to know if Gears is installed on a computer at an internet cafe, prior to logging in with any sensitive information. Currently, there are two ways to accomplish this:
<em:targetApplication>
<Description>
<em:id>{a463f10c-3994-11da-9945-000d60ca027b}</em:id>
<em:maxVersion>6.02</em:maxVersion>
<em:minVersion>0.2</em:minVersion>
</Description>
</em:targetApplication>
There are two ways to do so.
Since Gears allows web applications to write to your computer, Gears wants to be sure that the website has your permission to do so. You will see this dialog ever time the website tries to use Gears. If you trust the website and always want to permit it to use Gears, then check "Remember my decision for this site" and click Allow.
If you visit a new site that also wants to use Gears, you will see the message and can choose to give the new site permission or not.
Gears is an open source browser extension that lets developers create web applications that can run offline. Gears provides three key features:
Gears is currently an early-access developers' release. It is not yet intended for use by real users in production applications at this time.
If you're a developer interested in using Gears with your application, visit the Gears Developer Page.
If you wish to install Gears on your computer, visit the Gears Home Page. Please note, however, that Gears is not yet intended for general use.
Go to the Google Code Project home for Gears. There is also a wiki document that explains how to contribute to Gears.
Gears is currently a beta product; moreover, it is currently considered to be a developer-only release. When the developer community has had a chance to examine, critique, and improve Gears, a final version suitable for use with production applications will be made available.
Gears is open source software, licensed under the New BSD license. Generally speaking, this license allows you to embed the Gears runtime or API in your software, without restriction. You should, of course, consult a lawyer about licensing issues before choosing to embed Gears in your software. There is no restriction on web applications which make use of Gears installations on users' computers.
Google is working with a variety of partners to make Gears widely available, and easy for developers to use.
For more information, visit the Gears Developers' Site.
Gears extends browsers by making new APIs available to JavaScript code. Like all APIs, they must be used explicitly. To take advantage of the offline features provided by Gears, you'll need to add or change code in your web application.
There are three core modules provided by Gears: a LocalServer for storing and accessing application pages offline, a Database for storing and accessing application data on the user's computer, and a WorkerPool for performing long-running tasks (such as the code that synchronizes data between your server and users' computers). For more information, follow the links.
A Gears Tutorial is available that illustrates the basic concepts. You may also find the Gears sample applicationsuseful. Source code for these samples can be downloaded in a zip file found on the same page.
Gears works on the following browsers:
Additionally, the team is working on supporting Safari on Mac OS X in a future release.
Gears is open source software, licensed under the New BSD license . Generally speaking, this license is very permissive. You should, of course, always consult an attorney if you have any questions about software licensing.
There are generally two ways to use Gears: by embedding the API or runtime software in an application you distribute to end users, or by writing a web application which makes use of installations of Gears on end-users' computers.
The New BSD license allows you to embed the Gears runtime or API in your software, with very minimal restrictions. There are no restrictions on web applications which make use of Gears installations on users' computers.
Enhancing your web application with offline functionality can be challenging at first. Here are some resources to help you get started:
If those resources don't answer your question, you can also contact other Gears developers over at the Gears Discussion Group .
We'd love to hear your feedback and suggestions! Gears is open source software, so you should feel free to join our community. If you have a cool new idea you'd like to discuss, you should join our Google Group and post your comment there.
The Gears discussion group is intended for all topics, so don't be shy! You can post there whether your idea is about an application you'd like to build, or an enhancement or feature you'd like to see in Gears. Perhaps most importantly, you can also post there if you're having problems using Gears in an application you're building. The Gears discussion group is an open forum. Developers help each other, but the group also includes Google employees working on Gears who post regularly.
If you're interested in obtaining the source code for Gears and making some enhancements of your own, you should also visit the Gears Contributors Site.
You should not do so at all.
At this time, Gears is a developer-only release. Google is working with partners in the developer community and in industry to improve Gears in anticipation of a public release. Until that release, Gears is not suitable for deployment on end-user computers. As a result,applications built on Gears should not be relied on in production environments.
When the Gears community reaches consensus on a final API, Google will release a corresponding production-quality version of Gears. When that happens, this article will be updated.
No. Gears LocalServer is simply a static content cache that intercepts URL requests to static content and serves them locally. The LocalServer does not provide the capability to interpret any server-side scripting.
Yes. The Database Query Tool allows developers to interface with SQLite interactively via SQL commands. It can be downloaded at http://code.google.com/apis/gears/tools.html. Simply copy the "dbquery.html" file to your server directory and visit the URL in your browser, and you can start issuing SQL commands to the embedded SQLite. There is also a similar third party tool, called Gears In Motion which is very good.
If you desire to check the contents of localserver.db (the database for LocalServer) then it is suggested that you use a SQLite management client. A list of them can be found here.
The Gears API does not provide a programmatic way to delete an existing database. Consider the following code, which creates a Gears Database:
db = google.gears.factory.create('beta.database', '1.0');
db.open('mydb');
Databases created with code such as this can only be explicitly removed from your local machine by physically deleting the corresponding database file generated for the browser. Gears Database files reside in the Gears data directory associated with the browser. The specific path to this directory depends on your browser and the underlying operating system. The Gears data directories for common configurations are listed in http://code.google.com/apis/gears/api_database.html#directories.
The physical database file resides below the Gears data directory, according to this format:
[path]/[application url]/http_[port number]/[db name]#database
Since a Gears WorkerPool worker has no access to the address space of its parent worker, all source code must be explicitly passed in during child worker initialization as such -
childCode = '......'; /* JavaScript code as string */ childId = workerPool.createWorker(childCode);
The challenge lies in creating a string that encapsulates all the JavaScript codes that will be required by the child worker, and there are three ways to do this:
childCode = 'function square(num) { return num*num; }';
function square(num) { return num * num; }
childCode = String(square);
/* XMLHttpRequestObject is the XHR object of your browser */
XMLHttpRequestObject.open("GET", 'square.js');
XMLHttpRequestObject.onreadystatechange = function() {
if (XMLHttpRequestObject.readyState == 4 && XMLHttpRequestObject.status == 200) {
childCode = XMLHttpRequestObject.responseText;
}
}
No. Separate storages are made for separate domains. Gears looks at the protocol + host + port to determine domains. A different port would be a different domain.
A cross-origin worker is WorkerPool worker created in a JavaScript file on a domain and has been initialized to run JavaScript code on a cross-origin server.
A cross-origin worker is useful because it is a secure solution to the cross-origin restriction policy of the browser. It allows you to make a request to a cross-origin server, even though the browser usually restricts this.
What can it be used for?
Take a cross-origin resource offline with a cross-origin worker.
----cache_cross_origin_resource.html----
<script type="text/javascript" src="gears_init.js">
</script><script type="text/javascript">
// Create the workerpool
var workerPool = google.gears.factory.create('beta.workerpool','1.0');
// Set the message handler for when a worker sends a message
workerPool.onmessage = function(a, b, message) {
alert('Received message from worker ' + message.sender + ': ' + message.text);
};
// Create a worker from a JavaScript file on another origin
var childWorkerId = workerPool.createWorkerFromUrl('http://www.crossorigin.com/worker.js');
// Send a message to the worker. The worker's onmessage handler in worker.js will decide what to do with this
workerPool.sendMessage('crossOriginResource.html', childWorkerId);
</script>
----worker.js----
// Setup the WorkerPool
var wp = google.gears.workerPool;
// Allow a cross-origin script to run this
wp.allowCrossOrigin();
wp.onmessage = function(a,b,messageObject) {
// Ignore messages from unexpected origins
if(messageObject.origin == 'http://www.expectedorigin.com') {
// Create LocalServer
var localServer = google.gears.factory.create('beta.localserver');
// Create ResourceStore (Could also use ManagedResourceStore)
var store = localServer.createStore('Cross_Origin_Store');
// We are capturing the filename sent to us by the
// WorkerPool (crossOriginResource.html)
var fileToCapture = messageObject.text;
// Capture the file
store.capture(fileToCapture, function(url, success, captureId){
// When capture finishes, let the WorkerPool know the status
// This will cause workerPool.onmessage to alert the message received
wp.sendMessage(url + ' captured ' + (success ? 'succeeded' : 'failed'), messageObject.sender);
});
}
}
No. SQLite is thread-safe. However, if multiple workers attempt to access the database at once then some requests might fail. It is up to the application to have workers retry requests upon failure.
Yes. If you use a ResourceStore or a ManagedResourceStore and you store a URL with parameters then whatever was captured for that URL will be served back when that URL is requested. Ex:
store.capture('foobar.html?foo=1&bar=2');
When the browser requests foobar.html?foo=1&bar=2 it will be served the stored page, but not when it requests foobar.html.
In most cases, use the ManagedResourceStore. It is meant to be used for application resources such as CSS, HTML, JavaScript, and images. It is good because it enables you to push your updated application in one step to the clients.
The ResourceStore is meant to be more of a specialized tool and should be used accordingly. For instance, if your application has user-generated content or user-specific data then it would be difficult to control it with a ManagedResourceStore. Using a ResourceStore to handle this dynamic content is ideal.
First, read an article on the dangers of cross-origin scripting.
After understanding the security risks, here are two potential solutions:
(1) Use Gears' cross-origin workers
(2) Use cross-origin proxying
This is a safer alternative and therefore the suggested one. However, you must have access to put Javascript on any origins you wish to use. If you are trying to grab resources from an origin you do not control, use (2). However, be warned that this is unsafe and can expose you to attacks.
The first step is to grab the most recent version of Gears. One problem is that this is not the public version of gears that the average user will have installed - it is a developer release to play with new features.
Say we have two origins, http://www.foo.com/ and http://www.bar.com/ with the style.css file on bar.com. What you do is create a WorkerPool on foo.com which does a createWorkerFromUrl. The URL it will create it from is a Javascript worker file that you have placed on bar.com.
The worker file on bar.com will then create a LocalServer and ResourceStore, then capture style.css.
Here is example code:
<script type="text/javascript" src="gears_init.js"></script>
<script type="text/javascript">
var workerPool = google.gears.factory.create('beta.workerpool', '1.1');
workerPool.onmessage = function(a, b, message) {
alert('Received message from worker ' + message.sender + ': ' + message.text);
};
var childWorkerId = workerPool.createWorkerFromUrl('http://www.bar.com/worker.js');
workerPool.sendMessage('', childWorkerId);
</script>
worker.js (this origin is http://www.bar.com/)
var wp = google.gears.workerPool;
wp.allowCrossOrigin();
wp.onmessage = function(a, b, message) {
localServer = google.gears.factory.create('beta.localserver', '1.1');
var store = localServer.createStore("Test_Store");
store.capture("style.css", function(){
wp.sendMessage("Captured!", message.sender);
});
}
For ease of reading, the try catch blocks that you should be using are left out! Don't forget them or to make sure the user has Gears installed.
Be sure you understand the security risks of cross-origin proxying!
Use a PHP file that you store on the origin you are grabbing resources with to echo back the output of a resource from another origin. Then, to 'offline' this data, use resource store to store the PHP file with the exact parameters sent to it.
An example would be if I am on http://www.foo.com/ and I have a CSS located at http://www.bar.com/style.css. I would then tell my ResourceStore to pull down the URL http://www.foo.com/php_proxy.php?url=http://www.bar.com/style.css.php_proxy.php. The php_proxy would take the input url and do an HTTP request for that resource and echo it back as an image.
Here is what the code for php_proxy.php would look like:
<?php
header("Content-Type: text/css");
$base_url = $_GET['url'];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $base_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 );
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_HEADER, false);
echo( curl_exec($ch) );
?>
Then, in my HTML instead of:
<link rel="stylesheet" type="text/css" media="print" href="http://www.bar.com/style.css"/>I would use:
<link rel="stylesheet" type="text/css" media="print" href="http://www.foo.com/php_proxy.php?url=http://www.bar.com/style.css" />The last step is to have the ResourceStore grab http://www.foo.com/php_proxy.php?url=http://www.bar.com/style.css
If you've been wondering how to manage the stores and resources in Gears while developing, here's a solution. A script has been written which lets you add/remove stores, and the resources inside of them.
Limitations:
(Mac/Linux) How to use it:
ln localserver.db <domain>/http_80/localserver#databaseAn example would be
ln localserver.db www.google.com/http_80/localserver#database
(Windows) How to use it:
There is no utility built in to Windows to create a hard link (the equivalent of Mac/Linux symlink). There is an article that talks about making hard links. A simple utility is Hard Link Magic.
Use a hard link utility to connect the localserver.db file located in your Gears directory to a new file, <gears directory>/<domain>/http_80/localserver#database.
Follow steps 3 & 4 of the Mac/Linux section.
How it works:The file localserver.db, located in your Gears directory, is an SQLite database file that keeps track of all stores and resources on all domains in your Gears LocalServer. To prevent different domains from editing each other's offline data, this file is protected from being accessed in Gears code.
By creating a symlink to that file in your domain, it is like putting the localserver.db file in that folder. The script then opens that database and queries it for the stores and databases.
Troubleshooting:
If you received the "File exists" error while trying to create the symlink or there is an error when you open the LocalServer inspector tool, then delete the file <GearsDirectory>/<domain>/http_80/localserver#database and recreate the symlink.
No, there isn't an isOnline function in Gears at this time. And currently, there are no plans to implement it.
There are 2 reasons why we haven't implemented it yet:
We don't want users to neglect syncing reliability.
The popular suggestion to implement isOnline has been to make a periodic XMLHttpRequest to a resource, whose success/failure would designate the application being on/offline. The problem with this is that you cannot assume that when a ping succeeds you can start syncing and be guaranteed that that you are online. For example, if isOnline() returns true and you start sending sync updates, something could happen in the connection between the user and the server and these syncs would be permanently lost - meanwhile the application still thinks it is online.
So instead what we encourage people to do is to queue all updates locally in the database module, and then try and send them to their server separately. If the update succeeds, remove them from the database. If the update fails for any reason, try again next time. In that way, you're always ready for the server to go down at any time and you never lose anything.
Sample Code for periodic XMLHttpRequests - uses Gears v0.2+ HTTPRequest
Here is some sample code that makes use of Gears' HTTPRequest module to change the UI of an application - let the user know when they are on/offline. It requires gears_init.js to be in the same directory.
<div id="serverStatus"></div>
<div id="pings"></div>
<script src="gears_init.js"></script>
<script type="text/javascript" charset="utf-8">
var numPings = 0;
var request = google.gears.factory.create('beta.httprequest', '1.0');
var TIME_BETWEEN_PINGS = 3*1000;
var PING_TIMEOUT_SECONDS = 1*1000;
function pingSuccess() {
if(request.responseText != "" && request.responseText.indexOf("404 Page not found") == -1){
document.getElementById('serverStatus').innerHTML = "[Server Accessible]";
} else {
document.getElementById('serverStatus').innerHTML = "[Server Inaccessible]";
}
}
function isServerAvailable() {
var resource_to_test = "FAQs_to_write.txt";
resource_to_test += "?q=" + Math.floor(Math.random() * 100000);
request.open('GET', resource_to_test);
window.setTimeout("pingSuccess()",PING_TIMEOUT_SECONDS);
request.onreadystatechange = function() {
if (request.readyState == 4) {
numPings++;
document.getElementById('pings').innerHTML = "Number of pings: " + numPings;
}
};
request.send();
window.setTimeout("isServerAvailable()",TIME_BETWEEN_PINGS);
}
isServerAvailable();
</script>
Be aware that the resource_to_test must be a file located on the same domain this code is running on. Also note that in the pingSuccess function, there is a test for a page returning "404 Page not found". Different domains will send the user a different 404 error, so please be aware of what check is correct for your domain.
Sample Code for browser being offline
To check if the user has manually told the browser to work offline, use this:
alert(navigator.onLine);
Note: This works on IE and Firefox
Gears extends browsers by making new APIs available to JavaScript code. Like all APIs, they must be used explicitly. To take advantage of the offline features provided by Gears, you'll need to add or change code in your web application.
There are three core modules provided by Gears: a LocalServer for storing and accessing application pages offline, a Database for storing and accessing application data on the user's computer, and a WorkerPool for performing long-running tasks (such as the code that synchronizes data between your server and users' computers). For more information, follow the links.
A Gears Tutorial is available that illustrates the basic concepts. You may also find the Gears sample applications useful. Source code for these samples can be downloaded in a zip file found on the same page.
Gears provides a LocalServer module to access application data offline. This module consists of two sub-parts:
More information is available in theLocalServer API documentation.
Gears provides a Database module to store and retrieve data from a user's computer. This module consists of a SQL interface to a relational database embedded in the user's browser as part of Gears. Tables can be created to store data, in a manner that will be familiar to any SQL developer.
More information is available in theDatabase API Documentation.
Gears provides a WorkerPool module to run JavaScript code in separate contexts. These contexts (which are similar to threads) run in isolated JavaScript environments, and have no window object, document object, or other DOM elements. However, these threads do have access to the XmlHttpRequest function, and so can make AJAX-style calls as necessary. This is frequently useful to implement a component that synchronizes data between a user's computer (for offline use) and the server (for online use and backup).
Workers from the same pool can communicate with each other by passing messages.
More information is available in theWorkerPool API Documentation.
Windows Vista - Internet Explorer
Location: {FOLDERID_LocalAppDataLow}\Google\Gears for Internet Explorer
Example: C:\Users\Bob\AppData\LocalLow\Google\Gears for Internet Explorer
Windows Vista - Firefox - Files are stored in the user local profile directory.
Location: C:\Users\<username>\AppData\Local\Mozilla\Firefox\Profiles\{profile}.default\Gears for Firefox
Example: C:\Users\Bob\AppData\Local\Mozilla\Firefox\Profiles\uelib44s.default\Gears for Firefox
Windows XP - Internet Explorer - Files are stored in the user local profile directory.
Location: C:\Documents and Settings\<username>\Local Settings\Application Data\Google\Gears for Internet Explorer
Example: C:\Documents and Settings\Bob\Local Settings\Application Data\Google\Gears for Internet Explorer
Windows XP - Firefox - Files are stored in the user local profile directory.
Location: C:\Documents and Settings\<username>\Local Settings\Application Data\Mozilla\Firefox\Profiles\{profile}\Gears for Firefox
Example: C:\Documents and Settings\Bob\Local Settings\Application Data\Mozilla\Firefox\Profiles\uelib44s.default\Gears for Firefox
Mac OS/X - Firefox - Files are stored in the user local profile directory.
Location: Users/<username>/Library/Caches/Firefox/Profiles/{profile}.default/Gears for Firefox
Example: Users/Bob/Library/Caches/Firefox/Profiles/08ywpi3q.default/Gears for Firefox
Linux - Firefox - Files are stored in the user home directory.
Location: ~bob/.mozilla/firefox/<firefox's profile id>/Gears for Firefox
Example: ~bob/.mozilla/firefox/08ywpi3q.default/Gears for Firefox
Microsoft Windows Mobile - Internet Explorer - Files are stored in the Application Data directory.
Location: \Application Data\Google\Gears for Internet Explorer
localserver.db - This is a SQLite database that keeps track of all files that are stored in the LocalServer across all domains. This file is used in the internals of the Gears code, and cannot be accessed from within a Gears program.
permissions.db - This is a SQLite database that keeps track of all domains that have been allowed to use Gears.
<domain>/http_80/<filename>#database - This is a SQLite database file that has been created by an application on <domain>
<domain>/http_80/<filename>#localserver - This is a folder that contains files cached by either type of LocalServer store, a ResourceStore or a ManagedResourceStore, created by <domain >