Dokumentation signoAPI Android - signotec GmbH

Dokumentation signoAPI Android

Software-Komponenten für Android zum Erfassen von Unterschriften sowie zur Anzeige und zum Unterschreiben von PDF Dokumenten

signotec GmbH

Am Gierath 20 b

D-40885 Ratingen

+49 (0) 2102/53575-10

www.signotec.com

[email protected]

Version 2.3 vom 09.06.2021

© 2000 – 2021 signotec GmbH signoAPI Android Dokumentation Seite 2 von 46

Inhaltsverzeichnis

1 DOKUMENTENHISTORIE 5

2 FUNKTIONSÜBERSICHT 6

3 SYSTEMVORAUSSETZUNGEN UND INTEGRATION 7

ALLGEMEINE HINWEISE 9

4 KLASSE STSIGNOSIGNERCREATOR 10

METHODE CREATESIGNOSIGNER 10 METHODE RELEASESIGNOSIGNER 10

5 KLASSE STSIGNOSIGNER 11

METHODE SETLICENSEKEY 11 METHODE SETSIGNATURETIMESTAMPFORMAT 12 METHODE SETTIMESTAMPCOLOR 12 METHODE LOADDOCUMENTFROMFILE 12 METHODE GETDOCUMENTMETADATA 13 METHODE SETCERTIFICATES 13 METHODE CREATENEWSIGNATUREFIELD 13 METHODE GETSIGNATUREINFO 14 METHODE GETDOCUMENTASFILE 14

METHODE SIGNSIGNATUREFIELD 14 METHODE SETSIGNATUREFIELDINFO 15

6 KLASSE STSIGNOVIEWERCREATOR 16

METHODE CREATESIGNOVIEWER 16 METHODE RELEASESIGNOVIEWER 16

7 KLASSE STSIGNOVIEWER 17

METHODE SETSIGNOVIEWERNOTIFIER 17 METHODE LOADDOCUMENTFROMFILE 18 METHODE SHOWTOOLBAR 18 METHODE SETTOOLBARHEIGHT 19 METHODE STARTSIGNATURE 19 METHODE GETFORMFIELDSINFO 19 METHODE SETFORMFIELDSINFO 20 METHODE CLOSEVIEWER 20 METHODE SETCUSTOMTHEME 21

METHODE SIGNDOCUMENT 21 METHODE CREATEVIEWERRECT 21 METHODE ENABLEAUTOROTATION 22 METHODE ENABLETOUCHEVENTS 22 METHODE ADDIMAGES 23 METHODE STARTTEXTSEARCH 23 METHODE FINISHTEXTSEARCH 24 METHODE SHOWPAGENUMBER 24

8 INTERFACE STSIGNOVIEWERNOTIFIER 25

METHODE DOCUMENTLOADED 25 METHODE WILLSTARTSIGNING 25 METHODE SIGNINGPROCESSSTARTED 26 METHODE SIGNINGPROCESSCONFIRMED 26 METHODE SIGNINGPROCESSCANCELLED 27


METHODE SIGNINGPROCESSFAILED 27 METHODE SIGNATUREINFOPRESSED 28 METHODE DOCUMENTSAVED 28 METHODE BACKBUTTONPRESSED 29

METHODE VIEWERRECTCONFIRMED 29 METHODE VIEWERRECTCANCELLED 30

9 KLASSE STSIGNOUTILS 31

METHODE APPENDPAGE 31 METHODE CREATEDOCUMENT 31 METHODE GETDOCUMENTMETADATAFROMFILE 32 METHODE GETFORMFIELDSINFOFROMFILE 32 METHODE SETFORMFIELDSINFOTOFILE 33 METHODE GETSIGNATUREINFOFROMFILE 33

10 KLASSE STSIGNATUREFIELDINFODTO 35

11 KLASSE STFORMFIELDINFODTO 36

12 KLASSE STSIGNATURECAPTURECONFIG 37

13 KLASSE STIMAGEDTO 38

14 KLASSE STRECTDTO 39

15 KLASSE STSIGNATURECAPTURECREATOR 40

METHODE CREATESIGNATURECAPTURE 40 METHODE RELEASESIGNATURECAPTURE 40

16 KLASSE STSIGNATURECAPTURE 41

METHODE SETSIGNATURECAPTURENOTIFIER 41 METHODE CONFIGUREDIALOG 41 METHODE GETSIGNATUREIMAGE 42 METHODE GETSIGNDATA 42 METHODE SETLICENSEKEY 43 METHODE STARTSIGNATURECAPTURE 43 METHODE RESIZECAPTUREDIALOG 43

17 INTERFACE STSIGNATURECAPTURENOTIFIER 44

METHODE CAPTURINGCANCELLED 44 METHODE CAPTURINGCONFIRMED 44

18 KLASSE STLOGGER 45

METHODE GETLOGGER 45

19 KLASSE STVIEWERRECTDTO 46


Impressum

Alle Rechte vorbehalten. Diese Dokumentation und die darin beschriebenen Komponenten

sind urheberrechtlich geschützte Produkte der signotec GmbH Ratingen in Deutschland. In

diesem Produkt werden Software-Komponenten von anderen Herstellern verwendet,

rechtliche Hinweise zu diesen Komponenten finden Sie im Ordner „3rd Party“. Die teilweise

oder vollständige Vervielfältigung ist nur mit schriftlicher Genehmigung der signotec GmbH

zulässig. Alle verwendeten Hard- und Softwarenamen sind Handelsnamen und/oder

Warenzeichen der jeweiligen Hersteller/Inhaber. Änderungen jederzeit vorbehalten. Wir

übernehmen keine Haftung für Fehler in der Dokumentation.


1 Dokumentenhistorie

Version Datum Bearbeiter Status/Bemerkung

1.0 14.08.2018 Hasan Bas Dokument erstellt

1.1 13.12.2018 Hasan Bas Änderungen in 3 und 12

Punkte 5.7, 7.9 9, 13 und 14 hinzugefügt

1.2 11.01.2019 Hasan Bas Änderungen in 2 und 3

Punkte 7.10 und 7.11 hinzugefügt

1.3 28.01.2019 Hasan Bas Änderungen in 2, 3, 4, 7, 7.17, 9, 10, 11,

12, 13, 14

Punkte 15, 16 und 17 hinzugefügt

1.4 07.03.2019 Hasan Bas Änderungen in 2, 3, 4, 7, 8.6 und 15

Punkte 4.2, 13.2 und 18 hinzugefügt.

1.5 14.03.2019 Hasan Bas Änderungen in 3, 7.2 und 7.8.

1.6 14.06.2019 Hasan Bas Änderungen in 3, 5 und 10

Punkte 5.4, 5.20, 5.21, 5.22, 5.23, 5.24,

5.25, 6.10, 6.11, 7.3, 7.4, 7.5, 7.6 und 17

hinzugefügt.

1.7 14.08.2019 Hasan Bas Änderungen in 3, 10, 12 und 16.2

Punkte 5.11 und 16.7 hinzugefügt.

1.8 05.12.2019 Hasan Bas Änderungen 7.2 und 8.1

Punkt 3.1 hinzugefügt.

1.9 16.12.2019 Hasan Bas Änderungen in 7

2.0 17.02.2020 Hasan Bas Punkt 4.19 entfernt.

2.1 26.02.2020 Hasan Bas Änderung in 12

Punkt 7.17 hinzugefügt

2.2 03.07.2020 Hasan Bas Punkte 4 und 5 hinzugefügt.

Änderungen in 2, 3 und 7.

2.3 29.07.2020 Hasan Bas Änderungen in 5


2 Funktionsübersicht

Das signoAPI Android besteht aus den beiden statischen Bibliotheken libSignoPdfSigner und

libSignoSignatureCapture.

Über die Bibliothek libSignoPdfSigner kann das Anzeigen und ISO-konforme Unterschreiben

von PDF-Dokumenten in eine eigene Android-App integriert werden kann. Es werden sowohl

Dokumente unterstützt, die bereits über DigSig-Felder verfügen, als auch welche, die SGN-

Schlüsselwörter enthalten. Weitere Informationen zu dem korrekten Erstellen von kompatiblen

PDF-Dokumenten erhalten Sie bei Bedarf von Ihrem Ansprechpartner bei der signotec GmbH.

Die Bibliothek libSignoPdfSigner enthält eine Activity und eine Fragment Klasse, in denen das

Dokument angezeigt und bearbeitet werden kann, und einige Hilfsklassen. Mit der Bibliothek

kann auch ein Dokument geladen werden ohne es anzuzeigen, und die Signaturfelder dieses

Dokuments mit Hilfe von einem Signaturdialog unterschrieben werden. Die Bibliothek benötigt

keine weitere Software und ist auch offline ohne Einschränkungen verwendbar.

Mithilfe der Bibliothek libSignoSignatureCapture kann ein Signaturdialog zum Erfassen von

Unterschriften in eine eigene Android-App integriert werden. Eine erfasste Unterschrift kann

sowohl als Bild als auch im biometrischen SignData-Format zurückgegeben werden. Weitere

Informationen zum SignData-Format erhalten Sie bei Bedarf von Ihrem Ansprechpartner bei

der signotec GmbH.


3 Systemvoraussetzungen und Integration

Das signoAPI Android wird auf Android Geräten mit API 21 und neuer unterstützt und richtet

sich an die Android-Version Q (API 29). Es kann auf Android Geräten mit den ABIs

(Application Binary Interface) armeabi-v7a, arm64-v8a, x86_64 und x86 eingesetzt werden.

Die Geräte mit API 21 und neuer können anvisiert werden, indem Sie minSdkVersion im

build.gradle Ihrer App festlegen. Ihre minSdkVersion, compileSdkVersion und

targetSdkVersion können im build.gradle folgendermaßen festgelegt werden:

android {

compileSdkVersion 29

defaultConfig{

applicationId “com.demo.app”

minSdkVersion 21

targetSdkVersion 29

}

}

Das UI der Bibliothek ist für Smartphones und Android-Tablets optimiert.

Das signoAPI Android besteht aus zwei Bibliotheken, die im eigenen Projekt verwendet

werden müssen:

Um die Komponente libSignoPdfSigner einzusetzen, werden die folgenden Dateien und

Klassen benötigt (je nach verwendeter Funktionalität werden nicht alle aufgeführten Klassen

benötigt):

Android-Bibliothek als AAR-Datei libSignoPdfSigner_x.x.x.aar

Klasse STSignoViewerCreator

Klasse STSignoViewer

Klasse STSignoSignerCreator

Klasse STSignoSigner

Interface STSignoViewerNotifier

Klasse STSignatureFieldInfoDTO

Klasse STFormFieldInfoDTO

Klasse STSignatureCaptureConfig

Klasse STImageDTO

Klasse STRectDTO

Klasse STSignoUtils

Klasse STSignatureCaptureCreator

Klasse STSignatureCapture

Klasse STSignatureCaptureException

Klasse STSignoViewerException

Klasse STSignoSignerException

Klasse STLogger

Klasse STViewerRectDTO

Interface STSignatureCaptureNotifier

Die wichtigste Klasse STSignoViewer kann als Fragment-Klasse in einer Activity-Klasse

verwendet werden. Für weitere Informationen siehe auch die Methode STSignoViewerCreator

createSignoViewer(). In diesem Fall sollte das Attribut android:configChanges des

entsprechenden <activity>-Elements in der Manifest-Datei bearbeitet werden, um

anzugeben, dass diese Activity-Klasse die folgenden Konfigurationsänderungen vornimmt.


<activity

android:name="com.demo.app.DemoActivity"

android:configChanges="orientation|keyboard|keyboardHidden|screenSize">

</activity>

Die Bibliothek libSignoPdfSigner kann in Ihrer App als neues Modul mit dem Assistenten von

Android Studio integriert und als Abhängigkeit innerhalb der build.gradle-Datei Ihrer App

angegeben werden:

dependencies {

...

implementation project(‘:libSignoPdfSigner_x.x.x’)

}

Um die Komponente libSignoSignatureCapture einzusetzen, werden die folgenden Dateien und

Klassen benötigt (je nach verwendeter Funktionalität werden nicht alle aufgeführten Klassen

benötigt):

Android-Bibliothek als AAR-Datei libSignoSignatureCapture_x.x.x.a

Klasse STSignatureCaptureCreator

Klasse STSignatureCapture

Interface STSignatureCaptureNotifier

Klasse STSignatureCaptureConfig

Die Bibliothek libSignoSignatureCapture kann in Ihrer App als neues Modul mit dem Assistent

von Android Studio integriert und als Abhängigkeit innerhalb der build.gradle-Datei Ihrer

App angegeben werden:

dependencies {

...

implementation project(‘:libSignoSignatureCapture_x.x.x’)

}

Die benötigten Bilder für die Benutzeroberfläche sind in der Bibliothek vorhanden. Um die

vorhandenen Bilder durch eigene Bilder zu ersetzen, müssen eigene Bilder in den

entsprechenden „drawable“-Ordnern in Ihrer App angelegt werden. Eigene Bilder müssen in

den Abmessungen und im Dateinamen den vorhandenen Bildern entsprechen.

Folgende Bilder der Bibliothek libSignoPdfSigner können durch eigene Bilder ersetzt werden:

signoapi_capture_confirm.png

signoapi_capture_cancel.png

signoapi_capture_retry.png

signoapi_toolbar_back.png

signoapi_toolbar_back_pressed.png

signoapi_toolbar_logo.png

signoapi_toolbar_sign.png

signoapi_toolbar_sign_pressed.png

signoapi_toolbar_sign_summary.png

signoapi_toolbar_sign_summary_pressed.png

signoapi_toolbar_save.png

signoapi_toolbar_save_pressed.png

signoapi_sign_dialog.png

signoapi_signinfo_cancel.png

Folgende Bilder der Bibliothek libSignoSignatureCapture können durch eigene Bilder ersetzt

werden:


signoapi_capture_confirm.png

signoapi_capture_cancel.png

signoapi_capture_retry.png

signoapi_sign_dialog.png

Allgemeine Hinweise

Die Koordinaten beziehen sich immer auf das Koordinatensystem eines PDFs. Ein PDF hat

grundsätzlich die Auflösung von 72 dpi und der Punkt 0/0 ist die oben links.


4 Klasse STSignoSignerCreator

Die Klasse STSignoSignerCreator ist zuständig für die Erzeugung eines STSignoSigner-

Objekts und erzeugt nur genau eine Instanz der STSignoSigner-Klasse. Die Klasse ist

Bestandteil der libSignoPDFSigner.

public class STSignoSignerCreator

Methode createSignoSigner

Mit dieser Methode kann eine Instanz der STSignoSigner-Klasse erzeugt werden.

public static STSignoSigner createSignoSigner(Context context) throws

STSignoSignerException;

Parameter Bedeutung Context context Der Kontext einer Activity-Klasse.

Rückgabewert Bedeutung STSignoSigner Die Instanz der STSignoSigner-Klasse.

Exception Beschreibung STSignoSignerException Wird geworfen, wenn bei der Erzeugung der

STSignoSigner-Instanz ein Fehler auftritt.

Anwendung:

try{

STSignoSigner signoSigner = STSignoSignerCreator.createSignoSigner(

context, true);

} catch{

//error handling

}

Methode releaseSignoSigner

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

public static void releaseSignoSigner();

Parameter Bedeutung - -

Rückgabewert Bedeutung - -

Anwendung:

STSignoSignerCreator.releaseSignoSigner();


5 Klasse STSignoSigner

Die Klasse STSignoSigner ist ein wesentlicher Bestandteil der libSignoPDFSigner. Diese

Klasse wird zum Laden und Editeren von PDF-Dokumenten verwendet, ohne sie anzuzeigen

und bietet die Möglichkeit, dass die Signaturfelder unterschrieben werden. Sämtliche

Eigenschaften und Methoden dieser Klasse können auch mit der Klasse STSignoViewer

genutzt werden, wenn das Dokument auch angezeigt werden soll.

Anwendung:

STSignoSigner signoSigner =

STSignoSignerCreator.createSignoSigner(context);

Einige Methoden geben eine Ganzzahl zurück, anhand der ein Fehler erkannt werden kann.

Folgende Tabelle enthält die möglichen Fehlercodes:

Fehlercode Bedeutung

-100 Das Dokument konnte nicht geladen werden.

-110 Das Signaturfeld konnte nicht erzeugt werden.

-111 Das Dokument konnte nicht geladen werden, weil es Funktionen enthält,

die derzeit nicht unterstützt werden.

-112 Das Signaturfeld konnte nicht auf der gewünschten Seite erzeugt werden.

-113 Ein Formular- oder Signaturfeld mit dem gleichen Namen existiert bereits.

-114 Ein neues Signaturfeld kann nicht in einem signierten Dokument erzeugt

werden.

-115 Das Signaturfeld wurde bereits unterschrieben.

-116 Die Koordinaten des Signaturfeldes liegen außerhalb des sichtbaren

Bereichs.

-117 Das Dokument enthält keine Signaturfelder.

-118 Das Dokument enthält kein Signaturfeld mit dem gegebenen Namen.

-119 Ein neuer Signaturprozess kann nicht gestartet werden, weil es bereits ein

anderer aktiv ist.

-190 Ein Signaturfeld mit dem übergebenen Namen existiert nicht im

Dokument.

-191 Das Rechteck, welches die Größe und Position des Signaturfeldes definiert,

ist ungültig.

