mirror of
https://github.com/overte-org/overte.git
synced 2025-04-20 04:44:11 +02:00
Assets API methods that include mappings JSDoc
This commit is contained in:
David Rowe
parent
817bc6cd43
commit
5f3081784c
3 changed files with 217 additions and 76 deletions
|
|
@ -24,6 +24,21 @@
|
|||
class BaseAssetScriptingInterface : public QObject {
|
||||
Q_OBJECT
|
||||
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" };
|
||||
using Promise = MiniPromise::Promise;
|
||||
QSharedPointer<AssetClient> assetClient();
|
||||
|
|
|
|||
|
|
@ -215,21 +215,6 @@ void AssetScriptingInterface::deleteAsset(QScriptValue options, QScriptValue sco
|
|||
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) {
|
||||
JS_VERIFY(options.isObject() || options.isString(), "expected request options Object or URL as first parameter");
|
||||
|
||||
|
|
|
|||
|
|
@ -173,94 +173,235 @@ public:
|
|||
#endif
|
||||
|
||||
/**jsdoc
|
||||
* Request Asset data from the ATP Server
|
||||
* @function Assets.getAsset
|
||||
* @param {URL|Assets.GetOptions} options An atp: style URL, hash, or relative mapped path; or an {@link Assets.GetOptions} object with request parameters
|
||||
* @param {Assets~getAssetCallback} scope A scope callback function to receive (error, results) values
|
||||
* @param {function} [callback=undefined]
|
||||
* Details of a callback function.
|
||||
* @typedef {object} Assets.CallbackDetails
|
||||
* @property {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.
|
||||
* @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
|
||||
* A set of properties that can be passed to {@link Assets.getAsset}.
|
||||
* Source and download options for {@link Assets.getAsset}.
|
||||
* @typedef {object} Assets.GetOptions
|
||||
* @property {string} [url] an "atp:" style URL, hash, or relative mapped path to fetch
|
||||
* @property {string} [responseType=text] the desired reponse type (text | arraybuffer | json)
|
||||
* @property {boolean} [decompress=false] whether to attempt gunzip decompression on the fetched data
|
||||
* See: {@link Assets.putAsset} and its .compress=true option
|
||||
* @property {string} url - The mapped path or hash to download. May have a leading <code>"atp:"</code>.
|
||||
* @property {Assets.ResponseType} [responseType="text"] - The desired result type.
|
||||
* @property {boolean} [decompress=false] - <code>true</code> to gunzip decompress the downloaded data. Synonym:
|
||||
* <code>compressed</code>.
|
||||
*/
|
||||
|
||||
/**jsdoc
|
||||
* Called when Assets.getAsset is complete.
|
||||
* Called when an {@link Assets.getAsset} call is complete.
|
||||
* @callback Assets~getAssetCallback
|
||||
* @param {string} error - contains error message or null value if no error occured fetching the asset
|
||||
* @param {Asset~getAssetResult} result - result object containing, on success containing asset metadata and contents
|
||||
* @param {string} error - <code>null</code> 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~getAssetResult
|
||||
* @property {string} [url] the resolved "atp:" style URL for the fetched asset
|
||||
* @property {string} [hash] the resolved hash for the fetched asset
|
||||
* @property {string|ArrayBuffer|Object} [response] response data (possibly converted per .responseType value)
|
||||
* @property {string} [responseType] response type (text | arraybuffer | json)
|
||||
* @property {string} [contentType] detected asset mime-type (autodetected)
|
||||
* @property {number} [byteLength] response data size in bytes
|
||||
* @property {number} [decompressed] flag indicating whether data was decompressed
|
||||
* 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] - <code>true</code> if the content was decompressed, <code>false</code> 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, <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());
|
||||
|
||||
/**jsdoc
|
||||
* Upload Asset data to the ATP Server
|
||||
* @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}.
|
||||
* Content and upload options for {@link Assets.putAsset}.
|
||||
* @typedef {object} Assets.PutOptions
|
||||
* @property {ArrayBuffer|string} [data] byte buffer or string value representing the new asset's content
|
||||
* @property {string} [path=null] ATP path mapping to automatically create (upon successful upload to hash)
|
||||
* @property {boolean} [compress=false] whether to gzip compress data before uploading
|
||||
* @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
|
||||
* <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
|
||||
* Called when Assets.putAsset is complete.
|
||||
* @callback Assets~puttAssetCallback
|
||||
* @param {string} error - contains error message (or null value if no error occured while uploading/mapping the new asset)
|
||||
* @param {Asset~putAssetResult} result - result object containing error or result status of asset upload
|
||||
* Called when an {@link Assets.putAsset} call is complete.
|
||||
* @callback Assets~putAssetCallback
|
||||
* @param {string} error - <code>null</code> if the content was uploaded and any path-to-hash mapping set, otherwise a
|
||||
* description of the error.
|
||||
* @param {Assets.PutResult} result - Information on the content uploaded.
|
||||
*/
|
||||
|
||||
/**jsdoc
|
||||
* Result value returned by {@link Assets.putAsset}.
|
||||
* @typedef {object} Assets~putAssetResult
|
||||
* @property {string} [url] the resolved "atp:" style URL for the uploaded asset (based on .path if specified, otherwise on the resulting ATP hash)
|
||||
* @property {string} [path] the uploaded asset's resulting ATP path (or undefined if no path mapping was assigned)
|
||||
* @property {string} [hash] the uploaded asset's resulting ATP hash
|
||||
* @property {boolean} [compressed] flag indicating whether the data was compressed before upload
|
||||
* @property {number} [byteLength] flag indicating final byte size of the data uploaded to the ATP server
|
||||
* @typedef {object} Assets.PutResult
|
||||
* @property {number} [byteLength] - The number of bytes in the hash file stored on the asset server.
|
||||
* @property {boolean} [compressed] - <code>true</code> if the content stored is gzip compressed.
|
||||
* @property {string} [contentType] - <code>"application/gzip"</code> if the content stored is gzip compressed.
|
||||
* @property {string} [hash] - The SHA256 hash of the content.
|
||||
* @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());
|
||||
|
||||
/**jsdoc
|
||||
* @function Assets.deleteAsset
|
||||
* @param {} options
|
||||
* @param {} scope
|
||||
* @param {} [callback = ""]
|
||||
* Called when an {@link Assets.deleteAsset} call is complete.
|
||||
* <p class="important">Not implemented: This type is not implemented yet.</p>
|
||||
* @callback Assets~deleteAssetCallback
|
||||
* @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
|
||||
* @function Assets.resolveAsset
|
||||
* @param {} options
|
||||
* @param {} scope
|
||||
* @param {} [callback = ""]
|
||||
* Deletes content from the asset server.
|
||||
* <p class="important">Not implemented: This method is not implemented yet.</p>
|
||||
* @function Assets.deleteAsset
|
||||
* @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());
|
||||
|
||||
/**jsdoc
|
||||
|
|
|
|||
Loading…
Reference in a new issue