signoAPI Android – Lizenzierung – Klassenübersicht

Klasse STLicenceManager

Die Klasse STLicenceManager wird zur Lizenzierung der jeweiligen API-Komponenten libSignoPdfSigner oder libSignoSignatureCapture verwendet. Die Klasse bietet die Möglichkeit, eine Lizenz im neuen UUID-Format (XXXXXXXX–XXXX–XXXX–XXXX–XXXXXXXXXXXX) zu aktivieren, zu aktualisieren, zu übernehmen und freizugeben sowie die Statusinformationen der aktuell verwendeten Lizenz abzufragen. Für Lizenzschlüssel im alten Format verwenden Sie bitte die Methode setLicenseKey aus den Klassen STSignoSigner und STSignatureCapture.

Die Lizenz wird mithilfe eines Lizenzschlüssels aktiviert. Nach erfolgreicher Prüfung des Lizenzschlüssels wird die Aktivierung durchgeführt und somit der Demo-Hinweis aus dem Signaturbild und dem Unterschriftendialog entfernt. Sollte sich bei der Prüfung der Lizenz herausstellen, dass bereits die maximale Anzahl an Aktivierungen erreicht wurde, so ist eine kostenpflichtige Erweiterung der Lizenz erforderlich. Alternativ kann eine Aktivierung von einem anderen Gerät übernommen werden, z. B. wenn dieses nicht mehr verwendet wird; hierzu beachten Sie bitte die Methode activateLicence(). Nach Möglichkeit sollte eine Aktivierung vor der Deinstallation aber mit der Methode releaseLicence() freigegeben werden, um dieses Problem zu vermeiden.

Bei der Lizenzvalidierung wird durch den Aufruf von einer der Methoden STSignoViewerNotifier.notifyLicenceStatus() oder STSignoCaptureNotifier.notifyLicenceStatus() eine Instanz der STLicenceError-Klasse zurückgegeben, anhand der ein Fehler erkannt werden kann. Diese Instanz der STLicenceError-Klasse ist auch im von der Methode STLicenceManager.getLicenceStatus() zurückgegebenen Objekt (Methode STLicenceStatus.getLicenceResult().getLicenceError()) enthalten. Bei der Ausführung der Methoden zur Aktivierung, Aktualisierung und Freigabe kann im Fehlerfall eine Exception auftreten. Der entsprechende Fehler und die Fehlermeldung können in diesem Fall mithilfe der Methoden STLicenceException.getLicenceError() und STLicenceException.getMessage() bzw. STLicenceException.getLocalizedMessage() der Klasse STLicenceException abgefragt werden.

Die Deklaration der Klasse sieht wie folgt aus:

Java

public class STLicenceManager

Das Instanziieren der Klasse STLicenceManager ist nur möglich mit der statischen Methode STLicenceManager.getLicenceManager().

Methode getLicenceManager

Von der Klasse STLicenceManager existiert nur eine einzige Instanz (Singletoninstanz), auf die durch diese statische Methode zugegriffen werden kann.

Java

public static STLicenceManager getLicenceManager();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
STLicenceManager	Die Singletoninstanz der STLicenceManager-Klasse.

Anwendung:

Java

STLicenceManager licenceManager = STLicenceManager.getLicenceManager();

Methode activateLicence

Mit dieser Methode kann die Lizenzaktivierung und die Lizenzübernahme durchgeführt werden. Die Lizenzaktivierung erfolgt mithilfe eines Lizenzschlüssels. Nach der erfolgreichen Aktivierung wird der Demo-Hinweis aus dem Signaturbild und dem Unterschriftendialog entfernt. Bitte verwenden Sie den Lizenzschlüssel, der Ihnen von Ihrem Kontakt bei signotec mitgeteilt worden ist, oder bieten Sie dem Anwender die Möglichkeit, einen Lizenzschlüssel einzutragen.

Die Übernahme einer Aktivierung von einem anderen Gerät führt dazu, dass alle Aktivierungen der Lizenz zurückgesetzt und über die regelmäßige Lizenzüberprüfung automatisch im Rahmen der maximalen Anzahl an erlaubten Aktivierungen neu zugeordnet werden. Bitte beachten Sie, dass eine Aktivierung nur ein einziges Mal übernommen werden kann, ohne die App neu installieren zu müssen.

Java

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

Parameter	Bedeutung
String licenceKey	Lizenzschlüssel
boolean forceActivation	true	Aktivierung von einem anderen Gerät übernehmen.
	false	Aktivierung nicht übernehmen.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STLicenceException	Instanz der STLicenceException-Klasse. Wird geworfen, wenn bei der Lizenzaktivierung ein Fehler auftritt. Die Software konnte nicht aktiviert werden. Der entsprechende Fehler und die Fehlermeldung können mit den Methoden STLicenceException.getLicenceError() und STLicenceException.getMessage() bzw. STLicenceException.getLocalizedMessage() abgefragt werden.

Anwendung:

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());
   }
}

Methode updateLicence

Mit dieser Methode können die Eigenschaften der Lizenz erneut abgerufen werden, falls diese sich geändert haben.

Java

void updateLicence() throws STLicenceException;

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STLicenceException	Instanz der STLicenceException-Klasse. Wird geworfen, wenn bei der Lizenzaktualisierung ein Fehler auftritt. Die Lizenz der Software konnte nicht aktualisiert werden. Der entsprechende Fehler und die Fehlermeldung können mit den Methoden STLicenceException.getLicenceError() und STLicenceException.getMessage() bzw. STLicenceException.getLocalizedMessage() abgefragt werden.

Anwendung:

Java

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

Methode releaseLicence

Diese Methode bietet die Möglichkeit, die Aktivierung rückgängig zu machen und somit eine Aktivierung freizugeben. Im Erfolgsfall läuft die Software anschließend im Demomodus.

Java

void releaseLicence() throws STLicenceException;

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STLicenceException	Instanz der STLicenceException-Klasse. Wird geworfen, wenn bei der Lizenzfreigabe ein Fehler auftritt. Der Lizenzierungsstatus hat sich nicht geändert. Der entsprechende Fehler und die Fehlermeldung können mit den Methoden STLicenceException.getLicenceError() und STLicenceException.getMessage() bzw. STLicenceException.getLocalizedMessage() abgefragt werden.

Anwendung:

Java

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

Methode getLicenceStatus

Diese Methode kann verwendet werden, um die Statusinformationen der aktuell verwendeten Lizenz abzufragen.

Java

STLicenceStatus getLicenceStatus();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
STLicenceStatus	Instanz der STLicenceStatus-Klasse.

Anwendung:

Java

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

Methode releaseLicenceManager

Mit dieser Methode kann die erzeugte Instanz der STLicenceManager-Klasse freigegeben werden.

Java

public static void releaseLicenceManager();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
-	-

Anwendung:

STLicenceManager.releaseLicenceManager();

Klasse STLicenceStatus

Die Klasse STLicenceStatus ist ein Datenobjekt, das Statusinformationen der aktuell verwendeten Lizenz enthält. Für weitere Informationen siehe auch STLicenceManager.getLicenceStatus(). Die Klasse ist Bestandteil sowohl der libSignoPDFSigner als auch der libSignoSignatureCapture. In der folgenden Tabelle werden die einzelnen Getter-Methoden der Klasse STLicenceStatus bzw. die Statusinformationen beschrieben.

Eigenschaft	Bedeutung
public LicenceType getLicenceType()	Lizenzierungsstatus.
public Date getLicenceDate()	Ablaufdatum der Lizenz.
public AmsType getAmsType()	Status des Softwarepflegevertrags.
public Date getAmsDate()	Ablaufdatum des Softwarepflegevertrags.
public OfflineType getOfflineType()	Status der Offlinelizenzierung.
public Date getOfflineDate()	Ablaufdatum der Offlinelizenzierung.
public Date getTimeStampDate()	Zeitpunkt, wann die Lizenz das letzte Mal online aktualisiert worden ist.
public boolean getActivationReminder()	Die Information, ob der Anwender aufgefordert werden sollte, die Lizenz online zu aktualisieren.
	true	Der Anwender sollte aufgefordert werden, die Lizenz online zu aktualisieren.
	false	Der Anwender sollte nicht aufgefordert werden, die Lizenz online zu aktualisieren.
public Date getActivationReminderDate()	Zeitpunkt, wann der Anwender aufgefordert werden sollte, die Lizenz online zu aktualisieren.
public String getCustomerName()	Name des Unternehmens, für das die Lizenz ausgestellt worden ist.
public String getCustomerNumber()	Kundennummer des Unternehmens, für das die Lizenz ausgestellt worden ist.
public String getResellerName()	Verkäufer, der die Lizenz erstellt hat.
public Date getPurchasedDateOn()	Datum, an dem die Lizenz ausgestellt worden ist.
public int getActivations()	Aktuelle Anzahl an Lizenzaktivierungen.
public int getMaxActivations()	Maximale Anzahl an Lizenzaktivierungen.
public List<String> getFeatures()	Liste lizenzierter Features.
public String getActivationId()	Aktivierungs-ID.
public String getProductId()	ID des Produkts, für das die Lizenz ausgestellt worden ist.
public STLicenceResult getLicenceResult()	Instanz der STLicenceResult-Klasse. Siehe auch die Lizenzfehler-Tabelle in der STLicenceError-Klasse.