Methode setLicenseKey

Mit dieser Methode kann die Komponente libSignoPDFSigner freigeschaltet und somit der

Demo-Hinweis entfernt werden. Bitte verwenden Sie den Lizenzstring, der Ihnen von Ihrem

Kontakt bei signotec mitgeteilt worden ist.

void setLicenseKey(String licenseKey);

Parameter Bedeutung String licenseKey Lizenzstring


Anwendung:

signoSigner.setLicenseKey("1234");


Methode setSignatureTimeStampFormat

Mit dieser Methode kann eine Instanz der DateFormat Klasse gesetzt werden, um einen

Zeitstempel mit der Unterschrift visuell ins Dokument einbringen zu können. Im Falle, dass

keine Instanz dieser Klasse erzeugt und gesetzt wird, wird keinen Zeitstempel ins Dokument

eingebracht. Sie muss gesetzt werden, bevor die Methode loadDocumentFromFile()

aufgerufen wird.

void setSignatureTimeStampFormat(DateFormat dateFormat);

Parameter Bedeutung DateFormat dateFormat Die Instanz der DateFormat Klasse.


Anwendung:

DateFormat dateFormat =

new SimpleDateFormat(("E, dd MMM yyyy HH:mm:ss z", Locale.getDefault();

signoSigner.setSignatureTimeStampFormat(dateformat);

Methode setTimeStampColor

Mit dieser Eigenschaft kann die Farbe des Zeitstempels im Unterschriftbild konfiguriert

werden. Wenn die Eigenschaft nicht gesetzt wird, wird standardmäßig Schwarz verwendet.

void setTimeStampColor(int timeStampColor);

Parameter Bedeutung int timeStampColor Farbe des Zeitstempels


Anwendung:

signoSigner.setTimeStampColor(Color.BLUE);

Methode loadDocumentFromFile

Diese Methode lädt ein PDF-Dokument und interpretiert ggf. die enthaltenen SGN-

Schlüsselwörter.

int loadDocumentFromFile(byte[] documentData);

Parameter Bedeutung byte[] documentData Das zu ladende Dokument als Byte-Array.

Rückgabewert Bedeutung int 0 Methode wurde erfolgreich ausgeführt.

< 0 Es ist ein Fehler aufgetreten (s. o.).

Anwendung:

int ret = signoSigner.loadDocumentFromFile(documentData);

if (ret < 0) {

// error handling

}


Methode getDocumentMetaData

Diese Methode liest die Metadaten des Dokuments aus.

String getDocumentMetaData();


Rückgabewert Bedeutung String „Metadata“-Eintrag aus dem „Document Catalog“

Anwendung:

String metaData = signoSigner.getDocumentMetaData();

Methode setCertificates

Mit dieser Methode können die Schlüssel und Zertifikate zum Verschlüsseln der Biometrie und

zum Signieren des Dokuments übergeben werden.

void setCertificates:(byte[] signingCertificate, String signCertPassword,

byte[] biometricCertificate);

Parameter Bedeutung byte[]

signingCertificate PKCS#12-Datei als Byte-Array mit dem privaten Schlüssel

und dem öffentlichen Zertifikat zum Signieren des

Dokuments. String

signCertPassword Passwort der PKCS#12-Datei. Wird ignoriert, wenn für

signingCertificate null übergeben wird. byte[]

biometricCertificate X.509-Zertifikat als Byte-Array mit dem öffentlichen

Schlüssel zum Verschlüsseln der Biometrie.


Anwendung:

signoSigner.setCertificates(signCertificate, @"Password" bioCertificate);

Methode createNewSignatureField

Diese Methode erzeugt ein neues leeres Signaturfeld.

int createNewSignatureField(STSignatureFieldInfoDTO signatureField);

Parameter Bedeutung STSignatureFieldInfoDTO

signatureField Objekt, das die Eigenschaften des neuen Feldes

enthält.



Anwendung:

int ret = signoSigner.createNewSignatureField(signatureField);

if (ret < 0) {

// error handling

}


Methode getSignatureInfo

Mit dieser Methode können Informationen über die im Dokument enthaltenen Signaturfelder

abgerufen werden.

List<STSignatureFieldInfoDTO> getSignatureInfo();


Rückgabewert Bedeutung List<STSignatureFieldIn

foDTO> Eine Liste mit je einem STSignatureFieldInfoDTO-

Objekt pro Signaturfeld oder null, wenn das Dokument

keine Signaturfelder enthält.

Anwendung:

List<STSignatureFieldInfoDTO> signFields =

signoSigner.getSignatureInfo();

Methode getDocumentAsFile

Diese Methode gibt das Dokument im aktuellen Zustand zurück.

byte[] getDocumentAsFile();


Rückgabewert Bedeutung byte[] Das Dokument als Byte-Array

Anwendung:

byte[] document = signoSigner.getDocumentAsFile();

Methode signSignatureField

Mit dieser Methode kann ein bestimmtes Signaturfeld mit einer Unterschrift signiert werden,

die separat erfasst wurde. Eine Unterschrift bestehend aus den biometrischen Daten und dem

Bild der Unterschrift kann z. B. mit dem STSignatureCapture erfasst werden.

int signSignatureField(String signatureFieldName, byte[] signData, byte[]

image);

Parameter Bedeutung String

signatureFieldName Name des Signaturfeldes, das signiert werden soll; das

Feld darf noch nicht signiert sein. Wenn das Dokument

kein Feld mit diesem Namen enthält, wird ein neues Feld

auf Seite 1 mit den Koordinaten (0, 0, 0, 0) eingebracht. byte[] signData Byte-Array mit den biometrischen Daten, wie es von

STSignatureCapture getSignData() zurückgegeben wird. byte[] image Byte-Array mit dem Bild der Unterschrift, wie es von

STSignatureCapture getSignatureImage()

zurückgegeben wird.



< 0 Es ist ein Fehler aufgetreten (s. a. STSignoViewerNotifier signingProcessFailed().

Anwendung:

byte[] signData = signoCapture.getSignData();

byte[] image = signoCapture.getSignatureImage(800, 600, Color.Blue, 5);

int ret = signoSigner.signSignatureField("test_signature", signData,

image);

if (ret < 0) {

// error handling

}

Methode setSignatureFieldInfo

Mit dieser Methode können einer digitalen Signatur die Signatureinzelheiten wie den Standort

der Signatur und den Signaturgrund hinzugefügt werden. Diese Methode wird i.d.R. in der

Methode STSignoViewerNotifier willStartSigning() oder vor der Methode

STSignoSigner signSignatureField() aufgerufen.

void setSignatureFieldInfo(STSignatureFieldInfoDTO signatureFieldInfoDTO);

Parameter Bedeutung STSignatureFieldInfoDTO

signatureFieldInfoDTO Ein STSignatureFieldInfoDTO-Objekt


Anwendung:

STSignatureFieldInfoDTO signFieldDTO = new STSignatureFieldInfoDTO(“My

Signature”, “My Location”, “My Reason”);

oder

STSignatureFieldInfoDTO signFieldDTO = new STSignatureFieldInfoDTO();

signFieldDTO.setName(“My Signature”);

signFieldDTO.setLocation(“My Location”);

signFieldDTO.setReason(“My Reason”);

signoSigner.setSignatureFieldInfo(signFieldDTO);


6 Klasse STSignoViewerCreator

Die Klasse STSignoViewerCreator ist zuständig für die Erzeugung eines STSignoViewer-

Objekts und erzeugt nur genau eine Instanz der STSignoViewer-Klasse. Die Klasse ist


public class STSignoViewerCreator

Methode createSignoViewer

Mit dieser Methode kann eine Instanz der STSignoViewer-Klasse erzeugt werden.

public static STSignoViewer createSignoViewer(Context context, boolean

useAsFragment) throws STSignoViewerException;

Parameter Bedeutung Context context Der Kontext einer Activity-Klasse. boolean useAsFragment true Die erzeugte STSignoViewer-Instanz kann als

Fragment-Instanz verwendet werden.

false Die erzeugte STSignoViewer-Instanz ist die

Instanz einer Wrapper-Klasse für die Verwendung

der Activity-Klasse.

Rückgabewert Bedeutung STSignoViewer Die Instanz der STSignoViewer-Klasse.

Exception Beschreibung STSignoViewerException Wird geworfen, wenn bei der Erzeugung der

STSignoViewer-Instanz ein Fehler auftritt.

Anwendung:

try{

STSignoViewer signoViewer = STSignoViewerCreator.createSignoViewer(

context, true);

} catch{

//error handling

}

Methode releaseSignoViewer

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

public static void releaseSignoViewer();



Anwendung:

STSignoViewerCreator.releaseSignoViewer();


7 Klasse STSignoViewer

Die Klasse STSignoViewer ist das Herzstück der libSignoPDFSigner. Diese Klasse wird zur

Anzeige und zum Editieren von PDF-Dokumenten verwendet. Der STSignoViewer kann PDF-

Dokumente laden und anzeigen. Es kann durch Gesten gezoomt und geblättert werden,

Formularfelder können ausgefüllt und Signaturfelder unterschrieben werden. Sämtliche

Methoden der Klasse STSignoSigner gehören auch zur Klasse STSignoViewer, nachfolgend

sind nur die zusätzlich enthaltenen aufgeführt.

Anwendung:

STSignoViewer signoViewer =

STSignoViewerCreator.createSignoViewer(context, true);

Einige Methoden geben eine Ganzzahl zurück, anhand der ein Fehler erkannt werden kann.

Folgende Tabelle enthält die möglichen Fehlercodes:


-107 Die Toolbar kann nicht erzeugt werden, weil die Activity bereits über eine

Aktionsleiste verfügt. Es muss windowActionBar im Theme auf false

gesetzt werden, um stattdessen eine Toolbar zu verwenden.

-138 Die Unterschrifterfassung kann nicht gestartet werden, weil keine Instanz

der Klasse STSignatureCaptureConfig als Rückgabewert der Methode

STSignoViewerNotifier.willStartSigning() zurückgegeben worden

ist.

-160 Es konnte kein Bild zum Einbringen gefunden werden.

-161 Das Bild konnte nicht eingebracht werden.

-162 Das Bild hat eine unzulässige Größe.

-163 Das Bild konnte nicht auf der gewünschten Seite eingebracht werden.

-164 Die Bilddaten sind ungültig oder das Bild hat ein nicht unterstütztes

Format.

-165 Die Koordinaten des Bilds liegen außerhalb des sichtbaren Bereichs.

-166 Ein neues Bild kann nicht in ein signiertes Dokument eingebracht werden.

-167 Ein transparentes Bild kann nicht in ein PDF/A-

konformes Dokument eingebracht werden.

Methode setSignoViewerNotifier

Mit dieser Methode kann die Instanz gesetzt werden, die die Klasse STSignoViewerNotifier

implementiert und somit über Ereignisse im STSignoViewer informiert werden soll.

void setSignoViewerNotifier(STSignoViewerNotifier signoViewerNotifier);

Parameter Bedeutung STSignoViewerNotifier

signoViewerNotifier STSignoViewerNotifier-Instanz


Anwendung:

STSignoViewerNotifier signoViewerNotifier =

new STSignoViewerNotifierImpl();

signoViewer.setSignoViewerNotifier(signoViewerNotifier);


Methode loadDocumentFromFile

Diese Methode startet das asynchrone Laden und Anzeigen eines PDF-Dokuments.

Anschließend wird die Methode STSignoViewerNotifier documentLoaded() aufgerufen und

das Ergebnis dieser Methode kann erhalten werden. Beim erfolgreichen Laden des Dokuments

können die Methoden, die Änderungen im Dokument vornehmen, innerhalb der Methode

STSignoViewerNotifier documentLoaded() ausgeführt werden. Für weitere Informationen

siehe auch die Methode STSignoViewerNotifier documentLoaded().

Wenn die STSignoViewer-Instanz als Fragment-Instanz erzeugt wird, ist diese Methode nur

zuständig, das PDF-Dokument zu laden. Um das PDF-Dokument anzuzeigen, muss die

Methode FragmentTransaction.show() verwendet werden. Für weitere Informationen siehe

auch die Methode STSignoViewerCreator createSignoViewer().

void loadDocumentFromFile(byte[] documentData);

Parameter Bedeutung byte[] documentData Das zu ladende Dokument als Byte-Array.


Anwendung:

signoViewer.loadDocumentFromFile(documentData);

signoViewer.loadDocumentFromFile(documentData);

FragmentTransaction ft = fragmentManager.beginTransaction();

ft.add(R.id.docLayout, signoViewer).show(signoViewer).commit();

Methode showToolbar

Mit dieser Methode kann definiert werden, ob die Werkzeugleiste angezeigt werden soll. Sie

muss gesetzt werden, bevor die Methode loadDocumentFromFile() aufgerufen wird.

Die Werkzeugleiste enthält derzeit die folgenden vier Schaltflächen:

„Zurück“: Ruft die Methode STSignoViewerNotifier backButtonPressed() auf.

„Unterschreiben“: Springt die Signaturfelder der Reihe nach ab.

„Signaturfelder“: Ruft die Methode STSignoViewerNotifier signatureInfoPressed()

auf und zeigt ggf. einen Dialog mit den Signaturfeldern des Dokuments an.

„Speichern“: Ruft die Methode STSignoViewerNotifier documentSaved() auf.

void showToolbar(boolean show);

Parameter Bedeutung boolean show true Die Werkzeugleiste wird angezeigt.

false Die Werkzeugleiste wird nicht angezeigt.


Anwendung:

signoViewer.showToolbar(true);


Methode setToolbarHeight

Mit dieser Methode kann die Höhe der Werkzeugleiste gesetzt und somit auch den oberen

Rand der Dokumentanzeige gesetzt. Die Elemente der Werkzeugleiste werden immer am

oberen Rand der Werkzeugleiste angezeigt. Sie muss gesetzt werden, bevor die Methode

loadDocumentFromFile() aufgerufen wird.

void setToolbarHeight(int toolbarHeight);

Parameter Bedeutung int toolbarHeight Die Höhe der Werkzeugleiste.


Anwendung:

signoViewer.setToolbarHeight(120);

Methode startSignature

Diese Methode startet das Erfassen von Unterschriften. Diese Funktionalität kann auch durch

die „Unterschreiben“-Schaltfläche in der Werkzeugleiste oder durch das Antippen eines

Signaturfeldes im Dokument ausgelöst werden.

int startSignature();

int startSignature(String signatureFieldName);


signatureFieldName (Optional) Name des Signaturfeldes, das unterschrieben

werden soll; wird kein Name übergeben, werden alle Felder

in der Reihenfolge abgesprungen, in der sie in das

Dokument eingebracht worden sind.



Anwendung:

int ret = signoViewer.startSignature(“customer_signature”);

if (ret < 0) {

// error handling

}

Methode getFormFieldsInfo

Mit dieser Methode können Informationen über die im Dokument enthaltenen Formularfelder

abgerufen werden.

List<STFormFieldInfoDTO> getFormFieldsInfo();


Rückgabewert Bedeutung List<STFormFieldInfoDT

O> Eine Liste mit je einem STFormFieldInfoDTO-Objekt pro

Formularfeld oder null, wenn das Dokument keine

Formularfelder enthält.


Anwendung:

List<STFormFieldInfoDTO> formFields = signoViewer.getFormFieldsInfo();

Methode setFormFieldsInfo

Mit dieser Methode können der Inhalt und die „read only“-Eigenschaft von Formularfeldern

geändert werden.

void setFormFieldsInfo(List<STFormFieldInfoDTO> fields);

Parameter Bedeutung List<STFormFieldInfoDT

O> Formularfelder, deren Eigenschaften geändert werden

sollen, in Form einer Liste von STFormFieldInfoDTO-

Objekten. Von den Objekten werden derzeit nur die

Eigenschaften name, value und readOnly ausgewertet.


Anwendung:

List<STFormFieldInfoDTO> formFields = signoViewer.getFormFieldsInfo();

for (STFormFieldInfo formField : formFields) {

if (formField.name.equals("MyField")) {

formFields.value = "My value";

formField.readOnly = true;

}

}

signoViewer.setFormFieldsInfo.(formFields);

Methode closeViewer

Mit dieser Methode kann die View entfernt und zurück zur eigenen App-Oberfläche gewechselt

werden.

Wenn die STSignoViewer-Instanz als Fragment-Instanz erzeugt wurde, kann die View auch

mit der Methode FragmentTransaction.remove() entfernt werden. Für weitere Informationen

siehe auch die Methode STSignoViewerCreator.createSignoViewer().

void closeViewer();



Anwendung:

signoViewer.closeViewer();

FragmentTransaction ft = fragmentManager.beginTransaction();

ft.remove(signoViewer).commit();


Methode setCustomTheme

Mit dieser Methode kann das Standard Design der Werkzeugleiste durch benutzerdefiniertes

Design ersetzt werden. Die Activity-Klasse in der API basiert auf der Android Compability

Library v7, was bedeutet, dass das benutzerdefiniertes Design von Theme.AppCombat geerbt

werden muss. Im benutzerdefinierten Design können die Primärfarben mit den Attributen

colorPrimary, colorAccent und colorPrimaryDark definiert und muss die Standard

Aktionsleiste des Fensterdekors manuell deaktiviert werden, indem windowActionBar auf

false und windowNoTitle auf true gesetzt wird.

void setCustomTheme(int customTheme);

Parameter Bedeutung int customTheme Wert der Theme


Anwendung:

<style name="SignoApiTheme" parent="Theme.AppCompat.Light">

<item name="colorPrimary">@color/colorPrimary</item>

<item name="colorPrimaryDark">@color/colorPrimaryDark</item>

<item name="colorAccent">@color/colorAccent</item>

<item name="windowActionBar">false</item>

<item name="windowNoTitle">true</item>

</style>

signoViewer.setCustomTheme(R.style.SignoApiTheme);

Methode signDocument

Diese Methode fügt dem Dokument eine digitale Signatur hinzu, ohne dass eine

Unterschrifterfassung durchgeführt wird.

int signDocument(String signatureFieldName);


signatureFieldName Name des Signaturfeldes, das signiert werden soll; das

Feld darf noch nicht signiert sein. Wenn das Dokument

kein Feld mit diesem Namen enthält, wird ein neues Feld

auf Seite 1 mit den Koordinaten (0, 0, 0, 0) eingebracht.


< 0 Es ist ein Fehler aufgetreten (s. a. signingProcessFailed()).

Anwendung:

int ret = signoViewer.signDocument("final_doc_signature");

if (ret < 0) {

// error handling

}

Methode createViewerRect

Mit dieser Methode kann ein Rechteck auf dem PDF-Viewer angezeigt werden, welches vom

Anwender in der Größe und Position verändert werden kann. Zusätzlich zum Rechteck werden


zwei Schaltflächen zum Abbrechen und Bestätigen erzeugt. Beim Antippen der Abbrechen-

Schaltfläche wird die Methode STSignoViewerNotifier.viewerRectCancelled() aufgerufen.

Beim Antippen der Bestätigungs-Schaltfläche wird die Methode

STSignoViewerNotifier.viewerRectConfirmed() aufgerufen. Mit Hilfe der Klasse

STViewerRectDTO können weitere Eigenschaften des Rechtecks konfiguriert werden. Für

weitere Informationen siehe auch die Klasse STViewerRectDTO.

int createViewerRect(STViewerRectDTO viewerRectDTO);

Parameter Bedeutung STViewerRectDTO

viewerRectDTO Das STViewerRectDTO–Objekt

Rückgabewert Bedeutung int > 0 Eindeutige ID des erzeugten Rechtecks.

-1 Es ist ein Fehler aufgetreten.

Anwendung:

STViewerRectDTO rectViewerDTO = new STViewerRectDTO();

int rectViewId = signoViewer.createViewerRect(rectViewerDTO);

Methode enableAutoRotation

Mit dieser Methode kann das Drehen des Bildschirms gesperrt und entsperrt werden.

void enableAutoRotation(boolean enabled);

Parameter Bedeutung boolean enabled true Drehen des Bildschirms wird entsperrt.

false Drehen des Bildschirms wird gesperrt.


Anwendung:

signoViewer.enableAutoRotation(true);

Methode enableTouchEvents

Mit dieser Methode können alle Touch-Events im PDF-Viewer gesperrt und entsperrt werden.

void enableTouchEvents(boolean enabled);

Parameter Bedeutung boolean enabled true Alle Touch Events werden entsperrt.

false Alle Touch Events werden gesperrt.


Anwendung:

signoViewer.enableTouchEvents(true);


Methode addImages

Mit dieser Methode können Bilder in das geladene Dokument eingefügt werden.

int addImages(List<STImageDTO> images);

Parameter Bedeutung List<STImageDTO>

images Eine Liste von STImageDTO-Objekten. Darf null sein, dann

werden keine Bilder hinzugefügt.


< 0 Es ist ein Fehler aufgetreten. (s. o.).

Anwendung:

STRectDTO size = new STRectDTO();

size.setUnit(STRectDTO.Unit.UnitMillimetres);

size.setRectangle(new RectF(0.0f, 0.0f, 210.0f, 297.0f));

STImageDTO imageDTO = new STImageDTO();

Bitmap myimage = BitmapFactory.decodeResource(this.getResources(),

R.drawable.myimage);

imageDTO.setImage(myimage);

imageDTO.setRectDTO(size);

imageDTO.setPage(1);

List<STImageDTO> images = new ArrayList<>();

images.add(imageDTO);

int result = signoViewer.addImages(images);

Methode startTextSearch

Diese Methode sucht nach einem Text auf einer PDF-Seite, hebt ggf. alle Fundstellen visuell

hervor und liefert die Positionen aller Fundstellen zurück.

List<Rect> startTextSearch(String text, int page, int highlightColor, boolean

onlyWholeWord, boolean caseSensitive);

Parameter Bedeutung String text Text, der gesucht wird. int page Seite, auf der der Text gesucht wird. Die erste

Seitennummer des Dokuments beginnt mit 1. int highlightColor Hintergrundfarbe des Rechtecks, welches den gefundenen

Suchtext im PDF-Viewer visuell hervorhebt. Wenn 0

übergeben wird, wird keine Hervorhebung angezeigt. boolean onlyWholeWord true Es werden nur ganze Wörter gefunden.

false Es werden alle Vorkommen gefunden. boolean caseSensitive true Die Groß-/Kleinschreibung wird berücksichtigt.

false Die Groß-/Kleinschreibung wird ignoriert.

Rückgabewert Bedeutung List Die Positionen aller Fundstellen in Form einer Liste von

Rect-Objekten oder eine leere Liste.


Anwendung:

List<Rect> foundedTextPositions =

signoViewer.startTextSearch(“Signature”, 1, null, true, true);

for(Rect rect : foundedTextPositions){

SignatureFieldInfoDTO field = new SignatureFieldInfoDTO();

field.setName(“@New_Signature”);

field.setPage(1);

field.setRectangle(rect);

int result = signoViewer.createNewSigantureField(field);

}

Methode finishTextSearch

Mit dieser Methode können die visuellen Hervorhebungen, die nach der Ausführung der

Methode STSignoViewer startTextSearch() an allen Fundstellen des Suchtextes angezeigt

werden, aus dem PDF-Viewer entfernt werden.

void finishTextSearch();



Anwendung:

signoViewer.finishTextSearch();

Methode showPageNumber

Mit dieser Methode kann konfiguriert werden, ob die Seitennummer im PDF-Viewer angezeigt

wird.

void showPageNumber(boolean show);

Parameter Bedeutung boolean show true Die Seitennummer wird angezeigt.

false Die Seitennummer wird nicht angezeigt.


Anwendung:

signoViewer.showPageNumber(true);


8 Interface STSignoViewerNotifier

Das Interface STSignoViewerNotifier enthält Methoden, die bei bestimmten Ereignissen aus

der Klassen STSignoViewer aufgerufen werden. Diese Klasse muss von einer Klasse

implementiert werden. Die Instanz dieser Klasse soll mit der Methode STSignoViewer

setSignoViewerNotifier() gesetzt werden. Die Klasse ist Bestandteil der libSignoPDFSigner.

public interface STSignoViewerNotifier

public class STSignoViewerNotifierImpl implements STSignoViewerNotifier

Anwendung:

STSignoViewerNotifier signoViewerNotifier = new

STSignoViewerNotfierImpl();

signoViewer.setSignoViewerNotifier(signoViewerNotifier);

Methode documentLoaded

Diese Methode wird am Ende der asynchronen STSignoViewer loadDocumentFromFile()

aufgerufen. Im Erfolgsfall können die Änderungen im Dokument vorgenommen werden. (z.B

Signaturfelder hinzufügen durch die Methode STSignoViewer createNewSignatureField()).

void documentLoaded(int resultCode);

Parameter Bedeutung int resultCode 0 Die Methode STSignoViewer

loadDocumentFromFile() wurde erfolgreich

ausgeführt. < 0 Es ist ein Fehler aufgetreten (s. o.).


Anwendung:

void documentLoaded(int resultCode)

{

// event handling

}

Methode willStartSigning

Diese Methode wird jedes Mal aufgerufen, wenn die Unterschrifterfassung für ein noch nicht

unterschriebenes Signaturfeld gestartet werden soll.

STSignatureCaptureConfig willStartSigning(String signatureFieldName);

Parameter Bedeutung String signatureFieldName Name des Signaturfeldes, für das die Unterschrift

erfasst werden soll.

Rückgabewert Bedeutung STSignatureCaptureConfig !=

null Die Unterschrifterfassung soll mit den in der

zurückgegebenen Instanz eingestellten

Eigenschaften gestartet werden. null Die Unterschrifterfassung soll nicht gestartet

werden.


Anwendung:

STSignatureCaptureConfig willStartSigning(String signatureFieldName)

{

STSignatureCaptureConfig config = new STSignatureCaptureConfig();

config.setSignatureColor(Color.BLUE);

config.setLineWidth(10);

config.setFont(TypeFace.create(“Arial”, TypeFace.Bold_ITALIC));

config.setDisplayText(signatureFieldName);

config.setFontSize(40);

config.setTextColor(Color.BLACK);

config.setPosition(new Rect(0,0,1000,100));

return config;

}

Methode signingProcessStarted

Diese Methode wird aufgerufen, wenn die Unterschrifterfassung für ein noch nicht

unterschriebenes Signaturfeld gestartet worden ist.

List<STFormFieldInfoDTO> signingProcessStarted(String signatureFieldName);


signatureFieldName Name des Signaturfeldes, für das die Unterschrift erfasst

wird.


O> Für zukünftige Verwendung reserviert.

Anwendung:

List<STFormFieldInfoDTO> signingProcessStarted(String signatureFieldName)

{

return null;

}

Methode signingProcessConfirmed

Diese Methode wird jedes Mal aufgerufen, wenn die Unterschrifterfassung für ein Signaturfeld

erfolgreich beendet und das Dokument fertig signiert ist.

void signingProcessConfirmed(String signatureFieldName);


signatureFieldName Name des Signaturfeldes, für das die Unterschrift erfasst

worden ist.


Anwendung:

void signingProcessConfirmed(String signatureFieldName)

{

// event handling

}


Methode signingProcessCancelled

Diese Methode wird aufgerufen, wenn die Unterschrifterfassung vom Anwender abgebrochen

worden ist, indem er den „Abbrechen“-Button betätigt hat.

void signingProcessCancelled(String signatureFieldName);


signatureFieldName Name des Signaturfeldes, für das die Erfassung

abgebrochen worden ist.


Anwendung:

void signingProcessCancelled(String signatureFieldName)

{

// event handling

}

Methode signingProcessFailed

Diese Methode wird aufgerufen, wenn die Unterschrifterfassung oder das Einbringen der

Unterschrift in das Dokument fehlgeschlagen ist.

void signingProcessFailed(String signatureFieldName, String errorMessage,

String errorCode);


signatureFieldName Name des Signaturfeldes, bei dem die Erfassung

fehlgeschlagen ist. String errorMessage Beschreibung des Fehlers String errorCode Fehlercode.


Anwendung:

void signingProcessFailed(String signatureFieldName, String errorMessage,

String errorCode)

{

// event handling

}


Folgende Fehler können auftreten:


-108 Der Signaturprozess kann nicht gestartet werden.

-120 Das Dokument konnte nicht geladen werden.

-121 Das Dokument konnte nicht gelesen werden.

-122 Das PDF ist passwortgeschützt.

-123 Der Schlüsselcontainer wurde nicht gefunden.

-124 Der Schlüsselcontainer konnte nicht gelesen werden.

-125 Das Passwort des Schlüsselcontainers ist ungültig.

-126 Der Schlüsselcontainer hat ein nicht unterstütztes Format.

-127 Der Schlüsselcontainer enthält keinen privaten Schlüssel.

-128 Fehler beim Schreiben der Datei.

-129 Fehler beim Signieren des Dokuments.

-130 Der Signaturfeldname ist ungültig.

-131 Das Zertifikat konnte nicht gelesen werden.

-132 Die erfasste Unterschrift ist zu kurz.

-135 Vor dem Unterschreiben wurde kein privater Schlüssel oder kein Zertifikat

übergeben.

-137 Beim Erstellen des Signaturbildes ist ein Fehler aufgetreten.

Methode signatureInfoPressed

Diese Methode wird aufgerufen, wenn die „Signaturfelder“-Schaltfläche in der Werkzeugleiste

angetippt worden ist.

boolean signatureInfoPressed();


Rückgabewert Bedeutung boolean true Die Bibliothek zeigt den Standarddialog mit den

Signaturfeldern des Dokuments an. false Die Bibliothek reagiert nicht mehr auf das Event;

üblicherweise würde die App dann das

Eventhandling übernehmen.

Anwendung:

boolean signatureInfoPressed

{

return true;

}

Methode documentSaved

Diese Methode wird aufgerufen, wenn die „Speichern“-Schaltfläche in der Werkzeugleiste

angetippt worden ist. Üblicherweise sollte in diesem Event die Methode STSignoViewer

getDocumentAsFile() aufgerufen werden.

boolean documentSaved();



Rückgabewert Bedeutung boolean true Die „Speichern“-Schaltfläche soll ausgegraut

werden. false Die „Speichern“-Schaltfläche soll nicht ausgegraut

werden.

Anwendung:

boolean documentSaved()

{

// event handling

return true;

}

Methode backButtonPressed

Diese Methode wird aufgerufen, wenn die „Zurück“-Schaltfläche in der Werkzeugleiste

angetippt worden ist. Üblicherweise sollte die Methode STSignoViewer closeViewer()

aufgerufen werden. Für weitere Informationen siehe auch die Methode STSignoViewer closeViewer().

void backButtonPressed()



Anwendung:

void backButtonPressed()

{

// event handling

}

Methode viewerRectConfirmed

Diese Methode wird aufgerufen, wenn die Bestätigungs-Schaltfläche eines durch den Aufruf

von STSignoViewer.createViewerRect() erzeugten Rechtecks angetippt worden ist.

Üblicherweise sollte in diesem Event STSignoViewer createNewSignatureField() oder

STSignoViewer.addImages() aufgerufen werden.

boolean viewerRectConfirmed(Rect rectInPdf, int page, int viewerRectId);

Parameter Bedeutung Rect rectInPdf Position und Größe des Rechtecks auf der Seite im PDF-

Koordinatensystem. int page Nummer der Seite, auf der das Rechteck bestätigt wurde.

Die erste Seitennummer des Dokuments beginnt mit 1. Int viewerRectId Eindeutige ID des erzeugten Rechtecks.

Rückgabewert Bedeutung boolean true Das Rechteck soll ausgeblendet werden.

false Das Rechteck soll weiterhin angezeigt werden.


Anwendung:

boolean viewerRectConfirmed(Rect rectInPdf, int page, int viewerRectId

{

STSignatureFieldInfoDTO sigField = new STSignatureFieldInfoDTO();

sigField.setName("New_Signature");

sigField.setPage(page);

sigField.setRectangle(rectInPdf);

int result = signoViewer.createNewSignatureField(sigField);

if (result < 0)

// error handling

return false;

return true;

}

Methode viewerRectCancelled

Diese Methode wird aufgerufen, wenn die Abbrechen-Schaltfläche eines durch den Aufruf von

STSignoViewer.createViewerRect() erzeugten Rechtecks angetippt worden ist.

void viewerRectCancelled(int viewerRectId);

Parameter Bedeutung int viewerRectId Eindeutige ID des erzeugten Rechtecks.


Anwendung:

void viewerRectCancelled(int viewerRectId)

{

//error handling

}


9 Klasse STSignoUtils

Die Klasse STSignoUtils ist eine Utility Klasse in der libSignoPDFSigner und besteht aus

statischen Methoden. Diese Klasse kann verwendet werden, um die PDF-Dokumente zu

bearbeiten und neue PDF-Dokumente zu erzeugen, ohne sie anzuzeigen. Die Klasse ist


Methode appendPage

Mit dieser Methode kann eine leere Seite an ein Dokument angehängt und optional Bilder auf

dieser Seite eingefügt werden.

public static byte[] appendPage(STRectDTO size, byte[] document,

List<STImageDTO> images);

Parameter Bedeutung STRectDTO size Die Größe der neuen Seite. byte[] document Das Dokument als Byte-Array. List<STImageDTO>



Rückgabewert Bedeutung byte[] Das geänderte Dokument als Byte-Array.

Anwendung:


size.setUnit(STRectDTO.Unit. UnitMillimetres);







List<STImageDTO> images = new ArrayList<>(); images.add(imageDTO);

byte[] changedDoc = STSignoUtils.appendPage(size, document, images);

Methode createDocument

Mit dieser Methode kann ein Dokument aus leeren Seiten erzeugt und optional Bilder auf den

Seiten eingefügt werden.

public static byte[] createDocument(STRectDTO size, int pages, PdfACompliance

compliance, List<STImageDTO> images);

Parameter Bedeutung STRectDTO size Die Größe der neuen Seite. int pages Die Anzahl der Seiten. PdfACompliance

compliance PDF/A-Konformität

List<STImageDTO>




Die Enumeration PdfACompliance ist in der Klasse STSignoUtils wie folgt definiert:


public enum PdfACompliance

{

None,

PdfA1b,

PdfA3b

}

Wert Bedeutung None Keine PDF/A-Konformität PdfA1b PDF/A1b-Konformität PdfA3b PDF/A3b-Konformität

Anwendung:


size.setUnit(STRectDTO.Unit.UnitMillimetres);







List<STImageDTO> images = new ArrayList<>(); images.add(imageDTO);

byte[] createdDoc = STSignoUtils.createDocument(size, 1,

STSignoUtils.PdfACompliance.None, images);

Methode getDocumentMetaDataFromFile

Diese Methode liest die Metadaten des Dokuments aus, ohne dass eine ggf. vorhandene

Instanz der Klasse STSignoViewer beeinflusst wird.

public static String getDocumentMetaDataFromFile(byte[] document);

Parameter Bedeutung byte[] document Das Dokument als Byte-Array.

Rückgabewert Bedeutung String „Metadata“-Eintrag aus dem „Document Catalog“

Anwendung:

String metaData = STSignoUtils.getDocumentMetaDataFromFile(document);

Methode getFormFieldsInfoFromFile

Mit dieser Methode können Informationen über die im Dokument enthaltenen Formularfelder

abgerufen werden, ohne dass eine ggf. vorhandene Instanz der Klasse STSignoViewer

beeinflusst wird.

public static List<STFormFieldInfoDTO> getFormFieldsInfoFromFile(byte[]

document);




O> Eine Liste mit je einem STFormFieldInfoDTO-Objekt pro

Formularfeld oder null, wenn das Dokument keine

Formularfelder enthält.

Anwendung:

List<STFormFieldInfoDTO> formFields =

STSignoUtils.getFormFieldsInfoFromFile(document);

Methode setFormFieldsInfoToFile

Mit dieser Methode können der Inhalt und die „read only“-Eigenschaft von Formularfeldern

geändert werden.

public static byte[] setFormFieldsInfoToFile(List<STFormFieldInfoDTO>

formFieldsInfo, byte[] document);

Parameter Bedeutung List<STFormFieldInfoDT

O> formFieldsInfo Formularfelder, deren Eigenschaften geändert werden

sollen, in Form einer Liste von STFormFieldInfoDTO-

Objekten. Von den Objekten werden derzeit nur die

Eigenschaften name, value und readOnly ausgewertet. byte[] document Das Dokument als Byte-Array.


Anwendung:

List<STFormFieldInfoDTO> formFields =

STSignoUtils.getFormFieldsInfoFromFile(document);

for (STFormFieldInfo formField : formFields) {

if (formField.getName().equals("MyField")) {

formFields.setValue("My value");

formField.setReadOnly(true);

}

}

byte[] changedDoc = STSignoUtils.setFormFieldsInfo(formFields, document);

Methode getSignatureInfoFromFile

Mit dieser Methode können Informationen über die im Dokument enthaltenen Signaturfelder

abgerufen werden, ohne dass eine ggf. vorhandene Instanz der Klasse STSignoViewer

beeinflusst wird.

public static List<STSignatureFieldInfoDTO> getSignatureInfoFromFile(byte[]

document);


Rückgabewert Bedeutung List<STSignatureFieldI

nfoDTO> Eine Liste mit je einem STSignatureFieldInfoDTO-Objekt

pro Signaturfeld oder null, wenn das Dokument keine

Signaturfelder enthält.


Anwendung:

List<STSignatureFieldInfoDTO> sigFields =

STSignoUtils.getSignatureInfoFromFile(document);


10 Klasse STSignatureFieldInfoDTO

Die Klasse STSignatureFieldInfoDTO ist ein Datenobjekt, das die Eigenschaften eines

Signaturfeldes enthält. Die Klasse ist Bestandteil der libSignoPDFSigner.

Eigenschaft Bedeutung String name Name des Signaturfeldes Rect rectangle Positionsangabe des Signaturfeldes int page Seite, auf der sich das Signaturfeld befindet. Die

erste Seitennummer des Dokuments beginnt mit 1. boolean isSigned true, wenn das Feld bereits unterschrieben ist, sonst

false boolean isRequired true, wenn das Feld ein Pflichtfeld ist, sonst false String location Standort der Signatur String reason Grund der Signatur


11 Klasse STFormFieldInfoDTO

Die Klasse STFormFieldInfoDTO ist ein Datenobjekt, das die Eigenschaften eines

Formularfeldes enthält. Die Klasse ist Bestandteil der libSignoPDFSigner.

Eigenschaft Bedeutung String name Name des Formularfeldes Rect rectangle Positionsangabe des Formularfeldes int page Seite, auf der sich das Formularfeld befindet. Die

erste Seitennummer des Dokuments beginnt mit 1. FormFieldType type Typ des Formularfeldes String value Wert des Formularfeldes boolean readOnly „read only“-Eigenschaft des Formularfeldes boolean isRequired true, wenn das Feld ein Pflichtfeld ist, sonst false


12 Klasse STSignatureCaptureConfig

Die Klasse STSignatureCaptureConfig ist ein Datenobjekt, das Konfigurationseigenschaften

für den Signaturdialog enthält. Für weitere Informationen siehe auch die Methode

STSignoViewerNotifier.willStartSigning() oder

STSignatureCapture.configureDialog().Die Klasse ist Bestandteil sowohl der

libSignoPDFSigner als auch der libSignoSignatureCapture.

Eigenschaft Bedeutung String displayText Text, der im Signaturdialog angezeigt wird Typeface font Schriftart und -stil des Textes im Signaturdialog int fontSize Schriftgröße des Textes im Signaturdialog (in dp) Int textColor Farbe des Textes im Signaturdialog Rect position Positionsangabe des Textes im Signaturdialog int signatureColor Stiftfarbe der Unterschrift int lineWidth Stiftbreite der Unterschrift in dp (1-20) boolean

enablePressureDependentCaptu

ring

true Die Unterschrift wird im Signaturdialog mit

Druckstufen abgebildet. false Die Unterschrift wird im Signaturdialog nicht

mit Druckstufen abgebildet. boolean

enableFullScreenCapture

true Der Signaturdialog wird im Vollbildmodus

angezeigt. false Der Signaturdialog wird im Standardmodus

angezeigt. boolean enableTouchSignature true Die Unterschriftenerfassung mit dem Finger

wird im Signaturdialog aktiviert. false Die Unterschriftenerfassung mit dem Finger

wird im Signaturdialog deaktiviert. boolean

enablePencilSignature

true Die Unterschriftenerfassung mit dem Stift

wird im Signaturdialog aktiviert. false Die Unterschriftenerfassung mit dem Stift

wird im Signaturdialog deaktiviert. boolean

enableBiometricDataCapturing

true Es werden biometrische Daten erfasst. false Es werden keine biometrischen Daten

erfasst.

dp = density-independent pixels


13 Klasse STImageDTO

Die Klasse STImageDTO ist ein Datenobjekt, das ein Bild auf einer PDF-Seite und seine Position

repräsentiert. Die Klasse ist Bestandteil der libSignoPDFSigner.

Eigenschaft Bedeutung Bitmap image Bild STRectDTO rectangle Positionsangabe des Bildes innerhalb einer PDF-Seite int page Seitenangabe des Bildes innerhalb eines Dokuments.

Die erste Seitennummer des Dokuments beginnt mit

1.


14 Klasse STRectDTO

Die Klasse STRectDTO ist ein Datenobjekt, das ein Rechteck repräsentiert. Die Klasse ist


Eigenschaft Bedeutung RectF rectangle Positionsangabe des Rechtecks Unit unit Maßeinheit der Koordinaten

Die Enumeration Unit ist wie folgt definiert:

public enum Unit{UnitPoints(0), UnitMilimetres(1), UnitInches(2);

Wert Bedeutung UnitPoints Die Koordinaten sind in Punkten angegeben. Ein PDF

hat grundsätzlich die Auflösung von 72 dpi. UnitMillimetres Die Koordinaten sind in Millimetern angegeben. UnitInches Die Koordinaten sind in Zoll angegeben.


15 Klasse STSignatureCaptureCreator

Die Klasse STSignatureCaptureCreator ist zuständig für die Erzeugung eines

STSignatureCapture-Objekts und erzeugt nur genau eine Instanz der STSignatureCapture-

Klasse. Die Klasse ist Bestandteil sowohl der libSignoPDFSigner als auch der


public class STSignatureCaptureCreator

Methode createSignatureCapture

Mit dieser Methode kann eine Instanz der STSignatureCapture-Klasse erzeugt werden.

public static STSignatureCapture createSignatureCapture(Context context)

throws STSignatureCaptureException;

Parameter Bedeutung Context context Der Kontext einer Activity-Klasse

Rückgabewert Bedeutung STSignatureCapture Die Instanz der STSignatureCapture-Klasse

Exception Beschreibung STSignatureCaptureExce

ption Wird geworfen, wenn bei der Erzeugung der

STSignatureCapture-Instanz ein Fehler auftritt.

Anwendung:

try{

STSignatureCapture signatureCapture =

STSignatureCaptureCreator.createSignatureCapture(context);

} catch {

//error handling

}

Methode releaseSignatureCapture

Mit dieser Methode kann die erzeugte Instanz der STSignatureCapture-Klasse freigegeben

werden.

public static void releaseSignatureCapture();



Anwendung:

STSignoViewerCreator.releaseSignatureCapture();


16 Klasse STSignatureCapture

Die Klasse STSignatureCapture ist der wichtigste Bestandteil der Bibliothek

libSignoSignatureCapture. Diese Klasse kann zur Anzeige eines Dialogs zum Erfassen einer

Unterschrift verwendet werden. Die Klasse ist Bestandteil sowohl der libSignoPDFSigner als

auch der libSignoSignatureCapture.

Anwendung:

STSignatureCapture signatureCapture =

STSignatureCaptureCreator.createSignatureCapture(context);

Methode setSignatureCaptureNotifier

Mit dieser Methode kann die Instanz gesetzt werden, die die Klasse

STSignatureCaptureNotifier implementiert und somit über Ereignisse im

STSignatureCapture informiert werden soll.

void setSignatureCaptureNotifier(STSignatureCaptureNotifier

signatureCaptureNotifier);

Parameter Bedeutung STSignatureCaptureNotifier

signatureCaptureNotifier STSignatureCaptureNotifier-Instanz


Anwendung:

STSignatureCaptureNotifier signatureCaptureNotifier =

new STSignatureCaptureNotifierImpl();

signatureCapture.setSignatureCaptureNotifier(signatureCaptureNotifier);

Methode configureDialog

Mit dieser Methode kann der Signaturdialog positioniert und konfiguriert werden. Die

Konfiguration wird ignoriert, wenn die Eigenschaft enableFullScreenCapture der Klasse

STSignatureCaptureConfig auf true gesetzt wird.

void configureDialog(Rect dialogFrame, STSignatureCaptureConfig

captureConfig);

Parameter Bedeutung Rect dialogFrame Positionsangabe des Signaturdialogs. STSignatureCaptureConfig

captureConfig Das STSignatureCaptureConfig–Objekt oder null.



Anwendung:

STSignatureCaptureConfig captureConfig = new STSignatureCaptureConfig();

captureConfig.setSignatureColor(Color.BLUE);

captureConfig.setLineWidth(10);

captureConfig.setFont(TypeFace.create(“Arial”, TypeFace.Bold_ITALIC));

captureConfig.setDisplayText(signatureFieldName);

captureConfig.setFontSize(40);

captureConfig.setTextColor(Color.BLACK);

captureConfig.setPosition(new Rect(0,0,1000,100));

Rect rect = new Rect(0, 0, 700, 500);

signatureCapture.configureDialog(rect, captureConfig);

Methode getSignatureImage

Diese Methode gibt die zuletzt erfasste Unterschrift als Bild im PNG-Format zurück.

byte[] getSignautureImage(float width, float height, int penColor, int

penWidth) throws STSignatureCaptureException;

Parameter Bedeutung float width Maximale Breite des Bildes in Pixeln. float height Maximale Höhe des Bildes in Pixeln. int penColor Farbe der Unterschriftlinie. int penWidth Breite der Unterschriftlinie in Pixeln.

Rückgabewert Bedeutung byte[] Das Signaturbild als Byte-Array oder null.

Exception Beschreibung STSignatureCaptureExce

ption Wird geworfen, wenn bei der Erzeugung des Signaturbilds

ein Fehler auftritt.

Anwendung:

try{

byte[] signatureImage =

signatureCapture.getSignatureImage(1500, 1000, Color.BLUE, 10);

} catch (STSignatureCaptureException e){

//error handling

}

Methode getSignData

Diese Methode gibt die zuletzt erfasste Unterschrift im SignData-Format zurück.

byte[] getSignData();


Rückgabewert Bedeutung byte[] Die SignData als Byte-Array oder null.

Anwendung:

byte[] signData = signatureCapture.getSignData();


Methode setLicenseKey

Mit dieser Methode kann die Komponente libSignoSignatureCapture freigeschaltet und somit

der Demo-Hinweis entfernt werden. Bitte verwenden Sie den Lizenzstring, der Ihnen von

Ihrem Kontakt bei signotec mitgeteilt worden ist.

void setLicenseKey(String licenseKey);

Parameter Bedeutung String licenseKey Lizenzstring


Anwendung:

signatureCapture.setLicenseKey("1234");

Methode startSignatureCapture

Mit dieser Methode kann die Unterschrifterfassung gestartet werden.

void startSignatureCapture();



Anwendung:

signatureCapture.startSignatureCapture();

Methode resizeCaptureDialog

Diese Methode kann die Größe und Position des Signaturdialogs entsprechend der neuen

Konfiguration des Signaturdialogs durch die Methode configureDialog() beim Drehen des

Geräts ändern und wird i.d.R. in der Methode onConfigurationChanged() der jeweiligen

Activity Klasse aufgerufen.

void resizeCaptureDialog();



Anwendung:

signatureCapture.resizeCaptureDialog();


17 Interface STSignatureCaptureNotifier

Das Interface STSignatureCaptureNotifier enthält Methoden, die bei bestimmten

Ereignissen aus der Klasse STSignatureCapture aufgerufen werden. Dieses Interface muss

von einer Klasse implementiert werden. Die Instanz dieser Klasse muss mit der Methode

STSignatureCapture setSignatureCaptureNotifier() gesetzt werden. Das Interface ist

Bestandteil sowohl der libSignoPDFSigner als auch der libSignoSignatureCapture.

public interface STSignatureCaptureNotifier

public class STSignatureCaptureNotifierImpl implements

STSignatureCaptureNotifier

Anwendung:

STSignatureCaptureNotifier signatureCaptureNotifier = new

STSignatureCaptureNotifierImpl();

signatureCapture.setSignatureCaptureNotifier(signatureCaptureNotifier);

Methode capturingCancelled

Diese Methode wird aufgerufen, wenn die Unterschrifterfassung vom Anwender abgebrochen

worden ist.

void capturingCancelled();



Anwendung:

void capturingCancelled()

{

// event handling

}

Methode capturingConfirmed

Diese Methode wird aufgerufen, wenn die Unterschrifterfassung vom Anwender bestätigt

worden ist.

void capturingConfirmed(int numberOfPoints);

Parameter Bedeutung int numberOfPoints Anzahl der erfassten Punkte.


Anwendung:

void capturingConfirmed(int numberOfPoints){

// event handling

}


18 Klasse STLogger

Die Klasse STLogger wird zur Aktivierung und Konfiguration des Logging durch das Java

Logging API verwendet. Die Klasse ist Bestandteil sowohl der libSignoPDFSigner als auch der


Methode getLogger

Diese Methode gibt das in der API generierte Logger-Objekt zurück, so dass die Logging

außerhalb des API konfiguriert werden kann.

public static Logger getLogger();


Rückgabewert Bedeutung Logger Logger-Objekt des Java Logging API

Anwendung:

String logFilePath = Environment.getExternalStorageDirectory() + log.txt;

Logger logger = STLogger.getLogger();

logger.setLevel(Level.ALL);

FileHandler fileTxt = null;

try {

fileTxt = new FileHandler(logFilePath);

} catch (IOException e) {

return;

}

// create a TXT formatter

SimpleFormatter formatterTxt = new SimpleFormatter();

fileTxt.setFormatter(formatterTxt);

logger.addHandler(fileTxt);


19 Klasse STViewerRectDTO

Die Klasse STViewerRectDTO ist ein Datenobjekt, das ein Rechteck auf dem PDF-Viewer

repräsentiert. Die Klasse ist Bestandteil der libSignoPDFSigner.

Eigenschaft Bedeutung Rect rectangle Positionsangabe des Rechtecks (Standard-Maßeinheit in dp) int borderColor Rahmenfarbe des Rechtecks int backgroundColor Hintergrundfarbe des Rechtecks Bitmap backgroundImage Hintergrundbild des Rechtecks

Die Positionsangabe des Rechtecks kann in zwei verschiedenen Maßeinheiten übergeben

werden. Diesbezüglich wird die Enumeration STViewerRectUnit verwendet. Die Enumeration

STViewerRectUnit ist in der Klasse STViewerRectDTO wie folgt definiert:

public enum STViewerRectUnit

{

DP,

PX

}

Wert Bedeutung DP Positionsangabe des Rechtecks in dp (Density-independent Pixels). PX Positionsangabe des Rechtecks in Pixel.

Anwendung:

STViewerRectDTO viewerRectDTO = new STViewerRectDTO();

viewerRectDTO.setRectangle(new Rect(10,10,100,100));

viewerRectDTO.setRectangle(new Rect(10,10,100,100),

STViewerRectDTO.STViewerRectUnit.PX);

viewerRectDTO.setRectangle(new Rect(10,10,100,100),

STViewerRectDTO.STViewerRectUnit.DP);

Documents

Dokumentation signoAPI Android - signotec GmbH