signoAPI Android – 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, Signaturfelder zu unterschreiben. Sämtliche Eigenschaften und Methoden dieser Klasse können auch mit der Klasse STSignoViewer genutzt werden, wenn das Dokument auch angezeigt werden soll.

Anwendung:

Java

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.
-101	Das vorherige Dokument wurde nicht entladen. Siehe die Methode STSignoSigner.unloadDocument().
-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.
-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.
-200	Der Fehlercode wird von den Methoden STSignoViewer.createViewerRect(), STSignoViewer.startSignature(), STSignoViewer.signDocument(), STSignoViewer.createNewSignatureField() und STSignoViewer.addImages() zurückgegeben, wenn sich der Viewer im Notizen-Modus befindet und die gewünschte Aktion aufgrund des aktuellen Notizen-Modus nicht durchgeführt werden kann.
-201	Eine gezeichnete Notiz kann nicht in das PDF-Dokument übernommen werden, weil der Viewer sich nicht im Notizen-Modus befindet.
-202	Der Fehlercode wird beim Starten des Notizen-Modus zurückgegeben, wenn es sich bei dem aktuellen Dokument um ein PDF/A-1b-Dokument handelt. Das Einfügen von Bildern mit Alphakanal, die für den Notizen-Modus erforderlich sind, würde die PDF/A-1b-Konformität verletzen, weshalb der Vorgang abgebrochen wird.

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.

Diese Methode kann nur für Lizenzschlüssel im alten Format verwendet werden. Wenn Sie einen Lizenzschlüssel im neuen UUID-Format (XXXXXXXX–XXXX–XXXX–XXXX–XXXXXXXXXXXX) haben, verwenden Sie bitte die Klasse STLicenceManager.

Java

void setLicenseKey(String licenseKey);

Parameter	Bedeutung
String licenseKey	Lizenzstring
Rückgabewert	Bedeutung
-	-

Anwendung:

Java

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 kein Zeitstempel ins Dokument eingebracht. Sie muss gesetzt werden, bevor die Methode loadDocumentFromFile() aufgerufen wird.

Java

void setSignatureTimeStampFormat(DateFormat dateFormat);

Parameter	Bedeutung
DateFormat dateFormat	Die Instanz der DateFormat Klasse.
Rückgabewert	Bedeutung
-	-

Anwendung:

Java

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
Rückgabewert	Bedeutung
-	-

Anwendung:

Java

signoSigner.setTimeStampColor(Color.BLUE);

Methode loadDocumentFromFile

Diese Methode lädt ein PDF-Dokument und interpretiert ggf. die enthaltenen SGN-Schlüsselwörter.

Java

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:

Java

int ret = signoSigner.loadDocumentFromFile(documentData);
if (ret < 0) {
    // error handling
}

Methode unloadDocument

Mit dieser Methode kann das zuletzt mit der Methode loadDocumentFromFile() geladene Dokument entladen werden. Sie sollte spätestens aufgerufen werden, bevor ein neues Dokument geladen wird.

void unloadDocument();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
-	-

Anwendung:

signoSigner.unloadDocument();

Methode getDocumentMetaData

Diese Methode liest die Metadaten des Dokuments aus.

Java

String getDocumentMetaData();

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

Anwendung:

Java

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.

Diese Methode ist veraltet und nur noch aus Kompatibilitätsgründen enthalten. Bitte verwenden Sie stattdessen die Methoden von der Klasse STCertificateManager.

Java

void setCertificates:(byte[] signingCertificate, String signCertPassword, byte[] biometricCertificate) throws STCerticateException;

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.
Rückgabewert	Bedeutung
-	-
Exception	Beschreibung
STCerticateException	Instanz der STCerticateException-Klasse

Anwendung:

Java

try {
    signoSigner.setCertificates(signCertificate, @"Password" bioCertificate);
} catch (STCertificateException certException) {
    STCertificateError certError = certException.getCertificateError();
    if (certError == STCertificateError.EXPIRED_SIGNING_CERTIFICATE) {
      // Certificate is expired. Show user message here.
    } else if (certError == STCertificateError.INVALID_KEYSTORE_PASSWORD) {
      // Password is wrong. Show user message here.
    } else if (certError == STCertificateError.INVALID_BIOMETRIC_CERTIFICATE) {
      // Biometric cetificate is invalid. Show user message here.
    }
    Log.d("CertificateError", certException.getLocalizedMessage());
}