Die Enumeration LicenceType ist wie folgt definiert:

Java

public enum LicenceType {
    UNKNOWN_LICENCE,
    DEMO_LICENCE
    UNLIMITED_LICENCE,
    LIMITED_LICENCE
}

Wert	Bedeutung
UNKNOWN_LICENCE	Unbekannter Lizenzierungsstatus.
DEMO_LICENCE	API ist nicht lizenziert und läuft im Demomodus.
UNLIMITED_LICENCE	API ist zeitlich unbegrenzt lizenziert.
LIMITED_LICENCE	API ist nur bis zu einem bestimmten Ablaufdatum lizenziert.

Die Enumeration AmsType ist wie folgt definiert:

Java

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

Wert	Bedeutung
UNKNOWN	Unbekannter Status des Softwarepflegevertrags.
UNAVAILABLE	Kein Softwarepflegevertrag ist vorhanden.
AVAILABLE	Ein zeitlich unbegrenzter Softwarepflegevertrag ist vorhanden.
LIMITED	Ein Softwarepflegevertrag ist nur bis zu einem bestimmten Ablaufdatum vorhanden.

Die Enumeration OfflineType ist wie folgt definiert:

Java

public enum OfflineType {
    UNKNOWN_OFFLINE_USE,
    LIMITED_OFFLINE_USE,
    UNLIMITED_OFFLINE_USE
}

Wert	Bedeutung
UNKNOWN_OFFLINE_USE	Unbekannter Status der Offlinelizenzierung.
LIMITED_OFFLINE_USE	API ist nur bis zum Ablaufdatum offline verwendbar.
UNLIMITED_OFFLINE_USE	API ist zeitlich unbegrenzt offline verwendbar.

Klasse STLicenceResult

Die Klasse STLicenceResult ist ein Datenobjekt, das den Lizenzstatus der API angibt. Für weitere Informationen siehe auch STLicenceStatus.getLicenceResult(). Die Klasse ist Bestandteil sowohl der libSignoPDFSigner als auch der libSignoSignatureCapture.

Eigenschaft	Bedeutung
boolean isSuccessful()	true	API ist lizenziert.
	false	API ist nicht lizenziert. Siehe die Lizenzfehler-Tabelle unten.
STLicenceError getLicenceError()	Instanz der STLicenceError-Klasse

Klasse STLicenceException

Die Klasse STLicenceException wird geworfen, wenn während lizenzbezogener Operationen (z. B. Aktivierung, Aktualisierung oder Freigabe einer Lizenz) ein Fehler auftritt und die entsprechende Aktion nicht erfolgreich abgeschlossen werden kann.

Detaillierte Informationen zum aufgetretenen Fehler können über STLicenceException.getLicenceError() sowie über die Fehlermeldungen mittels STLicenceException.getMessage() bzw. STLicenceException.getLocalizedMessage() abgefragt werden.

Methode getLicenceError

Diese Methode gibt den Lizenzfehler zurück, der während einer lizenzbezogenen Operation aufgetreten ist.

Java

public STLicenceError getLicenceError();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
STLicenceError	Instanz der STLicenceError-Klasse

Anwendung:

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());
   }
}

Klasse STLicenceError

Die Enumeration STLicenceError ist wie folgt definiert:

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
}

