Mirrors/overte
3
0
Fork 0
mirror of https://github.com/overte-org/overte.git synced 2025-08-09 10:07:58 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Assets API methods that include mappings JSDoc

Browse source
This commit is contained in:
David Rowe 2019-08-21 12:36:37 +12:00
parent 817bc6cd43
commit 5f3081784c
3 changed files with 217 additions and 76 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
libraries/networking/src/BaseAssetScriptingInterface.h
View file

@ -24,6 +24,21 @@
class BaseAssetScriptingInterface : public QObject { class BaseAssetScriptingInterface : public QObject {
Q_OBJECT Q_OBJECT
public: public:
/**jsdoc
* <p>Types of response that {@link Assets.getAsset} and {@link Assets.loadFromCache} may provide.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"text"</code></td><td>UTF-8 decoded <code>string</code> value.</td></tr>
* <tr><td><code>"arraybuffer"</code></td><td>A binary <code>ArrayBuffer</code> object.</td></tr>
* <tr><td><code>"json"</code></td><td>A parsed <code>JSON</code> object.</td></tr>
* </tbody>
* </table>
* @typedef {string} Assets.ResponseType
*/
const QStringList RESPONSE_TYPES{ "text", "arraybuffer", "json" }; const QStringList RESPONSE_TYPES{ "text", "arraybuffer", "json" };
using Promise = MiniPromise::Promise; using Promise = MiniPromise::Promise;
QSharedPointer<AssetClient> assetClient(); QSharedPointer<AssetClient> assetClient();

15
libraries/script-engine/src/AssetScriptingInterface.cpp
View file

@ -215,21 +215,6 @@ void AssetScriptingInterface::deleteAsset(QScriptValue options, QScriptValue sco
jsVerify(false, "TODO: deleteAsset API"); jsVerify(false, "TODO: deleteAsset API");
} }
/**jsdoc
* @typedef {string} Assets.GetOptions.ResponseType
* <p>Available <code>responseType</code> values for use with @{link Assets.getAsset} and @{link Assets.loadFromCache} configuration option. </p>
* <table>
* <thead>
* <tr><th>responseType</th><th>typeof response value</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"text"</code></td><td>contents returned as utf-8 decoded <code>String</code> value</td></tr>
* <tr><td><code>"arraybuffer"</code></td><td>contents as a binary <code>ArrayBuffer</code> object</td></tr>
* <tr><td><code>"json"</code></td><td>contents as a parsed <code>JSON</code> object</td></tr>
* </tbody>
* </table>
*/
void AssetScriptingInterface::getAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) { void AssetScriptingInterface::getAsset(QScriptValue options, QScriptValue scope, QScriptValue callback) {
JS_VERIFY(options.isObject() || options.isString(), "expected request options Object or URL as first parameter"); JS_VERIFY(options.isObject() || options.isString(), "expected request options Object or URL as first parameter");

263
libraries/script-engine/src/AssetScriptingInterface.h
View file

@ -173,94 +173,235 @@ public:
#endif #endif
/**jsdoc /**jsdoc
* Request Asset data from the ATP Server * Details of a callback function.
* @function Assets.getAsset * @typedef {object} Assets.CallbackDetails
* @param {URL|Assets.GetOptions} options An atp: style URL, hash, or relative mapped path; or an {@link Assets.GetOptions} object with request parameters * @property {object} scope - The scope that the <code>callback</code> function is defined in. This object is bound to
* @param {Assets~getAssetCallback} scope A scope callback function to receive (error, results) values * <code>this</code> when the function is called.
* @param {function} [callback=undefined] * @property {Assets~putAssetCallback|Assets~getAssetCallback|Assets~resolveAssetCallback} 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 <code>scope</code>.
*/ */
/**jsdoc /**jsdoc
* A set of properties that can be passed to {@link Assets.getAsset}. * Source and download options for {@link Assets.getAsset}.
* @typedef {object} Assets.GetOptions * @typedef {object} Assets.GetOptions
* @property {string} [url] an "atp:" style URL, hash, or relative mapped path to fetch * @property {string} url - The mapped path or hash to download. May have a leading <code>"atp:"</code>.
* @property {string} [responseType=text] the desired reponse type (text | arraybuffer | json) * @property {Assets.ResponseType} [responseType="text"] - The desired result type.
* @property {boolean} [decompress=false] whether to attempt gunzip decompression on the fetched data * @property {boolean} [decompress=false] - <code>true</code> to gunzip decompress the downloaded data. Synonym:
* See: {@link Assets.putAsset} and its .compress=true option * <code>compressed</code>.
*/ */
/**jsdoc /**jsdoc
* Called when Assets.getAsset is complete. * Called when an {@link Assets.getAsset} call is complete.
* @callback Assets~getAssetCallback * @callback Assets~getAssetCallback
* @param {string} error - contains error message or null value if no error occured fetching the asset * @param {string} error - <code>null</code> if the content was downloaded, otherwise a description of the error.
* @param {Asset~getAssetResult} result - result object containing, on success containing asset metadata and contents * @param {Assets.GetResult} result - Information on and the content downloaded.
*/ */
/**jsdoc /**jsdoc
* Result value returned by {@link Assets.getAsset}. * Result value returned by {@link Assets.getAsset}.
* @typedef {object} Assets~getAssetResult * @typedef {object} Assets.GetResult
* @property {string} [url] the resolved "atp:" style URL for the fetched asset * @property {number} [byteLength] - The number of bytes in the downloaded response.
* @property {string} [hash] the resolved hash for the fetched asset * @property {boolean} cached -
* @property {string|ArrayBuffer|Object} [response] response data (possibly converted per .responseType value) * @property {string} [contentType] - Automatically detected MIME type of the content.
* @property {string} [responseType] response type (text | arraybuffer | json) * @property {boolean} [decompressed] - <code>true</code> if the content was decompressed, <code>false</code> if it wasn't.
* @property {string} [contentType] detected asset mime-type (autodetected) * @property {string} [hash] - The hash for the downloaded asset.
* @property {number} [byteLength] response data size in bytes * @property {string} [hashURL] - The ATP URL of the hash file.
* @property {number} [decompressed] flag indicating whether data was decompressed * @property {string} [path] - The path for the asset, if a path was requested. Otherwise, <code>undefined</code>.
* @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 <code>"atp:"</code> if a path was
* requested, otherwise the requested URL.
* @property {boolean} [wasRedirected] - <code>true</code> if the downloaded data is the baked version of the asset,
* <code>false</code> 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
* to download, optionally including a leading <code>"atp:"</code>.
* @param {Assets~getAssetCallback} callback - The function to call upon completion. May be a function identifier or an
* inline function.
* @example <caption>Retrieve a string from the asset server.</caption>
* Assets.getAsset(
* {
* url: "/assetsExamples/helloWorld.txt",
* responseType: "text"
* },
* function (error, result) {
* if (error) {
* print("ERROR: Data not downloaded");
* } else {
* print("Data: " + result.response);
* }
* }
* );
*/
/**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 <code>"atp:"</code>.
* @param {object} scope - The scope that the <code>callback</code> function is defined in. This object is bound to
* <code>this</code> 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 <code>scope</code>.
*/
/**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 <code>"atp:"</code>.
* @param {Assets.CallbackDetails} callbackDetails - Details of the function to call upon completion.
*/ */
Q_INVOKABLE void getAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue()); Q_INVOKABLE void getAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue());
/**jsdoc /**jsdoc
* Upload Asset data to the ATP Server * Content and upload options for {@link Assets.putAsset}.
* @function Assets.putAsset
* @param {Assets.PutOptions} options A PutOptions object with upload parameters
* @param {Assets~putAssetCallback} scope[callback] A scoped callback function invoked with (error, results)
* @param {function} [callback=undefined]
*/
/**jsdoc
* A set of properties that can be passed to {@link Assets.putAsset}.
* @typedef {object} Assets.PutOptions * @typedef {object} Assets.PutOptions
* @property {ArrayBuffer|string} [data] byte buffer or string value representing the new asset's content * @property {string|ArrayBuffer} data - The content to upload.
* @property {string} [path=null] ATP path mapping to automatically create (upon successful upload to hash) * @property {string} [path] - A user-friendly path for the file in the asset server. May have a leading
* @property {boolean} [compress=false] whether to gzip compress data before uploading * <code>"atp:"</code>.
* <p>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.</p>
* @property {boolean} [compress=false] - <code>true</code> to gzip compress the content for upload and storage,
* <code>false</code> to upload and store the data without gzip compression. Synonym: <code>compressed</code>.
*/ */
/**jsdoc /**jsdoc
* Called when Assets.putAsset is complete. * Called when an {@link Assets.putAsset} call is complete.
* @callback Assets~puttAssetCallback * @callback Assets~putAssetCallback
* @param {string} error - contains error message (or null value if no error occured while uploading/mapping the new asset) * @param {string} error - <code>null</code> if the content was uploaded and any path-to-hash mapping set, otherwise a
* @param {Asset~putAssetResult} result - result object containing error or result status of asset upload * description of the error.
* @param {Assets.PutResult} result - Information on the content uploaded.
*/ */
/**jsdoc /**jsdoc
* Result value returned by {@link Assets.putAsset}. * Result value returned by {@link Assets.putAsset}.
* @typedef {object} Assets~putAssetResult * @typedef {object} Assets.PutResult
* @property {string} [url] the resolved "atp:" style URL for the uploaded asset (based on .path if specified, otherwise on the resulting ATP hash) * @property {number} [byteLength] - The number of bytes in the hash file stored on the asset server.
* @property {string} [path] the uploaded asset's resulting ATP path (or undefined if no path mapping was assigned) * @property {boolean} [compressed] - <code>true</code> if the content stored is gzip compressed.
* @property {string} [hash] the uploaded asset's resulting ATP hash * @property {string} [contentType] - <code>"application/gzip"</code> if the content stored is gzip compressed.
* @property {boolean} [compressed] flag indicating whether the data was compressed before upload * @property {string} [hash] - The SHA256 hash of the content.
* @property {number} [byteLength] flag indicating final byte size of the data uploaded to the ATP server * @property {string} [url] - The <code>atp:</code> 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
* string is uploaded but a path-to-hash mapping is not set.
* @param {Assets~putAssetCallback} callback - The function to call upon completion. May be an inline function or a
* function identifier.
* @example <caption>Store a string in the asset server.</caption>
* Assets.putAsset(
* {
* data: "Hello world!",
* path: "/assetsExamples/helloWorld.txt"
* },
* function (error, result) {
* if (error) {
* print("ERROR: Data not uploaded or mapping not set");
* } else {
* print("URL: " + result.url); // atp:/assetsExamples/helloWorld.txt
* }
* }
* );
*/
/**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 <code>callback</code> function is defined in. This object is bound to
* <code>this</code> 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 <code>scope</code>.
*/
/**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 {Assets.CallbackDetails} callbackDetails - Details of the function to call upon completion.
*/ */
Q_INVOKABLE void putAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue()); Q_INVOKABLE void putAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue());
/**jsdoc /**jsdoc
* @function Assets.deleteAsset * Called when an {@link Assets.deleteAsset} call is complete.
* @param {} options * <p class="important">Not implemented: This type is not implemented yet.</p>
* @param {} scope * @callback Assets~deleteAssetCallback
* @param {} [callback = ""] * @param {string} error - <code>null</code> if the content was deleted, otherwise a description of the error.
* @param {Assets.DeleteResult} result - Information on the content deleted.
*/ */
Q_INVOKABLE void deleteAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue());
/**jsdoc /**jsdoc
* @function Assets.resolveAsset * Deletes content from the asset server.
* @param {} options * <p class="important">Not implemented: This method is not implemented yet.</p>
* @param {} scope * @function Assets.deleteAsset
* @param {} [callback = ""] * @param {Assets.DeleteOptions} options - The content to delete and delete options.
* @param {object} scope - he scope that the <code>callback</code> function is defined in.
* @param {Assets~deleteAssetCallback} callback - The function to call upon completion.
*/ */
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 <code>"atp:"</code>.
*/
/**jsdoc
* Called when an {@link Assets.resolveAsset} call is complete.
* @callback Assets~resolveAssetCallback
* @param {string} error - <code>null</code> 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}.
* <p>Note: If resolving a hash, a file of that hash need not be present on the asset server for the hash to resolve.</p>
* @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 <code>atp:</code>.
* @property {string} [path] - The path to the asset.
* @property {string} [url] - The URL of the asset.
* @property {boolean} [wasRedirected] - <code>true</code> if the resolved data is for the baked version of the asset,
* <code>false</code> 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 <code>"atp:"</code>.
* @param {Assets~resolveAssetCallback} callback - The function to call upon completion. May be a function identifier or
* an inline function.
* @example <caption>Get the hash and URL for a path.</caption>
* Assets.resolveAsset(
* "/assetsExamples/helloWorld.txt",
* function (error, result) {
* if (error) {
* print("ERROR: " + error);
* } else {
* print("Hash: " + result.hash);
* print("URL: " + result.url);
* }
* }
* );
*/
/**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 <code>"atp:"</code>.
* @param {object} scope - The scope that the <code>callback</code> function is defined in. This object is bound to
* <code>this</code> 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 <code>scope</code>.
*/
/**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 <code>"atp:"</code>.
* @param {Assets.CallbackDetails} callbackDetails - Details of the function to call upon completion.
*/
Q_INVOKABLE void resolveAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue()); Q_INVOKABLE void resolveAsset(QScriptValue options, QScriptValue scope, QScriptValue callback = QScriptValue());
/**jsdoc /**jsdoc