Loading...
Searching...
No Matches
juce::OnlineUnlockStatus Class Referenceabstract

## Detailed Description

A base class for online unlocking systems.

This class stores information about whether your app has been unlocked for the current machine, and handles communication with a web-store to perform the unlock procedure.

You probably won't ever use this base class directly, but rather a store-specific subclass such as TracktionMarketplaceStatus, which knows how to talk to the particular online store that you're using.

To use it, you create a subclass which implements all the pure virtual methods (see their comments to find out what you'll need to make them do).

Then you can create an instance of your subclass which will hold the registration state. Typically, you'll want to just keep a single instance of the class around for the duration of your app. You can then call its methods to handle the various registration tasks.

Areas of your code that need to know whether the user is registered (e.g. to decide whether a particular feature is available) should call isUnlocked() to find out.

If you want to create a GUI that allows your users to enter their details and register, see the OnlineUnlockForm class.

See also
  OnlineUnlockForm, KeyGeneration

The documentation for this class was generated from the following file:

- juce_product_unlocking/marketplace/juce_OnlineUnlockStatus.h

Inheritance diagram for juce::OnlineUnlockStatus:

## Classes

struct | LicenseResult
| The possible error strings that can applyKeyFile() can return on failure. More...
struct | UnlockResult
| This provides some details about the reply that the server gave in a call to attemptWebserverUnlock(). More...
struct | MachineIDUtilities
| This class contains some utility functions that might help with machine ID generation. More...

## Public Member Functions

| OnlineUnlockStatus ()
virtual | ~OnlineUnlockStatus ()
| Destructor.
virtual String | getProductID ()=0
| This must return your product's ID, as allocated by the store.
virtual bool | doesProductIDMatch (const String &returnedIDFromServer)=0
| This must check whether a product ID string that the server returned is OK for unlocking the current app.
virtual RSAKey | getPublicKey ()=0
| This must return the RSA public key for authenticating responses from the server for this app.
virtual void | saveState (const String &)=0
| This method must store the given string somewhere in your app's persistent properties, so it can be retrieved later by getState().
virtual String | getState ()=0
| This method must retrieve the last state that was provided by the saveState method.
virtual String | getWebsiteName ()=0
| Returns the name of the web-store website, not for communication, but for presenting to the user.
virtual URL | getServerAuthenticationURL ()=0
| Returns the URL of the authentication API.
virtual String | readReplyFromWebserver (const String &email, const String &password)=0
| Subclasses that talk to a particular web-store will implement this method to contact their webserver and attempt to unlock the current machine for the given username and password.
virtual StringArray | getLocalMachineIDs ()
| Returns a list of strings, any of which should be unique to this physical computer.
virtual void | userCancelled ()
| This method will be called if the user cancels the connection to the webserver by clicking the cancel button in OnlineUnlockForm::OverlayComp.
virtual String | getMessageForConnectionFailure (bool isInternetConnectionWorking)
virtual String | getMessageForUnexpectedReply ()
var | isUnlocked () const
| Returns true if the product has been successfully authorised for this machine.
Time | getExpiryTime () const
| Returns the Time when the keyfile expires.
void | setUserEmail (const String &usernameOrEmail)
| Optionally allows the app to provide the user's email address if it is known.
String | getUserEmail () const
| Returns the user's email address if known.
Result | applyKeyFile (const String &keyFileContent)
| Attempts to perform an unlock using a block of key-file data provided.
UnlockResult | attemptWebserverUnlock (const String &email, const String &password)
| Contacts the webserver and attempts to perform a registration with the given user details.
void | load ()
| Attempts to load the status from the state retrieved by getState().
void | save ()
| Triggers a call to saveState which you can use to store the current unlock status in your app's settings.

## Constructors and Destructors

## OnlineUnlockStatus()

juce::OnlineUnlockStatus::OnlineUnlockStatus | ( |  | ) |

## ~OnlineUnlockStatus()

virtual juce::OnlineUnlockStatus::~OnlineUnlockStatus | ( |  | ) |

virtual

Destructor.

## Member Functions

## getProductID()

virtual String juce::OnlineUnlockStatus::getProductID | ( |  | ) |

pure virtual

This must return your product's ID, as allocated by the store.

## doesProductIDMatch()

virtual bool juce::OnlineUnlockStatus::doesProductIDMatch | ( | const String & | returnedIDFromServer | ) |

pure virtual

This must check whether a product ID string that the server returned is OK for unlocking the current app.

Implemented in juce::TracktionMarketplaceStatus.

## getPublicKey()

virtual RSAKey juce::OnlineUnlockStatus::getPublicKey | ( |  | ) |

pure virtual

This must return the RSA public key for authenticating responses from the server for this app.

You can get this key from your marketplace account page.

## saveState()

virtual void juce::OnlineUnlockStatus::saveState | ( | const String & |  | ) |

pure virtual

This method must store the given string somewhere in your app's persistent properties, so it can be retrieved later by getState().

## getState()

virtual String juce::OnlineUnlockStatus::getState | ( |  | ) |

pure virtual

This method must retrieve the last state that was provided by the saveState method.

On first-run, it should just return an empty string.

## getWebsiteName()

virtual String juce::OnlineUnlockStatus::getWebsiteName | ( |  | ) |

pure virtual

Returns the name of the web-store website, not for communication, but for presenting to the user.

Implemented in juce::TracktionMarketplaceStatus.

## getServerAuthenticationURL()

virtual URL juce::OnlineUnlockStatus::getServerAuthenticationURL | ( |  | ) |

pure virtual

Returns the URL of the authentication API.

Implemented in juce::TracktionMarketplaceStatus.

## readReplyFromWebserver()

virtual String juce::OnlineUnlockStatus::readReplyFromWebserver | ( | const String & | email,
|  | const String & | password )

pure virtual

Subclasses that talk to a particular web-store will implement this method to contact their webserver and attempt to unlock the current machine for the given username and password.

The return value is the XML text from the server which contains error information and/or the encrypted keyfile.

Implemented in juce::TracktionMarketplaceStatus.

## getLocalMachineIDs()

virtual StringArray juce::OnlineUnlockStatus::getLocalMachineIDs | ( |  | ) |

virtual

Returns a list of strings, any of which should be unique to this physical computer.

When testing whether the user is allowed to use the product on this machine, this list of tokens is compared to the ones that were stored on the webserver.

The default implementation of this method will simply call MachineIDUtilities::getLocalMachineIDs(), which provides a default version of this functionality.

## userCancelled()

virtual void juce::OnlineUnlockStatus::userCancelled | ( |  | ) |

virtual

This method will be called if the user cancels the connection to the webserver by clicking the cancel button in OnlineUnlockForm::OverlayComp.

The default implementation of this method does nothing but you should use it to cancel any WebInputStreams that may be connecting.

Reimplemented in juce::TracktionMarketplaceStatus.

## getMessageForConnectionFailure()

virtual String juce::OnlineUnlockStatus::getMessageForConnectionFailure | ( | bool | isInternetConnectionWorking | ) |

virtual

## getMessageForUnexpectedReply()

virtual String juce::OnlineUnlockStatus::getMessageForUnexpectedReply | ( |  | ) |

virtual

## isUnlocked()

var juce::OnlineUnlockStatus::isUnlocked | ( |  | ) | const

inline

Returns true if the product has been successfully authorised for this machine.

The reason it returns a variant rather than a bool is just to make it marginally more tedious for crackers to work around. Hopefully if this method gets inlined they'll need to hack all the places where you call it, rather than just the function itself.

Bear in mind that each place where you check this return value will need to be changed by a cracker in order to unlock your app, so the more places you call this method, the more hassle it will be for them to find and crack them all.

## getExpiryTime()

Time juce::OnlineUnlockStatus::getExpiryTime | ( |  | ) | const

inline

Returns the Time when the keyfile expires.

If a the key file obtained has an expiry time, isUnlocked will return false and this will return a non-zero time. The interpretation of this is up to your app but could be used for subscription based models or trial periods.

## setUserEmail()

void juce::OnlineUnlockStatus::setUserEmail | ( | const String & | usernameOrEmail | ) |

Optionally allows the app to provide the user's email address if it is known.

You don't need to call this, but if you do it may save the user typing it in.

## getUserEmail()

String juce::OnlineUnlockStatus::getUserEmail | ( |  | ) | const

Returns the user's email address if known.

## applyKeyFile()

Result juce::OnlineUnlockStatus::applyKeyFile | ( | const String & | keyFileContent | ) |

Attempts to perform an unlock using a block of key-file data provided.

You may wish to use this as a way of allowing a user to unlock your app by drag-and-dropping a file containing the key data, or by letting them select such a file. This is often needed for allowing registration on machines without internet access.

You can find the possible string values Result can return in LicenseResult.

## attemptWebserverUnlock()

UnlockResult juce::OnlineUnlockStatus::attemptWebserverUnlock | ( | const String & | email,
|  | const String & | password )

Contacts the webserver and attempts to perform a registration with the given user details.

The return value will either be a success, or a failure with an error message from the server, so you should show this message to your user.

Because this method blocks while it contacts the server, you must run it on a background thread, not on the message thread. For an easier way to create a GUI to do the unlocking, see OnlineUnlockForm.

## load()

void juce::OnlineUnlockStatus::load | ( |  | ) |

Attempts to load the status from the state retrieved by getState().

Call this somewhere in your app's startup code.

## save()

void juce::OnlineUnlockStatus::save | ( |  | ) |

Triggers a call to saveState which you can use to store the current unlock status in your app's settings.

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited