From 9457aed631b3dfdefe9deb8b216d151f91fe581e Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 4 Sep 2019 15:43:18 +1200 Subject: [PATCH] Tidying and polishing Assets JSDoc --- libraries/networking/src/AssetClient.cpp | 6 +- .../src/BaseAssetScriptingInterface.h | 4 +- .../src/AssetScriptingInterface.cpp | 114 ++++++- .../src/AssetScriptingInterface.h | 288 ++++++------------ 4 files changed, 202 insertions(+), 210 deletions(-) diff --git a/libraries/networking/src/AssetClient.cpp b/libraries/networking/src/AssetClient.cpp index 0ba21e93cd..44f42caec2 100644 --- a/libraries/networking/src/AssetClient.cpp +++ b/libraries/networking/src/AssetClient.cpp @@ -226,10 +226,10 @@ namespace { /**jsdoc * Last-modified and expiry times for a cache item. * @typedef {object} Assets.SaveToCacheHeaders - * @property {string} [last-modified] - The date and time the cache value was last modified, in the format: - * "ddd, dd MMM yyyy HH:mm:ss". The default value is the current date and time. - * @property {string} [expires] - The date and time the cache value expires, in the format: + * @property {string} [expires] - The date and time the cache value expires, in the format: * "ddd, dd MMM yyyy HH:mm:ss". The default value is an invalid date, representing "never expires". + * @property {string} [last-modified] - The date and time the cache value was last modified, in the format: + * "ddd, dd MMM yyyy HH:mm:ss". The default value is the current date and time. */ /**jsdoc * Information on saving asset data to the cache with {@link Assets.saveToCache}. diff --git a/libraries/networking/src/BaseAssetScriptingInterface.h b/libraries/networking/src/BaseAssetScriptingInterface.h index ac2c211343..7d118e1979 100644 --- a/libraries/networking/src/BaseAssetScriptingInterface.h +++ b/libraries/networking/src/BaseAssetScriptingInterface.h @@ -26,16 +26,16 @@ class BaseAssetScriptingInterface : public QObject { public: /**jsdoc - *

Types of response that {@link Assets.getAsset}, {@link Assets.loadFromCache}, or {@link Assets.decompressData} may + *

Types of response that {@link Assets.decompressData}, {@link Assets.getAsset}, or {@link Assets.loadFromCache} may * provide.

* * * * * - * * * + * * *
ValueDescription
"text"UTF-8 decoded string value.
"arraybuffer"A binary ArrayBuffer object.
"json"A parsed JSON object.
"text"UTF-8 decoded string value.
* @typedef {string} Assets.ResponseType diff --git a/libraries/script-engine/src/AssetScriptingInterface.cpp b/libraries/script-engine/src/AssetScriptingInterface.cpp index c440aab830..db5776663c 100644 --- a/libraries/script-engine/src/AssetScriptingInterface.cpp +++ b/libraries/script-engine/src/AssetScriptingInterface.cpp @@ -81,6 +81,11 @@ void AssetScriptingInterface::setMapping(QString path, QString hash, QScriptValu setMappingRequest->start(); } +/**jsdoc + * The success or failure of an {@link Assets.downloadData} call. + * @typedef {object} Assets.DownloadDataError + * @property {string} errorMessage - "" if the download was successful, otherwise a description of the error. + */ void AssetScriptingInterface::downloadData(QString urlString, QScriptValue callback) { // FIXME: historically this API method failed silently when given a non-atp prefixed // urlString (or if the AssetRequest failed). @@ -215,6 +220,32 @@ void AssetScriptingInterface::deleteAsset(QScriptValue options, QScriptValue sco jsVerify(false, "TODO: deleteAsset API"); } +/**jsdoc + * Source and download options for {@link Assets.getAsset}. + * @typedef {object} Assets.GetOptions + * @property {boolean} [decompress=false] - true to gunzip decompress the downloaded data. Synonym: + * compressed. + * @property {Assets.ResponseType} [responseType="text"] - The desired result type. + * @property {string} url - The mapped path or hash to download. May have a leading "atp:". + */ +/**jsdoc + * Result value returned by {@link Assets.getAsset}. + * @typedef {object} Assets.GetResult + * @property {number} [byteLength] - The number of bytes in the downloaded content in response. + * @property {boolean} cached - true if the item was retrieved from the cache, false if it was + * downloaded. + * @property {string} [contentType] - The automatically detected MIME type of the content. + * @property {boolean} [decompressed] - true if the content was decompressed, false if it wasn't. + * @property {string} [hash] - The hash for the downloaded asset. + * @property {string} [hashURL] - The ATP URL of the hash file. + * @property {string} [path] - The path for the asset, if a path was requested. Otherwise, undefined. + * @property {string|object|ArrayBuffer} [response] - The downloaded content. + * @property {Assets.ResponseType} [responseType] - The type of the downloaded content in response. + * @property {string} [url] - The URL of the asset requested: the path with leading "atp:" if a path was + * requested, otherwise the requested URL. + * @property {boolean} [wasRedirected] - true if the downloaded data is the baked version of the asset, + * false if it isn't baked. + */ void AssetScriptingInterface::getAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) { JS_VERIFY(options.isObject() || options.isString(), "expected request options Object or URL as first parameter"); @@ -262,6 +293,22 @@ void AssetScriptingInterface::getAsset(QScriptValue options, QScriptValue scope, } } +/**jsdoc + * Source options for {@link Assets.resolveAsset}. + * @typedef {object} Assets.ResolveOptions + * @property {string} url - The hash or path to resolve. May have a leading "atp:". + */ +/**jsdoc + * Result value returned by {@link Assets.resolveAsset}. + *

Note: If resolving a hash, a file of that hash need not be present on the asset server for the hash to resolve.

+ * @typedef {object} Assets.ResolveResult + * @property {string} [hash] - The hash of the asset. + * @property {string} [hashURL] - The url of the asset's hash file, with leading atp:. + * @property {string} [path] - The path to the asset. + * @property {string} [url] - The URL of the asset. + * @property {boolean} [wasRedirected] - true if the resolved data is for the baked version of the asset, + * false if it isn't. + */ void AssetScriptingInterface::resolveAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) { const QString& URL{ "url" }; @@ -274,6 +321,21 @@ void AssetScriptingInterface::resolveAsset(QScriptValue options, QScriptValue sc jsPromiseReady(getAssetInfo(asset), scope, callback); } +/**jsdoc + * Content and decompression options for {@link Assets.decompressData}. + * @typedef {object} Assets.DecompressOptions + * @property {ArrayBuffer} data - The data to decompress. + * @property {Assets.ResponseType} [responseType=text] - The type of decompressed data to return. + */ +/**jsdoc + * Result value returned by {@link Assets.decompressData}. + * @typedef {object} Assets.DecompressResult + * @property {number} [byteLength] - The number of bytes in the decompressed data. + * @property {string} [contentType] - The MIME type of the decompressed data. + * @property {boolean} [decompressed] - true if the data is decompressed. + * @property {string|object|ArrayBuffer} [response] - The decompressed data. + * @property {Assets.ResponseType} [responseType] - The type of the decompressed data in response. + */ void AssetScriptingInterface::decompressData(QScriptValue options, QScriptValue scope, QScriptValue callback) { auto data = options.property("data"); QByteArray dataByteArray = qscriptvalue_cast(data); @@ -298,6 +360,23 @@ namespace { const int32_t DEFAULT_GZIP_COMPRESSION_LEVEL = -1; const int32_t MAX_GZIP_COMPRESSION_LEVEL = 9; } + +/**jsdoc + * Content and compression options for {@link Assets.compressData}. + * @typedef {object} Assets.CompressOptions + * @property {string|ArrayBuffer} data - The data to compress. + * @property {number} level - The compression level, range -1 – 9. -1 means + * use the default gzip compression level, 0 means no compression, and 9 means maximum + * compression. + */ +/**jsdoc + * Result value returned by {@link Assets.compressData}. + * @typedef {object} Assets.CompressResult + * @property {number} [byteLength] - The number of bytes in the compressed data. + * @property {boolean} [compressed] - true if the data is compressed. + * @property {string} [contentType] - The MIME type of the compressed data, i.e., "application/gzip". + * @property {ArrayBuffer} [data] - The compressed data. + */ void AssetScriptingInterface::compressData(QScriptValue options, QScriptValue scope, QScriptValue callback) { auto data = options.property("data").isValid() ? options.property("data") : options; QByteArray dataByteArray = data.isString() ? data.toString().toUtf8() : qscriptvalue_cast(data); @@ -306,6 +385,27 @@ void AssetScriptingInterface::compressData(QScriptValue options, QScriptValue sc jsPromiseReady(compressBytes(dataByteArray, level), scope, callback); } +/**jsdoc + * Content and upload options for {@link Assets.putAsset}. + * @typedef {object} Assets.PutOptions + * @property {boolean} [compress=false] - true to gzip compress the content for upload and storage, + * false to upload and store the data without gzip compression. Synonym: compressed. + * @property {string|ArrayBuffer} data - The content to upload. + * @property {string} [path] - A user-friendly path for the file in the asset server. May have a leading + * "atp:". IF not specified, no path-to-hash mapping is set. + *

Note: The asset server destroys any unmapped SHA256-named file at server restart. Either set the mapping path + * with this property or use {@link Assets.setMapping} to set a path-to-hash mapping for the uploaded file.

+ */ +/**jsdoc + * Result value returned by {@link Assets.putAsset}. + * @typedef {object} Assets.PutResult + * @property {number} [byteLength] - The number of bytes in the hash file stored on the asset server. + * @property {boolean} [compressed] - true if the content stored is gzip compressed. + * @property {string} [contentType] - "application/gzip" if the content stored is gzip compressed. + * @property {string} [hash] - The SHA256 hash of the content. + * @property {string} [url] - The atp: URL of the content: using the path if specified, otherwise the hash. + * @property {string} [path] - The uploaded content's mapped path, if specified. + */ void AssetScriptingInterface::putAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) { auto compress = options.property("compress").toBool() || options.property("compressed").toBool(); auto data = options.isObject() ? options.property("data") : options; @@ -356,6 +456,12 @@ void AssetScriptingInterface::putAsset(QScriptValue options, QScriptValue scope, } } +/**jsdoc + * Source for {@link Assets.queryCacheMeta}. + * @typedef {object} Assets.QueryCacheMetaOptions + * @property {string} url - The URL of the cached asset to get information on. Must start with "atp:" or + * "cache:". + */ void AssetScriptingInterface::queryCacheMeta(QScriptValue options, QScriptValue scope, QScriptValue callback) { QString url = options.isString() ? options.toString() : options.property("url").toString(); JS_VERIFY(QUrl(url).isValid(), QString("Invalid URL '%1'").arg(url)); @@ -365,11 +471,11 @@ void AssetScriptingInterface::queryCacheMeta(QScriptValue options, QScriptValue /**jsdoc * Source and retrieval options for {@link Assets.loadFromCache}. * @typedef {object} Assets.LoadFromCacheOptions - * @property {string} url - The URL of the asset to load from cache. Must start with "atp:" or - * "cache:". - * @property {Assets.ResponseType} [responseType=text] - The desired result type. - * @property {boolean} [decompress=false] - true to gunzip decompress the cached data. Synonym: + * @property {boolean} [decompress=false] - true to gunzip decompress the cached data. Synonym: * compressed. + * @property {Assets.ResponseType} [responseType=text] - The desired result type. + * @property {string} url - The URL of the asset to load from cache. Must start with "atp:" or + * "cache:". */ void AssetScriptingInterface::loadFromCache(QScriptValue options, QScriptValue scope, QScriptValue callback) { QString url, responseType; diff --git a/libraries/script-engine/src/AssetScriptingInterface.h b/libraries/script-engine/src/AssetScriptingInterface.h index 8a0ec27817..c4c7940a80 100644 --- a/libraries/script-engine/src/AssetScriptingInterface.h +++ b/libraries/script-engine/src/AssetScriptingInterface.h @@ -25,9 +25,15 @@ #include /**jsdoc - * The Assets API provides facilities for interacting with the domain's asset server. Assets are stored in the - * asset server in files with SHA256 names. These files are mapped to user-friendly URLs of the format: - * atp:/path/filename. + * The Assets API provides facilities for interacting with the domain's asset server and the client cache. + * cache. + *

Assets are stored in the asset server in files with SHA256 names. These files are mapped to user-friendly URLs of the + * format: atp:/path/filename. The assets may optionally be baked, in which case a request for the original + * unbaked version of the asset is automatically redirected to the baked version. The asset data may optionally be stored as + * compressed.

+ *

The client cache can be access directly, using "atp:" "cache:" URLs. Interface, avatar, and + * assignment client scripts can write to the cache. All script types can read from the cache.

+ * * @namespace Assets * * @hifi-interface @@ -69,6 +75,12 @@ public: */ Q_INVOKABLE void uploadData(QString data, QScriptValue callback); + /**jsdoc + * Called when an {@link Assets.downloadData} call is complete. + * @callback Assets~downloadDataCallback + * @param {string} data - The content that was downloaded. + * @param {Assets.DownloadDataError} error - The success or failure of the download. + */ /**jsdoc * Downloads content from the asset server, form a SHA256-named file. * @function Assets.downloadData @@ -97,19 +109,13 @@ public: * }); * }, 1000); */ - /**jsdoc - * Called when an {@link Assets.downloadData} call is complete. - * @callback Assets~downloadDataCallback - * @param {string} data - The content that was downloaded. - * @param {Assets.DownloadDataError} error - The success or failure of the download. - */ - /**jsdoc - * The success or failure of an {@link Assets.downloadData} call. - * @typedef {object} Assets.DownloadDataError - * @property {string} errorMessage - "" if the download was successful, otherwise a description of the error. - */ Q_INVOKABLE void downloadData(QString url, QScriptValue callback); + /**jsdoc + * Called when an {@link Assets.setMapping} call is complete. + * @callback Assets~setMappingCallback + * @param {string} error - null if the path-to-hash mapping was set, otherwise a description of the error. + */ /**jsdoc * Sets a path-to-hash mapping within the asset server. * @function Assets.setMapping @@ -117,13 +123,14 @@ public: * @param {string} hash - The hash in the asset server. * @param {Assets~setMappingCallback} callback - The function to call upon completion. */ - /**jsdoc - * Called when an {@link Assets.setMapping} call is complete. - * @callback Assets~setMappingCallback - * @param {string} error - null if the path-to-hash mapping was set, otherwise a description of the error. - */ Q_INVOKABLE void setMapping(QString path, QString hash, QScriptValue callback); + /**jsdoc + * Called when an {@link Assets.getMapping} call is complete. + * @callback Assets~getMappingCallback + * @param {string} error - null if the path was found, otherwise a description of the error. + * @param {string} hash - The hash value if the path was found, "" if it wasn't. + */ /**jsdoc * Gets the hash for a path within the asset server. The hash is for the unbaked or baked version of the * asset, according to the asset server setting for the particular path. @@ -140,14 +147,14 @@ public: * }); * } */ - /**jsdoc - * Called when an {@link Assets.getMapping} call is complete. - * @callback Assets~getMappingCallback - * @param {string} error - null if the path was found, otherwise a description of the error. - * @param {string} hash - The hash value if the path was found, "" if it wasn't. - */ Q_INVOKABLE void getMapping(QString path, QScriptValue callback); + /**jsdoc + * Called when an {@link Assets.setBakingEnabled} call is complete. + * @callback Assets~setBakingEnabledCallback + * @param {string} error - null if baking was successfully enabled or disabled, otherwise a description of the + * error. + */ /**jsdoc * Sets whether or not to bake an asset in the asset server. * @function Assets.setBakingEnabled @@ -155,12 +162,6 @@ public: * @param {boolean} enabled - true to enable baking of the asset, false to disable. * @param {Assets~setBakingEnabledCallback} callback - The function to call upon completion. */ - /**jsdoc - * Called when an {@link Assets.setBakingEnabled} call is complete. - * @callback Assets~setBakingEnabledCallback - * @param {string} error - null if baking was successfully enabled or disabled, otherwise a description of the - * error. - */ // Note: Second callback parameter not documented because it's always {}. Q_INVOKABLE void setBakingEnabled(QString path, bool enabled, QScriptValue callback); @@ -177,50 +178,32 @@ public: * @typedef {object} Assets.CallbackDetails * @property {object} scope - The scope that the callback function is defined in. This object is bound to * this when the function is called. - * @property {Assets~putAssetCallback|Assets~getAssetCallback|Assets~resolveAssetCallback|Assets~compressDataCallback - * |Assets~decompressDataCallback} + * @property {Assets~compressDataCallback|Assets~decompressDataCallback|Assets~getAssetCallback + * |Assets~getCacheStatusCallback|Assets~loadFromCacheCallback|Assets~putAssetCallback|Assets~queryCacheMetaCallback + * |Assets~resolveAssetCallback|Assets~saveToCacheCallback} * callback - The function to call upon completion. May be an inline function or a function identifier. If a function * identifier, it must be a member of scope. */ - /**jsdoc - * Source and download options for {@link Assets.getAsset}. - * @typedef {object} Assets.GetOptions - * @property {string} url - The mapped path or hash to download. May have a leading "atp:". - * @property {Assets.ResponseType} [responseType="text"] - The desired result type. - * @property {boolean} [decompress=false] - true to gunzip decompress the downloaded data. Synonym: - * compressed. - */ /**jsdoc * Called when an {@link Assets.getAsset} call is complete. * @callback Assets~getAssetCallback * @param {string} error - null if the content was downloaded, otherwise a description of the error. * @param {Assets.GetResult} result - Information on and the content downloaded. */ - /**jsdoc - * Result value returned by {@link Assets.getAsset}. - * @typedef {object} Assets.GetResult - * @property {number} [byteLength] - The number of bytes in the downloaded response. - * @property {boolean} cached - - * @property {string} [contentType] - Automatically detected MIME type of the content. - * @property {boolean} [decompressed] - true if the content was decompressed, false if it wasn't. - * @property {string} [hash] - The hash for the downloaded asset. - * @property {string} [hashURL] - The ATP URL of the hash file. - * @property {string} [path] - The path for the asset, if a path was requested. Otherwise, undefined. - * @property {string|ArrayBuffer|object} [response] - The downloaded content. - * @property {Assets.ResponseType} [responseType] - The type of the downloaded content. - * @property {string} [url] - The URL of the asset requested: the path with leading "atp:" if a path was - * requested, otherwise the requested URL. - * @property {boolean} [wasRedirected] - true if the downloaded data is the baked version of the asset, - * false if it isn't baked. - */ /**jsdoc * Downloads content from the asset server. * @function Assets.getAsset - * @param {Assets.GetOptions|string} source - What to download and download options. If a string, the mapped path or hash + * @param {string|Assets.GetOptions} source - What to download and download options. If a string, the mapped path or hash * to download, optionally including a leading "atp:". - * @param {Assets.CallbackDetails|Assets~getAssetCallback} callback - The function to call upon completion. May be a - * function identifier or an inline function. + * @param {object|Assets.CallbackDetails|Assets~getAssetCallback} scopeOrCallback - If an object, then the scope that + * the callback function is defined in. This object is bound to this when the function is + * called. + *

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

+ * @param {Assets~getAssetCallback} [callback] - Used if scopeOrCallback specifies the scope. + *

The function to call upon completion. May be an inline function, a function identifier, or the name of a function + * in a string. If the name of a function or a function identifier, it must be a member of the scope specified by + * scopeOrCallback.

* @example Retrieve a string from the asset server. * Assets.getAsset( * { @@ -236,30 +219,8 @@ public: * } * ); */ - /**jsdoc - * Downloads content from the asset server. - * @function Assets.getAsset - * @param {Assets.GetOptions|string} source - What to download and download options. If a string, the mapped path or hash - * to download, optionally including a leading "atp:". - * @param {object} scope - The scope that the callback function is defined in. This object is bound to - * this when the function is called. - * @param {Assets~getAssetCallback} callback - The function to call upon completion. May be an inline function, a function - * identifier, or the name of a function in a string. If the name of a function or a function identifier, it must be - * a member of scope. - */ Q_INVOKABLE void getAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue()); - /**jsdoc - * Content and upload options for {@link Assets.putAsset}. - * @typedef {object} Assets.PutOptions - * @property {string|ArrayBuffer} data - The content to upload. - * @property {string} [path] - A user-friendly path for the file in the asset server. May have a leading - * "atp:". - *

Note: The asset server destroys any unmapped SHA256-named file at server restart. Either set the mapping path - * with this property or use {@link Assets.setMapping} to set a path-to-hash mapping for the uploaded file.

- * @property {boolean} [compress=false] - true to gzip compress the content for upload and storage, - * false to upload and store the data without gzip compression. Synonym: compressed. - */ /**jsdoc * Called when an {@link Assets.putAsset} call is complete. * @callback Assets~putAssetCallback @@ -267,23 +228,19 @@ public: * description of the error. * @param {Assets.PutResult} result - Information on the content uploaded. */ - /**jsdoc - * Result value returned by {@link Assets.putAsset}. - * @typedef {object} Assets.PutResult - * @property {number} [byteLength] - The number of bytes in the hash file stored on the asset server. - * @property {boolean} [compressed] - true if the content stored is gzip compressed. - * @property {string} [contentType] - "application/gzip" if the content stored is gzip compressed. - * @property {string} [hash] - The SHA256 hash of the content. - * @property {string} [url] - The atp: URL of the content: using the path if specified, otherwise the hash. - * @property {string} [path] - The uploaded content's mapped path, if specified. - */ /**jsdoc * Uploads content to the assert server and sets a path-to-hash mapping. * @function Assets.putAsset - * @param {Assets.PutOptions|string} options - The content to upload and upload options. If a string, the value of the + * @param {string|Assets.PutOptions} options - The content to upload and upload options. If a string, the value of the * string is uploaded but a path-to-hash mapping is not set. - * @param {Assets.CallbackDetails|Assets~putAssetCallback} callback - The function to call upon completion. May be an - * inline function or a function identifier. + * @param {object|Assets.CallbackDetails|Assets~putAssetCallback} scopeOrCallback - If an object, then the scope that + * the callback function is defined in. This object is bound to this when the function is + * called. + *

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

+ * @param {Assets~putAssetCallback} [callback] - Used if scopeOrCallback specifies the scope. + *

The function to call upon completion. May be an inline function, a function identifier, or the name of a function + * in a string. If the name of a function or a function identifier, it must be a member of the scope specified by + * scopeOrCallback.

* @example Store a string in the asset server. * Assets.putAsset( * { @@ -299,17 +256,6 @@ public: * } * ); */ - /**jsdoc - * Uploads content to the assert server and sets a path-to-hash mapping. - * @function Assets.putAsset - * @param {Assets.PutOptions|string} options - The content to upload and upload options. If a string, the value of the - * string is uploaded but a path-to-hash mapping is not set. - * @param {object} scope - The scope that the callback function is defined in. This object is bound to - * this when the function is called. - * @param {Assets~getAssetCallback} callback - The function to call upon completion. May be an inline function, a function - * identifier, or the name of a function in a string. If the name of a function or a function identifier, it must be - * a member of scope. - */ Q_INVOKABLE void putAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue()); /**jsdoc @@ -329,35 +275,25 @@ public: */ Q_INVOKABLE void deleteAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue()); - /**jsdoc - * Source options for {@link Assets.resolveAsset}. - * @typedef {object} Assets.ResolveOptions - * @property {string} url - The hash or path to resolve. May have a leading "atp:". - */ /**jsdoc * Called when an {@link Assets.resolveAsset} call is complete. * @callback Assets~resolveAssetCallback * @param {string} error - null if the asset hash or path was resolved, otherwise a description of the error. * @param {Assets.ResolveResult} result - Information on the hash or path resolved. */ - /**jsdoc - * Result value returned by {@link Assets.resolveAsset}. - *

Note: If resolving a hash, a file of that hash need not be present on the asset server for the hash to resolve.

- * @typedef {object} Assets.ResolveResult - * @property {string} [hash] - The hash of the asset. - * @property {string} [hashURL] - The url of the asset's hash file, with leading atp:. - * @property {string} [path] - The path to the asset. - * @property {string} [url] - The URL of the asset. - * @property {boolean} [wasRedirected] - true if the resolved data is for the baked version of the asset, - * false if it isn't. - */ /**jsdoc * Resolves and returns information on a hash or a path in the asset server. * @function Assets.resolveAsset * @param {string|Assets.ResolveOptions} source - The hash or path to resolve if a string, otherwise an object specifying * what to resolve. If a string, it may have a leading "atp:". - * @param {Assets.CallbackDetails|Assets~resolveAssetCallback} callback - The function to call upon completion. May be a - * function identifier or an inline function. + * @param {object|Assets.CallbackDetails|Assets~resolveAssetCallback} scopeOrCallback - If an object, then the scope that + * the callback function is defined in. This object is bound to this when the function is + * called. + *

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

+ * @param {Assets~resolveAssetCallback} [callback] - Used if scopeOrCallback specifies the scope. + *

The function to call upon completion. May be an inline function, a function identifier, or the name of a function + * in a string. If the name of a function or a function identifier, it must be a member of the scope specified by + * scopeOrCallback.

* @example Get the hash and URL for a path. * Assets.resolveAsset( * "/assetsExamples/helloWorld.txt", @@ -371,111 +307,60 @@ public: * } * ); */ - /**jsdoc - * Resolves and returns information on a hash or a path in the asset server. - * @function Assets.resolveAsset - * @param {string|Assets.ResolveOptions} source - The hash or path to resolve if a string, otherwise an object specifying - * what to resolve. If a string, it may have a leading "atp:". - * @param {object} scope - The scope that the callback function is defined in. This object is bound to - * this when the function is called. - * @param {Assets~resolveAssetCallback} callback - The function to call upon completion. May be an inline function, a - * function identifier, or the name of a function in a string. If the name of a function or a function identifier, it - * must be a member of scope. - */ Q_INVOKABLE void resolveAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue()); - /**jsdoc - * Content and decompression options for {@link Assets.decompressData}. - * @typedef {object} Assets.DecompressOptions - * @property {ArrayBuffer} data - The data to decompress. - * @property {Assets.ResponseType} [responseType=text] - The type of data to return. - */ /**jsdoc * Called when an {@link Assets.decompressData} call is complete. * @callback Assets~decompressDataCallback * @param {string} error - null if the data was successfully compressed, otherwise a description of the error. * @param {Assets.DecompressResult} result - Information on and the decompressed data. */ - /**jsdoc - * Result value returned by {@link Assets.decompressData}. - * @typedef {object} Assets.DecompressResult - * @property {number} [byteLength] - The number of bytes in the decompressed data. - * @property {string} [contentType] - The MIME type of the decompressed data. - * @property {boolean} [decompressed] - true if the data is decompressed. - * @property {string|ArrayBuffer|object} [response] - The decompressed data. - * @property {Assets.ResponseType} [responseType] - The type of the response. - */ /**jsdoc * Decompresses data in memory using gunzip. * @function Assets.decompressData * @param {Assets.DecompressOptions} source - What to decompress and decompression options. - * @param {Assets.CallbackDetails|Assets~decompressDataCallback} callback - The function to call upon completion. May be a - * function identifier or an inline function. - */ - /**jsdoc - * Decompresses data in memory using gunzip. - * @function Assets.decompressData - * @param {Assets.DecompressOptions} source - What to decompress and decompression options. - * @param {object} scope - The scope that the callback function is defined in. This object is bound to - * this when the function is called. - * @param {Assets~decompressDataCallback} callback - The function to call upon completion. May be an inline function, a - * function identifier, or the name of a function in a string. If the name of a function or a function identifier, it - * must be a member of scope. + * @param {object|Assets.CallbackDetails|Assets~decompressDataCallback} scopeOrCallback - If an object, then the scope that + * the callback function is defined in. This object is bound to this when the function is + * called. + *

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

+ * @param {Assets~decompressDataCallback} [callback] - Used if scopeOrCallback specifies the scope. + *

The function to call upon completion. May be an inline function, a function identifier, or the name of a function + * in a string. If the name of a function or a function identifier, it must be a member of the scope specified by + * scopeOrCallback.

*/ Q_INVOKABLE void decompressData(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue()); - /**jsdoc - * Content and compression options for {@link Assets.compressData}. - * @typedef {object} Assets.CompressOptions - * @property {ArrayBuffer|string} data - The data to compress. - * @property {number} level - The compression level, range -1 – 9. -1 means - * use the default gzip compression level, 0 means no compression, and 9 means maximum - * compression. - */ /**jsdoc * Called when an {@link Assets.compressData} call is complete. * @callback Assets~compressDataCallback * @param {string} error - null if the data was successfully compressed, otherwise a description of the error. * @param {Assets.CompressResult} result - Information on and the compressed data. */ - /**jsdoc - * Result value returned by {@link Assets.compressData}. - * @typedef {object} Assets.CompressResult - * @property {boolean} [compressed] - true if the data is compressed. - * @property {number} [byteLength] - The number of bytes in the compressed data. - * @property {string} [contentType] - The MIME type of the compressed data, i.e., "application/gzip". - * @property {ArrayBuffer} [data] - The compressed data. - */ /**jsdoc * Compresses data in memory using gzip. * @function Assets.compressData - * @param {Assets.CompressOptions|ArrayBuffer|string} source - What to compress and compression options. If an ArrayBuffer - * or a string, the data to compress. - * @param {Assets.CallbackDetails|Assets~compressDataCallback} callback - The function to call upon completion. May be a - * function identifier or an inline function. - */ - /**jsdoc - * Compresses data in memory using gzip. - * @function Assets.compressData - * @param {Assets.CompressOptions|ArrayBuffer|string} source - What to compress and compression options. If an ArrayBuffer - * or a string, the data to compress. - * @param {object} scope - The scope that the callback function is defined in. This object is bound to - * this when the function is called. - * @param {Assets~compressDataCallback} callback - The function to call upon completion. May be an inline function, a - * function identifier, or the name of a function in a string. If the name of a function or a function identifier, it - * must be a member of scope. + * @param {string|ArrayBuffer|Assets.CompressOptions} source - What to compress and compression options. If a string or + * ArrayBuffer, the data to compress. + * @param {object|Assets.CallbackDetails|Assets~compressDataCallback} scopeOrCallback - If an object, then the scope that + * the callback function is defined in. This object is bound to this when the function is + * called. + *

Otherwise, the function to call upon completion. This may be an inline function or a function identifier.

+ * @param {Assets~compressDataCallback} [callback] - Used if scopeOrCallback specifies the scope. + *

The function to call upon completion. May be an inline function, a function identifier, or the name of a function + * in a string. If the name of a function or a function identifier, it must be a member of the scope specified by + * scopeOrCallback.

*/ Q_INVOKABLE void compressData(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue()); /**jsdoc - * Initializes the local cache if it isn't already initialized. + * Initializes the cache if it isn't already initialized. * @function Assets.initializeCache - * @returns {boolean} true if the local cache is initialized, false if it isn't. + * @returns {boolean} true if the cache is initialized, false if it isn't. */ Q_INVOKABLE bool initializeCache() { return Parent::initializeCache(); } /**jsdoc - * Checks whether the script can write to the local cache. + * Checks whether the script can write to the cache. * @function Assets.canWriteCacheValue * @param {string} url - Not used. * @returns {boolean} true if the script is an Interface, avatar, or assignment client script, @@ -490,7 +375,7 @@ public: * @callback Assets~getCacheStatusCallback * @param {string} error - null if the cache status was retrieved without error, otherwise a description of * the error. - * @param {Assets.GetCacheStatusResult} status - Details of the current cache status. + * @param {Assets.GetCacheStatusResult} result - Details of the current cache status. */ /**jsdoc * Gets the current cache status. @@ -518,13 +403,14 @@ public: * Called when {@link Assets.queryCacheMeta} is complete. * @callback Assets~queryCacheMetaCallback * @param {string} error - null if the URL has a valid cache entry, otherwise a description of the error. - * @param {Assets.CacheItemMetaData} queryResult - Information on an asset in the cache. + * @param {Assets.CacheItemMetaData} result - Information on an asset in the cache. */ /**jsdoc * Gets information about the status of an asset in the cache. * @function Assets.queryCacheMeta - * @param {string|object} path - The URL of the cached asset to get information on. If an object then path.url - * is used. Must start with "atp:" or "cache:". + * @param {string|Assets.QueryCacheMetaOptions} path - The URL of the cached asset to get information on if a string, + * otherwise an object specifying the cached asset to get information on. The URL must start with "atp:" + * or "cache:". * @param {object|Assets.CallbackDetails|Assets~queryCacheMetaCallback} scopeOrCallback - If an object, then the scope that * the callback function is defined in. This object is bound to this when the function is * called.