signoAPI iOS – STSignoInfoDelegate class

The STSignoInfoDelegate class contains methods that are called for certain events of the classes and STSignoSigner class. The class is part of libSignoPDFSigner.

@protocol STSignoInfoDelegate

Usage:

@interface ViewController : UIViewController<STSignoInfoDelegate>

willStartSigning:completion: method

This method is called whenever the signature capture needs to be initiated for a signature field that has not yet been signed.

-(void)willStartSigning:(NSString*)signatureFieldName completion:(void(^)(BOOL))startSigning

Parameter	Description
(NSString*) signatureFieldName	Name of the signature field for which the signature needs to be captured.
(void(^)(BOOL)) startSigning	Callback that must be called to cancel or start the signature capture. Here, the parameter value has the following meaning:
	YES	The signature capture should be initiated.
	NO	The signature capture should be cancelled.
Return value	Description
-	-

Usage:

-(void)willStartSigning:(NSString*)signatureFieldName
completion:(void(^)(BOOL))startSigning
{
    // do some stuff, e. g. configure the capture dialog
    signoVC.signatureCaptureConfig.displayText = signatureFieldName;
    // go on with the signature capture
    startSigning(YES);
}

signingProcessStarted: method

This method is called if the signature capture is initiated for a signature field that has not yet been signed.

-(NSMutableArray*)signingProcessStarted:(NSString*)signatureFieldName

Parameter	Description
(NSString*) signatureFieldName	Name of the signature field for which the signature is being captured.
Return value	Description
NSMutableArray*	Form fields that are to be set to ‘read only’ before signing, as an array of STFormFieldInfoDTO objects or nil, if the form fields are not to be changed. Form fields that are already set to ‘read only’ will not be changed. If the user aborts the signature capture process, the form fields that have been passed will not be changed.

Usage:

-(NSMutableArray*)signingProcessStarted:(NSString*)signatureFieldName
{
    return [signoVC getFormFields:FormFieldTypeEditableFields];
}

willConfirmSigning:completion: method

This method is called whenever the signature capture process for a signature field has ended and the captured data is to be inserted into the document.

-(void)willConfirmSigning:(NSString*)signatureFieldName completion:(void(^)(BOOL))acceptSignature

Parameter	Description
(NSString*) signatureFieldName	Name of the signature field for which the signature has been captured.
(void(^)(BOOL)) acceptSignature	Callback that must be called to complete the signature capture. Here, the parameter value has the following meaning:
	YES	The signature should be inserted into the signature field.
	NO	The signature should not be inserted into the signature field, and the capture should be aborted. The document should not be changed.
Return value	Description
-	-

Usage:

-(void)willConfirmSigning:(NSString*)signatureFieldName completion:(void(^)(BOOL))acceptSignature
{
    // do some stuff and then go on with the signing process
    acceptSignature(YES);
}

computeDigitalSignature:completion: method

This method is called if the digital signature has to be calculated. See also the corresponding methods.

-(void)computeDigitalSignature:(NSData*)documentDigest completion:(void(^)(NSData*))addSignatureToDocument

Parameter	Description
(NSData*) documentDigest	Checksum (SHA-256) of the prepared document that has to be used for calculating the signature.
(void(^)(NSData*)) addSignatureToDocument	Callback that must be called to complete document signing. The transfer parameter must contain the signature calculated in PKCS#7 format. If nil is transferred, signing will be cancelled.
Return value	Description
-	-

Usage:

-(void)computeDigitalSignature:(NSData*)documentDigest completion:(void(^)(NSData))addSignatureToDocument
{
    // compute digital signature, i. e. in your backend...
    addSignatureToDocument(computedSignature);
}

signingProcessConfirmed: method

This method is called whenever the signature capture for a signature field has successfully ended and there is a signed document.

-(void)signingProcessConfirmed:(NSString*)signatureFieldName

Parameter	Description
(NSString*) signatureFieldName	Name of the signature field for which the signature has been captured.
Return value	Description
-	-

