signoAPI Android – STSignoSigner class

The STSignoSigner class is a significant part of libSignoPDFSigner. This class is used to load and edit PDF documents without displaying them, and offers the option of signing signature fields. All properties and methods of this class can also be used with the STSignoViewer class if the document should also be displayed.

Usage:

Java

STSignoSigner signoSigner = STSignoSignerCreator.createSignoSigner(context);

Some methods return an integer, which can be used to identify errors. The possible error codes are listed in the table below:

Error code	Description
-100	Unable to load the document.
-101	The previous document was not unloaded. See the STSignoSigner.unloadDocument() method.
-110	Unable to generate the signature field.
-111	The document could not be loaded because it contains functions that are not currently supported.
-112	Unable to generate the signature field on the desired page.
-113	A form or signature field with the same name already exists.
-115	The signature field has already been signed.
-116	The coordinates of the signature field lie outside of the visible area.
-117	The document contains no signature fields.
-118	The document contains no signature field with the given name.
-119	A new signature process cannot be started because another one is already active.
-190	A signature field with the transferred name does not exist in the document.
-191	The rectangle that defines the size and position of the signature field is invalid.
-200	The error code is returned by the STSignoViewer.createViewerRect(), STSignoViewer.startSignature(), STSignoViewer.signDocument(), STSignoViewer.createNewSignatureField() and STSignoViewer.addImages() methods when the viewer is in notes mode and the desired action cannot be performed due to the current notes mode.
-201	A recorded note cannot be added to the PDF because the viewer is not in notes mode.
-202	This error code is returned when notes mode is started up if the current document is a PDF/A-1b document. Inserting images with an alpha channel, which is needed for notes mode, would breach PDF/A-1b conformity, so the process is cancelled.

setLicenseKey method

This method can be used to enable the libSignoPDFSigner component and, in so doing, to remove the demo message. Please use the licence string that was given to you by your contact at signotec.

This method can only be used for licence keys in the old format. If you have a licence key in the new UUID format (XXXXXXXX–XXXX–XXXX–XXXX–XXXXXXXXXXXX), please use the STLicenceManager class.

Java

void setLicenseKey(String licenseKey);

Parameter	Description
String licenseKey	Licence string
Return value	Description
-	-

Usage:

Java

signoSigner.setLicenseKey("1234");

setSignatureTimeStampFormat method

This method can be used to set an instance of the DateFormat class. This makes it possible to visually add a time stamp with the signature to the document. If no instance from this class is created and set, no time stamp is added to the document. It must be set before the loadDocumentFromFile() method is called.

Java

void setSignatureTimeStampFormat(DateFormat dateFormat);

Parameter	Description
DateFormat dateFormat	The instance of the DateFormat class
Return value	Description
-	-

Usage:

Java

DateFormat dateFormat = new SimpleDateFormat("E, dd MMM yyyy HH:mm:ss z", Locale.getDefault());
signoSigner.setSignatureTimeStampFormat(dateformat);

setTimeStampColor method

This property allows the colour of the time stamp in the signature image to be configured. If the property is not set, black is used by default.

void setTimeStampColor(int timeStampColor);

Parameter	Description
int timeStampColor	Colour of the time stamp
Return value	Description
-	-

Usage:

Java

signoSigner.setTimeStampColor(Color.BLUE);

loadDocumentFromFile method

This method loads a PDF document and interprets any SGN keywords it may contain.

Java

int loadDocumentFromFile(byte[] documentData);

Parameter	Description
byte[] documentData	The document to be loaded, as a byte array.
Return value	Description
int	0	Method was executed successfully
	< 0	An error occurred (see above).

Usage:

Java

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

unloadDocument method

This method can be used to unload the document last loaded with the loadDocumentFromFile() method. This method should be called before a new document is loaded at the latest.

void unloadDocument();

Parameter	Description
-	-
Return value	Description
-	-

Usage:

signoSigner.unloadDocument();

getDocumentMetaData method

This method reads the document’s metadata.

Java

String getDocumentMetaData();

Parameter	Description
-	-
Return value	Description
String	‘Metadata’ entry from the ‘Document Catalog’

Usage:

Java

String metaData = signoSigner.getDocumentMetaData();

setCertificates method

This method allows the keys and certificates for encrypting the biometric data and for signing the document to be passed.

This method is deprecated and is only included for compatibility reasons. Please use the methods of the STCertificateManager class instead.

Java

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

Parameter	Description
byte[] signingCertificate	PKCS#12 file as a byte array, with the private key and the public certificate for signing the document.
String signCertPassword	Password for PKCS#12 file. This is ignored if null is transferred for signingCertificate.
byte[] biometricCertificate	X.509 certificate as a byte array, with the public key for encrypting the biometrics.
Return value	Description
-	-
Exception	Description
STCertificateException	Instance of the STCertificateException class

Usage:

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

createNewSignatureField method

This method generates a new, empty signature field.

Java

int createNewSignatureField(STSignatureFieldInfoDTO signatureField);

Parameter	Description
STSignatureFieldInfoDTO signatureField	Object that contains the properties of the new field.
Return value	Description
int	0	Method was executed successfully
	< 0	An error occurred (see above).

