signoAPI Android – Licensing – Class overview

STLicenceManager class

The STLicenceManager class is used to license the respective API components libSignoPdfSigner or libSignoSignatureCapture. The class makes it possible to activate, update, apply and release a licence in the new UUID format (XXXXXXXX–XXXX–XXXX–XXXX–XXXXXXXXXXXX) and to request the status of the licence that is currently being used. For licence keys in the old format, please use the setLicenseKey method from the STSignoSigner and STSignatureCapture classes.

The licence is activated by means of a licence key. After a successful licence key check, the activation is performed and the demo notice is removed from the signature image and the signature dialog. If the licence check reveals that the maximum number of activations has been reached, the licence will need to be extended for a fee. Alternatively, an activation can be transferred from a different device, e.g. if it is no longer used; please observe in this regard the activateLicence() method. If possible, activation should be released before uninstallation using the releaseLicence() method to avoid this problem.

During licence validation, calling one of the STSignoViewerNotifier.notifyLicenceStatus() or STSignoCaptureNotifier.notifyLicenceStatus() methods returns an instance of the STLicenceError class, which can be used to detect an error. This instance of the STLicenceError class is also contained in the object returned by the STLicenceManager.getLicenceStatus() method (method STLicenceStatus.getLicenceResult().getLicenceError()). When executing the methods for activation, updating and release, an exception may occur in the event of an error. In this case, the corresponding error and the error message can be queried using the STLicenceException.getLicenceError() and STLicenceException.getMessage() or STLicenceException.getLocalisedMessage() methods of the STLicenceException class.

The class declaration is as follows:

Java

public class STLicenceManager

The STLicenceManager class can only be instantiated using the static STLicenceManager.getLicenceManager() method.

getLicenceManager method

For the STLicenceManager class there is only one single instance (singleton instance) that can be accessed by this static method.

Java

public static STLicenceManager getLicenceManager();

Parameter	Description
-	-
Return value	Description
STLicenceManager	The singleton instance of the STLicenceManager class.

Usage:

Java

STLicenceManager licenceManager = STLicenceManager.getLicenceManager();

activateLicence method

This method can be used to perform the licence activation and the licence acquisition. The licence is activated by means of a licence key. After successful activation, the demo notice is removed from the signature image and the signature dialog. Please use the licence key that was given to you by your contact at signotec or give the user the ability to enter a licence key.

Transferring an activation from another device results in all activations of the licence being reset and reallocated automatically on the basis of the maximum permitted number of activations by means of the regular licence check. Please note that an activation can only be transferred one single time without having to reinstall the app.

Java

void activateLicence(String licenceKey, boolean forceActivation) throws STLicenceException;

Parameter	Description
String licenceKey	Licence keys
boolean forceActivation	true	Transfer an activation from another device.
	false	Do not transfer activation.
Return value	Description
-	-
Exception	Description
STLicenceException	Instance of the STLicenceException class. Is thrown if an error occurs during licence activation. The software could not be activated. The corresponding error and the error message can be queried using the STLicenceException.getLicenceError() and STLicenceException.getMessage() or STLicenceException.getLocalisedMessage() methods.

Usage:

Java

try{
   licenceManager.activateLicence("1234", false);
} catch(STLicenceException e){
   if (e.getLicenceError == STLicenceError.ACTIVATION_LIMIT_REACHED) {
      // activation limit reached, ask user if he wants to transfer
      // the licence from another device...
      if (transfer) {
         try {
            licenceManager.activateLicence("1234", true);
         } catch (STLicenceException e){
            showErrorDialog("Error message: " + e.getLocalizedMessage() + " Licence error: " + e.getLicenceError());
         }
      }
   } else {
      showErrorDialog("Error message: " + e.getLocalizedMessage() + 
" Licence error: " + e.getLicenceError());
   }
}

updateLicence method

This method can be used to call the properties of the licence again if they have changed.

Java

void updateLicence() throws STLicenceException;

