GM.xmlHttpRequest: Difference between revisions
→HEAD request: HEAD is part of the standard, it works |
|||
Line 113: | Line 113: | ||
=== HEAD request === | === HEAD request === | ||
As defined in HTTP, you may issue a HEAD request to | As defined in HTTP, you may issue a HEAD request to get the response headers, without receiving the entire response body. | ||
<pre class='sample'> | <pre class='sample'> |
Revision as of 20:15, 14 March 2010
Description
This method performs a similar function to the standard XMLHttpRequest object, but allows these requests to cross the same origin policy boundaries.
Compatibility: Greasemonkey 0.2.5+
Syntax
function GM_xmlhttpRequest( details )
Arguments
This method only takes one argument, the details
object.
Described below are the properties that may be defined on that object.
See #Examples for more detail on how to use each.
method
String
Type of HTTP request to make (E.G."GET"
,"POST"
)url
String
The URL to make the request to. Must be an absolute URL, beginning with the scheme.headers
Object
Optional. A set of headers to include in the request. [2]overrideMimeType
String
(Compatibility: 0.6.8+) Optional. A MIME type to specify with the request (E.G."text/html; charset=ISO-8859-1"
).data
String
Optional. Data to send in the request body. Usually forPOST
method requests. [1]binary
Boolean
(Compatibility: 0.8.3+) Optional, default false. When true, use the underlying.sendAsBinary()
method.onerror
Function
Optional. Will be called when the request has completed successfully. Passed one argument, the #Response Object.onload
Function
Optional. Will be called when the request has completed successfully. Passed one argument, the #Response Object.onreadystatechange
Function
Optional. Will be called when the request has completed successfully. Passed one argument, the #Response Object.
Response Object
All three of the callback functions defined in the details
object, if called, will receive this type of object as their first (and only) argument.
status
Integer
The HTTP response status (E.G. 200 or 404) upon success, ornull
upon failure.statusText
String
The HTTP response status line (E.G."OK"
,"Not Found"
) upon success, ornull
upon failure.readyState
Number
ThereadyState
as defined in XMLHttpRequest.responseText
String
TheresponseText
as defined in XMLHttpRequest.responseHeaders
String
The response headers as defined in XMLHttpRequest.finalUrl
String
(Compatibility: 0.8.0+) The final URL requested, ifLocation
redirects were followed.
Returns
undefined
As of version 0.8.5, an object with one method, abort()
.
Examples
GET request
GM_xmlhttpRequest({ method: "GET", url: "http://www.example.net/", headers: { "User-Agent": "Mozilla/5.0", // If not specified, navigator.userAgent will be used. "Accept": "text/xml" // If not specified, browser defaults will be used. }, onload: function(response) { // Inject responseXML into existing Object if not present if (!response.responseXML) { response.responseXML = new DOMParser() .parseFromString(response.responseText, "text/xml"); } GM_log([ response.status, response.statusText, response.readyState, response.responseHeaders, response.responseText, response.finalUrl, response.responseXML ].join("\n")); } });
POST request
When making a POST request, most sites require the Content-Type header to be defined as such:
GM_xmlhttpRequest({ method: "POST", url: "http://www.example.net/login", data: "username=johndoe&password=xyz123", headers: { "Content-Type": "application/x-www-form-urlencoded" }, onload: function(response) { if (response.responseText.indexOf("Logged in as") > -1) { location.href = "http://www.example.net/dashboard"; } } });
HEAD request
As defined in HTTP, you may issue a HEAD request to get the response headers, without receiving the entire response body.
GM_xmlhttpRequest({ url: "http://www.example.com", method: "HEAD", onload: function(response) { GM_log(response.responseHeaders); } });
Notes
1
Note that if the data
field contains form-encoded data, you usually must also set the header 'Content-Type': 'application/x-www-form-urlencoded'
in the headers
field.
2
Some headers may not actually work through GM_xmlhttpRequest.
For example, the Referer
header cannot be overriden.
[1]
[2]