From d717e803dd21ba02a3df688198741453a1ef039e Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 15 Feb 2019 08:00:53 +1300 Subject: [PATCH] WalletScriptingInterface API JSDoc --- interface/src/commerce/Wallet.h | 23 ++++++ .../src/scripting/WalletScriptingInterface.h | 70 ++++++++++++++++--- 2 files changed, 85 insertions(+), 8 deletions(-) diff --git a/interface/src/commerce/Wallet.h b/interface/src/commerce/Wallet.h index c096713058..5e5e6c9b4f 100644 --- a/interface/src/commerce/Wallet.h +++ b/interface/src/commerce/Wallet.h @@ -54,6 +54,29 @@ public: void clear(); void getWalletStatus(); + + /**jsdoc + *

A WalletStatus may have one of the following values:

+ * + * + * + * + * + * + * + * + * + * + * + * + *
ValueMeaningDescription
0Not logged inThe user isn't logged in.
1Not set upThe user's wallet isn't set up.
2Pre-existingThere is a wallet present on the server but not one + * locally.
3ConflictingThere is a wallet present on the server plus one present locally, + * and they don't match.
4Not authenticatedThere is a wallet present locally but the user hasn't + * logged into it.
5ReadyThe wallet is ready for use.
+ *

Wallets used to be stored locally but now they're stored on the server, unless the computer once had a wallet stored + * locally in which case the wallet may be present in both places.

+ * @typedef {number} WalletScriptingInterface.WalletStatus + */ enum WalletStatus { WALLET_STATUS_NOT_LOGGED_IN = 0, WALLET_STATUS_NOT_SET_UP, diff --git a/interface/src/scripting/WalletScriptingInterface.h b/interface/src/scripting/WalletScriptingInterface.h index 36ee021b29..c526f52765 100644 --- a/interface/src/scripting/WalletScriptingInterface.h +++ b/interface/src/scripting/WalletScriptingInterface.h @@ -1,4 +1,4 @@ - +// // WalletScriptingInterface.h // interface/src/scripting // @@ -30,13 +30,18 @@ public: }; /**jsdoc - * @namespace Wallet + * The WalletScriptingInterface API provides functions related to the user's wallet and verification of certified + * avatar entities. + * + * @namespace WalletScriptingInterface * * @hifi-interface * @hifi-client-entity * - * @property {number} walletStatus - * @property {bool} limitedCommerce + * @property {WalletScriptingInterface.WalletStatus} walletStatus - The status of the user's wallet. Read-only. + * @property {boolean} limitedCommerce - true if Interface is running in limited commerce mode. In limited commerce + * mode, certain Interface functionality is disabled, e.g., users can't buy non-free items from the Marketplace. The Oculus + * Store version of Interface runs in limited commerce mode. Read-only. */ class WalletScriptingInterface : public QObject, public Dependency { Q_OBJECT @@ -49,19 +54,56 @@ public: WalletScriptingInterface(); /**jsdoc + * Check and update the user's wallet status. * @function WalletScriptingInterface.refreshWalletStatus */ Q_INVOKABLE void refreshWalletStatus(); /**jsdoc + * Get the current status of the user's wallet. * @function WalletScriptingInterface.getWalletStatus - * @returns {number} + * @returns {WalletScriptingInterface.WalletStatus} + * @example Two ways to report your wallet status. + * print("Wallet status: " + WalletScriptingInterface.walletStatus); // Same value as next line. + * print("Wallet status: " + WalletScriptingInterface.getWalletStatus()); */ Q_INVOKABLE uint getWalletStatus() { return _walletStatus; } /**jsdoc + * Check that a certified avatar entity is owned by the avatar whose entity it is. The result of the check is provided via + * the {@link WalletScriptingInterface.ownershipVerificationSuccess|ownershipVerificationSuccess} and + * {@link WalletScriptingInterface.ownershipVerificationFailed|ownershipVerificationFailed} signals.
+ * Warning: Neither of these signals fire if the entity is not an avatar entity or it's not a certified + * entity. * @function WalletScriptingInterface.proveAvatarEntityOwnershipVerification - * @param {Uuid} entityID + * @param {Uuid} entityID - The ID of the avatar entity to check. + * @example Check ownership of all nearby certified avatar entities. + * // Set up response handling. + * function ownershipSuccess(entityID) { + * print("Ownership test succeeded for: " + entityID); + * } + * function ownershipFailed(entityID) { + * print("Ownership test failed for: " + entityID); + * } + * WalletScriptingInterface.ownershipVerificationSuccess.connect(ownershipSuccess); + * WalletScriptingInterface.ownershipVerificationFailed.connect(ownershipFailed); + * + * // Check ownership of all nearby certified avatar entities. + * var entityIDs = Entities.findEntities(MyAvatar.position, 10); + * var i, length; + * for (i = 0, length = entityIDs.length; i < length; i++) { + * var properties = Entities.getEntityProperties(entityIDs[i], ["entityHostType", "certificateID"]); + * if (properties.entityHostType === "avatar" && properties.certificateID !== "") { + * print("Prove ownership of: " + entityIDs[i]); + * WalletScriptingInterface.proveAvatarEntityOwnershipVerification(entityIDs[i]); + * } + * } + * + * // Tidy up. + * Script.scriptEnding.connect(function () { + * WalletScriptingInterface.ownershipVerificationFailed.disconnect(ownershipFailed); + * WalletScriptingInterface.ownershipVerificationSuccess.disconnect(ownershipSuccess); + * }); */ Q_INVOKABLE void proveAvatarEntityOwnershipVerification(const QUuid& entityID); @@ -75,33 +117,45 @@ public: signals: /**jsdoc + * Triggered when the status of the user's wallet changes. * @function WalletScriptingInterface.walletStatusChanged * @returns {Signal} + * @example Report when your wallet status changes, e.g., when you log in and out. + * WalletScriptingInterface.walletStatusChanged.connect(function () { + * print("Wallet status changed to: " + WalletScriptingInterface.walletStatus"); + * }); */ void walletStatusChanged(); /**jsdoc + * Triggered when the user's limited commerce status changes. * @function WalletScriptingInterface.limitedCommerceChanged * @returns {Signal} */ void limitedCommerceChanged(); /**jsdoc + * Triggered when the user rezzes a certified entity but the user's wallet is not ready and so the certified location of the + * entity cannot be updated in the metaverse. * @function WalletScriptingInterface.walletNotSetup * @returns {Signal} */ void walletNotSetup(); /**jsdoc + * Triggered when a certified avatar entity's ownership check requested via + * {@link WalletScriptingInterface.proveAvatarEntityOwnershipVerification|proveAvatarEntityOwnershipVerification} succeeds. * @function WalletScriptingInterface.ownershipVerificationSuccess - * @param {Uuid} entityID + * @param {Uuid} entityID - The ID of the avatar entity checked. * @returns {Signal} */ void ownershipVerificationSuccess(const QUuid& entityID); /**jsdoc + * Triggered when a certified avatar entity's ownership check requested via + * {@link WalletScriptingInterface.proveAvatarEntityOwnershipVerification|proveAvatarEntityOwnershipVerification} fails. * @function WalletScriptingInterface.ownershipVerificationFailed - * @param {Uuid} entityID + * @param {Uuid} entityID - The ID of the avatar entity checked. * @returns {Signal} */ void ownershipVerificationFailed(const QUuid& entityID);