Lizenzfehler	Bedeutung
NO_ERROR	Die Lizenz ist gültig / Aktion wurde erfolgreich durchgeführt.
INTERNAL_GENERIC_ERROR	Interner Fehler.
ACTIVATION_EXPIRED	Ihre Lizenz muss regelmäßig online überprüft werden. Bitte verbinden Sie Ihr Gerät mit dem Internet, um die Überprüfung durchzuführen. Solange die Lizenz nicht überprüft wurde, können Sie die Software nur im Demomodus verwenden.
SOFTWARE_MAINTENANCE_EXPIRED	Die Lizenz unterstützt nicht die aktuell verwendete Version der API-Komponente, weil die Softwarepflege abgelaufen ist. Bitte verwenden Sie eine ältere Version oder erwerben Sie eine neue Lizenz, vorzugsweise mit einem Softwarepflegevertrag, um auch alle künftigen Versionen nutzen zu können.
PURCHASED_DATE_EXPIRED	Die Lizenz unterstützt nicht die aktuell verwendete Version der API-Komponente, weil keine Softwarepflege enthalten ist. Bitte verwenden Sie eine ältere Version oder erwerben Sie eine neue Lizenz, vorzugsweise mit einem Softwarepflegevertrag, um auch alle künftigen Versionen nutzen zu können.
INVALID_FEATURE	Dieses Feature wird von der Lizenz nicht unterstützt.
INVALID_APPLICATION_ID	Die Lizenz wurde nicht für die Bundle-ID dieser App ausgestellt.
INVALID_PARAMETER	Es ist ein interner Fehler aufgetreten: ungültiger Parameter.
INVALID_LICENCE_KEY	Der verwendete Lizenzschlüssel ist ungültig.
INVALID_LICENCE_FILE	Die Lizenzdatei ist ungültig.
LICENCE_DEACTIVATED	Die Lizenz wurde deaktiviert.
LICENCE_EXPIRED	Der Lizenzierungszeitraum ist abgelaufen.
ACTIVATION_LIMIT_REACHED	Die maximale Anzahl an Aktivierungen wurde erreicht. Die Übernahme einer Aktivierung von einem anderen Gerät ist aber möglich.
ACTIVATION_NOT_ALLOWED	Die maximale Anzahl an Aktivierungen wurde erreicht. Die Übernahme einer Aktivierung von einem anderen Gerät ist nicht möglich.
CLIENT_INCOMPATIBLE	Die Software ist inkompatibel mit dem Lizenzservice. Bitte kontaktieren Sie den Support!
INTERNAL_SERVER_ERROR	Es ist ein unerwarteter Fehler am Lizenzservice aufgetreten.
INTERNAL_ERROR	Es ist ein interner Fehler aufgetreten.
CLIENT_HAS_NOT_YET_BEEN_ACTIVATED	Die Software wurde noch nicht aktiviert.
LICENCE_FILE_COULD_NOT_BE_SAVED	Die Lizenzdatei konnte nicht gespeichert werden.
LICENCE_FILE_COULD_NOT_BE_DELETED	Die Lizenzdatei konnte nicht gelöscht werden.
NO_LICENCE_FILE_LOADED	Es wurde noch keine gültige Lizenzdatei geladen. Bitte rufen Sie zunächst activateLicence() oder getLicenceStatus() auf.
CLIENT_IDS_COULD_NOT_BE_GENERATED	Die benötigten Clientinformationen konnten nicht erzeugt werden.
INVALID_SOCKET	Allgemeiner Fehler bei der Kommunikation mit dem Lizenzserver.
HOST_NOT_FOUND	Fehler bei der Kommunikation mit dem Lizenzserver: Der angeforderte Host konnte nicht gefunden werden oder es fehlt die Berechtigung android.permission.INTERNET in der AndroidManifest.xml Datei der App, die die API benutzt.
NETWORK_DATABASE_ERROR	Fehler bei der Kommunikation mit dem Lizenzserver: In „network database operations“ ist ein Fehler aufgetreten.
CONNECTION_TIMEDOUT	Fehler bei der Kommunikation mit dem Lizenzserver: Zeitüberschreitung der Verbindung.
CONNECTION_REFUSED	Fehler bei der Kommunikation mit dem Lizenzserver: Der Server hat die Verbindung abgelehnt.
SSL_GENERAL_ERROR	Fehler bei der Kommunikation mit dem Lizenzserver: Allgemeiner SSL-Fehler.
SSL_STREAM_ERROR	Fehler bei der Kommunikation mit dem Lizenzserver: Fehler im SSL-Stream.
ADDRINFO_ERROR	Fehler bei der Kommunikation mit dem Lizenzserver: Nicht unterstützter Socket-Typ.
SOCKET_COMMUNICATION_ERROR	Fehler bei der Kommunikation mit dem Lizenzserver: Ein nicht spezifizierter Kommunikationsfehler ist aufgetreten.
SOCKET_ACCESS_ERROR	Fehler bei der Kommunikation mit dem Lizenzserver: Es wurde versucht, auf eine Weise auf einen Socket zuzugreifen, der durch seine Zugriffsberechtigungen nicht zulässig ist. Dies wird normalerweise durch eine Firewall verursacht, die den Port oder die Anwendung blockiert.
CLIENT_HAS_ALREADY_BEEN_ACTIVATED	Es wurde versucht, eine bereits aktivierte Software mit einer anderen Lizenz zu aktivieren, obwohl die Software bereits erfolgreich aktiviert wurde.
UNDEFINED	Unbekannter Fehler.