mirror of
https://github.com/lubosz/overte.git
synced 2025-04-13 11:52:09 +02:00
Merge pull request #16577 from ctrlaltdavid/DOC-55-A
DOC-55: XMLHttpRequest JSDoc
This commit is contained in:
Brad Hefta-Gaub
GitHub
commit
e93adce7ae
4 changed files with 258 additions and 3 deletions
|
|
@ -99,7 +99,7 @@ void WebSocketClass::handleOnClose() {
|
|||
* @param {WebSocket.SocketError} error - The error.
|
||||
*/
|
||||
/**jsdoc
|
||||
* Information on a socket error.
|
||||
* <p>The type of socket error.</p>
|
||||
* <table>
|
||||
* <thead>
|
||||
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
|
||||
|
|
|
|||
|
|
@ -17,9 +17,9 @@
|
|||
#include <QWebSocket>
|
||||
|
||||
/**jsdoc
|
||||
* Provides a bi-direcctional, event-driven communication session between the script and another WebSocket connection. It is a
|
||||
* Provides a bi-directional, event-driven communication session between the script and another WebSocket connection. It is a
|
||||
* near-complete implementation of the WebSocket API described in the Mozilla docs:
|
||||
* <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSocket">https://developer.mozilla.org/en-US/docs/Web/API/WebSocket</a>.</p>
|
||||
* <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSocket">https://developer.mozilla.org/en-US/docs/Web/API/WebSocket</a>.
|
||||
*
|
||||
* <p>Constructed by <code>new WebSocket(...)</code> in Interface, client entity, avatar, and server entity scripts, or the
|
||||
* {@link WebSocketServer} class in server entity and assignment client scripts.
|
||||
|
|
|
|||
|
|
@ -110,6 +110,10 @@ QScriptValue XMLHttpRequestClass::getResponseHeader(const QString& name) const {
|
|||
return QScriptValue::NullValue;
|
||||
}
|
||||
|
||||
/**jsdoc
|
||||
* Called when the request's ready state changes.
|
||||
* @callback XMLHttpRequest~onReadyStateChangeCallback
|
||||
*/
|
||||
void XMLHttpRequestClass::setReadyState(ReadyState readyState) {
|
||||
if (readyState != _readyState) {
|
||||
_readyState = readyState;
|
||||
|
|
@ -183,6 +187,10 @@ void XMLHttpRequestClass::doSend() {
|
|||
}
|
||||
}
|
||||
|
||||
/**jsdoc
|
||||
* Called when the request times out.
|
||||
* @callback XMLHttpRequest~onTimeoutCallback
|
||||
*/
|
||||
void XMLHttpRequestClass::requestTimeout() {
|
||||
if (_onTimeout.isFunction()) {
|
||||
_onTimeout.call(QScriptValue::NullValue);
|
||||
|
|
|
|||
|
|
@ -21,6 +21,132 @@
|
|||
#include <QScriptValue>
|
||||
#include <QTimer>
|
||||
|
||||
/*
|
||||
XMlHttpRequest object
|
||||
XMlHttpRequest.objectName string
|
||||
XMlHttpRequest.response undefined
|
||||
XMlHttpRequest.responseText string
|
||||
XMlHttpRequest.responseType string
|
||||
XMlHttpRequest.status number
|
||||
XMlHttpRequest.statusText string
|
||||
XMlHttpRequest.readyState number
|
||||
XMlHttpRequest.errorCode number
|
||||
XMlHttpRequest.timeout number
|
||||
XMlHttpRequest.UNSENT number
|
||||
XMlHttpRequest.OPENED number
|
||||
XMlHttpRequest.HEADERS_RECEIVED number
|
||||
XMlHttpRequest.LOADING number
|
||||
XMlHttpRequest.DONE number
|
||||
XMlHttpRequest.ontimeout object
|
||||
XMlHttpRequest.onreadystatechange object
|
||||
XMlHttpRequest.destroyed(QObject*) function
|
||||
XMlHttpRequest.destroyed() function
|
||||
XMlHttpRequest.objectNameChanged(QString) function
|
||||
XMlHttpRequest.deleteLater() function
|
||||
XMlHttpRequest.requestComplete() function
|
||||
XMlHttpRequest.abort() function
|
||||
XMlHttpRequest.setRequestHeader(QString,QString) function
|
||||
XMlHttpRequest.open(QString,QString,bool,QString,QString) function
|
||||
XMlHttpRequest.open(QString,QString,bool,QString) function
|
||||
XMlHttpRequest.open(QString,QString,bool) function
|
||||
XMlHttpRequest.open(QString,QString) function
|
||||
XMlHttpRequest.send() function
|
||||
XMlHttpRequest.send(QScriptValue) function
|
||||
XMlHttpRequest.getAllResponseHeaders() function
|
||||
XMlHttpRequest.getResponseHeader(QString) function
|
||||
*/
|
||||
|
||||
/**jsdoc
|
||||
* Provides a means to interact with web servers. It is a near-complete implementation of the XMLHttpRequest API described in
|
||||
* the Mozilla docs:
|
||||
* <a href="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest">https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest</a>.
|
||||
*
|
||||
* @class XMLHttpRequest
|
||||
*
|
||||
* @hifi-interface
|
||||
* @hifi-client-entity
|
||||
* @hifi-avatar
|
||||
* @hifi-server-entity
|
||||
* @hifi-assignment-client
|
||||
*
|
||||
* @property {*} response - The response data.
|
||||
* <em>Read-only.</em>
|
||||
* @property {string} responseText - The response data as text.
|
||||
* <em>Read-only.</em>
|
||||
* @property {string} responseType - The response type required or received (e.g., <code>"text"</code>, <code>"json"</code>,
|
||||
* <code>"arraybuffer"</code>, ...).
|
||||
* @property {number} status - The <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status">HTTP response status
|
||||
* code</a> (<code>100</code> – <code>599</code>).
|
||||
* <em>Read-only.</em>
|
||||
* @property {string} statusText - The HTTP response status text.
|
||||
* <em>Read-only.</em>
|
||||
* @property {XMLHttpRequest.ReadyState} readyState - The status of the request.
|
||||
* <em>Read-only.</em>
|
||||
* @property {XMLHttpRequest.NetworkError} errorCode - The network result of the request: including, <code>0</code> (NoError)
|
||||
* if there was no error, <code>4</code> (TimeoutError) if the request timed out.
|
||||
* <em>Read-only.</em>
|
||||
* @property {number} timeout - The time a request can take before timing out, in ms.
|
||||
*
|
||||
* @property {XMLHttpRequest.ReadyState} UNSENT - Request has been created; {@link XMLHttpRequest.open} not called yet.
|
||||
* <em>Read-only.</em>
|
||||
* @property {XMLHttpRequest.ReadyState} OPENED - {@link XMLHttpRequest.open} has been called.
|
||||
* <em>Read-only.</em>
|
||||
* @property {XMLHttpRequest.ReadyState} HEADERS_RECEIVED - {@link XMLHttpRequest.send} has been called; headers and status
|
||||
* are available.
|
||||
* <em>Read-only.</em>
|
||||
* @property {XMLHttpRequest.ReadyState} LOADING - Downloading; {@link XMLHttpRequest|XMLHttpRequest.responseText} has partial
|
||||
* data.
|
||||
* <em>Read-only.</em>
|
||||
* @property {XMLHttpRequest.ReadyState} DONE - Operation complete.
|
||||
* <em>Read-only.</em>
|
||||
*
|
||||
* @property {XMLHttpRequest~onTimeoutCallback} ontimeout - Function called when the request times out.
|
||||
* <p>Note: This is called in addition to any function set for <code>onreadystatechange</code>.</p>
|
||||
* @property {XMLHttpRequest~onReadyStateChangeCallback} onreadystatechange - Function called when the request's ready state
|
||||
* changes.
|
||||
*
|
||||
* @example <caption>Get a web page's HTML.</caption>
|
||||
* var URL = "https://www.highfidelity.com/";
|
||||
*
|
||||
* var req = new XMLHttpRequest();
|
||||
* req.onreadystatechange = function () {
|
||||
* if (req.readyState === req.DONE) {
|
||||
* if (req.status === 200) {
|
||||
* print("Success");
|
||||
* print("Content type:", req.getResponseHeader("content-type"));
|
||||
* print("Content:", req.responseText.slice(0, 100), "...");
|
||||
*
|
||||
* } else {
|
||||
* print("Error", req.status, req.statusText);
|
||||
* }
|
||||
*
|
||||
* req = null;
|
||||
* }
|
||||
* };
|
||||
*
|
||||
* req.open("GET", URL);
|
||||
* req.send();
|
||||
*
|
||||
* @example <caption>Get a web page's HTML — alternative method.</caption>
|
||||
* var URL = "https://www.highfidelity.com/";
|
||||
*
|
||||
* var req = new XMLHttpRequest();
|
||||
* req.requestComplete.connect(function () {
|
||||
* if (req.status === 200) {
|
||||
* print("Success");
|
||||
* print("Content type:", req.getResponseHeader("content-type"));
|
||||
* print("Content:", req.responseText.slice(0, 100), "...");
|
||||
*
|
||||
* } else {
|
||||
* print("Error", req.status, req.statusText);
|
||||
* }
|
||||
*
|
||||
* req = null;
|
||||
* });
|
||||
*
|
||||
* req.open("GET", URL);
|
||||
* req.send();
|
||||
*/
|
||||
class XMLHttpRequestClass : public QObject {
|
||||
Q_OBJECT
|
||||
Q_PROPERTY(QScriptValue response READ getResponse)
|
||||
|
|
@ -46,6 +172,26 @@ public:
|
|||
~XMLHttpRequestClass();
|
||||
|
||||
static const int MAXIMUM_REDIRECTS = 5;
|
||||
|
||||
/**jsdoc
|
||||
* <p>The state of an XMLHttpRequest.</p>
|
||||
* <table>
|
||||
* <thead>
|
||||
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
|
||||
* </thead>
|
||||
* <tbody>
|
||||
* <tr><td><code>0</code></td><td>UNSENT</td><td>Request has been created; {@link XMLHttpRequest.open} not called
|
||||
* yet.</td></tr>
|
||||
* <tr><td><code>1</code></td><td>OPENED</td><td>{@link XMLHttpRequest.open} has been called.</td></tr>
|
||||
* <tr><td><code>2</code></td><td>HEADERS_RECEIVED</td><td>{@link XMLHttpRequest.send} has been called; headers and
|
||||
* status are available.</td></tr>
|
||||
* <tr><td><code>3</code></td><td>LOADING</td><td>Downloading; {@link XMLHttpRequest|XMLHttpRequest.responseText} has
|
||||
* partial data.</td></tr>
|
||||
* <tr><td><code>4</code></td><td>DONE</td><td>Operation complete.</td></tr>
|
||||
* </tbody>
|
||||
* </table>
|
||||
* @typedef {number} XMLHttpRequest.ReadyState
|
||||
*/
|
||||
enum ReadyState {
|
||||
UNSENT = 0,
|
||||
OPENED,
|
||||
|
|
@ -79,16 +225,66 @@ public:
|
|||
void setOnReadyStateChange(QScriptValue function) { _onReadyStateChange = function; }
|
||||
|
||||
public slots:
|
||||
|
||||
/**jsdoc
|
||||
* Aborts the request.
|
||||
* @function XMLHttpRequest.abort
|
||||
*/
|
||||
void abort();
|
||||
|
||||
/**jsdoc
|
||||
* Sets the value of an HTTP request header. Must be called after {@link XMLHttpRequest.open} but before
|
||||
* {@link XMLHttpRequest.send};
|
||||
* @function XMLHttpRequest.setRequestHeader
|
||||
* @param {string} name - The name of the header to set.
|
||||
* @param {string} value - The value of the header.
|
||||
*/
|
||||
void setRequestHeader(const QString& name, const QString& value);
|
||||
|
||||
/**jsdoc
|
||||
* Initializes a request.
|
||||
* @function XMLHttpRequest.open
|
||||
* @param {string} method - The <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods">HTTP request method</a>
|
||||
* to use, e.g., <code>"GET"</code>, <code>"POST"</code>, <code>"PUT"</code>, or <code>"DELETE"</code>.
|
||||
* @param {string} url - The URL to send the request to.
|
||||
* @param {boolean} [async=true] - <code>true</code> if the method returns without waiting for the response,
|
||||
* <code>false</code> if the method returns only once the request is complete.
|
||||
* @param {string} [username=""] - User name for authentication.
|
||||
* @param {string} [password=""] - Password for authentication.
|
||||
*/
|
||||
void open(const QString& method, const QString& url, bool async = true, const QString& username = "",
|
||||
const QString& password = "");
|
||||
|
||||
/**jsdoc
|
||||
* Sends the request to the server.
|
||||
* @function XMLHttpRequest.send
|
||||
* @param {*} [data] - The data to send.
|
||||
*/
|
||||
void send();
|
||||
void send(const QScriptValue& data);
|
||||
|
||||
/**jsdoc
|
||||
* Gets the response headers.
|
||||
* @function XMLHttpRequest.getAllResponseHeaders
|
||||
* @returns {string} The response headers, separated by <code>"\n"</code> characters.
|
||||
*/
|
||||
QScriptValue getAllResponseHeaders() const;
|
||||
|
||||
/**jsdoc
|
||||
* Gets a response header.
|
||||
* @function XMLHttpRequest.getResponseHeader
|
||||
* @param {string} name -
|
||||
* @returns {string} The response header.
|
||||
*/
|
||||
QScriptValue getResponseHeader(const QString& name) const;
|
||||
|
||||
signals:
|
||||
|
||||
/**jsdoc
|
||||
* Triggered when the request is complete — with or without error (incl. timeout).
|
||||
* @function XMLHttpRequest.requestComplete
|
||||
* @returns {Signal}
|
||||
*/
|
||||
void requestComplete();
|
||||
|
||||
private:
|
||||
|
|
@ -111,7 +307,58 @@ private:
|
|||
QScriptValue _onTimeout { QScriptValue::NullValue };
|
||||
QScriptValue _onReadyStateChange { QScriptValue::NullValue };
|
||||
ReadyState _readyState { XMLHttpRequestClass::UNSENT };
|
||||
|
||||
/**jsdoc
|
||||
* <p>The type of network error.</p>
|
||||
* <table>
|
||||
* <thead>
|
||||
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
|
||||
* </thead>
|
||||
* <tbody>
|
||||
* <tr><td><code>0</code></td><td>NoError</td><td>No error.</td></tr>
|
||||
* <tr><td><code>1</code></td><td>ConnectionRefusedError</td><td>The server refused the connection.</td></tr>
|
||||
* <tr><td><code>2</code></td><td>RemoteHostClosedError</td><td>The server closed the connection.</td></tr>
|
||||
* <tr><td><code>3</code></td><td>HostNotFoundError</td><td>Host name not found.</td></tr>
|
||||
* <tr><td><code>4</code></td><td>TimeoutError</td><td>Connection timed out</td></tr>
|
||||
* <tr><td><code>5</code></td><td>OperationCanceledError</td><td>Operation canceled by
|
||||
* {@link XMLHttpRequest.abort}.</td></tr>
|
||||
* <tr><td><code>6</code></td><td>SslHandshakeFailedError</td><td>SSL/TLS handshake failed.</td></tr>
|
||||
* <tr><td><code>7</code></td><td>TemporaryNetworkFailureError</td><td>Temporarily disconnected from the
|
||||
* network.</td></tr>
|
||||
* <tr><td><code>8</code></td><td>NetworkSessionFailedError</td><td>Disconnection from the network.</td></tr>
|
||||
* <tr><td><code>9</code></td><td>BackgroundRequestNotAllowedError</td><td>Background request not allowed.</td></tr>
|
||||
* <tr><td><code>10</code></td><td>TooManyRedirectsError</td><td>Too many redirects.</td></tr>
|
||||
* <tr><td><code>11</code></td><td>InsecureRedirectError</td><td>Redirect from secure to insecure protocol.</td></tr>
|
||||
* <tr><td><code>101</code></td><td>ProxyConnectionRefusedError</td><td>Connection to proxy server refused.</td></tr>
|
||||
* <tr><td><code>102</code></td><td>ProxyConnectionClosedError</td><td>Proxy server closed the connection.</td></tr>
|
||||
* <tr><td><code>103</code></td><td>ProxyNotFoundError</td><td>Proxy host name not found.</td></tr>
|
||||
* <tr><td><code>104</code></td><td>ProxyTimeoutError</td><td>Proxy connection timed out.</td></tr>
|
||||
* <tr><td><code>105</code></td><td>ProxyAuthenticationRequiredError</td><td>Proxy requires authentication.</td></tr>
|
||||
* <tr><td><code>201</code></td><td>ContentAccessDenied</td><td>Access denied.</td></tr>
|
||||
* <tr><td><code>202</code></td><td>ContentOperationNotPermittedError</td><td>Operation not permitted.</td></tr>
|
||||
* <tr><td><code>203</code></td><td>ContentNotFoundError</td><td>Content not found.</td></tr>
|
||||
* <tr><td><code>204</code></td><td>AuthenticationRequiredError</td><td>Authentication required.</td></tr>
|
||||
* <tr><td><code>205</code></td><td>ContentReSendError</td><td>Resend failed.</td></tr>
|
||||
* <tr><td><code>206</code></td><td>ContentConflictError</td><td>Resource state conflict.</td></tr>
|
||||
* <tr><td><code>207</code></td><td>ContentGoneError</td><td>Resource no longer available.</td></tr>
|
||||
* <tr><td><code>401</code></td><td>InternalServerError</td><td>Internal server error.</td></tr>
|
||||
* <tr><td><code>402</code></td><td>OperationNotImplementedError</td><td>Operation not supported.</td></tr>
|
||||
* <tr><td><code>403</code></td><td>ServiceUnavailableError</td><td>Request not able to be handled at this
|
||||
* time.</td></tr>
|
||||
* <tr><td><code>301</code></td><td>ProtocolUnknownError</td><td>Protocol unknown.</td></tr>
|
||||
* <tr><td><code>302</code></td><td>ProtocolInvalidOperationError</td><td>Operation invalid fro protocol.</td></tr>
|
||||
* <tr><td><code>99</code></td><td>UnknownNetworkError</td><td>Unknown network-related error.</td></tr>
|
||||
* <tr><td><code>199</code></td><td>UnknownProxyError</td><td>Unknown proxy-related error.</td></tr>
|
||||
* <tr><td><code>299</code></td><td>UnknownContentError</td><td>Unknown content-related error.</td></tr>
|
||||
* <tr><td><code>399</code></td><td>ProtocolFailure</td><td>Protocol error.</td></tr>
|
||||
* <tr><td><code>499</code></td><td>UnknownServerError</td><td>Unknown server response error.</td></tr>
|
||||
|
||||
* </tbody>
|
||||
* </table>
|
||||
* @typedef {number} XMLHttpRequest.NetworkError
|
||||
*/
|
||||
QNetworkReply::NetworkError _errorCode { QNetworkReply::NoError };
|
||||
|
||||
int _timeout { 0 };
|
||||
QTimer _timer;
|
||||
int _numRedirects { 0 };
|
||||
|
|
|
|||
Loading…
Reference in a new issue