Parameter	Description
-	-
Return value	Description
-	-
Exception	Description
STLicenceException	Instance of the STLicenceException class. Is thrown if an error occurs during the licence update. The software licence could not be updated. The corresponding error and the error message can be queried using the STLicenceException.getLicenceError() and STLicenceException.getMessage() or STLicenceException.getLocalisedMessage() methods.

Usage:

Java

try{
   licenceManager.updateLicence();
} catch(STLicenceException e){
   // error handling
   showErrorDialog("Error message: " + e.getLocalizedMessage() + 
" Licence error: " + e.getLicenceError());
}

releaseLicence method

This method makes it possible to revoke the activation and therefore release an activation. If successful, the software will then run in demo mode.

Java

void releaseLicence() throws STLicenceException;

Parameter	Description
-	-
Return value	Description
-	-
Exception	Description
STLicenceException	Instance of the STLicenceException class. Is thrown if an error occurs during licence release. The licensing status has not changed. The corresponding error and the error message can be queried using the STLicenceException.getLicenceError() and STLicenceException.getMessage() or STLicenceException.getLocalisedMessage() methods.

Usage:

Java

try{
   licenceManager.releaseLicence();
} catch(STLicenceException e){
   // error handling
   showErrorDialog("Error message: " + e.getLocalizedMessage() + 
" Licence error: " + e.getLicenceError());
}

getLicenceStatus method

This method can be used to query the status information of the licence that is currently used.

Java

STLicenceStatus getLicenceStatus();

Parameter	Description
-	-
Return value	Description
STLicenceStatus	Instance of the STLicenceStatus class.

Usage:

Java

STLicenceStatus licenceStatus = licenceManager.getLicenceStatus();
if (!licenceStatus.getLicenceResult().isSuccesfull()) {
   // demo mode
}

releaseLicenceManager method

This method can be used to release the generated instance of the STLicenceManager class.

Java

public static void releaseLicenceManager();

Parameter	Description
-	-
Return value	Description
-	-

Usage:

STLicenceManager.releaseLicenceManager();

STLicenceStatus class

The STLicenceStatus class is a data object that contains status information for the licence currently used. For further information, see also STLicenceManager.getLicenceStatus(). The class is part of libSignoPDFSigner as well as of libSignoSignatureCapture. The individual Getter methods of the STLicenceStatus class or the status information are described in the following table.

Property	Description
public LicenceType getLicenceType()	Licensing status.
public Date getLicenceDate()	Expiry date of the licence.
public AmsType getAmsType()	Status of the software maintenance contract.
public Date getAmsDate()	Expiry date of the software maintenance contract.
public OfflineType getOfflineType()	Status of the offline licensing.
public Date getOfflineDate()	Expiry date of the offline licensing.
public Date getTimeStampDate()	Time when the licence was last updated online.
public boolean getActivationReminder()	Information as to whether the user should be asked to update the licence online.
	true	The user should be asked to update the licence online.
	false	The user should not be asked to update the licence online.
public Date getActivationReminderDate()	Time when the user should be asked to update the licence online.
public String getCustomerName()	Name of the company for which the licence was issued.
public String getCustomerNumber()	Customer number of the company for which the licence was issued.
public String getResellerName()	Vendor that created the licence.
public Date getPurchasedDateOn()	Date when the licence was issued.
public int getActivations()	Current number of licence activations.
public int getMaxActivations()	Maximum number of licence activations.
public List<String> getFeatures()	List of licensed features.
public String getActivationId()	Activation ID.
public String getProductId()	ID of the product for which the licence was issued.
public STLicenceResult getLicenceResult()	Instance of the STLicenceResult class. See also the licence error table in the STLicenceError class.

The LicenceType enumeration is defined as follows:

Java

public enum LicenceType {
    UNKNOWN_LICENCE,
    DEMO_LICENCE
    UNLIMITED_LICENCE,
    LIMITED_LICENCE
}

