GM xmlhttpRequest
From GreaseSpot
- The correct title of this article is GM_xmlhttpRequest. The substitution or omission of an _ is due to technical restrictions.
[edit] Description
This API method provides access to the chrome-privileged XMLHttpRequest object. This means that it is possible to issue requests to domains other than that of the current page.
Additional reference may be found at:
[edit] Syntax
GM_xmlhttpRequest( details )
- Value: Function
- Returns: Nothing, details Object
- Compatibility: Greasemonkey 0.2.5+
details Object Properties Event Handler Callbacks methodonloadurlonreadystatechangeheadersonerroroverrideMimeTypedata
[edit] Properties
[edit] method
- Value: String
- Usage:
details.method = "GET"';
[edit] url
- Value: String
- Usage:
details.url = "http://www.greasespot.net/";
[edit] headers
- Value: Object
- Usage:
details.headers = {"User-Agent":"Mozilla/5.0"};
- The
headersproperty is an object which is typically used to override the default browser generated headers, also known as atoms. It should contain the atom-value pairs of the headers to send.[2]
- The
[edit] overrideMimeType
- Value: String
- Compatibility: Greasemonkey 0.6.8+
- Usage:
details.overrideMimeType = "text/html; charset=ISO-8859-1";
- While each character set name may have multiple aliases defined, there may be a preferred name which can be found at IANA
[edit] data
- Value: String
- Usage:
details.data = null; /* some code */ if (details.data) { /* some code */ }
[edit] Event Handler Callbacks
[edit] onload
- Usage:
details.onload = function (response) { /* some code */ }; - Returns: Nothing, response Object
[edit] onreadystatechange
- Usage:
details.onreadystatechange = function (response) { /* some code */ }; - Returns: Nothing, response Object
[edit] onerror
- Usage:
details.onerror = function (response) { /* some code */ }; - Returns: Nothing, response Object
response Object Properties statusreadyStateresponseTextfinalUrlstatusTextresponseHeaders
[edit] Properties
[edit] status
- Value: Number
- Usage:
if (response.status == 200) { /* some code */ }
[edit] statusText
- Value: String
- Usage:
if (response.statusText == "OK") { /* some code */ }
[edit] readyState
- Value: Number
- Usage:
if (response.readyState == 4) { /* some code */ }
[edit] responseText
- Value: String
- Usage:
alert(response.responseText);
[edit] responseHeaders
- Value: String
- Usage:
if (response.responseHeaders) { /* some code */ }
- The
responseHeadersis the string representation of response headers returned byXMLHTTPRequest.getAllResponseHeaders().
- The
[edit] finalUrl
- Value: String
- Compatibility: Greasemonkey 0.8.0+
- Usage:
if (response.finalUrl) { /* some code */ }
[edit] Examples
GM_xmlhttpRequest({
method:"GET",
url:"http://www.greasespot.net/",
headers:{
"User-Agent":"Mozilla/5.0", // Recommend using navigator.userAgent when possible
"Accept":"text/xml"
},
onload:function(response) {
alert([
response.status,
response.statusText,
response.readyState,
response.responseHeaders,
response.responseText,
response.finalUrl
].join("\n"));
}
});
[edit] Notes
[1]Some users have reported problems with international character sets. See these mailing list threads
- http://www.mozdev.org/pipermail/greasemonkey/2006-June/008785.html
- http://www.mozdev.org/pipermail/greasemonkey/2006-April/008064.html
Resolved: Greasemonkey exposed the overrideMimeType method to allow changing of the desired charset.
[2]Some header atoms may not actually work through GM_xmlhttpRequest. The Referer atom is one that is known to be recognized but appears to be content filtered by the browser. This may be due to security restrictions to keep user scripts from doing unsafe things.