Methode createNewSignatureField

Diese Methode erzeugt ein neues leeres Signaturfeld.

Java

int createNewSignatureField(STSignatureFieldInfoDTO signatureField);

Parameter	Bedeutung
STSignatureFieldInfoDTO signatureField	Objekt, das die Eigenschaften des neuen Feldes enthält.
Rückgabewert	Bedeutung
int	0	Methode wurde erfolgreich ausgeführt.
	< 0	Es ist ein Fehler aufgetreten (s. o.).

Anwendung:

Java

int ret = signoSigner.createNewSignatureField(signatureField);
if (ret < 0) {
  // error handling
}

Methode getSignatureInfo

Diese Methode ist veraltet und nur noch aus Kompatibilitätsgründen enthalten. Bitte verwenden Sie stattdessen die Methode getFormFields().

Methode getFormFields

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

Java

<T extends STFormFieldInfoDTO> List<T> getFormFields(EnumSet<STFormFieldType> formFieldTypes);

Parameter	Bedeutung
EnumSet<STFormFieldType> formFieldTypes	EnumSet-Objekt der Enum-Klasse STFormFieldType
Rückgabewert	Bedeutung
<T extends STFormFieldInfoDTO> List<T>	Eine Liste mit je einem STFormFieldInfoDTO-Objekt oder einem Objekt der Klasse, die von der Klasse STFormFieldInfoDTO abgeleitet ist, pro Formularfeld oder eine leere Liste, wenn das Dokument keine Formularfelder enthält, die den gesuchten Formularfeldtypen entsprechen.

Anwendung:

Java

List<STFormFieldInfoDTO> allFields = signoSigner.getFormFields(EnumSet.allOf(STFormFieldType.class));
List<STEditableFieldInfoDTO> allEditableFields = signoSigner.getFormFields(EnumSet.of(STFormFieldType.TEXT, STFormFieldType.CHOICE, STFormFieldType.BUTTON));
List<STSignatureFieldInfoDTO> signatureFields = signoSigner.getFormFields(EnumSet.of(SIGNATURE));
List<STTextFieldInfoDTO> textFields = signoSigner.getFormFields(EnumSet.of(TEXT));
List<STButtonFieldInfoDTO> buttonFields = signoSigner.getFormFields(EnumSet.of(BUTTON));
List<STButtonFieldInfoDTO> choiceFields = signoSigner.getFormFields(EnumSet.of(CHOICE));
List<STFormFieldInfoDTO> allEditableFields = signoSigner.getFormFields(EnumSet.of(STFormFieldType.TEXT, STFormFieldType.CHOICE, STFormFieldType.BUTTON));
List<STFormFieldInfoDTO> signatureFields = signoSigner.getFormFields(EnumSet.of(SIGNATURE));
List<STFormFieldInfoDTO> textFields = signoSigner.getFormFields(EnumSet.of(TEXT));
List<STFormFieldInfoDTO> buttonFields = signoSigner.getFormFields(EnumSet.of(BUTTON));
List<STFormFieldInfoDTO> choiceFields = signoSigner.getFormFields(EnumSet.of(CHOICE));

Methode isDocumentModified

Mit dieser Methode kann überprüft werden, ob das geladene Dokument geändert wurde.

Java

boolean isDocumentModified();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
boolean	true	Das Dokument wurde geändert.
	false	Das Dokument wurde nicht geändert.

Anwendung:

Java

boolean documentState = signoSigner.isDocumentModified();

Methode getPageDimension

Java

Size getPageDimension(int pageNr);

Parameter	Bedeutung
int pageNr	Die Seitennnummer
Rückgabewert	Bedeutung
Size	Die Seitendimension der Seite oder Size(0,0), wenn keine Seite für die übergebene Seitennummer gefunden wird.

Anwendung:

Java