Value	Description
UNKNOWN_LICENCE	Unknown licensing status.
DEMO_LICENCE	API is not licensed and is running in demo mode.
UNLIMITED_LICENCE	API is licensed for an unlimited time period.
LIMITED_LICENCE	API is only licensed until a certain expiry date.

The AmsType enumeration is defined as follows:

Java

public enum AmsType {
    UNKNOWN,
    UNAVAILABLE,
    AVAILABLE,
    LIMITED
}

Value	Description
UNKNOWN	Unknown status of the software maintenance contract.
UNAVAILABLE	No software maintenance contract is available.
AVAILABLE	A software maintenance contract without time limitation is available.
LIMITED	A software maintenance contact is only available up until a certain expiry date.

The OfflineType enumeration is defined as follows:

Java

public enum OfflineType {
    UNKNOWN_OFFLINE_USE,
    LIMITED_OFFLINE_USE,
    UNLIMITED_OFFLINE_USE
}

Value	Description
UNKNOWN_OFFLINE_USE	Unknown status of offline licensing.
LIMITED_OFFLINE_USE	API can only be used offline up until the expiry date.
UNLIMITED_OFFLINE_USE	API can be used offline for an unlimited time period.

STLicenceResult class

The STLicenceResult class is a data object that indicates the licence status of the API. For further information, see also STLicenceStatus.getLicenceResult(). The class is part of libSignoPDFSigner as well as of libSignoSignatureCapture.

Property	Description
boolean isSuccessful()	true	API is licensed.
	false	API is not licensed. See the licence error table below.
STLicenceError getLicenceError()	Instance of the STLicenceError class

STLicenceException class

The STLicenceException class is thrown when an error occurs during licence-related operations (e.g. activation, update or release of a licence) and the corresponding action cannot be completed successfully.

Detailed information about the error that occurred can be queried using STLicenceException.getLicenceError() and the error messages using STLicenceException.getMessage() or STLicenceException.getLocalizedMessage().

getLicenceError method

This method returns the licence error that occurred during a licence-related operation.

Java

public STLicenceError getLicenceError();

Parameter	Description
-	-
Return value	Description
STLicenceError	Instance of the STLicenceError class

Usage:

Java

try{
   licenceManager.activateLicence("1234", false);
} catch(STLicenceException e){
   if (e.getLicenceError == STLicenceError.ACTIVATION_EXPIRED) {
      showErrorDialog("Activation is expired: " + e.getLocalizedMessage() + " Licence error: " + e.getLicenceError());
   } else {
      showErrorDialog("Other error message: " + e.getLocalizedMessage() + 
" Licence error: " + e.getLicenceError());
   }
}

STLicenceError class

The STLicenceError enumeration is defined as follows:

Java

public enum STLicenceError {
  NO_ERROR,
  INTERNAL_GENERIC_ERROR,
  ACTIVATION_EXPIRED,
  SOFTWARE_MAINTENANCE_EXPIRED,
  PURCHASED_DATE_EXPIRED,
  INVALID_FEATURE,
  INVALID_APPLICATION_ID,
  INVALID_PARAMETER,
  INVALID_LICENCE_KEY,
  INVALID_LICENCE_FILE,
  LICENCE_DEACTIVATED,
  LICENCE_EXPIRED,
  ACTIVATION_LIMIT_REACHED,
  ACTIVATION_NOT_ALLOWED,
  CLIENT_INCOMPATIBLE,
  INTERNAL_SERVER_ERROR,
  INTERNAL_ERROR,
  CLIENT_HAS_NOT_YET_BEEN_ACTIVATED,
  LICENCE_FILE_COULD_NOT_BE_SAVED,
  LICENCE_FILE_COULD_NOT_BE_DELETED,
  NO_LICENCE_FILE_LOADED,
  CLIENT_IDS_COULD_NOT_BE_GENERATED,
  INVALID_SOCKET,
  HOST_NOT_FOUND,
  NETWORK_DATABASE_ERROR,
  CONNECTION_TIMEDOUT,
  CONNECTION_REFUSED,
  SSL_GENERAL_ERROR,
  SSL_STREAM_ERROR,
  ADDRINFO_ERROR,
  SOCKET_COMMUNICATION_ERROR,
  SOCKET_ACCESS_ERROR,
  CLIENT_HAS_ALREADY_BEEN_ACTIVATED,
  UNDEFINED
}

