Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
xmlhttprequest.qdoc
Go to the documentation of this file.
1// Copyright (C) 2023 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \qmltype XMLHttpRequest
6 \inqmlmodule QtQml
7 \brief Object for sending requests to a server.
8
9 The \c XMLHttpRequest object allows scripts to perform HTTP client functionality,
10 such as submitting form data or loading data asynchronously from a server.
11
12 The \c XMLHttpRequest API is a partial implementation of the
13 \l {https://www.w3.org/TR/2014/WD-XMLHttpRequest-20140130/}{W3C XHR Level 1 standard}
14 with the following exception:
15 \list
16 \li It does not enforce the same origin policy.
17 \endlist
18
19 \section1 Sending requests
20
21 Use the following steps to send a request using the \c XMLHttpRequest API:
22 \list 1
23 \li Create a \c XMLHttpRequest object.
24 \li Assign a callback function to the \l {XMLHttpRequest::onreadystatechange}{onreadystatechange} signal handler.
25 \li Call \l {XMLHttpRequest::open}{open()} with the appropriate HTTP method and URL to request.
26 \li Call \l {XMLHttpRequest::send}{send()}
27 \endlist
28
29 The callback function handles the HTTP response for a request.
30 It's a good practice to check if the \l{XMLHttpRequest::readyState}{readyState} is \c DONE in the handler,
31 before you use one of the following methods to read the response:
32 \list
33 \li \l {XMLHttpRequest::response}{response}
34 \li \l {XMLHttpRequest::responseText}{responseText}
35 \li \l {XMLHttpRequest::responseXML}{responseXML}
36 \endlist
37
38 The following example demonstrates how to send a request and read the response:
39
40 \snippet qml/XHRForm.qml 0
41
42 The earlier snippet connects the button's clicked signal to an external \c sendRequest function.
43 A resource URL is passed as the first argument, and a callback function to handle UI updates is passed as the second.
44 The \c sendRequest function, which exists in an external \c request.js file, can be implemented like this:
45
46 \snippet qml/xmlhttprequest.js 0
47
48 The earlier snippet follows the four simple steps mentioned at the beginning.
49 It instantiates the \c XMLHttpRequest object first, and assigns a callback function to handle the response.
50 It also calls \l {XMLHttpRequest::open}{open()} with an HTTP method and URL, before it sends the request to the server.
51 Notice that the second argument to \c sendRequest is called at the end of \l {XMLHttpRequest::onreadystatechange}{onreadystatechange},
52 in order to handle UI updates based on the HTTP response.
53
54 Set the \c QML_XHR_DUMP environment variable to \c 1 if you want to debug a request.
55 This will log the following information:
56 \list
57 \li Method type (GET or POST), URL, and body of sent requests.
58 \li URL and body of responses received.
59 \li Network error, if any.
60 \endlist
61
62 \section1 Accessing local files
63
64 By default, you cannot use the \c XMLHttpRequest object to read files from your local file system.
65 If you wish to use this feature to access local files, you can set the following environment variables to \c 1.
66 \list
67 \li QML_XHR_ALLOW_FILE_READ
68 \li QML_XHR_ALLOW_FILE_WRITE
69 \endlist
70 \warning Use this feature only if you know that the application runs trusted QML and JavaScript code.
71
72 \section1 responseXML document
73
74 The \c responseXML XML DOM tree currently supported by QML is a reduced subset of
75 the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web browser.
76 The following objects and properties are supported by the QML implementation:
77
78 \table
79 \header
80 \li \b {Node}
81 \li \b {Document}
82 \li \b {Element}
83 \li \b {Attr}
84 \li \b {CharacterData}
85 \li \b {Text}
86
87 \row
88 \li
89 \list
90 \li nodeName
91 \li nodeValue
92 \li nodeType
93 \li parentNode
94 \li childNodes
95 \li firstChild
96 \li lastChild
97 \li previousSibling
98 \li nextSibling
99 \li attributes
100 \endlist
101
102 \li
103 \list
104 \li xmlVersion
105 \li xmlEncoding
106 \li xmlStandalone
107 \li documentElement
108 \endlist
109
110 \li
111 \list
112 \li tagName
113 \endlist
114
115 \li
116 \list
117 \li name
118 \li value
119 \li ownerElement
120 \endlist
121
122 \li
123 \list
124 \li data
125 \li length
126 \endlist
127
128 \li
129 \list
130 \li isElementContentWhitespace
131 \li wholeText
132 \endlist
133
134 \endtable
135*/
136
137/*!
138 \qmlmethod void XMLHttpRequest::abort()
139
140 Cancels the current request.
141
142 It changes the \l {XMLHttpRequest::readyState}{readyState} property to be \c XMLHttpRequest.UNSENT and emits the \c readystatechange signal.
143*/
144
145/*!
146 \qmlmethod string XMLHttpRequest::getAllResponseHeaders()
147
148 Returns a \c String of headers received from the last response.
149
150 The following is an example response header:
151 \code
152 content-encoding: gzip
153 content-type: text/html; charset=UTF-8
154 date: Mon, 06 Feb 2023 09:00:08 GMT
155 expires: Mon, 13 Feb 2023 09:00:08 GMT
156 last-modified: Thu, 17 Oct 2019 07:18:26 GMT
157 \endcode
158
159 \sa {XMLHttpRequest::getResponseHeader}{getResponseHeader()}
160*/
161
162/*!
163 \qmlmethod string XMLHttpRequest::getResponseHeader(headerName)
164
165 Returns either the \a headerName value from the last response, or an empty \c String, if the \a headerName is missing.
166
167 \sa {XMLHttpRequest::getAllResponseHeaders}{getAllResponseHeaders()}
168*/
169
170/*!
171 \qmlmethod void XMLHttpRequest::open(method, url, async)
172
173 Specify the HTTP \a method you want the request to use, as well as the \a url you wish to request.
174 You should make sure to always call this function before \l {XMLHttpRequest::send}{send()}.
175 An optional third parameter \a async can be used to decide whether the request should be asynchronous or not.
176 The default value is \c true.
177
178 Emits the \c readystatechange signal, which calls the \l {XMLHttpRequest::onreadystatechange}{onreadystatechange} handler with
179 the \l {XMLHttpRequest::readyState}{readyState} property set to \c XMLHttpRequest.OPENED.
180*/
181
182/*!
183 \qmlmethod void XMLHttpRequest::send(data)
184
185 Sends the request to the server.
186 You can use the optional argument \a data to add extra data to the body of the request.
187 This can be useful for POST requests, where you typically want the request to contain extra data.
188
189 The \l {XMLHttpRequest::readyState}{readyState} property is updated once a response has been received from the server,
190 and while the response is being processed. It will first be set to \c HEADERS_RECEIVED, then to \c LOADING,
191 and finally \c DONE, once the response has been fully processed.
192 The \c readystatechange signal is emitted every time \l {XMLHttpRequest::readyState}{readyState} is updated.
193*/
194
195/*!
196 \qmlmethod void XMLHttpRequest::setRequestHeader(header, value)
197
198 Adds a new header to the next request you wish to send.
199 This is a key-value pair, which has the name \a header and the corresponding \a value.
200*/
201
202/*!
203 \qmlmethod void XMLHttpRequest::overrideMimeType(mime)
204 \since 6.6
205
206 Forces the \c XMLHttpRequest to interpret the data received in the next HTTP response,
207 as if it had the MIME type \a mime, rather than the one provided by the server.
208*/
209
210/*!
211 \qmlproperty function XMLHttpRequest::onreadystatechange
212
213 Choose a callback function you want to get invoked whenever the \l {XMLHttpRequest::readyState}{readyState} of the \c XMLHttpRequest object changes.
214
215 \sa {XMLHttpRequest::readyState}{readyState}
216*/
217
218/*!
219 \qmlproperty enumeration XMLHttpRequest::readyState
220 \readonly
221
222 Indicates the current state of the \c XMLHttpRequest object.
223
224 The value can be one of the following:
225 \value XMLHttpRequest.UNSENT The request is not initialized, which is the state before calling \l {XMLHttpRequest::open}{open()}.
226 \value XMLHttpRequest.OPENED The request is initialized, meaning \l {XMLHttpRequest::open}{open()} was previously called, but no further progress.
227 \value XMLHttpRequest.HEADERS_RECEIVED Received a reply from the sever, but the request is not fully processed yet.
228 \value XMLHttpRequest.LOADING Downloading data from the server.
229 \value XMLHttpRequest.DONE Finished processing the request.
230
231 \sa {XMLHttpRequest::onreadystatechange}{onreadystatechange}
232*/
233
234/*!
235 \qmlproperty string XMLHttpRequest::responseURL
236 \readonly
237 \since 6.6
238
239 Returns the url that was used to retrieve the response data, after any redirects have occurred.
240*/
241
242/*!
243 \qmlproperty string XMLHttpRequest::responseText
244 \readonly
245
246 Returns a \c String containing the data received from the last response.
247
248 \sa {XMLHttpRequest::responseXML}{responseXML}
249*/
250
251/*!
252 \qmlproperty var XMLHttpRequest::responseXML
253 \readonly
254
255 Returns either a \c Document, or \c null, if the response content cannot be parsed as XML or HTML.
256 See the \l {responseXML document}{responseXML document} section for more information.
257
258 \sa {XMLHttpRequest::responseText}{responseText}
259*/
260
261/*!
262 \qmlproperty var XMLHttpRequest::response
263 \readonly
264
265 Returns either a \c String, an \c ArrayBuffer, or a \c Document,
266 depending on the \l {XMLHttpRequest::responseType}{responseType} of the last request.
267
268 \sa {XMLHttpRequest::responseType}{responseType}, {XMLHttpRequest::responseText}{responseText}, {XMLHttpRequest::responseXML}{responseXML}
269*/
270
271/*!
272 \qmlproperty string XMLHttpRequest::responseType
273
274 Returns a \c String describing the content type of the last response received.
275 \list
276 \li If the response type is "text" or an empty \c String, the response content is a UTF-16 encoded \c String.
277 \li If the response type is "arraybuffer", it means that the response content is an \c ArrayBuffer containing binary data.
278 \li If the response type is "json", the response content should be a JSON \c Document.
279 \li If the response type is "document", it means that the response content is an XML \c Document, which can be safely read with the \l {XMLHttpRequest::responseXML}{responseXML} property.
280 \endlist
281
282 \sa {XMLHttpRequest::response}{response}
283*/
284
285/*!
286 \qmlproperty int XMLHttpRequest::status
287 \readonly
288
289 Returns the status code for the last response received.
290
291 \sa {XMLHttpRequest::statusText}{statusText}
292*/
293
294/*!
295 \qmlproperty string XMLHttpRequest::statusText
296 \readonly
297
298 Returns a \c String that has the status message associated with the status code for the last response received.
299
300 \sa {XMLHttpRequest::status}{status}
301*/