Usage:

-(void)signingProcessConfirmed:(NSString*)signatureFieldName
{
    // event handling
}

signingProcessCancelled: method

This method is called if the signature capture process has been aborted by the user (with the ‘Cancel’ button).

-(void)signingProcessCancelled:(NSString*)signatureFieldName

Parameter	Description
(NSString*) signatureFieldName	Name of the signature field for which the capture process has been aborted.
Return value	Description
-	-

Usage:

-(void)signingProcessCancelled:(NSString*)signatureFieldName
{
    // event handling
}

signingProcessFailed:errorText:errorCode: method

This method is called if the signature capture process or signature insertion into the document failed.

-(void)signingProcessFailed:(NSString*)signatureFieldName errorText:(NSString*)errorText errorCode:(int)errorCode

Parameter	Description
(NSString*) signatureFieldName	Name of the signature field for which the capture process failed.
(NSString*)errorText	Description of the error
(int)errorCode	Error code.
Return value	Description
-	-

Usage:

-(void)signingProcessFailed:(NSString*)signatureFieldName errorText:(NSString*)errorText errorCode:(int)errorCode
{
    // event handling
}

The following errors may occur:

Error code	Description
-120	Unable to load the document.
-121	Unable to read the document.
-122	The PDF is password protected.
-123	Unable to find the key container.
-124	Unable to read the key container.
-125	The key container password is invalid.
-126	The format of the key container is not supported.
-127	The key container does not contain a private key.
-128	Error when writing the file.
-129	Error when signing the document.
-130	Invalid signature field name.
-131	Unable to read the biometrics certificate.
-132	The captured signature is too short.
-133	The private key could not be found.
-134	Unable to read the signature certificate.
-137	The document could not be signed because the ‘NeedAppearances’ flag is set to ‘true’.
-136	The digital signature could not be inserted because it is longer than the value specified in the digitalSignatureMaxLength property.
-138	The signature certificate has expired.
-145	The document could not be signed because of a problem with an xref table.
-146	The document could not be signed because of a time stamp problem.
-147	Unable to find the signature certificate in the key container.
-150	An unknown error occurred during the signature capture process.

signatureInfoPressed method

This method is called if the ‘signature fields’ button in the toolbar has been touched.

-(BOOL)signatureInfoPressed

Parameter	Description
-	-
Return value	Description
BOOL	YES	The library displays the standard dialog with the signature fields of the document.
	NO	The library no longer reacts to the event; the app then typically carries out the event handling.

Usage:

-(BOOL)signatureInfoPressed
{
    return YES;
}

documentSaved method

This method is called if the ‘save’ button in the toolbar has been touched. Usually, the corresponding method should be called for this event.

-(BOOL)documentSaved

Parameter	Description
-	-
Return value	Description
BOOL	YES	The ‘Save’ button needs to be greyed out.
	NO	The ‘Save’ button should not be greyed out.

Usage:

-(BOOL)documentSaved
{
    // event handling
    return YES;
}

backButtonPressed method

This method is called if the ‘back’ button in the toolbar has been touched. Usually, the view should then disappear and the user should be returned to the custom app interface.

-(void)backButtonPressed

Parameter	Description
-	-
Return value	Description
-	-

Usage:

-(void)backButtonPressed
{
    // event handling
}

photoCaptureFailed:errorText:errorCode: method

This method is called if the app does not have any usage rights for the camera or if the image capture failed.

-(void)photoCaptureFailed:(NSString*)photoFieldName errorText:(NSString*) errorText errorCode:(int)errorCode

Parameter	Description
(NSString*) photoFieldName	Name of the photo field for which the image capture process failed.
(NSString*)errorText	Description of the error
(int)errorCode	Error code.
Return value	Description
-	-

Usage:

-(void)photoCaptureFailed:(NSString*)photoFieldName errorText:(NSString*) errorText errorCode:(int)errorCode
{
    // event handling
}