Licence error	Description
NO_ERROR	The licence is valid/action was performed successfully.
INTERNAL_GENERIC_ERROR	Internal error.
ACTIVATION_EXPIRED	Your licence must be checked regularly online. Please connect your device to the Internet to perform the check. Until the licence is checked, you can only use the software in demo mode.
SOFTWARE_MAINTENANCE_EXPIRED	The licence does not support the version of the API component that is currently used as the software maintenance has expired. Please use an older version or acquire a new licence, preferably with a software maintenance contract, in order to be able to use all future versions.
PURCHASED_DATE_EXPIRED	The licence does not support the version of the API component that is currently used as no software maintenance is included. Please use an older version or acquire a new licence, preferably with a software maintenance contract, in order to be able to use all future versions.
INVALID_FEATURE	This feature is not supported by the licence.
INVALID_APPLICATION_ID	The licence was not issued for the bundle ID of this app.
INVALID_PARAMETER	An internal error has occurred: invalid parameter.
INVALID_LICENCE_KEY	The licence key used is invalid.
INVALID_LICENCE_FILE	The licence file is invalid.
LICENCE_DEACTIVATED	The licence has been deactivated.
LICENCE_EXPIRED	The licensing period has expired.
ACTIVATION_LIMIT_REACHED	The maximum number of activations has been reached. It is possible to transfer an activation from another device, however.
ACTIVATION_NOT_ALLOWED	The maximum number of activations has been reached. It is not possible to transfer an activation from another device.
CLIENT_INCOMPATIBLE	The software is not compatible with the licence service. Please contact support!
INTERNAL_SERVER_ERROR	An unexpected error has occurred with the licence service.
INTERNAL_ERROR	An internal error has occurred.
CLIENT_HAS_NOT_YET_BEEN_ACTIVATED	The software has not yet been activated.
LICENCE_FILE_COULD_NOT_BE_SAVED	The licence file could not be saved.
LICENCE_FILE_COULD_NOT_BE_DELETED	The licence file could not be deleted.
NO_LICENCE_FILE_LOADED	A valid licence file has not yet been loaded. Please first call activateLicence() or getLicenceStatus().
CLIENT_IDS_COULD_NOT_BE_GENERATED	The required client information could not be generated.
INVALID_SOCKET	General error in communication with the licence server.
HOST_NOT_FOUND	Error in communication with the licence server: The requested host could not be found or the authorisation android.permission.INTERNET is missing in the AndroidManifest.xml file of the app that uses the API.
NETWORK_DATABASE_ERROR	Error in communication with the licence server: An error occurred in ‘network database operations’.
CONNECTION_TIMEDOUT	Error in communication with the licence server: Connection timeout.
CONNECTION_REFUSED	Error in communication with the licence server: The server has rejected the connection.
SSL_GENERAL_ERROR	Error in communication with the licence server: General SSL error.
SSL_STREAM_ERROR	Error in communication with the licence server: Error in the SSL stream.
ADDRINFO_ERROR	Error in communication with the licence server: Socket type not supported.
SOCKET_COMMUNICATION_ERROR	Error in communication with the licence server: A non-specified communication error has occurred.
SOCKET_ACCESS_ERROR	Error in communication with the licence server: An attempt was made to access a socket in a way not supported by the socket’s access authorisations. This is normally caused by a firewall blocking the port or the application.
CLIENT_HAS_ALREADY_BEEN_ACTIVATED	An attempt has been made to activate an already activated software with another licence, although the software has already been successfully activated.
UNDEFINED	Unknown error.