Usage:

Java

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

getSignatureInfo method

This method is deprecated and is only included for compatibility reasons. Please use the getFormFields() method instead.

getFormFields method

This method can be used to retrieve information about the form fields contained within the document.

Java

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

Parameter	Description
EnumSet<STFormFieldType> formFieldTypes	EnumSet object of the enum class STFormFieldType
Return value	Description
<T extends STFormFieldInfoDTO> List<T>	A list with one STFormFieldInfoDTO object or one object of the class derived from the STFormFieldInfoDTO class for each form field, or an empty list if the document does not contain any form fields that correspond to the form field types searched for.

Usage:

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

isDocumentModified method

This method can be used to check whether the loaded document has been changed.

Java

boolean isDocumentModified();

Parameter	Description
-	-
Return value	Description
boolean	true	The document has been changed.
	false	The document has not been changed.

Usage:

Java

boolean documentState = signoSigner.isDocumentModified();

getPageDimension method

Java

Size getPageDimension(int pageNr);

Parameter	Description
int pageNr	The page number
Return value	Description
Size	The page dimension of the page or Size(0,0) if no page is found for the transferred page number.

Usage:

Java

Size pageDimension = signoSigner.getPageDimension(1);

getPageCount method

This method returns the number of pages of the loaded document.

Java

int getPageCount();

Parameter	Description
-	-
Return value	Description
int	> 0	The number of pages.
	-1	An error occurred

Usage:

Java

int pageCount = signoSigner.getPageCount();

getDocumentAsFile method

This method returns the document in its current state.

Java

byte[] getDocumentAsFile();

Parameter	Description
-	-
Return value	Description
byte[]	The document as a byte array

Usage:

Java

byte[] document = signoSigner.getDocumentAsFile();

signSignatureField method

This method can be used to sign a specific signature field with a signature that was captured separately. A signature consisting of the biometric data and the image of the signature may be captured with the STSignatureCapture, for example.

Java

int signSignatureField(String signatureFieldName, byte[] signData, byte[] image);

Parameter	Description
String signatureFieldName	The name of the signature field that is to be signed; the field must not be signed already. If the document does not contain a field with this name, a new field will be inserted on page 1 with the coordinates (0, 0, 0, 0).
byte[] signData	Byte array containing the biometric data, as returned by STSignatureCapture.getSignData().
byte[] image	Byte array containing the image of the signature, as returned by STSignatureCapture.getSignatureImage().
Return value	Description
int	0	Method was executed successfully
	< 0	An error has occurred (see also STSignoViewerNotifier.signingProcessFailed()).

Usage:

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
}

setSignatureFieldInfo method

This method can be used to add signature details such as the location and reason for signing, the signatory's contact information, and the name and version of the signature application to a digital signature. This method should generally be called in the STSignoViewerNotifier.willStartSigning() method or before the STSignoSigner.signSignatureField() method.

Java

void setSignatureFieldInfo(STSignatureFieldInfoDTO signatureFieldInfoDTO);

Parameter	Description
STSignatureFieldInfoDTO signatureFieldInfoDTO	An STSignatureFieldInfoDTO object
Return value	Description
-	-

Usage:

Java

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

setSignoSignerNotifier method

This method can be used to specify the instance of a class that implements the STSignoSignerNotifier interface and is therefore to be informed about events in STSignoSigner.

Java

void setSignoSignerNotifier(STSignoSignerNotifier signoSignerNotifier);

Parameter	Description
STSignoSignerNotifier signoSignerNotifier	STSignoSignerNotifier instance
Return value	Description
-	-

Usage:

Java

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

addImages method

This method can be used to insert images into the loaded document.

Java

int addImages(List<STImageDTO> images);

Parameter	Description
List<STImageDTO> images	A list of STImageDTO objects. May be null, in which case no images are added.
Return value	Description
int	0	Method was executed successfully
	< 0	An error occurred (see above)

Usage:

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

startTextSearch method

This method searches for text on a PDF page, visually highlights all the places where the text was found (if applicable) and returns the positions of all these places.

Java

List<Rect> startTextSearch(String text, int page, boolean onlyWholeWord, boolean caseSensitive);

Parameter	Description
String text	Text to search for.
int page	Page on which to search for the text. The first page number of the document begins with 1.
boolean onlyWholeWord	true	Only finds whole words.
	false	Finds all occurrences.
boolean caseSensitive	true	The search is case-sensitive.
	false	The search is not case-sensitive.
Return value	Description
List	The positions of all the places where the text was found as a list of Rect objects or an empty list.

Usage:

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

setDigitalSignatureMaxLength method

This method can be used to define the maximum length of the digital signature in bytes for which space is reserved in the document when preparing the signature. If the signature is longer than the defined length, the document cannot be signed.

Java

void setDigitalSignatureMaxLength(int digitalSignatureMaxLength);

Parameter	Description
int digitalSignatureMaxLength	The maximum reserved length of the digital signature in bytes.
Return value	Description
-	-

Usage:

Java

signoSigner.setDigitalSignatureMaxLength(16348);