diff options
Diffstat (limited to 'files/nl/web/api/xmlhttprequest/index.html')
| -rw-r--r-- | files/nl/web/api/xmlhttprequest/index.html | 741 |
1 files changed, 0 insertions, 741 deletions
diff --git a/files/nl/web/api/xmlhttprequest/index.html b/files/nl/web/api/xmlhttprequest/index.html deleted file mode 100644 index 4668644ddd..0000000000 --- a/files/nl/web/api/xmlhttprequest/index.html +++ /dev/null @@ -1,741 +0,0 @@ ---- -title: XMLHttpRequest -slug: Web/API/XMLHttpRequest -tags: - - AJAX - - XMLHttpRequest -translation_of: Web/API/XMLHttpRequest ---- -<p><code>XMLHttpRequest</code> is een <a class="internal" href="/en/JavaScript" title="En/JavaScript">JavaScript</a> object dat is ontwikkeld door Microsoft en aangepast is door Mozilla, Apple, en Google. Het wordt nu <a href="http://www.w3.org/TR/XMLHttpRequest/"><font color="#0088cc" face="Helvetica Neue, Helvetica, Arial, sans-serif"><span style="line-height: 18px;">gestandaardiseerd</span></font> in het W3C</a>. Het zorgt voor een makkelijke manier om informatie uit een URL op te halen zonder de gehele pagina te herladen. Een webpagina kan een gedeelte van de pagina bijwerken zonder dat de gebruiker er last van heeft. <span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;">XMLHttpRequest</span><span style="line-height: 1.572;"> word veel gebruikt in <a href="/en-US/docs/AJAX" title="/en-US/docs/AJAX">AJAX</a> programering. </span><span style="line-height: 1.5;">Ondanks de naam kan </span><code style="font-size: 14px;">XMLHttpRequest</code><span style="line-height: 1.5;"> gebruikt worden om elke soort data op te halen, dus niet alleen XML, en ondersteunt protocollen anders dan <a href="https://developer.mozilla.org/en/HTTP">HTTP</a> (onder andere </span><span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;">file </span>en<span style="font-family: 'Courier New','Andale Mono',monospace; line-height: normal;"> ftp)</span><span style="line-height: 1.5;">.</span></p> - -<p>Om een instantie van <code>XMLHttpRequest</code> aan te maken schrijft men simpelweg:</p> - -<pre>var myRequest = new XMLHttpRequest(); -</pre> - -<p>Voor meer informatie over het gebruik van <code>XMLHttpRequest</code>, zie <a class="internal" href="/en/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="En/Using XMLHttpRequest">Using XMLHttpRequest</a>.</p> - -<h2 id="Methods_overzicht">Methods overzicht</h2> - -<table class="standard-table"> - <tbody> - <tr> - <td><code><a class="internal" href="/en/DOM/XMLHttpRequest#XMLHttpRequest()" title="/en/DOM/XMLHttpRequest#XMLHttpRequest()">XMLHttpRequest</a>(JSObject objParameters);</code></td> - </tr> - <tr> - <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#abort()" title="en/DOM/XMLHttpRequest#abort()">abort</a>();</code></td> - </tr> - <tr> - <td><code>DOMString <a class="internal" href="/en/DOM/XMLHttpRequest#getAllResponseHeaders()" title="en/DOM/XMLHttpRequest#getAllResponseHeaders()">getAllResponseHeaders</a>();</code></td> - </tr> - <tr> - <td><code>DOMString? <a class="internal" href="/en/DOM/XMLHttpRequest#getResponseHeader()" title="en/DOM/XMLHttpRequest#getResponseHeader()">getResponseHeader</a>(DOMString header);</code></td> - </tr> - <tr> - <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#open()" title="en/DOM/XMLHttpRequest#open()">open</a>(DOMString method, DOMString url, optional boolean async, optional DOMString? user, optional DOMString? password);</code></td> - </tr> - <tr> - <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#overrideMimeType()" title="en/DOM/XMLHttpRequest#overrideMimeType()">overrideMimeType</a>(DOMString mime);</code></td> - </tr> - <tr> - <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>();</code><br> - <s><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(ArrayBuffer data);</code></s><br> - <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(ArrayBufferView data);</code><br> - <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(Blob data);</code><br> - <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(Document data);</code><br> - <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(DOMString? data);</code><br> - <code>void <a class="internal" href="/en/DOM/XMLHttpRequest#send()" title="en/DOM/XMLHttpRequest#send()">send</a>(FormData data);</code></td> - </tr> - <tr> - <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#setRequestHeader()" title="en/DOM/XMLHttpRequest#setRequestHeader()">setRequestHeader</a>(DOMString header, DOMString value);</code></td> - </tr> - <tr> - <th>Niet-standaard methods</th> - </tr> - <tr> - <td><code>[noscript] void <a class="internal" href="/en/DOM/XMLHttpRequest#init()" title="en/DOM/XMLHttpRequest#init()">init</a>(in nsIPrincipal principal, in nsIScriptContext scriptContext, in nsPIDOMWindow ownerWindow);</code></td> - </tr> - <tr> - <td><code>[noscript] void <a class="internal" href="/en/DOM/XMLHttpRequest#openRequest()" title="en/DOM/XMLHttpRequest#openRequest()">openRequest</a>(in AUTF8String method, in AUTF8String url, in boolean async, in AString user, in AString password); </code></td> - </tr> - <tr> - <td><code>void <a class="internal" href="/en/DOM/XMLHttpRequest#sendAsBinary()" title="en/DOM/XMLHttpRequest#sendAsBinary()">sendAsBinary</a>(in DOMString body);</code></td> - </tr> - </tbody> -</table> - -<h2 id="Eigenschappen">Eigenschappen</h2> - -<table class="standard-table"> - <tbody> - <tr> - <th>Attribuut</th> - <th>Type</th> - <th>Omschrijving</th> - </tr> - <tr id="onreadystatechange"> - <td> - <p><code>onreadystatechange</code></p> - </td> - <td><code>Function?</code></td> - <td> - <p>A JavaScript function object that is called whenever the <code>readyState</code> attribute changes. The callback is called from the user interface thread.</p> - - <div class="warning"><strong>Warning:</strong> This should not be used with synchronous requests and must not be used from native code.</div> - </td> - </tr> - <tr id="readyState"> - <td><code>readyState</code></td> - <td><code>unsigned short</code></td> - <td> - <p>The state of the request:</p> - - <table class="standard-table"> - <tbody> - <tr> - <td class="header">Value</td> - <td class="header">State</td> - <td class="header">Description</td> - </tr> - <tr> - <td><code>0</code></td> - <td><code>UNSENT</code></td> - <td><code>open()</code>has not been called yet.</td> - </tr> - <tr> - <td><code>1</code></td> - <td><code>OPENED</code></td> - <td><code>send()</code>has not been called yet.</td> - </tr> - <tr> - <td><code>2</code></td> - <td><code>HEADERS_RECEIVED</code></td> - <td><code>send()</code> has been called, and headers and status are available.</td> - </tr> - <tr> - <td><code>3</code></td> - <td><code>LOADING</code></td> - <td>Downloading; <code>responseText</code> holds partial data.</td> - </tr> - <tr> - <td><code>4</code></td> - <td><code>DONE</code></td> - <td>The operation is complete.</td> - </tr> - </tbody> - </table> - </td> - </tr> - <tr id="response"> - <td><code>response</code></td> - <td>varies</td> - <td> - <p>The response entity body according to <code><a href="#responseType">responseType</a></code>, as an <a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a>, <a href="/en/DOM/Blob" title="en/DOM/Blob"><code>Blob</code></a>, {{ domxref("Document") }}, JavaScript object (for "json"), or string. This is <code>null</code> if the request is not complete or was not successful.</p> - </td> - </tr> - <tr id="responseText"> - <td><code>responseText</code> {{ReadOnlyInline()}}</td> - <td><code>DOMString</code></td> - <td>The response to the request as text, or <code>null</code> if the request was unsuccessful or has not yet been sent.</td> - </tr> - <tr id="responseType"> - <td><code>responseType</code></td> - <td><code>XMLHttpRequestResponseType</code></td> - <td> - <p>Can be set to change the response type.</p> - - <table class="standard-table" style="width: auto;"> - <tbody> - <tr> - <td class="header">Value</td> - <td class="header">Data type of <code>response</code> property</td> - </tr> - <tr> - <td><code>""</code> (empty string)</td> - <td>String (this is the default)</td> - </tr> - <tr> - <td><code>"arraybuffer"</code></td> - <td><a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a></td> - </tr> - <tr> - <td><code>"blob"</code></td> - <td>{{ domxref("Blob") }}</td> - </tr> - <tr> - <td><code>"document"</code></td> - <td>{{ domxref("Document") }}</td> - </tr> - <tr> - <td><code>"json"</code></td> - <td>JavaScript object, parsed from a JSON string returned by the server</td> - </tr> - <tr> - <td><code>"text"</code></td> - <td>String</td> - </tr> - <tr> - <td><code>"moz-blob"</code></td> - <td>Used by Firefox to allow retrieving partial {{ domxref("Blob") }} data from progress events. This lets your progress event handler start processing data while it's still being received.</td> - </tr> - <tr> - <td><code>"moz-chunked-text"</code></td> - <td> - <p>Similar to <code>"text"</code>, but is streaming. This means that the value in <code>response</code> is only available during dispatch of the <code>"progress"</code> event and only contains the data received since the last <code>"progress"</code> event.</p> - - <p>When <code>response</code> is accessed during a <code>"progress"</code> event it contains a string with the data. Otherwise it returns <code>null</code>.</p> - - <p>This mode currently only works in Firefox.</p> - </td> - </tr> - <tr> - <td><code>"moz-chunked-arraybuffer"</code></td> - <td> - <p>Similar to <code>"arraybuffer"</code>, but is streaming. This means that the value in <code>response</code> is only available during dispatch of the <code>"progress"</code> event and only contains the data received since the last <code>"progress"</code> event.</p> - - <p>When <code>response</code> is accessed during a <code>"progress"</code> event it contains a string with the data. Otherwise it returns <code>null</code>.</p> - - <p>This mode currently only works in Firefox.</p> - </td> - </tr> - </tbody> - </table> - - <div class="note"><strong>Note:</strong> Starting with Gecko 11.0, as well as WebKit build 528, these browsers no longer let you use the <code>responseType</code> attribute when performing synchronous requests. Attempting to do so throws an <code>NS_ERROR_DOM_INVALID_ACCESS_ERR</code> exception. This change has been proposed to the W3C for standardization.</div> - </td> - </tr> - <tr id="responseXML"> - <td><code>responseXML</code> {{ReadOnlyInline()}}</td> - <td><code>Document?</code></td> - <td> - <p>The response to the request as a DOM <code><a class="internal" href="/en/DOM/document" title="En/DOM/Document">Document</a></code> object, or <code>null</code> if the request was unsuccessful, has not yet been sent, or cannot be parsed as XML or HTML. The response is parsed as if it were a <code>text/xml</code> stream. When the <code>responseType</code> is set to <code>"document"</code> and the request has been made asynchronously, the response is parsed as a <code>text/html</code> stream.</p> - - <div class="note"><strong>Note:</strong> If the server doesn't apply the <code>text/xml</code> Content-Type header, you can use <code>overrideMimeType()</code>to force <code>XMLHttpRequest</code> to parse it as XML anyway.</div> - </td> - </tr> - <tr id="status"> - <td><code>status</code> {{ReadOnlyInline()}}</td> - <td><code>unsigned short</code></td> - <td>The status of the response to the request. This is the HTTP result code (for example, <code>status</code> is 200 for a successful request).</td> - </tr> - <tr id="statusText"> - <td><code>statusText</code> {{ReadOnlyInline()}}</td> - <td><code>DOMString</code></td> - <td>The response string returned by the HTTP server. Unlike <code>status</code>, this includes the entire text of the response message ("<code>200 OK</code>", for example).</td> - </tr> - <tr id="timeout"> - <td><code>timeout</code></td> - <td><code>unsigned long</code></td> - <td> - <p>The number of milliseconds a request can take before automatically being terminated. A value of 0 (which is the default) means there is no timeout.</p> - - <div class="note"><strong>Note:</strong> You may not use a timeout for synchronous requests with an owning window.</div> - </td> - </tr> - <tr id="ontimeout"> - <td><code>ontimeout</code></td> - <td><code>Function</code></td> - <td> - <p>A JavaScript function object that is called whenever the request times out.</p> - </td> - </tr> - <tr id="upload"> - <td><code>upload</code></td> - <td><code>XMLHttpRequestUpload</code></td> - <td>The upload process can be tracked by adding an event listener to <code>upload</code>.</td> - </tr> - <tr id="withCredentials"> - <td><code>withCredentials</code></td> - <td><code>boolean</code></td> - <td> - <p>Indicates whether or not cross-site <code>Access-Control</code> requests should be made using credentials such as cookies or authorization headers. The default is <code>false</code>.</p> - - <div class="note"><strong>Note:</strong> This never affects same-site requests.</div> - - <div class="note"><strong>Note:</strong> Starting with Gecko 11.0, Gecko no longer lets you use the <code>withCredentials</code> attribute when performing synchronous requests. Attempting to do so throws an <code>NS_ERROR_DOM_INVALID_ACCESS_ERR</code> exception.</div> - </td> - </tr> - </tbody> -</table> - -<h3 id="Non-standard_properties">Non-standard properties</h3> - -<table class="standard-table"> - <tbody> - <tr> - <th>Attribute</th> - <th>Type</th> - <th>Description</th> - </tr> - <tr id="channel"> - <td><code>channel</code> {{ReadOnlyInline()}}</td> - <td>{{Interface("nsIChannel")}}</td> - <td>The channel used by the object when performing the request. This is <code>null</code> if the channel hasn't been created yet. In the case of a multi-part request, this is the initial channel, not the different parts in the multi-part request. <strong>Requires elevated privileges to access.</strong></td> - </tr> - <tr id="mozAnon"> - <td><code>mozAnon</code> {{ReadOnlyInline()}}</td> - <td><code>boolean</code></td> - <td> - <p>If true, the request will be sent without cookie and authentication headers.</p> - </td> - </tr> - <tr id="mozSystem"> - <td><code>mozSystem</code> {{ReadOnlyInline()}}</td> - <td><code>boolean</code></td> - <td> - <p>If true, the same origin policy will not be enforced on the request.</p> - </td> - </tr> - <tr id="mozBackgroundRequest"> - <td><code>mozBackgroundRequest</code></td> - <td><code>boolean</code></td> - <td> - <p>Indicates whether or not the object represents a background service request. If <code>true</code>, no load group is associated with the request, and security dialogs are prevented from being shown to the user. <strong>Requires elevated privileges to access.</strong></p> - - <p>In cases in which a security dialog (such as authentication or a bad certificate notification) would normally be shown, the request simply fails instead.</p> - - <div class="note"><strong>Note: </strong>This property must be set before calling <code>open()</code>.</div> - </td> - </tr> - <tr id="mozResponseArrayBuffer"> - <td><code>mozResponseArrayBuffer</code> {{ obsolete_inline("6") }} {{ReadOnlyInline()}}</td> - <td><a href="/en/JavaScript_typed_arrays/ArrayBuffer" title="en/JavaScript typed arrays/ArrayBuffer"><code>ArrayBuffer</code></a></td> - <td>The response to the request, as a JavaScript typed array. This is <code>NULL</code> if the request was not successful, or if it hasn't been sent yet.</td> - </tr> - <tr id="multipart"> - <td><code>multipart</code> {{ obsolete_inline("22") }}</td> - <td><code>boolean</code></td> - <td> - <p><strong>This Gecko-only feature was removed in Firefox/Gecko 22.</strong> Please use <a href="/en-US/docs/Server-sent_events" title="/en-US/docs/Server-sent_events">Server-Sent Events</a>, <a href="/en-US/docs/WebSockets" title="/en-US/docs/WebSockets">Web Sockets</a>, or <code>responseText</code> from progress events instead.</p> - - <p>Indicates whether or not the response is expected to be a stream of possibly multiple XML documents. If set to <code>true</code>, the content type of the initial response must be <code>multipart/x-mixed-replace</code> or an error will occur. All requests must be asynchronous.</p> - - <p>This enables support for server push; for each XML document that's written to this request, a new XML DOM document is created and the <code>onload</code> handler is called between documents.</p> - - <div class="note"><strong>Note:</strong> When this is set, the <code>onload</code> handler and other event handlers are not reset after the first XMLdocument is loaded, and the <code>onload</code> handler is called after each part of the response is received.</div> - </td> - </tr> - </tbody> -</table> - -<h2 id="Constructor">Constructor</h2> - -<h3 id="XMLHttpRequest" name="XMLHttpRequest()">XMLHttpRequest()</h3> - -<p>The constructor initiates an XMLHttpRequest. It must be called before any other method calls.</p> - -<p>Gecko/Firefox 16 adds a non-standard parameter to the constructor that can enable anonymous mode (see <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=692677" title="692677 – Relax same-origin XHR restrictions for privileged applications">Bug 692677</a>). Setting the <code>mozAnon</code> flag to <code>true</code> effectively resembles the <a href="http://www.w3.org/TR/2012/WD-XMLHttpRequest-20120117/#dom-anonxmlhttprequest" title="see AnonXMLHttpRequest in the XMLHttpRequest specification"><code>AnonXMLHttpRequest()</code></a> constructor described in the XMLHttpRequest specification which has not been implemented in any browser yet (as of September 2012).</p> - -<pre>XMLHttpRequest ( - JSObject objParameters -);</pre> - -<h5 id="Parameters_non-standard">Parameters (non-standard)</h5> - -<dl> - <dt><code>objParameters</code></dt> - <dd>There are two flags you can set: - <dl> - <dt><code>mozAnon</code></dt> - <dd>Boolean: Setting this flag to <code>true</code> will cause the browser not to expose the origin and <a href="http://www.w3.org/TR/2012/WD-XMLHttpRequest-20120117/#user-credentials" title="Defintion of “User credentials” in the XMLHttpRequest specification.">user credentials</a> when fetching resources. Most important, this means that cookies will not be sent unless explicitly added using setRequestHeader.</dd> - <dt><code>mozSystem</code></dt> - <dd>Boolean: Setting this flag to <code>true</code> allows making cross-site connections without requiring the server to opt-in using CORS. <em>Requires setting <code>mozAnon: true</code>, i.e. this can't be combined with sending cookies or other user credentials. This <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=692677#c68" title="Bug 692677 comment 68">only works in privileged (reviewed) apps</a>; it does not work on arbitrary webpages loaded in Firefox.</em></dd> - </dl> - </dd> -</dl> - -<h2 id="Methods">Methods</h2> - -<h3 id="abort" name="abort()">abort()</h3> - -<p>Aborts the request if it has already been sent.</p> - -<h3 id="getAllResponseHeaders" name="getAllResponseHeaders()">getAllResponseHeaders()</h3> - -<pre>DOMString getAllResponseHeaders();</pre> - -<p>Returns all the response headers as a string, or <code>null</code> if no response has been received.<strong> Note:</strong> For multipart requests, this returns the headers from the <em>current</em> part of the request, not from the original channel.</p> - -<h3 id="getResponseHeader" name="getResponseHeader()">getResponseHeader()</h3> - -<pre>DOMString? getResponseHeader(DOMString <var>header</var>);</pre> - -<p>Returns the string containing the text of the specified header, or <code>null</code> if either the response has not yet been received or the header doesn't exist in the response.</p> - -<h3 id="open" name="open()">open()</h3> - -<p>Initializes a request. This method is to be used from JavaScript code; to initialize a request from native code, use <a class="internal" href="/en/nsIXMLHttpRequest#openRequest()" title="/en/XMLHttpRequest#openRequest()"><code>openRequest()</code></a>instead.</p> - -<div class="note"><strong>Note:</strong> Calling this method for an already active request (one for which <code>open()</code>or <code>openRequest()</code>has already been called) is the equivalent of calling <code>abort()</code>.</div> - -<pre>void open( - DOMString <var>method</var>, - DOMString <var>url</var>, - optional boolean <var>async</var>, - optional DOMString <var>user</var>, - optional DOMString <var>password</var> -); -</pre> - -<h6 id="Parameters">Parameters</h6> - -<dl> - <dt><code>method</code></dt> - <dd>The HTTP method to use, such as "GET", "POST", "PUT", "DELETE", etc. Ignored for non-HTTP(S) URLs.</dd> - <dt><code>url</code></dt> - <dd>The URL to send the request to.</dd> - <dt><code>async</code></dt> - <dd>An optional boolean parameter, defaulting to <code>true</code>, indicating whether or not to perform the operation asynchronously. If this value is <code>false</code>, the <code>send()</code>method does not return until the response is received. If <code>true</code>, notification of a completed transaction is provided using event listeners. This <em>must</em> be true if the <code>multipart</code> attribute is <code>true</code>, or an exception will be thrown. - <div class="note"><strong>Note:</strong> Starting with Gecko 30.0, synchronous requests on the main thread have been deprecated due to the negative effects to the user experience.</div> - </dd> - <dt><code>user</code></dt> - <dd>The optional user name to use for authentication purposes; by default, this is an empty string.</dd> - <dt><code>password</code></dt> - <dd>The optional password to use for authentication purposes; by default, this is an empty string.</dd> -</dl> - -<h3 id="overrideMimeType" name="overrideMimeType()">overrideMimeType()</h3> - -<p>Overrides the MIME type returned by the server. This may be used, for example, to force a stream to be treated and parsed as text/xml, even if the server does not report it as such. This method must be called before <code>send()</code>.</p> - -<pre>void overrideMimeType(DOMString <var>mimetype</var>);</pre> - -<h3 id="send" name="send()">send()</h3> - -<p>Sends the request. If the request is asynchronous (which is the default), this method returns as soon as the request is sent. If the request is synchronous, this method doesn't return until the response has arrived.</p> - -<div class="note"><strong>Note:</strong> Any event listeners you wish to set must be set before calling <code>send()</code>.</div> - -<div class="note"><strong>Note:</strong> Be aware to stop using a plain ArrayBuffer as parameter. This is not part of the <code>XMLHttpRequest</code> specification any longer. Use an ArrayBufferView instead (see compatibility table for version information).</div> - -<pre>void send(); -<s>void send(ArrayBuffer <var>data</var>);</s> -void send(ArrayBufferView <var>data</var>); -void send(Blob <var>data</var>); -void send(Document <var>data</var>); -void send(DOMString? <var>data</var>); -void send(FormData <var>data</var>);</pre> - -<h6 id="Notes">Notes</h6> - -<p>If the <var>data</var> is a <code>Document</code>, it is serialized before being sent. When sending a Document, versions of Firefox prior to version 3 always send the request using UTF-8 encoding; <a href="/en/Firefox_3" rel="internal" title="en/Firefox_3">Firefox 3</a> properly sends the document using the encoding specified by <code>body.xmlEncoding</code>, or UTF-8 if no encoding is specified.</p> - -<p>If it's an <code>nsIInputStream</code>, it must be compatible with <code>nsIUploadChannel</code>'s <code>setUploadStream()</code>method. In that case, a Content-Length header is added to the request, with its value obtained using <code>nsIInputStream</code>'s <code>available()</code>method. Any headers included at the top of the stream are treated as part of the message body. The stream's MIMEtype should be specified by setting the Content-Type header using the <a class="internal" href="/en/nsIXMLHttpRequest#setRequestHeader()" title="/en/XMLHttpRequest#setRequestHeader()"><code>setRequestHeader()</code></a> method prior to calling <code>send()</code>.</p> - -<p>The best way to send binary content (like in files upload) is using an <a href="/en-US/docs/JavaScript/Typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript/Typed_arrays/ArrayBufferView">ArrayBufferView</a> or <a href="/en-US/docs/DOM/Blob" title="/en-US/docs/DOM/Blob">Blobs</a> in conjuncton with the <code>send()</code> method. However, if you want to send a <a href="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify" title="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify">stringifiable</a> raw data, use the <a href="/en-US/docs/DOM/XMLHttpRequest#sendAsBinary()" title="/en-US/docs/DOM/XMLHttpRequest#sendAsBinary()"><code>sendAsBinary()</code></a> method instead, or the <a href="/en-US/docs/Web/JavaScript/Typed_arrays/StringView" title="/en-US/docs/Web/JavaScript/Typed_arrays/StringView"><code>StringView</code></a> <span class="inlineIndicator" title="This API is not native.">Non native</span> typed arrays superclass.</p> - -<h3 id="setRequestHeader" name="setRequestHeader()">setRequestHeader()</h3> - -<p>Sets the value of an HTTP request header. You must call <code>setRequestHeader()</code> after <a href="#open"><code>open()</code></a>, but before <code>send()</code>. If this method is called several times with the same header, the values are merged into one single request header.</p> - -<pre>void setRequestHeader( - DOMString <var>header</var>, - DOMString <var>value</var> -); -</pre> - -<h6 id="Parameters_2">Parameters</h6> - -<dl> - <dt><code>header</code></dt> - <dd>The name of the header whose value is to be set.</dd> - <dt><code>value</code></dt> - <dd>The value to set as the body of the header.</dd> -</dl> - -<h3 id="Non-standard_methods">Non-standard methods</h3> - -<h4 id="init">init()</h4> - -<p>Initializes the object for use from C++ code.</p> - -<div class="warning"><strong>Warning:</strong> This method must <em>not</em> be called from JavaScript.</div> - -<pre>[noscript] void init( - in nsIPrincipal principal, - in nsIScriptContext scriptContext, - in nsPIDOMWindow ownerWindow -); -</pre> - -<h5 id="Parameters_3">Parameters</h5> - -<dl> - <dt><code>principal</code></dt> - <dd>The principal to use for the request; must not be <code>null</code>.</dd> - <dt><code>scriptContext</code></dt> - <dd>The script context to use for the request; must not be <code>null</code>.</dd> - <dt><code>ownerWindow</code></dt> - <dd>The window associated with the request; may be <code>null</code>.</dd> -</dl> - -<h4 id="openRequest">openRequest()</h4> - -<p>Initializes a request. This method is to be used from native code; to initialize a request from JavaScript code, use <a class="internal" href="/en/nsIXMLHttpRequest#open()" title="/en/XMLHttpRequest#open()"><code>open()</code></a>instead. See the documentation for <code>open()</code>.</p> - -<h3 id="sendAsBinary">sendAsBinary()</h3> - -<p>A variant of the <code>send()</code> method that sends binary data.</p> - -<pre>void sendAsBinary( - in DOMString body -); -</pre> - -<p>This method, used in conjunction with the <a href="/en-US/docs/DOM/FileReader#readAsBinaryString()" title="/en-US/docs/DOM/FileReader#readAsBinaryString()"><code>readAsBinaryString</code></a> method of the <a href="/en-US/docs/DOM/FileReader" title="/en-US/docs/DOM/FileReader"><code>FileReader</code></a> API, makes it possible to <a href="https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files" title="/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Submitting_forms_and_uploading_files">read and <strong>upload</strong> any type of file</a> and to <a href="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify" title="/en-US/docs/JavaScript/Reference/Global_Objects/JSON/stringify">stringify</a> the raw data.</p> - -<h5 id="Parameters_4">Parameters</h5> - -<dl> - <dt><code>body</code></dt> - <dd>The request body as a DOMstring. This data is converted to a string of single-byte characters by truncation (removing the high-order byte of each character).</dd> -</dl> - -<h5 id="sendAsBinary_polyfill"><code>sendAsBinary()</code> polyfill</h5> - -<p>Since <code>sendAsBinary()</code> is an experimental feature, here is <strong>a polyfill</strong> for browsers that <em>don't</em> support the <code>sendAsBinary()</code> method but support <a href="/en-US/docs/JavaScript/Typed_arrays" title="/en-US/docs/JavaScript/Typed_arrays">typed arrays</a>.</p> - -<pre class="brush: js">/*\ -|*| -|*| :: XMLHttpRequest.prototype.sendAsBinary() Polyfill :: -|*| -|*| https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest#sendAsBinary() -|*| -\*/ - -if (!XMLHttpRequest.prototype.sendAsBinary) { - XMLHttpRequest.prototype.sendAsBinary = function (sData) { - var nBytes = sData.length, ui8Data = new Uint8Array(nBytes); - for (var nIdx = 0; nIdx < nBytes; nIdx++) { - ui8Data[nIdx] = sData.charCodeAt(nIdx) & 0xff; - } - /* send as ArrayBufferView...: */ - this.send(ui8Data); - /* ...or as ArrayBuffer (legacy)...: this.send(ui8Data.buffer); */ - }; -}</pre> - -<div class="note"><strong>Note:</strong> It's possible to build this polyfill putting two types of data as argument for <code>send()</code>: an <a href="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer" title="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer"><code>ArrayBuffer</code></a> (<code>ui8Data.buffer</code> – the commented code) or an <a href="/en-US/docs/JavaScript/Typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript/Typed_arrays/ArrayBufferView"><code>ArrayBufferView</code></a> (<code>ui8Data</code>, which is a <a href="/en-US/docs/JavaScript/Typed_arrays/Uint8Array" title="/en-US/docs/JavaScript/Typed_arrays/Uint8Array">typed array of 8-bit unsigned integers</a> – uncommented code). However, on Google Chrome, when you try to send an <code>ArrayBuffer</code>, the following warning message will appear: <code>ArrayBuffer is deprecated in XMLHttpRequest.send(). Use ArrayBufferView instead.</code> Another possible approach to send binary data is the <a href="/en-US/docs/Web/JavaScript/Typed_arrays/StringView" title="/en-US/docs/Web/JavaScript/Typed_arrays/StringView"><code>StringView</code></a> <span class="inlineIndicator" style="background-color: #ffffff;" title="This API is not native.">Non native</span> typed arrays superclass in conjunction with the <a href="#send()" title="#send()"><code>send()</code></a> method.</div> - -<h2 id="Notes_2">Notes</h2> - -<ul> - <li class="note">By default, Firefox 3 limits the number of <code>XMLHttpRequest</code> connections per server to 6 (previous versions limit this to 2 per server). Some interactive web sites may keep an <code>XMLHttpRequest</code> connection open, so opening multiple sessions to such sites may result in the browser hanging in such a way that the window no longer repaints and controls don't respond. This value can be changed by editing the <code>network.http.max-persistent-connections-per-server</code> preference in <code><a class="linkification-ext" href="/about:config" title="Linkification: about:config">about:config</a></code>.</li> - <li class="note">From Gecko 7 headers set by {{ manch("setRequestHeader") }} are sent with the request when following a redirect. Previously these headers would not be sent.</li> - <li class="note">When a request reaches its timeout value, a "timeout" event is raised.</li> -</ul> - -<h4 class="note" id="Events">Events</h4> - -<p><code>onreadystatechange</code> as a property of the <code>XMLHttpRequest</code> instance is supported in all browsers.</p> - -<p>Since then, a number of additional event handlers were implemented in various browsers (<code>onload</code>, <code>onerror</code>, <code>onprogress</code>, etc.). These are supported in Firefox. In particular, see {{ interface("nsIXMLHttpRequestEventTarget") }} and <a href="/en/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="En/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a>.</p> - -<p>More recent browsers, including Firefox, also support listening to the <code>XMLHttpRequest</code> events via standard <code><a href="/en/DOM/element.addEventListener" title="element.addEventListener">addEventListener</a></code> APIs in addition to setting <code>on*</code> properties to a handler function.</p> - -<h2 id="Permissions" name="Permissions">Permissions</h2> - -<p>When using System XHR via the <code>mozSystem</code> property, for example for Firefox OS apps, you need to be sure to add the <code>systemXHR</code> permission into your manifest file. System XHR can be used in privileged or certified apps.</p> - -<pre class="brush: js">"permissions": { - "systemXHR":{} -}</pre> - -<h2 id="Browser_Compatibility" name="Browser_Compatibility">Browser compatibility</h2> - -<p>{{ CompatibilityTable() }}</p> - -<div id="compat-desktop"> -<table class="compat-table"> - <tbody> - <tr> - <th>Feature</th> - <th>Chrome</th> - <th>Firefox (Gecko)</th> - <th>Internet Explorer</th> - <th>Opera</th> - <th>Safari (WebKit)</th> - </tr> - <tr> - <td>Basic support (XHR1)</td> - <td>1</td> - <td>1.0</td> - <td>5 (via ActiveXObject)<br> - 7 (XMLHttpRequest)</td> - <td>{{ CompatVersionUnknown() }}</td> - <td>1.2</td> - </tr> - <tr> - <td><code>send(ArrayBuffer)</code></td> - <td>9</td> - <td>9</td> - <td>10</td> - <td>11.60</td> - <td>{{ compatUnknown() }}</td> - </tr> - <tr> - <td><code>send(ArrayBufferView)</code></td> - <td>22</td> - <td>20</td> - <td>{{ compatUnknown() }}</td> - <td>{{ compatUnknown() }}</td> - <td>{{ compatUnknown() }}</td> - </tr> - <tr> - <td><code>send(Blob)</code></td> - <td>7</td> - <td>3.6</td> - <td>10</td> - <td>12</td> - <td>{{ compatUnknown() }}</td> - </tr> - <tr> - <td><code>send(FormData)</code></td> - <td>6</td> - <td>4</td> - <td>10</td> - <td>12</td> - <td>{{ compatUnknown() }}</td> - </tr> - <tr> - <td><code>sendAsBinary(DOMString)</code></td> - <td>{{ compatNo() }} – use the <a href="#sendAsBinary%28%29_polyfill" title="sendAsBinary() polyfill">polyfill</a></td> - <td>1.9</td> - <td>{{ CompatNo() }}</td> - <td>{{ CompatNo() }}</td> - <td>{{ CompatNo() }}</td> - </tr> - <tr> - <td><code>response</code></td> - <td>10</td> - <td>6</td> - <td>10</td> - <td>11.60</td> - <td>{{ compatUnknown() }}</td> - </tr> - <tr> - <td><code>responseType</code> = 'arraybuffer'</td> - <td>10</td> - <td>6</td> - <td>10</td> - <td>11.60</td> - <td>{{ compatUnknown() }}</td> - </tr> - <tr> - <td><code>responseType</code> = 'blob'</td> - <td>19</td> - <td>6</td> - <td>10</td> - <td>12</td> - <td>{{ compatUnknown() }}</td> - </tr> - <tr> - <td><code>responseType</code> = 'document'</td> - <td>18</td> - <td>11</td> - <td>10</td> - <td>{{ CompatNo() }}</td> - <td>6.1</td> - </tr> - <tr> - <td><code>responseType</code> = 'json'</td> - <td>{{ CompatNo() }}</td> - <td>10</td> - <td>{{ CompatNo() }}</td> - <td>12</td> - <td>{{ CompatNo() }}</td> - </tr> - <tr> - <td>Progress Events</td> - <td>7</td> - <td>3.5</td> - <td>10</td> - <td>12</td> - <td>{{ compatUnknown() }}</td> - </tr> - <tr> - <td><code>withCredentials</code></td> - <td>3</td> - <td>3.5</td> - <td>10</td> - <td>12</td> - <td>4</td> - </tr> - <tr> - <td><code>timeout</code></td> - <td><a href="https://code.google.com/p/chromium/issues/detail?id=231959" title="https://code.google.com/p/chromium/issues/detail?id=231959">29</a></td> - <td>12.0</td> - <td>8</td> - <td><a href="http://dev.opera.com/articles/view/xhr2/#xhrtimeouts" title="http://dev.opera.com/articles/view/xhr2/#xhrtimeouts">12</a></td> - <td>{{ CompatNo() }}</td> - </tr> - <tr> - <td><code>responseType</code> = 'moz-blob'</td> - <td>{{ CompatNo() }}</td> - <td>12.0</td> - <td>{{ CompatNo() }}</td> - <td>{{ CompatNo() }}</td> - <td>{{ CompatNo() }}</td> - </tr> - </tbody> -</table> -</div> - -<div id="compat-mobile"> -<table class="compat-table"> - <tbody> - <tr> - <th>Feature</th> - <th>Android</th> - <th>Chrome for Android</th> - <th>Firefox Mobile (Gecko)</th> - <th>IE Phone</th> - <th>Opera Mobile</th> - <th>Safari Mobile</th> - </tr> - <tr> - <td>Basic support</td> - <td>{{ CompatUnknown() }}</td> - <td>0.16</td> - <td>{{ CompatVersionUnknown() }}</td> - <td>{{ CompatUnknown() }}</td> - <td>{{ CompatUnknown() }}</td> - <td>{{ CompatUnknown() }}</td> - </tr> - </tbody> -</table> -</div> - -<h3 id="Gecko_notes">Gecko notes</h3> - -<p>Gecko 11.0 {{ geckoRelease("11.0") }} removed support for using the <code>responseType</code> and <code>withCredentials</code> attributes when performing synchronous requests. Attempting to do so throws an <code>NS_ERROR_DOM_INVALID_ACCESS_ERR</code> exception. This change has been proposed to the W3C for standardization.</p> - -<p>Gecko 12.0 {{ geckoRelease("12.0") }} and later support using <code>XMLHttpRequest</code> to read from <a href="/en/data_URIs" title="en/data_URIs"><code>data:</code> URLs</a>.</p> - -<p>Gecko 20.0 {{ geckoRelease("20.0") }} adds the support of sending an <a href="/en-US/docs/JavaScript/Typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript/Typed_arrays/ArrayBufferView"><code>ArrayBufferView</code></a> - sending a plain <a href="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer" title="/en-US/docs/JavaScript/Typed_arrays/ArrayBuffer"><code>ArrayBuffer</code></a> is not part of the <code>XMLHttpRequest</code> specification any longer and should be treated as deprecated.</p> - -<h2 id="See_also">See also</h2> - -<ul> - <li>MDN articles about XMLHttpRequest: - <ul> - <li><a href="/en/AJAX/Getting_Started" title="en/AJAX/Getting_Started">AJAX - Getting Started</a></li> - <li><a href="/en/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="En/Using XMLHttpRequest">Using XMLHttpRequest</a></li> - <li><a href="/en/HTML_in_XMLHttpRequest" title="en/HTML_in_XMLHttpRequest">HTML in XMLHttpRequest</a></li> - <li><a href="/en/DOM/XMLHttpRequest/FormData" title="en/XMLHttpRequest/FormData"><code>FormData</code></a></li> - </ul> - </li> - <li>XMLHttpRequest references from W3C and browser vendors: - <ul> - <li><a class="external" href="http://www.w3.org/TR/XMLHttpRequest1/">W3C: XMLHttpRequest</a> (base features)</li> - <li><a class="external" href="http://dvcs.w3.org/hg/xhr/raw-file/tip/Overview.html" title="http://dvcs.w3.org/hg/xhr/raw-file/tip/Overview.html">W3C: XMLHttpRequest</a> (latest editor's draft with extensions to the base functionality, formerly XMLHttpRequest Level 2</li> - <li><a class="external" href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/xmlsdk/html/xmobjxmlhttprequest.asp">Microsoft documentation</a></li> - <li><a class="external" href="https://developer.apple.com/library/safari/#documentation/AppleApplications/Conceptual/SafariJSProgTopics/Articles/XHR.html">Apple developers' reference</a></li> - </ul> - </li> - <li><a class="external" href="http://jibbering.com/2002/4/httprequest.html">"Using the XMLHttpRequest Object" (jibbering.com)</a></li> - <li><a class="external" href="http://www.peej.co.uk/articles/rich-user-experience.html">XMLHttpRequest - REST and the Rich User Experience</a></li> - <li><a class="external" href="http://www.html5rocks.com/en/tutorials/file/xhr2/">HTML5 Rocks - New Tricks in XMLHttpRequest2</a></li> -</ul> - -<p>{{ languages( { "es": "es/XMLHttpRequest", "fr": "fr/XMLHttpRequest", "it": "it/XMLHttpRequest", "ja": "ja/XMLHttpRequest", "ko": "ko/XMLHttpRequest", "pl": "pl/XMLHttpRequest", "zh-cn": "zh-cn/DOM/XMLHttpRequest" } ) }}</p> |