viewerRectConfirmed:inPage:viewerRectId method

This method is called if the confirm button of a rectangle generated by calling the corresponding method is touched. Usually, the corresponding method should be called for this event.

-(BOOL)viewerRectConfirmed:(CGRect)rectInPdf  inPage:(int)page viewerRectId:(int)viewerRectId

Parameter	Description
(CGRect)rectInPdf	Position and size of the rectangle on the page or CGRectZero if the rectangle has an invalid position.
(int)page	Number of the page on which the rectangle was confirmed or -1 if the rectangle has an invalid position. The first page number of the document begins with 1.
(int)viewerRectId	Unique ID of the generated rectangle.
Return value	Description
BOOL	YES	The rectangle should be hidden.
	NO	The rectangle should continue to be displayed.

Usage:

-(BOOL)viewerRectConfirmed:(CGRect)rectInPdf inPage:(int)page viewerRectId:(int)viewerRectId
{
    STSignatureFieldInfoDTO *sigField = [[STSignatureFieldInfoDTO alloc] init];
    sigField.name = @"New_Signature";
    sigField.page = page;
    sigField.isSigned = false;
    sigField.rectangle = rectInPdf;
    int result = [signoVC createNewSignatureField: sigField];
    if (result < 0)
    {
        // error handling
        return NO;
    }
    return YES;
}

viewerRectCancelled: method

This method is called if the cancel button of a rectangle generated by calling the corresponding method is touched.

-(void)viewerRectCancelled:(int)viewerRectId

Parameter	Description
(int)viewerRectId	Unique ID of the generated rectangle.
Return value	Description
-	-

Usage:

-(void)viewerRectCancelled:(int)viewerRectId
{
    // event handling
}

notifyLicenceStatus: method

This method is called to share the result of the licence validation. An app can in this case ask the user to enter a licence key, for example.

-(void)notifyLicenceStatus:(LicenceError)licenceError

Parameter	Description
(LicenceError)licenceError	A property that contains a value of the enum Error defined with NS_ENUM. See the licence error table in the corresponding chapter.
Return value	Description
-	-

Usage:

-(void)notifyLicenceStatus:(LicenceError)licenceError
{
    if (licenceError != No_Error)
    {
        // software is not licensed, prompt dialog for entering a key
    }
}

notesModeDidStartSuccessfully method

This method is called when the corresponding method has been successfully executed.

-(void)notesModeDidStartSuccessfully

Parameter	Description
-	-
Return value	Description
-	-

Usage:

-(void)notesModeDidStartSuccessfully
{
    // The notes mode was successfully executed.
}

notesModeDidFailToStart: method

The method is called if an error occurs during execution of the corresponding method.

-(void)onNotesModeFailedToStart:(int)errorCode

Parameter	Description
(int)errorCode	< 0	An error occurred (see above).
Return value	Description
-	-

Usage:

-(void)onNotesModeFailedToStart:(int)errorCode
{
     //The notes mode could not be executed successfully.
}

notesModeDidFinishWithSavedStatus: method

This method is called when the corresponding method has ended – regardless of whether notes were saved successfully or no notes were present.

-(void)notesModeDidFinishWithSavedStatus:(BOOL)isSaved

Parameter	Description
boolean isSaved	true	The notes created were saved successfully.
	false	No notes were saved as none were created.
Return value	Description
-	-

Usage:

-(void)notesModeDidFinishWithSavedStatus:(BOOL)isSaved
{
    if (isSaved)
    {
        // The notes were saved successfully.
    } else {
        // There were no notes available.
    }
}

notesModeDidFinishWithFailure: method

This method is called when an error occurs during execution of the corresponding method.

-(void)onNotesModeDidFinishWithFailure:(int)errorCode

Parameter	Description
(int)errorCode	< 0	An error occurred (see above).
Return value	Description
-	-

Usage:

-(void)onNotesModeFailedToStart:(int)errorCode
{
     // The notes could not be saved.
}