Size pageDimension = signoSigner.getPageDimension(1);

Methode getPageCount

Diese Methode gibt die Anzahl der Seiten des geladenen Dokuments zurück.

Java

int getPageCount();

Parameter	Bedeutung
-	-
Rückgabewert	Bedeutung
int	> 0	Die Anzahl der Seiten.
	-1	Es ist ein Fehler aufgetreten.

Anwendung:

Java

int pageCount = signoSigner.getPageCount();

Methode getDocumentAsFile

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

Java

byte[] getDocumentAsFile();

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

Anwendung:

Java

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.

Java

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.
Rückgabewert	Bedeutung
int	0	Methode wurde erfolgreich ausgeführt.
	< 0	Es ist ein Fehler aufgetreten (s. a. STSignoViewerNotifier.signingProcessFailed()).

Anwendung:

Java

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 Signaturdetails wie Ort und Grund der Unterschrift, Kontaktinformationen des Unterzeichners sowie der Name und die Version der Signaturanwendung hinzugefügt werden. Diese Methode sollte i. d. R. in der Methode STSignoViewerNotifier.willStartSigning() oder vor der Methode STSignoSigner.signSignatureField() aufgerufen werden.

Java

void setSignatureFieldInfo(STSignatureFieldInfoDTO signatureFieldInfoDTO);

Parameter	Bedeutung
STSignatureFieldInfoDTO signatureFieldInfoDTO	Ein STSignatureFieldInfoDTO-Objekt
Rückgabewert	Bedeutung
-	-

Anwendung:

Java

STSignatureFieldInfoDTO signFieldDTO = new STSignatureFieldInfoDTO("My Signature", "My Location", "My Reason", "info@mycompany.com");
signFieldDTO.setSignerApp("My App", "1.0.0");
signoSigner.setSignatureFieldInfo(signFieldDTO);

Methode setSignoSignerNotifier

Mit dieser Methode kann die Instanz einer Klasse festgelegt werden, die das Interface STSignoSignerNotifier implementiert und somit über Ereignisse im STSignoSigner informiert werden soll.

Java

void setSignoSignerNotifier(STSignoSignerNotifier signoSignerNotifier);

Parameter	Bedeutung
STSignoSignerNotifier signoSignerNotifier	STSignoSignerNotifier-Instanz
Rückgabewert	Bedeutung
-	-

Anwendung:

Java

STSignoSignerNotifier signoSignerNotifier = new STSignoSignerNotifierImpl();
signoSigner.setSignoSignerNotifier(signoSignerNotifier);

Methode addImages

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

Java

int addImages(List<STImageDTO> images);

Parameter	Bedeutung
List<STImageDTO> images	Eine Liste von STImageDTO-Objekten. Darf null sein, dann werden keine Bilder hinzugefügt.
Rückgabewert	Bedeutung
int	0	Methode wurde erfolgreich ausgeführt.
	< 0	Es ist ein Fehler aufgetreten. (s. o.).

Anwendung:

Java

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 = signoSigner.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.

Java

List<Rect> startTextSearch(String text, int page, 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.
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:

Java

List<Rect> foundTextPositions = signoViewer.startTextSearch("Signature", 1, true, true);
for (Rect rect : foundTextPositions) {
  SignatureFieldInfoDTO field = new SignatureFieldInfoDTO();
  field.setName("@New_Signature");
  field.setPage(1);
  field.setRectangle(rect);
  int result = signoSigner.createNewSigantureField(field);
}

Methode setDigitalSignatureMaxLength

Mit dieser Methode kann die max. Länge der digitalen Signatur in Bytes festgelegt werden, für die im Dokument beim Vorbereiten der Signierung Platz vorgehalten wird. Ist die Signatur länger als definiert, kann das Dokument nicht signiert werden.

Java

void setDigitalSignatureMaxLength(int digitalSignatureMaxLength);

Parameter	Bedeutung
int digitalSignatureMaxLength	Die max. reservierte Länge der digitalen Signatur in Bytes.
Rückgabewert	Bedeutung
-	-

Anwendung:

Java

signoSigner.setDigitalSignatureMaxLength(16348);