mirror of
https://github.com/overte-org/overte.git
synced 2025-04-16 10:28:57 +02:00
Merge pull request #14918 from ctrlaltdavid/M21128
Case 21128: AccountServices, HifiAbout, and WalletScriptingInterface JSDoc
This commit is contained in:
ingerjm0
GitHub
commit
c8791841de
5 changed files with 166 additions and 25 deletions
|
|
@ -16,15 +16,23 @@
|
|||
#include <QObject>
|
||||
|
||||
/**jsdoc
|
||||
* The <code>HifiAbout</code> API provides information about the version of Interface that is currently running. It also
|
||||
* provides the ability to open a Web page in an Interface browser window.
|
||||
*
|
||||
* @namespace HifiAbout
|
||||
*
|
||||
* @hifi-interface
|
||||
* @hifi-client-entity
|
||||
* @hifi-avatar
|
||||
*
|
||||
* @property {string} buildDate
|
||||
* @property {string} buildVersion
|
||||
* @property {string} qtVersion
|
||||
* @property {string} buildDate - The build date of Interface that is currently running. <em>Read-only.</em>
|
||||
* @property {string} buildVersion - The build version of Interface that is currently running. <em>Read-only.</em>
|
||||
* @property {string} qtVersion - The Qt version used in Interface that is currently running. <em>Read-only.</em>
|
||||
*
|
||||
* @example <caption>Report build information for the version of Interface currently running.</caption>
|
||||
* print("HiFi build date: " + HifiAbout.buildDate); // 11 Feb 2019
|
||||
* print("HiFi version: " + HifiAbout.buildVersion); // 0.78.0
|
||||
* print("Qt version: " + HifiAbout.qtVersion); // 5.10.1
|
||||
*/
|
||||
|
||||
class AboutUtil : public QObject {
|
||||
|
|
@ -44,8 +52,9 @@ public:
|
|||
public slots:
|
||||
|
||||
/**jsdoc
|
||||
* Display a Web page in an Interface browser window.
|
||||
* @function HifiAbout.openUrl
|
||||
* @param {string} url
|
||||
* @param {string} url - The URL of the Web page to display.
|
||||
*/
|
||||
void openUrl(const QString &url) const;
|
||||
private:
|
||||
|
|
|
|||
|
|
@ -54,6 +54,29 @@ public:
|
|||
void clear();
|
||||
|
||||
void getWalletStatus();
|
||||
|
||||
/**jsdoc
|
||||
* <p>A <code>WalletStatus</code> may have one of the following values:</p>
|
||||
* <table>
|
||||
* <thead>
|
||||
* <tr><th>Value</th><th>Meaning</th><th>Description</th></tr>
|
||||
* </thead>
|
||||
* <tbody>
|
||||
* <tr><td><code>0</code></td><td>Not logged in</td><td>The user isn't logged in.</td></tr>
|
||||
* <tr><td><code>1</code></td><td>Not set up</td><td>The user's wallet isn't set up.</td></tr>
|
||||
* <tr><td><code>2</code></td><td>Pre-existing</td><td>There is a wallet present on the server but not one
|
||||
* locally.</td></tr>
|
||||
* <tr><td><code>3</code></td><td>Conflicting</td><td>There is a wallet present on the server plus one present locally,
|
||||
* and they don't match.</td></tr>
|
||||
* <tr><td><code>4</code></td><td>Not authenticated</td><td>There is a wallet present locally but the user hasn't
|
||||
* logged into it.</td></tr>
|
||||
* <tr><td><code>5</code></td><td>Ready</td><td>The wallet is ready for use.</td></tr>
|
||||
* </tbody>
|
||||
* </table>
|
||||
* <p>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.</p>
|
||||
* @typedef {number} WalletScriptingInterface.WalletStatus
|
||||
*/
|
||||
enum WalletStatus {
|
||||
WALLET_STATUS_NOT_LOGGED_IN = 0,
|
||||
WALLET_STATUS_NOT_SET_UP,
|
||||
|
|
|
|||
|
|
@ -112,6 +112,12 @@ DownloadInfoResult::DownloadInfoResult() :
|
|||
{
|
||||
}
|
||||
|
||||
/**jsdoc
|
||||
* Information on the assets currently being downloaded and pending download.
|
||||
* @typedef {object} AccountServices.DownloadInfoResult
|
||||
* @property {number[]} downloading - The percentage complete for each asset currently being downloaded.
|
||||
* @property {number} pending - The number of assets waiting to be download.
|
||||
*/
|
||||
QScriptValue DownloadInfoResultToScriptValue(QScriptEngine* engine, const DownloadInfoResult& result) {
|
||||
QScriptValue object = engine->newObject();
|
||||
|
||||
|
|
|
|||
|
|
@ -38,17 +38,25 @@ class AccountServicesScriptingInterface : public QObject {
|
|||
Q_OBJECT
|
||||
|
||||
/**jsdoc
|
||||
* The AccountServices API contains helper functions related to user connectivity
|
||||
* The <code>AccountServices</code> API provides functions related to user connectivity, visibility, and asset download
|
||||
* progress.
|
||||
*
|
||||
* @hifi-interface
|
||||
* @hifi-client-entity
|
||||
* @hifi-avatar
|
||||
*
|
||||
* @namespace AccountServices
|
||||
* @property {string} username <em>Read-only.</em>
|
||||
* @property {boolean} loggedIn <em>Read-only.</em>
|
||||
* @property {string} findableBy
|
||||
* @property {string} metaverseServerURL <em>Read-only.</em>
|
||||
* @property {string} username - The user name if the user is logged in, otherwise <code>"Unknown user"</code>.
|
||||
* <em>Read-only.</em>
|
||||
* @property {boolean} loggedIn - <code>true</code> if the user is logged in, otherwise <code>false</code>.
|
||||
* <em>Read-only.</em>
|
||||
* @property {string} findableBy - The user's visibility to other people:<br />
|
||||
* <code>"none"</code> - user appears offline.<br />
|
||||
* <code>"friends"</code> - user is visible only to friends.<br />
|
||||
* <code>"connections"</code> - user is visible to friends and connections.<br />
|
||||
* <code>"all"</code> - user is visible to everyone.
|
||||
* @property {string} metaverseServerURL - The metaverse server that the user is authenticated against when logged in
|
||||
* — typically <code>"https://metaverse.highfidelity.com"</code>. <em>Read-only.</em>
|
||||
*/
|
||||
|
||||
Q_PROPERTY(QString username READ getUsername NOTIFY myUsernameChanged)
|
||||
|
|
@ -66,29 +74,38 @@ public:
|
|||
public slots:
|
||||
|
||||
/**jsdoc
|
||||
* Get information on the progress of downloading assets in the domain.
|
||||
* @function AccountServices.getDownloadInfo
|
||||
* @returns {DownloadInfoResult}
|
||||
* @returns {AccountServices.DownloadInfoResult} Information on the progress of assets download.
|
||||
*/
|
||||
DownloadInfoResult getDownloadInfo();
|
||||
|
||||
/**jsdoc
|
||||
* Cause a {@link AccountServices.downloadInfoChanged|downloadInfoChanged} signal to be triggered with information on the
|
||||
* current progress of the download of assets in the domain.
|
||||
* @function AccountServices.updateDownloadInfo
|
||||
*/
|
||||
void updateDownloadInfo();
|
||||
|
||||
/**jsdoc
|
||||
* Check whether the user is logged in.
|
||||
* @function AccountServices.isLoggedIn
|
||||
* @returns {boolean}
|
||||
* @returns {boolean} <code>true</code> if the user is logged in, <code>false</code> otherwise.
|
||||
* @example <caption>Report whether you are logged in.</caption>
|
||||
* var isLoggedIn = AccountServices.isLoggedIn();
|
||||
* print("You are logged in: " + isLoggedIn); // true or false
|
||||
*/
|
||||
bool isLoggedIn();
|
||||
|
||||
/**jsdoc
|
||||
* Prompts the user to log in (the login dialog is displayed) if they're not already logged in.
|
||||
* @function AccountServices.checkAndSignalForAccessToken
|
||||
* @returns {boolean}
|
||||
* @returns {boolean} <code>true</code> if the user is already logged in, <code>false</code> otherwise.
|
||||
*/
|
||||
bool checkAndSignalForAccessToken();
|
||||
|
||||
/**jsdoc
|
||||
* Logs the user out.
|
||||
* @function AccountServices.logOut
|
||||
*/
|
||||
void logOut();
|
||||
|
|
@ -106,43 +123,75 @@ private slots:
|
|||
signals:
|
||||
|
||||
/**jsdoc
|
||||
* Not currently used.
|
||||
* @function AccountServices.connected
|
||||
* @returns {Signal}
|
||||
*/
|
||||
void connected();
|
||||
|
||||
/**jsdoc
|
||||
* Triggered when the user logs out.
|
||||
* @function AccountServices.disconnected
|
||||
* @param {string} reason
|
||||
* @param {string} reason - Has the value, <code>"logout"</code>.
|
||||
* @returns {Signal}
|
||||
*/
|
||||
void disconnected(const QString& reason);
|
||||
|
||||
/**jsdoc
|
||||
* Triggered when the username logged in with changes, i.e., when the user logs in or out.
|
||||
* @function AccountServices.myUsernameChanged
|
||||
* @param {string} username
|
||||
* @param {string} username - The username logged in with if the user is logged in, otherwise <code>""</code>.
|
||||
* @returns {Signal}
|
||||
* @example <caption>Report when your username changes.</caption>
|
||||
* AccountServices.myUsernameChanged.connect(function (username) {
|
||||
* print("Username changed: " + username);
|
||||
* });
|
||||
*/
|
||||
void myUsernameChanged(const QString& username);
|
||||
|
||||
/**jsdoc
|
||||
* Triggered when the progress of the download of assets for the domain changes.
|
||||
* @function AccountServices.downloadInfoChanged
|
||||
* @param {} info
|
||||
* @param {AccountServices.DownloadInfoResult} downloadInfo - Information on the progress of assets download.
|
||||
* @returns {Signal}
|
||||
*/
|
||||
void downloadInfoChanged(DownloadInfoResult info);
|
||||
|
||||
/**jsdoc
|
||||
* Triggered when the user's visibility to others changes.
|
||||
* @function AccountServices.findableByChanged
|
||||
* @param {string} discoverabilityMode
|
||||
* @param {string} findableBy - The user's visibility to other people:<br />
|
||||
* <code>"none"</code> - user appears offline.<br />
|
||||
* <code>"friends"</code> - user is visible only to friends.<br />
|
||||
* <code>"connections"</code> - user is visible to friends and connections.<br />
|
||||
* <code>"all"</code> - user is visible to everyone.
|
||||
* @returns {Signal}
|
||||
* @example <caption>Report when your visiblity changes.</caption>
|
||||
* AccountServices.findableByChanged.connect(function (findableBy) {
|
||||
* print("Findable by changed: " + findableBy);
|
||||
* });
|
||||
*
|
||||
* var originalFindableBy = AccountServices.findableBy;
|
||||
* Script.setTimeout(function () {
|
||||
* // Change visiblity.
|
||||
* AccountServices.findableBy = originalFindableBy === "none" ? "all" : "none";
|
||||
* }, 2000);
|
||||
* Script.setTimeout(function () {
|
||||
* // Restore original visibility.
|
||||
* AccountServices.findableBy = originalFindableBy;
|
||||
* }, 4000);
|
||||
*/
|
||||
void findableByChanged(const QString& discoverabilityMode);
|
||||
|
||||
/**jsdoc
|
||||
* Triggered when the login status of the user changes.
|
||||
* @function AccountServices.loggedInChanged
|
||||
* @param {boolean} loggedIn
|
||||
* @param {boolean} loggedIn - <code>true</code> if the user is logged in, otherwise <code>false</code>.
|
||||
* @returns {Signal}
|
||||
* @example <caption>Report when your login status changes.</caption>
|
||||
* AccountServices.loggedInChanged.connect(function(loggedIn) {
|
||||
* print("Logged in: " + loggedIn);
|
||||
* });
|
||||
*/
|
||||
void loggedInChanged(bool loggedIn);
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
|
||||
//
|
||||
// WalletScriptingInterface.h
|
||||
// interface/src/scripting
|
||||
//
|
||||
|
|
@ -30,14 +30,19 @@ public:
|
|||
};
|
||||
|
||||
/**jsdoc
|
||||
* @namespace Wallet
|
||||
* The <code>WalletScriptingInterface</code> API provides functions related to the user's wallet and verification of certified
|
||||
* avatar entities.
|
||||
*
|
||||
* @namespace WalletScriptingInterface
|
||||
*
|
||||
* @hifi-interface
|
||||
* @hifi-client-entity
|
||||
* @hifi-avatar
|
||||
*
|
||||
* @property {number} walletStatus
|
||||
* @property {bool} limitedCommerce
|
||||
* @property {WalletScriptingInterface.WalletStatus} walletStatus - The status of the user's wallet. <em>Read-only.</em>
|
||||
* @property {boolean} limitedCommerce - <code>true</code> 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. <em>Read-only.</em>
|
||||
*/
|
||||
class WalletScriptingInterface : public QObject, public Dependency {
|
||||
Q_OBJECT
|
||||
|
|
@ -50,19 +55,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 <caption>Two ways to report your wallet status.</caption>
|
||||
* 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.<br />
|
||||
* <strong>Warning:</strong> 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 <caption>Check ownership of all nearby certified avatar entities.</caption>
|
||||
* // 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);
|
||||
|
||||
|
|
@ -76,33 +118,45 @@ public:
|
|||
signals:
|
||||
|
||||
/**jsdoc
|
||||
* Triggered when the status of the user's wallet changes.
|
||||
* @function WalletScriptingInterface.walletStatusChanged
|
||||
* @returns {Signal}
|
||||
* @example <caption>Report when your wallet status changes, e.g., when you log in and out.</caption>
|
||||
* 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);
|
||||
|
|
|
|||
Loading…
Reference in a new issue