Documentation signotec signoAPI/Win

Documentation

signotec signoAPI/Win

Version 1.213 2021-09-17

© 2000 - 2021 signotec GmbH SignoAPI Documentation

17.09.2021 Page 2 of 125

Contents

1. CHANGE LIST ................................................................................... 9

2. GENERAL OVERVIEW OF THE SIGNOTEC SIGNOAPI ............................. 21

2.1. SIGNOAPI FOR WINDOWS ................................................................ 21

2.2. VERSIONS ................................................................................... 21 2.2.1. Small Edition (SE) ..................................................................................... 21 2.2.2. Full Edition (FE) ......................................................................................... 22

2.3. FUNCTIONAL RANGE ........................................................................ 22

2.4. SYSTEM REQUIREMENTS FOR THE WINDOWS VERSION OF THE SIGNOAPI .......... 22 2.4.1. 64-bit systems .......................................................................................... 22 2.4.2. MFC dependency ....................................................................................... 22

2.5. SIGNOAPI FOR JAVA ....................................................................... 22

2.6. SIGNOAPI FOR LINUX...................................................................... 22

2.7. SILENT INSTALATION ....................................................................... 22 2.7.1. The features ............................................................................................. 23 2.7.2. Selecting and deselecting features ............................................................... 23 2.7.3. Update installation or initial installation with all features ................................. 23 2.7.4. Changing the installed features at a later time .............................................. 24

2.8. SILENT DEINSTALLATION ................................................................... 24

3. SIGNOTEC SIGNOAPI COMPONENTS ................................................. 25

3.1. APPLICATION AREA 1: ...................................................................... 25

3.2. DOCUMENT AND IMAGE VIEWER/GRAPHICAL USER INTERFACE/VISUALISATION OF

SIGNATURE DATA .................................................................................. 25


3.4. HARDWARE ACCESS/CAPTURING SIGNATURE DATA ..................................... 25


3.6. SIGNING DOCUMENTS AND IMAGES/VALIDITY CHECK AND SIGNATURE COMPARISON

...................................................................................................... 25


3.8. IMAGE CONVERSIONS/E-MAIL DISPATCH ................................................. 25

4. GENERAL INFORMATION ON THE SIGNOTEC SIGNOAPI ....................... 27

4.1. COMPONENT COMPATIBILITY ............................................................... 27

4.2. DATA FORMATS ............................................................................. 27

4.3. VISUAL BASIC .............................................................................. 27

4.4. PADDATA AND SIGNDATA STRUCTURES ................................................. 27

4.5. THE MOST FREQUENTLY USED COMPONENTS ............................................. 27

4.6. MD5 CHECKSUM ............................................................................ 28

4.7. LICENCE KEYS ............................................................................... 28

4.8. COMPLEX DATA STRUCTURES AS PARAMETER VALUES ................................... 28 4.8.1. Passing as a global handle in a VARIANT of type VT_I4 .................................. 29 4.8.2. Passing as a VARIANT Typ VT_ARRAY .......................................................... 29 4.8.3. Passing as a VARIANT of type VT_BSTR ........................................................ 30

5. SIGNPDF2.DLL COMPONENT: SIGNING PDF DOCUMENTS AND OTHER


17.09.2021 Page 3 of 125

FUNCTIONS ....................................................................................... 31

5.1. DEFINITION OF THE ISIGNPDF INTERFACE .............................................. 31

5.2. INTERFACE ID ASSIGNMENT ............................................................... 31

5.3. DECLARATION INFORMATION .............................................................. 31

5.4. METHODS AND PROPERTIES ............................................................... 31 SignPdfDocument and SignPdfDocumentVBS methods ............................................................................................... 31 SignPdfDocumentMemory method ............................................................................................................................... 33 SignPdfDocumentHttp method ...................................................................................................................................... 34 SignPdfDocumentHttp2 method .................................................................................................................................... 35 VerifyPdfDocument method .......................................................................................................................................... 36 VerifyPdfDocumentMemory method ............................................................................................................................ 36 GetReferenceCount method ........................................................................................................................................... 36 GetReferenceCountMemory method ............................................................................................................................. 37 GetReferenceCount2 method ......................................................................................................................................... 37 GetReference method .................................................................................................................................................... 37 GetReference2 method .................................................................................................................................................. 38 GetReferenceMemory method ....................................................................................................................................... 38 GetPdfDocumentSize method ........................................................................................................................................ 39 GetPdfDocumentSizeMemory method .......................................................................................................................... 39 GetAsciiText or GetAsciiText2 method ........................................................................................................................ 40 GetPdfPageCount method .............................................................................................................................................. 40 GetAsciiTextPosition or GetAsciiTextPosition2 method .............................................................................................. 40 GetAsciiTextPosition3 method ...................................................................................................................................... 41 GetAsciiTextPosition3 method ...................................................................................................................................... 42 SetLicenseKey method .................................................................................................................................................. 42 ImportFormfieldData method ........................................................................................................................................ 43 ExportFormfieldData method ........................................................................................................................................ 43 GetUploadURL method ................................................................................................................................................. 43 GetSignatureInfo method ............................................................................................................................................... 44 GetSignatureInfoMemory method ................................................................................................................................. 44 GetInlineImageCount method ........................................................................................................................................ 44 MergePDFDocuments method....................................................................................................................................... 45 AddTextbox method ...................................................................................................................................................... 45

6. STSGNLIB.DLL COMPONENT: PREPARING PDF DOCUMENTS FOR SIGNING, INSERTING AND READING OUT SGN ENTRIES ......................... 47

6.1. DEFINITION OF THE ISGNDOC INTERFACE ............................................... 47



6.4. METHODS AND PROPERTIES ............................................................... 47 get and put XMLInfoData property ............................................................................................................................... 47 AddSgnPos method ....................................................................................................................................................... 48 GetSgnPos method......................................................................................................................................................... 48 AddSgnPos2 method ..................................................................................................................................................... 49 GetSgnPos2 method....................................................................................................................................................... 49 GetSgnCount method ..................................................................................................................................................... 50 GetSgnCountOnPage method ........................................................................................................................................ 50 SetUploadURL method.................................................................................................................................................. 50 GetUploadURL method ................................................................................................................................................. 50 SetProperties method ..................................................................................................................................................... 51

6.5. PROPERTIES FOR INTERNAL USE ........................................................... 51 benutzerid property ........................................................................................................................................................ 51 kontoinhaber property .................................................................................................................................................... 51 kontonummer property .................................................................................................................................................. 51 kundennummer property ................................................................................................................................................ 51 formulartyp property ...................................................................................................................................................... 51 prozessid property .......................................................................................................................................................... 51 geschaeftsart property .................................................................................................................................................... 51 bankleitzahl property ..................................................................................................................................................... 52 email property ................................................................................................................................................................ 52


17.09.2021 Page 4 of 125

allowsigning property .................................................................................................................................................... 52 dokumentenschluessel property ..................................................................................................................................... 52 indexN (N = 1-10) properties ......................................................................................................................................... 52 indexnameN (N = 1-10) properties ................................................................................................................................ 52 databasename, ups, indexpart, agb, UUID properties .................................................................................................... 52

7. SIGNCAP.DLL COMPONENT: CAPTURING SIGNATURES FROM VARIOUS

INPUT DEVICES (PADS, TABLET PCS AND SCANNERS) ............................ 53

7.1. INTERFACE HARDWARE ASSIGNMENT ..................................................... 54

7.2. INTERFACE CLSID ASSIGNMENT ......................................................... 54

7.3. INTEFACE DEPENDENCIES .................................................................. 55


7.5. INFORMATION ON USING THE INTERFACES ............................................... 56

7.6. SPECIAL FUNCTIONS FOR HARDWARE DEVICES WITH AN LCD ......................... 56

7.7. TWAIN-COMPATIBLE SCANNERS ......................................................... 56

7.8. SHARED METHODS AND PROPERTIES ..................................................... 56 get SignData property .................................................................................................................................................... 56 get Image property ......................................................................................................................................................... 57 get PadData property ..................................................................................................................................................... 57 Capture method .............................................................................................................................................................. 57 SaveSignature method ................................................................................................................................................... 58 SaveSignatureEx method ............................................................................................................................................... 59 FreeHandle method ........................................................................................................................................................ 60 SetPenWidth method ..................................................................................................................................................... 60 SetWindowText method ............................................................................................................................................... 60 SetLicenseKey method .................................................................................................................................................. 60 SetImageParameter method ........................................................................................................................................... 61

7.9. IPADSIGNOTECSIGNATUREDEVICE INTERFACE – METHODS AND PROPERTIES ....... 61 PadID property .............................................................................................................................................................. 61 SignDataBase64 property .............................................................................................................................................. 61 get Image property ......................................................................................................................................................... 62 SelectDialog method ...................................................................................................................................................... 62 SetComPort method ....................................................................................................................................................... 63 SetPadType method ....................................................................................................................................................... 63 SetButtonPosition method ............................................................................................................................................. 63 SetOEMKey method ...................................................................................................................................................... 64 GetOEMPadData method .............................................................................................................................................. 64 SetIPAddress method ..................................................................................................................................................... 64 SetLCDText method ...................................................................................................................................................... 65 SetSampleRate method .................................................................................................................................................. 65 Important returncodes of the interface IPadSignotecSignatureDevice ........................................................................... 66

7.10. INTERFACE IPADTABLETPC – METHODS AND PROPERTIES ........................... 66 SelectDialog method ...................................................................................................................................................... 66

8. SIGNOUTILITIES.DLL COMPONENT: HELP FUNCTIONS FOR PAD SEARCHING, PAD CONFIGURATION AND PAD USE .................................. 68

8.1. DEFINITION OF THE PADUTIL INTERFACE ................................................ 68



8.4. METHODS AND PROPERTIES ............................................................... 68 Set_PadType method ..................................................................................................................................................... 68 Get_PadType method .................................................................................................................................................... 69 Set_TwainSetting method .............................................................................................................................................. 70 Set_TwainSettings2 method .......................................................................................................................................... 71 Set_TwainSettings3 method .......................................................................................................................................... 71 get_TwainSetting method .............................................................................................................................................. 72 Get_TwainSettings2 method .......................................................................................................................................... 73 Get_TwainSettings3 method .......................................................................................................................................... 73


17.09.2021 Page 5 of 125

PadCheck method .......................................................................................................................................................... 74 PadSearch method ......................................................................................................................................................... 75 GetFontSmoothing method ........................................................................................................................................... 76 DisableFontSmoothing method ..................................................................................................................................... 76 GetFontSmoothing method ............................................................................................................................................ 76

9. SIGNVIEW.DLL COMPONENT: DISPLAYING CAPTURED SIGNATURE DATA

77

9.1. DEFINITION OF THE ISIGNDRAW INTERFACE ............................................ 77



9.4. METHODS AND PROPERTIES ............................................................... 77 put SignData property .................................................................................................................................................... 77 put PadData property ..................................................................................................................................................... 78 put PenWidth property ................................................................................................................................................... 78 SetDrawingMode method .............................................................................................................................................. 78 Clear method.................................................................................................................................................................. 79 ApiLicenseKey method ................................................................................................................................................. 79

10. SIGNUTIL.DLL COMPONENT: CONVERTING TIFF DOCUMENTS TO PDF

DOCUMENTS AND VARIOUS OTHER ADDITIONAL FUNCTIONS .................. 80

10.1. DEFINITION OF THE IPDFCONV INTERFACE ............................................ 80

10.2. INTERFACE ID ALLOCATION .............................................................. 80

10.3. DECLARATION INFORMATION ............................................................ 80

10.4. METHODS AND PROPERTIES .............................................................. 80 TIFF2Pdf method .......................................................................................................................................................... 80 SetLicenseKey method .................................................................................................................................................. 80

10.5. DEFINITION OF THE IDATACONV INTERFACE .......................................... 81

10.6. INTERFACE ID ALLOCATION .............................................................. 81


10.8. METHODS AND PROPERTIES .............................................................. 81 CreateSignData method ................................................................................................................................................. 81 SaveSignature method ................................................................................................................................................... 81

10.9. DEFINITION OF THE ICHECKALGO INTERFACE ......................................... 82

10.10. INTERFACE ID ALLOCATION ............................................................ 82

10.11. DECLARATION INFORMATION ........................................................... 82

10.12. METHODS AND PROPERTIES ............................................................ 82 VerifyAccount method .................................................................................................................................................. 83

10.13. DEFINITION OF THE IBLOWFISH INTERFACE ......................................... 83



10.16. METHODS AND PROPERTIES ............................................................ 83 Initalize method ............................................................................................................................................................. 83 Encode method .............................................................................................................................................................. 84 Decode method .............................................................................................................................................................. 84

10.17. DEFINITION OF THE IJAVASCRIPT INTERFACE ....................................... 84



10.20. METHODS AND PROPERTIES ............................................................ 85 GetJSEngineName method ............................................................................................................................................ 85

10.21. DEFINITION OF THE INTERFACE ISTCOMM ........................................... 85



17.09.2021 Page 6 of 125


10.24. METHODS AND PROPERTIES ............................................................ 85 GetComPortList method ................................................................................................................................................ 85

11. SIGNDOC.DLL COMPONENT: SIGNING TIFF DOCUMENTS AND OTHER FUNCTIONS ....................................................................................... 87

11.1. DEFINITION OF THE IDOCFUN INTERFACE ............................................. 87

11.2. INTERFACE CLSID ALLOCATION ........................................................ 87


11.4. METHODS AND PROPERTIES .............................................................. 87 get SignedDocument property ....................................................................................................................................... 87 get MD5Checksum property .......................................................................................................................................... 87 SetDocPage method ....................................................................................................................................................... 88 SignDocument method .................................................................................................................................................. 88 SignDocument2 method ................................................................................................................................................ 89 CreateMD5Checksum method ....................................................................................................................................... 90 GetReferenceCount method ........................................................................................................................................... 90 GetSigReference method ............................................................................................................................................... 90 GetSigRect method ........................................................................................................................................................ 91 GetDocInfoID method ................................................................................................................................................... 91 GetDocResolution method ............................................................................................................................................. 92 GetDocSize method ....................................................................................................................................................... 92 InvalidateSignatory method ........................................................................................................................................... 92 InvalidateDocument method .......................................................................................................................................... 93 DrawText method .......................................................................................................................................................... 93 SetTextFont method....................................................................................................................................................... 94 GetPrinterSpoolerDocCount method ............................................................................................................................. 94 ApiLicenseKey method ................................................................................................................................................. 95 DeleteDocumentPage method ........................................................................................................................................ 95 ChangeDocumentResolution method ............................................................................................................................ 95 VerifyTIFFDocument method ....................................................................................................................................... 96

12. SIGNTIFF.DLL COMPONENT: DIRECT TIFF IMAGE FUNCTIONS ............ 97

12.1. DEFINITION OF THE ITIFFLIB INTERFACE ............................................. 97

12.2. INTERFACE CLSID ALLOCATION ........................................................ 97


12.4. METHODS AND PROPERTIES .............................................................. 97 BmpToTIFF method ...................................................................................................................................................... 97 TIFFToDib method ........................................................................................................................................................ 98 TIFFToPng method ....................................................................................................................................................... 98 DibToPng method .......................................................................................................................................................... 98 GetDocumentCompression method ............................................................................................................................... 99 TiffToTiff method ....................................................................................................................................................... 99 GetReferenceCount method ......................................................................................................................................... 100 GetSigReference method ............................................................................................................................................. 100 GetSigRect method ...................................................................................................................................................... 100 SetPage method ........................................................................................................................................................... 101 SignDocument method ................................................................................................................................................ 101 SignDocument2 method .............................................................................................................................................. 102 GetDocInfoID method ................................................................................................................................................. 103 GetDocInfo method ..................................................................................................................................................... 104 GetDocumentResolution method ................................................................................................................................. 104 GetDocumentSize method ........................................................................................................................................... 104 InvalidateSignatory method ......................................................................................................................................... 105 InvalidateDocument method ........................................................................................................................................ 105 DrawText method ........................................................................................................................................................ 106 SetTextFont method..................................................................................................................................................... 106 SetLicenseKey method ................................................................................................................................................ 107 DeleteDocumentPage method ...................................................................................................................................... 107 ChangeDocumentResolution method .......................................................................................................................... 108


17.09.2021 Page 7 of 125

VerifyTIFFDocument method ..................................................................................................................................... 108

13. SCALEBMP.DLL COMPONENT: REDUCING THE SIZE OF WINDOWS BITMAPS ......................................................................................... 109

13.1. DEFINITION OF THE IRESIZEBMP INTERFACE ........................................ 109


13.3. DECLARATION INFORMATION .......................................................... 109

13.4. METHODS AND PROPERTIES ............................................................ 109 Resize method: ............................................................................................................................................................ 109

14. SIGNOTEC SIGNOAPI COMPONENT FILES ....................................... 111

15. IMPORTANT FILES REQUIRED BY THE SIGNOAPI (DEPENDENCIES) ... 111

16. OTHER FILES .............................................................................. 111

17. FURTHER INFORMATION .............................................................. 112

17.1. REGISTER ................................................................................ 112

17.2. DEPENDENCIES .......................................................................... 113

17.3. HARDWARE DEPENDENCIES ............................................................ 113

18. THE SIGNCAP.INI CONFIGURATION FILE ........................................ 113

18.1. ENTRIES .................................................................................. 113

18.2. STRUCTURE .............................................................................. 114

19. TABLE LISTING THE RESOLUTIONS OF THE INPUT DEVICES' LCDS ... 115

20. CODE SNIPPETS .......................................................................... 116

20.1. METHODS FROM SIGNVIEW.DLL: ...................................................... 116 20.1.1. Displaying a signature in Visual Basic ....................................................... 116

20.2. METHODS FROM SIGNUTIL.DLL: ...................................................... 116 20.2.1. Converting a TIFF to a PDF in Visual Basic................................................. 116

20.3. METHODS FROM BMPSCALE.DLL: ...................................................... 116 20.3.1. Reducing the size of bitmaps in Visual Basic .............................................. 116

20.4. METHODS FROM SIGNPDF2.DLL: .................................................... 116 20.4.1. Attaching a signature in Visual Basic ........................................................ 117 20.4.2. Reading out signatures in Visual Basic ...................................................... 117

20.5. METHODS FROM STSGNLIB.DLL: ...................................................... 118 20.5.1. Inserting SGN entries in Visual Basic ........................................................ 118

21. PDF FORM FIELDS ....................................................................... 118

21.1. XML EXPORT STRUCTURE FOR FORM FIELD DATA .................................... 118

21.2. XML EXAMPLE (STRUCTURE): ......................................................... 118

21.3. ADDITIONAL ENTIRES FOR FORM FIELDS ............................................. 119

21.4. DEFINITION OF ENTRIES FOR THE FORM FIELD FLAGS (TAG: <FLAGS>) ......... 120

21.5. DEFINITION OF ENTRIES FOR THE FIELD TYPES (TAG: <TYPE>) .................. 120

21.6. CODE SNIPPET ........................................................................... 121

22. USED XML STRUCTURES IN THE COMPONENT SIGNPDF2 ................. 122

22.1. XML STRUCTURE TO SET THE TIMESTAMP IN THE SIGNATURE FIELD .............. 122


17.09.2021 Page 8 of 125

Element <Timestamp/Text> ........................................................................................................................................ 122 Element <Timestamp/Color> ...................................................................................................................................... 122 Element <CustomText/Text> (optional) ...................................................................................................................... 122 Element <CustomText/Color> ..................................................................................................................................... 122 Element <Signature/Color> (optional)......................................................................................................................... 123 Element <Signature/Alignment> (optional) ................................................................................................................. 123

23. SIGNOTEC SGN TAGS .................................................................. 124

23.1. INSERTING SGN TAGS IN POSTSCRIPT FILES ....................................... 124

24. SIGNOTEC TIFF TAGS .................................................................. 125

Legal notice All rights reserved. This documentation and the components it describes are protected by the copyright law of signotec GmbH based in Ratingen, Germany. Reproduction of this documentation, in part or in whole, is subject to prior written approval from signotec GmbH. All the hardware and software names used are trade names of their respective manufacturers/owners. signotec GmbH reserves the right to make technical changes.


17.09.2021 Page 9 of 125

1. Change list SignoAPI Version 8.2.4 Date 2021-09-17

Document version 1.213 Date 2021-09-17

Component

Interface

Kind of change Corrections

Chapters 14, 15, 16, 17.1 and 17.2 have been updated

SignoAPI Version 8.2.4 Date 2021-09-16


Component

Interface

Kind of change Corrections

Chapter 2.4 has been updated



Component STImgCtl.ocx

Interface

Kind of change Removed, as moved in separate document

Chapter 5, 20.5, 21.1 has been removed

Chapter (now): 4.5, 20 has been updated

Component signcap.dll

Interface

Kind of change Change

Chapter (now) 7.9: Method SetSampleRate() has been updated

Component

Interface

Kind of change Typo / details added

Chapter (now): 2.4, 4.5, 5, 9.4 has been updated



Component

Interface

Kind of change Zeta-pad and the Omega RealSeriel added

Chapter 9 has been updated


17.09.2021 Page 10 of 125


Interface

Kind of change Zeta-pad added

Chapter 8.9: Method SetPadType updated



Component

Interface


Chapters 16, 17.1-17.3 have been updated

Component SignPDF3

Interface


Chapter 25 removed



Component

Interface


The installation features have been updated

Component STImgCtl

Interface

Kind of change Bug fixing, Change

SetSelection() method changed.



Component STImgCtl

Interface

Kind of change Bug fixing, Change

SetSelection() method changed.



Component STImgCtl


17.09.2021 Page 11 of 125

Interface STImgCtlEvents

Kind of change Functionality extension, Change

MarkEnd() and MarkChange() methods, changed parameter description.



Component -

Interface -


AllowMouseSelection () and AllowMultiSelection () methods, parameter extended.



Component -

Interface -


Support only for the signotec pads, various changes in many chapters.



Component -

Interface -


Delta and Alpha support, various changes in many chapters.



Component -

Interface -


The signotec Gamma pad support. SignLib2.dll removed, STPdfLib.dll added.




Interface IPadSignotecSignatureDevice, IPadTopaz

Kind of change Correction of Description

The separate description of the property Image, types VT_I4, VT_BSTR and VT_ARRAY |

VT_UI1 of VARIANT


17.09.2021 Page 12 of 125



Component -

Interface -

Kind of change Correction

Revised the structure of the whole document




Interface IPadSignotecSignatureDevice

Kind of change Description

Description of SignDataBase64 property added





Kind of change Description

Description of return codes of interface IPadSignotecSignatureDevice added



Component aCaptureClientSE.ocx

Interface -

Kind of change The component has been removed

The component has been removed



Component Signcap.dll


Kind of change Extension of the description of SetPadType

The new Types for signotec Alpha.



Component SIGNLCD.OCX, SIGNWTAB.DLL, signmail.dll, ACaptureClient.ocx


17.09.2021 Page 13 of 125

Interface -

Kind of change Removing

The components are from signoAPI removed.



Component signview.dll

Interface ISignDraw


signotec signature pads don't need a licence.



Component SignPDF3.dll, signcap.dll, signview.dll, STImgCtl.ocx, SignPDF2.dll, signtiff.dll, stsgnlib.dll, SignoUtilities.dll, signdoc.dll, scalebmp.dll, aCaptureClientSE.ocx

Interface -

Kind of change Important information

Dependencies of interfaces and components.



Component SignPDF2.dll

Interface -

Kind of change Note

To create a DigSig field, pleas, use the SignPDF3.dll.



Component signcap.dll, ACaptureClientSE.ocx

Interface IPadSignotecSignatureDevice, aCaptureClientSE.aCaptureClient

Kind of change Important note

For full functionality of signotec pads use the free signotec signoPAD API.






17.09.2021 Page 14 of 125

Kind of change Adjustment

The method SetLCDText, If the font size is less than 12, set the font size 12.



Component

Interface

Kind of change General correction

In Chapter 4.5. “The most frequently used components” is emphasized rather than

signPDF2.dll to use the new signPDF3.dll. In Chapter 6. “SignPDF2.dll component:

Signing PDF documents and other functions” is emphasized rather than signPDF2.dll to

use the new signPDF3.dll.






Typ of pad 113 removed.




Interface ISignDigSigPDF


SignPDF3.dll removed. SignPDF3.dll is in the separate document documented.



Component SignKrnl.dll, SignPDF3.dll

Interface ISignEngn, ISiglearn, ISignDigSigPDF


SignKrnl.dll removed. SignKrnl.dll is in the Product signotec Boimetric API documented. ISignEngn

and ISiglearn removed. ISignEngn and ISiglearn are in the Product signotec Boimetric API documented. SignPDF3.dll updated. ISignDigSigPDF updated. Used XML-Structures in the Component SignPDF3.dll updated.



Component

Interface

Kind of change Documentation for Wacom STU-520


17.09.2021 Page 15 of 125

The description of the Wacom Interface added



Component

Interface

Kind of change Corrected

The description of the silent installation has been corrected.



Component SIGNPDF3.Dll



The description of the SignPdfDocumentMemory function has been corrected.



Component SIGNPDF3.Dll, STImgCtl.ocx

Interface ISignDigSigPDF, STImgCtl


The license of type 3 (memory functions, JBIG2 support) for components sinPDF3.dll

and STImgCtl.ocx is no longer needed, was removed.



Component SIGNPDF3.Dll


Kind of change Method is added

Methods VerifyCertificate (…), GetReferenceCountMemory(…),

VerifyPdfDocumentMemory(…), GetDSFieldInfoMemory(…), VerifyCertificateMemory(…),

GetReferenceMemory(…), SignPdfDocumentMemory(…),

CreatePKCS12CertificateMemory(…), CreateDSFieldMemory(…) are added.

The license of type 3 (memory functions, JBIG2 support) for components sinPDF3.dll

and STImgCtl.ocx is no longer needed, was removed.

"signotec – files" chapter has been updated.




Interface STImgCtl



17.09.2021 Page 16 of 125

Method SetPrintOptions (…) is added.






Method SetSampleRate (…) is added.




Interface _DSTImgCtl


Method GetEmptyOptionalField (…) is added.



The Component EP1Pad.dll has been deleted. The method SetLCDText has been added in

the interface IPadSignotecSignatureDevice.



Silent Uninstallation





Kind of change Method is moved

Method SetImageParameter (…) is moved to SHARED METHODS AND PROPERTIES.





Kind of change New method

Method SetImageParameter (…) - added.



17.09.2021 Page 17 of 125


Silent Installation

SignoAPI Version 7.0.107 Datum 2011-11-18

Dokumentenversion 1.171 Datum 2011-11-18

Component SignCap.dll



SetIPAddress



Component SignPDF2.DLL

Interface ISignPDF

Kind of change Error fixing

In the structure SIGNATURE_INFO the section Signature added



Component STSGNLIB.DLL

Interface ISgnDoc

Kind of change Error fixing

Method AddSgnPos2() error fixing, method SaveSignatureEx() – A new row in the table

Imagetyp for TabletPC windows bitmap





Kind of change New parameters

New parameters in the XML struct to define the color and the alignment of a signature in

DigSig fields.



Kind of change New methods

SetPenWidth(), PadData(), SetComPort(), SetPadType(), SetButtonPosition(),

SetOEMKey(), GetOEMPadData()

Component SignoUtilities.dll

Interface PadUtil



17.09.2021 Page 18 of 125

Get_TwainSettings2(), Get_TwainSettings3(), Set_TwainSettings2(),

Set_TwainSettings3()


Interface ISignPDF


SelectFormfield()


Interface all

Kind of change New parameter in the signcap.ini

New parameter in the signcap.ini to control the extended logging of the SigPlus.ocx (for

Topaz pads)

Component none

Interface none

Kind of change Control file for the STPadCapt.ocx

New control file (STPad.ini) for the STPadCapt.ocx. For the usage with signotec devices.

Component miscellaneous

Interface miscellaneous

Kind of change Correction of errors in the documentation

Corrected miscellaneous errors in the documentation.



Component ACaptureClientSE.dll

Interface ACaptureClientSE.aCaptureClient

Kind of change New component

New Component for the signotec pads.



Kind of change New interface

New Interface in Component signcap.dll for the signotec pads.


Interface ISignPDF


New methods for working with PDF documents directly in the memory.

VerifyPdfDocumentMemory, SignPdfDocumentMemory, GetPdfDocumentSizeMemory,

GetReferenceCountMemory, GetReferenceMemory, GetSignatureInfoMemory,

GetAsciiTextPosition3Memory.


17.09.2021 Page 19 of 125


Interface ISignPDF


New method AddTextbox to bring in text into a PDF document (only possible before

signing).


Interface IPadTopaz + other

Kind of change New formats for image output supported

The method SaveSignatureEx is now able to give back BASE64-coded Strings. So it is

possible to work directly in the memory with the result.

Component miscellaneous

Interface miscellaneous

Kind of change Correction of errors in the documentation

Corrected miscellaneous errors in the documentation.

SignoAPI version 7.0.91 Date 2009-09-09



Interface IPadTopaz

Kind of change Changed behavoir of a method

Values of a parameter for the method SaveSignatureEx has been extended (Saving a

picture of signature as an image into the memory).





Kind of change New component

Component SignPDF3.dll is integrated into the SignoAPI. Explainations of methods +

properties and explainations of the XML structures in the appendix. New system

requirements for this component!


Interface IPadTopaz

Kind of change Changed behavoir

Interactive pad controll (with LCD pads) implemented. Confirmation of the signature with

buttons on the LCD of the pad possible.


Interface IPadTopaz

Kind of change Changed behavoir of a method

CaptureWithoutDialog reviewed and changed.


17.09.2021 Page 20 of 125


Interface IPadTopaz

Kind of change New mode

Small bandwidth mode implemented (See signcap.ini)


Interface IPadTopaz

Kind of change New values for the signcap.ini

New values for the signcap.ini


Interface ISignPDF

Kind of change Explaination added

SignPdfDocument, SignPdfDocumentVBS, SignPdfDocumentHttp and

SignPdfDocumentHttp2

Explanation of the „nModeTimestamp“ and „strText“ parameters in the appendix.


Interface IPadTopaz

Kind of change New returncodes

New returncodes implemented and explained.


Interface STImgCtl

Kind of change Changed method

FitTo

New Mode: Pagescroll mode


Interface IPadTopaz

Kind of change Changed behavior

The Topaz driver component „SigPlus.ocx“ is checked for authenticity and integrity.

Internal check for integrity, external check for digital signature. Abort with returncode, if

checks fail.




Interface ISignPDF


MergePDFDocuments


Interface ISignPDF



17.09.2021 Page 21 of 125

ExportFormfieldData

Changed possibilities for the XML export structure (e.g. reading out the readonly flags)


Interface ISignPDF


ImportFormfieldData

Changed possibilities for the XML import structure (e.g. set the readonly flags)


Interface IPadTopaz, IPadSO und IPadTabletPC


SelectDialog

Component signutil.dll

Interface ISTComm

Kind of change New interface with one new method

GetComPortList

2. General overview of the signotec SignoAPI

The signotec SignoAPI is an Application Programming Interface (API) that allows programmers

to integrate a wide variety of functions into their programs for attaching digitalised electronic

signatures to documents.

2.1. SignoAPI for Windows

SignoAPI for Windows comprises various self-registering components for the Microsoft

Windows operating system that can be introduced according to functional requirements.

The components are compatible with the Microsoft Component Object Model (COM) and are

supplied either as DLL or OCX. The API’s installation program registers the components in the

system. Thanks to COM technology, use of the components is not restricted to any particular

programming language.

This document is a complete API reference. It contains all the available functions, variable

types and properties listed under the components in which they were implemented. The

documentation also includes small sample programs, mostly for the Visual Basic and

Visual Basic.NET programming languages.

2.2. Versions

Since the Version 7.0.95 there is only one edtion of the signotec SignoAPI available

The former existing editions

2.2.1. Small Edition (SE)


17.09.2021 Page 22 of 125

and

2.2.2. Full Edition (FE)

are not longer available as separate products. It only exists one edition, called SignoAPI, with

the features of the SignoAPI FE.

2.3. Functional range

The SignoAPI allow signature data to be captured from external or internal devices and

inserted into PDF documents or into image documents (as TIFF, for example). These

documents can also be displayed (images and PDF viewer). A lot more functions exist, such

as the transfer of signature data by e-mail, or the search for connected signature devices.

2.4. System requirements for the Windows version of the SignoAPI

Most of the components are useable in all Windows versions since Windows 7. Please also

refer to the separate documentation of the components signoMobileCapture.dll, SignPDF3

and STImgCtl.ocx.

2.4.1. 64-bit systems

The SignoAPI is compiled for 32-bit systems. It is also working on 64-bit system (via WOW64).

The applications that use the signoAPI, must be compiled for x86 platform. On request, some

of the components are available for 64 bit.

2.4.2. MFC dependency

Nearly all components and installed files of the signoAPI require Microsoft Runtimes (VCRT,

MFC, ATL), in version 6, 8, 10 or 14. These are installed by the setup.

2.5. SignoAPI for Java

The SignoAPI is also available for Java the “signoAPI Java Native 2”. This is implemented via

the Java Native Interface (JNI). This Java implementation is fully documented in the

separate document entitled ‘signoAPI Java Native 2 Documentation’. This Java

implementation is sold separately and is not part of the SignoAPI.

2.6. SignoAPI for Linux

Another version of the SignoAPI the “signoAPI Java Native 2”, allows signatures to be

attached to PDF documents under the Linux operating system. This Linux implementation is

fully documented in the separate document entitled ‘signoAPI Java Native 2 Documentation’.

This Java implementation is sold separately and is not part of the SignoAPI’s Full Edition or

Small Edition.

2.7. Silent Instalation

A silent installation makes it possible for you to install signoAPI without displaying dialogue

boxes, thus requiring no additional user interaction. To perform a silent installation, start the

command prompt. Then switch to the folder containing the signoAPI setup. There, you can

use various parameters to include a number of features during installation.

http://dict.leo.org/ende?lp=ende&p=Ci4HO3kMAA&search=functional&trestr=0x8001

http://dict.leo.org/ende?lp=ende&p=Ci4HO3kMAA&search=range&trestr=0x8001


17.09.2021 Page 23 of 125

2.7.1. The features

The signoAPI setup has a range of optional features:

▪ CodeSamples

▪ Access

▪ HTML

▪ VB6

▪ InfoPath

▪ LotusNotes

▪ SignPDFDemo

▪ CSharp

▪ Documentation

▪ PadConfiguration

▪ Applications

▪ signoMobileCapture

The bold terms are the feature names used in the setup and are important in the next chapter.

Information: The feature names are case-sensitive.

2.7.2. Selecting and deselecting features

There are two ways to specify the feature list for the initial installation or for an update

installation.

Method 1

Method 1 is useful if only a few features need to be deselected. First, select the Windows

installer parameter ‘ADDLOCAL’ and the value ‘ALL’ to select all features. Then select the

‘REMOVE’ parameter and specify the names of the features that should not be installed.

Here is a example for running with the command prompt:

signoAPI_X.X.X.exe /s /v" ADDLOCAL=ALL REMOVE=Documentation, PadConfiguration,

Applications /qn"

Method 2

Method 2 is useful if only a few optional features need to be installed. Here, use the

‘ADDLOCAL’ parameter to pass only the list of optional features that should be installed.

Here is a example for running with the command prompt:

signoAPI_X.X.X.exe /s /v"ADDLOCAL=Documentation, PadConfiguration /qn"

2.7.3. Update installation or initial installation with all features

If you only want to update to a new version while retaining the current feature list, or

perform an initial installation with all features, run the following command:


17.09.2021 Page 24 of 125

signoAPI_X.X.X.exe /s /v"/qn"

2.7.4. Changing the installed features at a later time

After successfully completing the installation, you can add or remove one or more optional

features. To do this, restart the setup for the version that is already installed.

Here is a examples for running with the command prompt:

signoAPI_X.X.X.exe /s /v"ADDLOCAL=Documentation REMOVE=PadConfiguration,

Applications /qn"

2.8. Silent deinstallation

A silent deinstallation makes it possible for you to uninstall signoAPI without displaying

dialogue boxes, thus requiring no additional user interaction. In order to carry out a silent

deinstallation, start the command prompt. Then switch to the folder containing the signoAPI

setup. Now use the following command to uninstall signoAPI:

signoAPI_X.X.X.exe /s /x /v"/qn"


17.09.2021 Page 25 of 125

3. signotec SignoAPI components

In the following we provide an overview of all the components included in the signotec

SignoAPI listed according to application area.

These components may also be referred to as COM components or modules/COM modules.

3.1. Application area 1:

3.2. Document and image viewer/graphical user interface/visualisation of signature data

File name Interfaces Brief description

STImgCtl.ocx STImgCtl

STImgCtlEvents For displaying and navigating within PDF and multi-TIFF

documents and the most common image formats.

signview.dll ISignDraw For visualising existing/stored signature data.


3.4. Hardware access/capturing signature data


signcap.dll IPadTabletPC

IPadSignotecSignatureDevice

For controlling various signature

pads and capturing signature data

from other sources such as tablet

PCs.


3.6. Signing documents and images/validity check and signature comparison


SignPDF2.dll ISignPDF For signing PDF documents.

SignPDF3.dll ISignDigSigPDF For signing PDF documents with DigSig fields.

stsgnlib.dll ISgnDoc For inserting meta tags into PDF documents and reading

them out (in preparation for signing).

signdoc.dl l IDocFun For signing non-PDF document types (e.g., TIFF) and

comprehensive library of signing functions.

signtiff.dl l ITIFFLib Basic component for signing non-PDF document types

(TIFF documents).


3.8. Image conversions/e-mail dispatch



17.09.2021 Page 26 of 125

signuti l .dl l

IPdfConv

IDataConv

ICheckAlgo

IBlowFish

Library of functions for converting image documents (e.g.,

TIFF) to PDF documents, amongst other things.

scalebmp.dll IResizeBmp Component for resizing bitmaps.

SignoUti l it ies.

dll PadUtil

Library of functions for pad searching and pad

configuration, amongst other things.


17.09.2021 Page 27 of 125

4. General information on the signotec SignoAPI

4.1. Component compatibility

All the SignoAPI components described in this documentation are self-registering and

support the Microsoft IDispatch interface. This makes them equally available under

environments such as Visual Basic, Delphi and Visual C++, for example.

4.2. Data formats

OLE-compliant and COM-compliant data types are used for complex data structures

(VARIANT, BSTR etc.) exclusively. Documents are expected in PDF or TIFF format

only. Signatures can be returned in PNG, TIFF or BMP format (however, generally not

in JPEG format, as this is a high-loss format that is unsuitable for displaying

signatures).

4.3. Visual Basic

In a Visual Basic environment WIN32 API functions are required in order to

guarantee BLOB handling for handles. This mainly affects global memory calls. These

need to be imported from the respective system DLLs.

4.4. PadData and SignData structures

The ‘SignData’ data structure is the standard format for signature data in all the

methods and properties. It is an encrypted, compressed, biometric format that can

be stored in a database and/or as a tag in a TIFF document or a PDF document. It is

therefore advisable to select SignData as a data-storage format.

The ‘PadData’ data structure is the raw format for signature data and used to be the

standard format for signature data. However, this format is uncompressed and

requires a relatively large amount of storage space. This is why this data format is no

longer recommended and should only be used in special cases.

Both formats can be visualised in real time using the ‘signview.dll’ component.

Note: When using the component SignPDF3.dll the SignData is also encrypted with

the given public key using RSA. This data can be decoded only with the matching

private key and can not be visualized without further notice.

4.5. The most frequently used components

The ‘STImgCtl.ocx ’, ‘signcap.dll ’ and ‘SignPDF3.dll’ components normally

combine all the standard calls used in an application for displaying and signing PDF

documents. Further components are only rarely required.

Note:

The early frequently used component “SignPDF2.dll” is how before fully executable

but uses proprietary signotec SGN signature format. To use the digital signatures

Adobe standard in its entirety, the new component “SignPDF3.dll” must be used.

Note:


17.09.2021 Page 28 of 125

The “SignPDF3.dll” component is described in detail in the separate documentation

“signoAPI SignPDF3 Documentation EN.pdf”, the component “STImgCtl.ocx” in

“signoAPI STImgCtl Documentation EN.pdf”.

The ‘signcap.dll’ and ‘signdoc.dll’ components combine all the standard calls for

signing TIFF documents.

All the other components described in this documentation do not necessarily have to

be used in an application; they are only listed here for the sake of completeness and

may also be used separately, if required.

4.6. MD5 checksum

The following information only applies to TIFF documents. Another mechanism is

employed for integrity checking in PDF documents, which is signature-based rather

than document-based.

The ‘CreateMD5Checksum’ method in the ‘signdoc.dll ’ generates an MD5 hash

that is designed only for additional use by the SignoAPI user, as a new encrypted

checksum (SHA512-based) is added to the document after each signing. If, after

signing, the document is tampered with or corrupted, no further signatures can be

attached.

4.7. Licence keys

The SignoAPI is unregistered when it is delivered, which means that a few of its

functions cannot be used. Other functions are furnished with a demo stamp, where

‘Demo’ is displayed in images and PDFs.

In order to be able to use the SignoAPI’s full range of functions, a licence key must

be obtained from signotec GmbH.

There are two different types of licence keys:

1. Hardware-dependent single-user licences

2. Hardware-independent company licences

For type 1 licences, an authorisation key (software code) is generated during

installation. This key is bound to specific hardware components and is only ever valid

for one computer (single user).

After a single-user licence has been purchased, a licence key can be requested and

entered with the help of the supplied ‘Signotec-Lizenz.exe’ program.

As soon as a valid licence key is present, this is stored in the computer’s registry and

all the SignoAPI’s components are subsequently activated and freed from their demo

stamps.

Type 2 licences are hardware-independent company licences that not bound to one

particular computer/workstation and whose keys are not stored in the registry.

Instead, the licence key must be set for each instantiation of a component by calling

the SetLicenseKey() or APILicenseKey() method.

4.8. Complex data structures as parameter values

The SignoAPI employs three different technologies for passing complex data

structures via the COM interface. These are described in the following:


17.09.2021 Page 29 of 125

4.8.1. Passing as a global handle in a VARIANT of type VT_I4

When a TIFF document (also referred to as a TIFF image) is requested as a method’s

input parameter, the TIFF's binary data is not channelled directly via the COM

interface; instead, the data has to be written to a global memory area (generated by

calling GlobalAlloc() ) and only the generated global handle to the memory area (of

type HGLOBAL) is passed to the method.

As the HGLOBAL data type is not COM-compliant, this handle is stored and passed in

a VARIANT (as a COM-compliant wrapper). Here, VT_I4 is used as the VARIANT’s

subtype, as this can store the 32-bit HGLOBAL value.

In order to subsequently use the data in the VARIANT, the developer must extract

the HGLOBAL from the VARIANT (stored here as a 32-bit value of type VT_I4

(long)), perform a casting operation (e.g., to C++), where necessary, and use

GlobalLock() and GlobalSize() to make the data area useable (i.e., determine the

pointer to and size of the memory area).

The developer can then extract the data from the locked, global memory area (copy)

and convert it to the target data format (into C++, for instance, using a type cast).

Afterwards, the memory area must be unlocked again using GlobalUnLock(). Finally,

the developer must call GlobalFree() to release the global handle again for the entire

system.

The sole exception is the shared Image() property in the ‘signcap.dll’. Here, users

must call the FreeHandle() method each time after they have called the Capture()

function; they should not execute GlobalFree() themselves.

If, during the following method and property descriptions, a global handle is

mentioned in connection with the VARIANT (VT_I4) type, then the procedure

described above must be implemented to either access or pass data.

This data passing method is also partly used for other data types and structures

(e.g., TifftoDib(), TifftoPng() etc.).

4.8.2. Passing as a VARIANT Typ VT_ARRAY

When a SignData data structure is requested as a parameter value, the data is

channelled directly via the COM interface. For this purpose, the binary data is written

to a VARIANT with a VT_ARRAY (type VT_I1) subtype.

C++ allows the content of the VT_ARRAY to be entered and extracted using the

WinAPI’s various SafeArray functions.

When a method in the API has an input parameter of type VARIANT that is marked as

a pointer (asterisk before the data type and begins with ‘p’), then the developer must

pass the pointer to the filled data structure of type VARIANT/VT_ARRAY (e.g., if the

SignData() property needs to be set).

If this is marked as an output parameter, then the developer must pass the pointer

to an empty data structure of type VARIANT. This will then be filled by the called

method (as type VT_ARRAY).


17.09.2021 Page 30 of 125

The "memory" functions of the component SignPDF2.dll also expect that the content

of the PDF document is stored in the memory as a VT_ARRAY.

4.8.3. Passing as a VARIANT of type VT_BSTR

When a PadData data structure is passed, it is always a pure character string (zero-

terminated). It is channelled via the COM interface in a VARIANT of data type

VT_BSTR.


17.09.2021 Page 31 of 125

5. SignPDF2.dll component: Signing PDF documents and other functions

PDF documents can be edited and signed with the help of this component. Up to nine

signatures can be attached to each page of a PDF document. After each signing, a new

security checksum is calculated internally and entered into the PDF document. This is

designed to protect against any unauthorised tampering.

Important information:

The component SignPDF2.dll has the following dependencies

1. The COM dependency is the Dll signlib.dll. Before the component SignPDF2.dll is

instantiated, the DLL must be registered. In the command line, run the command

regsvr32 signlib.dll.

Note:

The component uses the signotec SGN-signature proprietary format. To use the digital

signatures Adobe standard in its entirety, the new component “SignPDF3.dll” must be

used. The “SignPDF3.dll” component is described in detail in the separate

documentation “signoAPI SignPDF3 Documentation EN.pdf”.

5.1. Definition of the ISignPDF interface

interface ISignPDF : IDispatch

5.2. Interface ID assignment

The IID for the interface:

Interface IID

ISignPDF 499EFB9F-45A9-4CAE-9FDF-40746C66CC0E

The CLSID for the interface:

Interface CLSID

ISignPDF 2AD8DEC5-19B1-46E3-9796-A2B192D48920

5.3. Declaration information

The following declaration must be made when instantiating under Visual Basic

(VB).

Interface Declaration

ISignPDF Signotec.signpdf2

5.4. Methods and properties

SignPdfDocument and SignPdfDocumentVBS methods

Electronic signing of a PDF document using the signature data provided

(SignData). The signature field and supplementary data are inserted at a specific

position and page within the PDF.

The position of the signature field must be specified in points relative to the size

of the PDF document.


17.09.2021 Page 32 of 125

Note: Up to nine signatures can be attached to each page of the document.

Note: The signature data (SignData) can be passed from a previous Capture()

call by the ‘signcap.dll’ component, for example.

Note: The structure and the importance of the XML-encoded string in the parameter

strText if nModeTimestamp = 100 is described in the appendix under 22 (Used XML

structures in the component SignPDF2).

LPCTSTR

[in]

strPadID Unique ID of the connected pad.

LPCTSTR

[in]

strPdfFilename PDF file name and path.

VARIANT

(VT_ARRAY)

[in]

varArrSignDataBlock The biometric data block (VT_ARRAY

SignData).

short

[in]

xPos1 Upper left corner in points (X coordinate).

short

[in]

yPos1 Upper left corner in points (Y coordinate).

short

[in]

xPos2 Lower right corner in points (X coordinate).

short

[in]

yPos2 Lower right corner in points (Y coordinate).

short

[in]

nPage Page in the PDF document.

LPCTSTR

[in]

strText Optional supplementary text underneath the

signature (in place of the timestamp).

short

[in]

nModeTimestamp 0 = No timestamp.

1 = ‘Date: D:20040218110951’.

2 = ‘Date: 05.11.2004 10:12 o'clock’.

3 = ‘31.12.2004 14:54:35’

100 = Interpret optional text (XML structure).

HRESULT SignPdfDocument ( [in] LPCTSTR strPadID,

[in] LPCTSTR strPdfFilename,

[in] VARIANT varArrSignDataBlock,

[in] short xPos1,

[in] short yPos1,

[in] short xPos2,

[in] short yPos2,

[in] short nPage,

[in] LPCTSTR strText,

[in] short nModeTimestamp);

Use the following method when working with JavaScript or VBScript.

HRESULT SignPdfDocumentVBS ( [in] BSTR strPadID,

[in] BSTR strPdfFilename,


[in] short xPos1,

[in] short yPos1,

[in] short xPos2,

[in] short yPos2,

[in] short nPage,

[in] BSTR strText,

[in] short nMode);


17.09.2021 Page 33 of 125

SignPdfDocumentMemory method

Electronic signing of a PDF document which has already been loaded into the

memory, using the signature data provided (SignData).

The signature field and supplementary data are inserted at a specific position

and page within the PDF.

The position of the signature field must be specified in points relative to the size

of the PDF document.

After a successful call the value of the second parameter has been changed and

contains the signed PDF document.


Note: The signature data (SignData) can be passed from a previous Capture()

call by the ‘signcap.dll’ component, for example.




LPCTSTR

[in]


VARIANT

(VT_ARRAY)

[in, out]

*pvarPdfArray [in] Content of the PDF document to sign,

stored in a VARIANT as VT_ARRAY.

[out] Signed PDF document as VT_ARRAY.

VARIANT

(VT_ARRAY)

[in]

varArrSignDataBlock The biometric data block (VT_ARRAY

SignData).

short

[in]


short

[in]


short

[in]


short

[in]


short

[in]


LPCTSTR

[in]

strText Optional supplementary text underneath

the signature (in place of the timestamp).

short

[in]


1 = ‘Date: D:20040218110951’.

2 = ‘Date: 05.11.2004 10:12 o'clock’.

3 = ‘31.12.2004 14:54:35’

100 = Interpret optional text (XML

structure).

HRESULT SignPdfDocumentMemory (

[in] LPCTSTR strPadID,

[in, out] VARIANT* pvarPdfArray,


[in] short xPos1,

[in] short yPos1,

[in] short xPos2,

[in] short yPos2,

[in] short nPage,


17.09.2021 Page 34 of 125



SignPdfDocumentHttp method

Electronic signing of a PDF document online. The signature is inserted at a

specific position and page and includes supplementary data. The PDF document

will be downloaded from the given download URL before the signing process and

afterwards it will be send to the given Upload URL (HTTP-GET)

Note: HTTP and HTTPS calls for up- and downloading are supported.

Note: When the document is uploaded there must be a script running, to receive

and store/process the document.


Note: The biometric data block can be passed from a previous Pad Capture call

by the SignCap interface, for example. This data block is of data type

VT_ARRAY.

Note: The position must be specified in points.




LPCTSTR

[in]


LPCTSTR

[in]

strDownloadUrl HTTP download URL.

LPCTSTR

[in]

strUploadUrl HTTP upload URL.

VARIANT

(VT_ARRAY)

[in]

varArrSignDataBlock The biometric data block (VT_ARRAY with

SignData).

short

[in]


short

[in]


short

[in]


short

[in]


short

[in]


LPCTSTR

[in]

strText Optional supplementary text underneath the


short

[in]


1 = ‘Date: D:20040218110951’.

2 = ‘Date: 05.11.2004 10:12 o'clock’.

3 = "31.12.2004 14:54:35"


HRESULT SignPdfDocumentHttp ( [in] LPCTSTR strPadID,

[in] LPCTSTR strDownloadUrl,

[in] LPCTSTR strUploadUrl,


[in] short xPos1,


17.09.2021 Page 35 of 125

[in] short yPos1,

[in] short xPos2,

[in] short yPos2,

[in] short nPage,



SignPdfDocumentHttp2 method

Electronic signing of a PDF document online. The signature is inserted at a

specific position and page and includes supplementary data. The signature

position is calculated automatically with the help of a unique search string.

The PDF document will be downloaded from the given download URL before the

signing process and afterwards it will be send to the given Upload URL (HTTP-

GET)

Note: HTTP and HTTPS calls for up- and downloading are supported.

Note: When the document is uploaded there must be a script running, to receive

and store/process the document.


Note: The biometric data block can be passed from a previous Pad Capture call

by the SignCap interface, for example. This data block is of data type

VT_ARRAY.

Note: The offset must be specified in points.


bstrText if nModeTimestamp = 100 is described in the appendix under 22 (Used XML


LPCTSTR

[in]


LPCTSTR

[in]

strDownloadUrl HTTP download URL.

LPCTSTR

[in]

strUploadUrl HTTP upload URL.

VARIANT

(VT_ARRAY)

[in]

varArrSignDataBlock The biometric data block (VT_ARRAY with

SignData).

short

[in]

xSigOffset +/- signature adjustment in x direction

(default = 0).

short

[in]

ySigOffset +/- signature adjustment in y direction

(default = 0).

short

[in]

nSigPosition 0 = Underneath. 1 = Above the search string.

BSTR

[in]

bstrSearchString Unique search string in the PDF document.

BSTR

[in]

bstrText Optional supplementary text underneath the


short

[in]


1 = ‘Date: D:20040218110951’.

2 = ‘Date: 05.11.2004 10:12 Uhr’.

3 = "31.12.2004 14:54:35"


HRESULT SignPdfDocumentHttp2 ( [in] LPCTSTR strPadID,


17.09.2021 Page 36 of 125

[in] LPCTSTR strDownloadUrl,

[in] LPCTSTR strUploadUrl,


[in] short xSigOffset,

[in] short ySigOffset,

[in] short nSigPosition,

[in] BSTR bstrSearchString,

[in] BSTR strText,


VerifyPdfDocument method

Checks a PDF document to make sure it is intact. If a subsequent modification

of the PDF document is detected, the method highlights all the visible signatures

clearly in red and removes the security code and all the invisible data. This

makes the document invalid and will return a corresponding status code.

LPCTSTR

[in]

strPdfFilename PDF file name.

long*

[out]

plStatus Return value of the document verification

status.

0 = Status OK.

1 = Invalid CRC.

2 = No CRC.

3 = No PDF document.

HRESULT VerifyPDFDocument( [in] LPCTSTR strPdfFilename,

[out] long* plStatus);

VerifyPdfDocumentMemory method

Checks a PDF document to make sure it is intact. If a subsequent modification

of the PDF document is detected, the method highlights all the visible signatures

clearly in red and removes the security code and all the invisible data. This

makes the document invalid and will return a corresponding status code.

Note: This method expects that the contents of the PDF document is already

available as a VT_ARRAY in memory.

VARIANT

(VT_ARRAY)

[in]

VarPdfArray Content of the PDF document, stored in a

VARIANT as VT_ARRAY.

long*

[out]

plStatus Return value of the document verification status.

0 = Status OK.

1 = Invalid CRC.

2 = No CRC.

3 = No PDF document.

HRESULT VerifyPDFDocumentMemory( [in] VARIANT varPdfArray,

[out] long* plStatus);

GetReferenceCount method

Returns the total number of signatures already attached (using

SignPdfDocument() and other methods) for the given document.


17.09.2021 Page 37 of 125

LPCTSTR

[in]


long

[out]

*plCount Holds the number of signatures already attached.

HRESULT GetReferenceCount( [in] LPCTSTR strPdfFilename,

[out] long *plCount);

GetReferenceCountMemory method


SignPdfDocument() and other methods) for the given document.

Note: This method expects that the contents of the PDF document is already available

as a VT_ARRAY in memory.

VARIANT

(VT_ARRAY)

[in]

varPdfArray Content of the PDF document, stored in a


long

[out]

*plCount Holds the number of signatures already

attached.

HRESULT GetReferenceCountMemory( [in] VARIANT varPdfArray,

[out] long *plCount);

GetReferenceCount2 method


SignPdfDocument() and other methods) to a specific page for the given

document.

LPCTSTR strPdfFilename PDF file name.

int nPage Page number.

long *plCount Holds the number of signatures already attached.

HRESULT GetReferenceCount2( LPCTSTR strPdfFilename,

int nPage,

long *plCount);

GetReference method

Returns the signature specified in the 0-based index that was previously

attached using SignPdfDocument() and other methods. GetReferenceCount()

can be used to determine the total number of signatures. The signature is

returned as a SignData type and can be subsequently visualised or verified.

LPCTSTR

[in]


int

[in]

nIndex Signature index in the complete PDF document

(0-based).

VARIANT

(VT_ARRAY)

[out]

*pSignData SignData of type VT_ARRAY.

long *plPage Page in the PDF document.


17.09.2021 Page 38 of 125

[out]

HRESULT GetReference( [in] BSTR strPdfFilename,

[in] int nIndex,

[out] VARIANT *pSignData,

[out] long *plPage);

GetReference2 method



can be used to determine the total number of signatures.

The signature is returned as a SignData type and can be subsequently

visualised or verified (if it was stored without compression).

Also returns the coordinates in points and the respective page.

LPCTSTR

[in]


int

[in]


(0-based).

VARIANT

(VT_ARRAY)

[out]


long

[out]

*plPage Page in the PDF document.

long

[out]

*plX1 Upper left corner in points (X coordinate).

long

[out]

*plY1 Upper left corner in points (Y coordinate).

long

[out]

*plX2 Lower right corner in points (X coordinate).

long

[out]

*plY2 Lower right corner in points (Y coordinate).

HRESULT GetReference( [in] BSTR strPdfFilename,

[in] int nIndex,


[out] long *plPage,

[out] long *plX1,

[out] long *plY1,

[out] long *px2,

[out] long *py2);

GetReferenceMemory method



can be used to determine the total number of signatures.

The signature is returned as a SignData type and can be subsequently

visualised or verified (if it was stored without compression).

Also returns the coordinates in points and the respective page.




17.09.2021 Page 39 of 125

VARIANT

(VT_ARRAY)

[in]



int

[in]


(0-based).

VARIANT

(VT_ARRAY)

[out]


long

[out]

*plPage Page in the PDF document.

long

[out]


long

[out]


long

[out]

*plX2 Lower right corner in points (X coordinate).

long

[out]

*plY2 Lower right corner in points (Y coordinate).

HRESULT GetReferenceMemory( [in] VARIANT varPdfArray,

[in] int nIndex,


[out] long *plPage,

[out] long *plX1,

[out] long *plY1,

[out] long *px2,

[out] long *py2);

GetPdfDocumentSize method

Returns the page size of the PDF document in points.

LPCTSTR

[in]


long

[out]

*plWidth Width in points.

long

[out]

*plHeight Height in points.

HRESULT GetPdfDocumentSize( [in] BSTR strPdfFilename,

[out] long *plWidth,

[out] long *plHeight);

GetPdfDocumentSizeMemory method

Returns the page size of the PDF document in points.



VARIANT

(VT_ARRAY)

[in]



long

[out]

*plWidth Width in points.


17.09.2021 Page 40 of 125

long

[out]

*plHeight Height in points.

HRESULT GetPdfDocumentSizeMemory( [in] VARIANT varPdfArray,

[out] long *plWidth,

[out] long *plHeight);

GetAsciiText or GetAsciiText2 method

Extracts the ASCII text from a specific page in a PDF document and writes it to

the ‘strAsciiText’ parameter value.

GetAsciiText2() is an enhanced version of GetAsciiText().

LPCTSTR

[in]


BSTR

[out]

*strAsciiText Returns ASCII text.

int

[in]

nPage Page in the document.

HRESULT GetAsciiText( BSTR strPdfFilename,

BSTR *strAsciiText,

int nPage);

HRESULT GetAsciiText2( BSTR strPdfFilename,

BSTR *strAsciiText,

int nPage);

GetPdfPageCount method

Returns the total number of pages in a PDF document.

BSTR

[in]


long

[out]

*plPageCount Total number of pages.

HRESULT GetPdfPageCount( [in] BSTR strPdfFilename,

[out] long *plPageCount);

GetAsciiTextPosition or GetAsciiTextPosition2 method

Returns the X and Y positions and the page number of the specified search

string in the document. Searches the entire document. GetAsciiTextPosition2() is

an enhanced version of GetAsciiTextPosition().

The position of a found search string is represented by a rectangle which is virtually

laid around the text.

BSTR

[in]


BSTR

[in]

strSearchString Search string.

long *plPage Page number in the PDF document.


17.09.2021 Page 41 of 125

[out]

long

[out]


long

[out]


long

[out]

*plX2 Lower left corner in points (X coordinate).

long

[out]

*plY2 Lower left corner in points (Y coordinate).

HRESULT GetAsciiPosition( [in] BSTR strPdfFilename,

[in] BSTR strSearchString,

[out] long *plPage,

[out] long *plX1,

[out] long *plY1,

[out] long *px2,

[out] long *py2);

HRESULT GetAsciiPosition2( [in] BSTR strPdfFilename,


[out] long *plPage,

[out] long *plX1,

[out] long *plY1,

[out] long *px2,

[out] long *py2);

GetAsciiTextPosition3 method


string in the document. This method can also be used to find recurring search

strings by reusing the last position. See the VB6 example beneath.



BSTR

[in]


BSTR

[in]


long

[out]

*plPage Page number in the PDF document.

double

[out]

*dblX1 Upper left corner in points (X coordinate).

double

[out]

*dblY1 Upper left corner in points (Y coordinate).

double

[out]

*dblX2 Lower right corner in points (X coordinate).

double

[out]

*dblY2 Lower right corner in points (Y coordinate).

int

[in]

nMode Reserved. Always 0.

int

[in]

nOption Reserved. Always 0.

HRESULT GetAsciiTextPosition3( [in] BSTR strPdfFilename,

[in] BSTR strAsciiText,


17.09.2021 Page 42 of 125

[out] long *plPage,

[out] double *dblX1,

[out] double *dblY1,



[in] int nMode,

[in] int nOption);

GetAsciiTextPosition3 method


string in the document. This method can also be used to find recurring search

strings by reusing the last position. See the VB6 example beneath.





VARIANT

(VT_ARRAY)

[in]

varPdfArray Content of the PDF document, stored

in a VARIANT as VT_ARRAY.

BSTR

[in]


long

[out]

*plPage Page number in the PDF document.

double

[out]

*dblX1 Upper left corner in points (X

coordinate).

double

[out]

*dblY1 Upper left corner in points (Y

coordinate).

double

[out]

*dblX2 Lower right corner in points (X

coordinate).

double

[out]

*dblY2 Lower right corner in points (Y

coordinate).

int

[in]

nMode Reserved. Always 0.

int

[in]

nOption Reserved. Always 0.

HRESULT GetAsciiTextPosition3Memory(

[in] VARIANT varPdfArray,

[in] BSTR strAsciiText,

[out] long *plPage,





[in] int nMode,

[in] int nOption);

SetLicenseKey method

Sets the hardware-independent company licence key (if present).

Enables various functions and disables the demo stamps.


17.09.2021 Page 43 of 125

BSTR

[in]

bstrLicenseKe

y

Company licence key as a character string.

HRESULT SetLicenseKey( [in] BSTR bstrLicense);

ImportFormfieldData method

This method can be used to automatically and comfortably preassign all the form

fields in a document. The values to be entered must be available as a XML-coded

character string.

Note: For more details on building this XML-coded character string, see PDF form

fields XML export structure for form field data in the appendix. The appendix also

includes an explanatory Visual Basic 6 code snippet and explanations for the

nReserved parameter.

BSTR

[in]


BSTR

[in]

strXMLData Form fields to be modified as an XML character string.

Int

[in]

nReserved Write values. 0 for standard or 100 for all.

HRESULT ImportFormfieldData( [in] BSTR strPdfFilename,

[in] BSTR strXMLData,

[in] int nReserved);

ExportFormfieldData method

This method allows the values of all the form fields in a document to be read out

completely and comfortably with just one call. Returns the entered values as a

XML-coded character string.

Note: For more details on interpreting this XML-coded character string, see PDF form

fields XML export structure for form field data in the appendix. The appendix also

includes an explanatory Visual Basic 6 code snippet and explanations for the

nReserved parameter.

BSTR

[in]


BSTR

[out]

*strXMLData Returns the form fields as an XML character string.

Int

[in]

nReserved Read values. 0 for standard or 100 for all.

HRESULT ExportFormfieldData( [in] BSTR strPdfFilename,

[out] BSTR *strXMLData,

[in] int nReserved);

GetUploadURL method

Fetches the PDF upload address stored in a PDF document.

BSTR

[in]



17.09.2021 Page 44 of 125

BSTR

[out]

* strUploadUrl Returns the upload address as a character string.

HRESULT GetUploadURL( [in] BSTR strPdfFilename,

[out] BSTR *strUploadUrl);

GetSignatureInfo method

Fetches the required signature data from the specified PDF document as an XML

string.

BSTR

[in]


BSTR

[out]


int

[in]

nPos Signature position on the page.

long

[in]

plPage Page number.

HRESULT GetSignatureInfo( [in] BSTR strPdfFilename,


[in] int nPos,

[in] long *plPage);

GetSignatureInfoMemory method

Fetches the required signature data from the specified PDF document as an XML

string.



VARIANT

(VT_ARRAY)

[in]

varPdfArray Content of the PDF document, stored in a VARIANT

as VT_ARRAY.

BSTR

[out]


int

[in]

nPos Signature position on the page.

long

[in]

plPage Page number.

HRESULT GetSignatureInfoMemory(

[in] VARIANT varPdfArray,


[in] int nPos,

[in] long *plPage);

GetInlineImageCount method

Returns the number of images on the specified PDF page that are defined as

inline images.


17.09.2021 Page 45 of 125

BSTR

[in]

bstrPdfFilename PDF file name and path.

int

[in]

nPage Page number.

long

[out]

*plBICount Returns the number of images found (inline images).

HRESULT GetInlineImageCount( [in] BSTR bstrPdfFilename,

[in] int nPage,

[out] long *plBICount);

MergePDFDocuments method

Merges the content of two PDF documents together in one PDF.

The content of the second given PDF document will be appended to the content

of the first given PDF document. The output is in the specified target file (third

parameter) .

Note: The target file will be always new created (overwritten).

Note: Possibly duplicate labels (e.g. form field names) will be automatically

renamed (Appending from „_PDFMERGE_<Objectnumber>“.

Note: This method should only be applied on not signed documents.

Note: With PDF documents from version 1.5 there can be problems occur when

they will be merged.

BSTR

[in]

bstrFileNameFirst First PDF filename with path.

BSTR

[in]

bstrFileNameSecond Second PDF filename with path.

BSTR

[in]

bstrFileNameMerged New PDF filename with path (destination).

int

[in]

nOption reserved, always 0.

HRESULT MergePDFDocuments( [in] BSTR bstrFileNameFirst,

[in] BSTR bstrFileNameSecond,

[in] BSTR bstrFileNameMerged,

[in] int nOption);

AddTextbox method

Adds an arbitrary text into an existing PDF document.

The desired page and the position of the text must be defined, by giving the

corners of a rectangle (the actual text box).

Font name, font size, font color and emphasis can be chosen.

The text will not be framed and will be brought in transparent so that other texts are

not masked. The text is introduced as a string, not as an image.

Note: The method should not be used on already signed documents, otherwise the

previously given signatures will be invalidated, and to bring in another signature will

be impossible.

Note: There is an automatic text wrap when the width of the specified text box is too

small for the length of the text.


17.09.2021 Page 46 of 125

Note: There is no automatic scaling of the font size to the size of the text box. The

developer must itself ensure that the space requirement of the text does not exceed

the size of the text box. Otherwise, the non-displayable portion of the text is

truncated.

BSTR

[in]

bstrPdfFilename PDF filename with path.

BSTR

[in]

bstrText Text which should be inserted.

short

[in]

xPos1 Upper left corner of the text box in points (X

coordinate).

short

[in]

yPos1 Upper left corner of the text box in points (Y

coordinate).

short

[in]

xPos2 Lower right corner of the text box in points

(X coordinate).

short

[in]

yPos2 Lower right corner of the text box in points

(Y coordinate).

int

[in]

nPage Page of the document on which the text is to

be inserted.

BSTR

[in]

bstrFontName name of the font as wide-char string

double

[in]

dbFontSize Font size as double-value

VARIANT_BOOL

[in]

bFontBold Use text emphasis bold. Possible values:

VARIANT_TRUE or VARIANT_FALSE

VARIANT_BOOL

[in]

bFontItalic Use text emphasis italic. Possible values:

VARIANT_TRUE or VARIANT_FALSE

VARIANT_BOOL

[in]

bUnderline Use text emphasis Underline. Possible

values: VARIANT_TRUE or VARIANT_FALSE

OLE_COLOR

[in]

oleColor Color of the text be inserted as OLE_COLOR

structure (Note the order of the text color

BGR)

HRESULT AddTextbox(

[in] BSTR bstrPdfFilename,

[in] BSTR bstrText,

[in] short xPos1,

[in] short yPos1,

[in] short xPos2,

[in] short yPos2,

[in] int nPage,

[in] BSTR bstrFontName,

[in] double dbFontSize,

[in] VARIANT_BOOL bFontBold,

[in] VARIANT_BOOL bFontItalic,

[in] VARIANT_BOOL bUnderline,

[in] OLE_COLOR oleColor

);


17.09.2021 Page 47 of 125

6. stsgnlib.dll component: Preparing PDF documents for signing, inserting and reading out SGN entries

This component allows PDF documents to be prepared for (automatic) signing or a

signing operation to be performed. For this purpose, invisible meta data is inserted into

the PDF, which can then be read out again using this component (SGN tags). Up to nine

signature positions can be predefined for each page of a PDF document. Various

conditions may be defined for the signing operation such as whether the signature is

compulsory or voluntary, for example. An HTTP upload link or a target directory can also

be entered, in order to automatically send or save the document after signatures have

been attached.

SGN tags in the PDF are used to enter the designated signature fields and their

preassigned values. These are meta data blocks that can only be interpreted by this

component. For more details see signotec SGN tags in the appendix.


The component stsgnlib.dll has the following dependencies

1. Native dependencies are the DLLs MFC42.DLL and MSVCRT.DLL. The DLLs could

be installed with MFC 6.0.

2. The COM dependency is the Dll signlib.dll. Before the component stsgnlib.dll is


regsvr32 signlib.dll.

Note: All the meta data added by this component is also interpreted by the ‘SignoSign’

application.

6.1. Definition of the ISgnDoc interface

interface ISgnDoc : IDispatch



Interface IID

ISgnDoc F1CC1AAA-6C2B-4608-B751-436873885413.


Interface CLSID

ISgnDoc A1696D64-58AC-4713-B6C0-E7005504CD66.



(VB).


ISgnDoc STSGNLIBLib.SgnDoc.


get and put XMLInfoData property


17.09.2021 Page 48 of 125

Sets and fetches a freely definable XML-coded character string in which the

developer can store various supplementary data for a document.

Note: This property replaces all the other properties that were previously used

for this purpose. These former properties remain in the component for

compatibility reasons.

BSTR

[in/out]

(*)newVal XML-coded character string with

supplementary data.

HRESULT put_XMLInfoData( [in] BSTR newVal);

HRESULT put_XMLInfoData( [out] BSTR *newVal);

AddSgnPos method

Adds a complete signature field to a specific page of a PDF document. Position

of the signature field is specified in points for the rectangle, relative to the size

of the PDF (both corners).

BSTR [in] strFilename PDF file name and path.

int [in] nPage Page in the document.

int [in] nOption 1 = Field must be signed. 0 = May be signed.

int [in] xPos1 Upper left corner in points (X coordinate).

int [in] yPos1 Upper left corner in points (Y coordinate).

int [in] xPos2 Lower right corner in points (X coordinate).

int [in] yPos2 Lower right corner in points (Y coordinate).

BSTR [in] strInfo Optional text such as ‘signer’.

HRESULT AddSgnPos( [in] BSTR strFilename,

[in] int nPage,

[in] int nOption,

[in] int nXPos1,

[in] int nYPos1,

[in] int nXPos2,

[in] int nYPos2,

[in] BSTR strInfo);

GetSgnPos method

Fetches a signature field that has been added. Selected via nPos.


int [in] nPos Position from 1 (ascending).

int [out] *nPage Page in the document.

int [out] *nOption 1 = Field must be signed. 0 = May be signed.

int [out] *xPos1 Upper left corner in points (X coordinate).

int [out] *yPos1 Upper left corner in points (Y coordinate).

int [out] *xPos2 Lower right corner in points (X coordinate).

int [out] *yPos2 Lower right corner in points (Y coordinate).

BSTR [out] *strInfo Optional text.

HRESULT GetSgnPos( [in] BSTR strFilename,

[in] int nPos,

[out] int *nPage,


17.09.2021 Page 49 of 125

[out] int *nOption,

[out] int *nXPos1,

[out] int *nYPos1,

[out] int *nXPos2,

[out] int *nYPos2,

[out] BSTR *strInfo);

AddSgnPos2 method

Enter a search position to search on all pages of the PDF document. Start position of

the signature field is set in points relative to the position of the search criterion

found (character string). Subsequently, the height and width of the signature

field are entered.

A (unique) character string that is used as an identifying characteristic (search

criterion) must be specified. The specified page in the PDF document is

searched. Once the character string is found, its position is determined.

BSTR

[in]

strFilename PDF file name and path.

int [in] nOption 1 = Field must be signed. 0 = May be signed.

int [in] nSigXOffset Upper left corner in points (X coordinate) (also negative).

int [in] nSigYOffset Upper left corner in points (Y coordinate) (also negative).

int [in] nSigWidth Lower right corner in points (X coordinate).

int [in] nSigHeight Lower right corner in points (Y coordinate).

BSTR

[in]

strSearchString Character string as a search criterion.

BSTR

[in]

strInfo Optional text such as ‘signer’.

HRESULT AddSgnPos2( [in] BSTR strFilename,

[in] int nOption,

[in] int nSigXOffset,

[in] int nSigYOffset,

[in] int nSigWidth,

[in] int nSigHeight,


[in] BSTR strInfo);

GetSgnPos2 method

Fetches a signature field that has been added. Selected via nPos.


int [in] nSigPos Position from 1 (ascending).

int [out] *nPage Page in the document.

int [out] *nOption 1 = Field must be signed. 0 = May be signed.

int [out] *nSigXOffset Upper left corner in points (X coordinate).

int [out] *nSigYOffset Upper left corner in points (Y coordinate).

int [out] *nSigWidth Lower right corner in points (X coordinate).

int [out] *nSigHeight Lower right corner in points (Y coordinate).

BSTR [out] *strSearchString Character string as a search criterion.

BSTR [out] *strInfo Optional text.

HRESULT GetSgnPos2( [in] BSTR strFilename,

[in] int nSigPos,


17.09.2021 Page 50 of 125

[out] int *nPage,

[out] int *nOption,

[out] int *nSigXOffset,

[out] int *nSigYOffset,

[out] int *nSigWidth,

[out] int *nSigHeight,

[out] BSTR *strSearchString,

[out] BSTR *strInfo)*;

GetSgnCount method

Fetches the total number of signature positions added to a document. After this

call, the internal property fields are filled temporarily and, where necessary,

must be read out immediately.


long [out] *plSgnCount Total number of signature positions.

HRESULT GetSgnCount( [in] BSTR strFilename,

[out] long *plSgnCount);

GetSgnCountOnPage method

Fetches the total number of signature positions added to a particular page. After

this call, the internal property fields are filled temporarily and, where necessary,

must be read out immediately.


int [out] *plSgnCount Number of signature positions.

int[in] nPage Page in the document.

HRESULT GetSgnCountOnPage( [in] BSTR strFilename,

[out] int *plSgnCount,

[in] int nPage);

SetUploadURL method

An HTTP upload server or other directories may be optionally specified.


BSTR [in] strURL URL of the upload server.

HRESULT SetUploadURL( [in] BSTR strFilename,

[in] BSTR strURL);

GetUploadURL method

Fetches the optional HTTP upload server or other directories.


BSTR [out] *strURL URL of the upload server.

HRESULT GetUploadURL( [in] BSTR strFilename,

[out] BSTR *strURL);


17.09.2021 Page 51 of 125

SetProperties method

Transfers the property fields to a PDF document.


HRESULT SetProperties( [in] BSTR strFilename);

6.5. Properties for internal use

The following properties are intended for internal use only and are not

documented in full.

benutzerid property

Specifies a user ID.

BSTR benutzerid Text is optional.

kontoinhaber property

Specifies an account holder.

BSTR kontoinhaber Text is optional.

kontonummer property

Specifies an account number.

BSTR kontonummer Text is optional.

kundennummer property

Specifies a customer number.

BSTR kundennummer Text is optional.

formulartyp property

Specifies a form type.

BSTR formulartyp Text is optional.

prozessid property

Specifies a process ID.

BSTR prozessid Text is optional.

geschaeftsart property

Specifies a business type.

BSTR geschaeftsart Text is optional.


17.09.2021 Page 52 of 125

bankleitzahl property

Specifies a sort code.

BSTR bankleitzahl Text is optional.

email property

Specifies an e-mail address.

BSTR email Text is optional.

allowsigning property

Specifies whether a document may be signed or not.

BSTR allowsigning Text is optional.

dokumentenschluessel property

Specifies a document key.

BSTR dokumentenschluess

el

Text is optional.

indexN (N = 1-10) properties

Specifies a customer-specific text.

BSTR indexN Text is optional.

indexnameN (N = 1-10) properties

Specifies a customer-specific text.

BSTR indexnameN Text is optional.

databasename, ups, indexpart, agb, UUID properties

Specifies other customer-specific data.

BSTR databasename, ups,

indexpart, agb, UUID

Text is optional.


17.09.2021 Page 53 of 125

7. signcap.dll component: Capturing signatures from various input devices (pads, tablet PCs and scanners)

This component is responsible for controlling various hardware input devices

(generally signature pads, but also tablet PC digitisers). The component can also

be used to control TWAIN-compatible scanners and fetch image data from them.

Our aim was to offer developers of applications that use signature data an

interface that is as straightforward and standardised as possible, so that the

developers do not have to adapt to the different types of hardware available and

their specific features. It makes no difference what type of hardware is used to

capture signatures; the calls required for capturing them are basically the same

in all the components (e.g., Capture() for capturing signatures).

Several different interfaces for the various hardware input devices are defined in

this component.

Efforts are being made to standardise the method and property names for all the

interfaces defined here. However, as this step is insufficient for controlling the

devices, some of which vary greatly, some interfaces have more methods and

properties than others. For this reason we first list the methods and properties

that are common to all the interfaces. Then we describe the extended and

divergent methods and properties that are specific to the respective interfaces.

Some of the interfaces described here require additional drivers to be installed

that are not included in the SignoAPI. They include tablet PC help files from

Windows (IPadTabletPC).


The component signcap.dll has the following dependencies

1. The COM dependencies are the Dlls/OCXs STPadCapt.ocx, signwtab.dll and

signtiff.dll. Before the component signcap.dll is instantiated, the Dlls/OCXs

must be registered. In the command line, run the command regsvr32 for the

Dlls/OCXs.


17.09.2021 Page 54 of 125

7.1. Interface hardware assignment

The following table lists the various hardware types and the interfaces that need

to be operated with the devices:

Hardware type Interface

all signotec Pads IPadSignotecSignatureDevice

different Windows Tablet PCs IPadTabletPC

7.2. Interface CLSID assignment

The CLSIDs for the different interfaces:

Interface CLSID

IPadSignotecSignatureDevice 985C2A49-74D7-4863-8ED9-9F19560E59F3

IPadTabletPC BED9F26B-2E41-448B-A494-9F795C85BCD8


17.09.2021 Page 55 of 125

7.3. Inteface dependencies

The dependencies for the different interfaces:

Interface Abhängigkeiten

IPadSignotecSignatureDevice STPadCapt.ocx

IPadTabletPC signtiff.dll

Note: The dependencies are COM components. Before use they must be registred.


The following interfaces must be made when instantiating under Visual Basic

(VB).


IPadSignotecSignatureDevice SignCapLib.SignotecSignatureDevice

IPadTabletPC SignCapLib.PadTabletPC

The following interfaces are instantiating when using .NET.


IPadSignotecSignatureDevice SignCapLib.ISignotecSignatureDevice

IPadTabletPC SignCapLib.IPadTabletPC


17.09.2021 Page 56 of 125

7.5. Information on using the interfaces

The following applies to all the interfaces:

When Capture() is called a modal dialog box opens for capturing a signature.

The pad hardware is controlled in the background and a signature is expected

from the signer. If the pad has an LCD, the LCD displays a standard dialog box

(a signature line and a signing prompt). The modal dialog box displays the same

on the monitor.

Once this dialog box has been closed properly (i.e., OK was clicked and the

signature is long enough) the SignData data structure is filled and is available

for further use.

This data structure holds all the information on the signature that has been

provided (depending on the hardware, this may include signature coordinates,

time values and pressure values). This information is also referred to as the

signature’s biometric data. It can be used to verify a signature or to sign PDF

documents directly using the ‘signpdf2.dll’ or ‘signpdf3.dll’ component.

In addition, once Capture() has finished successfully, a TIFF image (as the

Image property) is also always available. This can be further processed directly

using the ‘signdoc.dll’ component, for example.

7.6. Special functions for hardware devices with an LCD

Since version 7.0.0.271 of the component signcap.dll has an interactive dialog

integrated. This dialog allows the signer to confirm the signature on the LCD of the

pad after signing, so no confirmation on the modal dialog window is needed anymore.

It is also possible to display and confirm a text (i.e. legal notices) on the LCD before

the signature is captured.

7.7. TWAIN-compatible scanners

Although TWAIN-compatible scanners may be used to capture paper-based

signatures, they are not normally utilised as they are unable to capture any

biometric information (no SignData); they only capture pure image data (as a

TIFF image).

The TWAIN interface does not therefore share any of the methods that are

common to the other interfaces defined in this component and is described

separately.

7.8. Shared methods and properties

get SignData property

Fetches all the current signature data (SignData) from the internal memory

(signature with supplementary biometric data). Only available once Capture() has

been called successfully.

VARIANT

(VT_ARRAY)

[out]

*pSignData [in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of Typ VT_ARRAY that

holds the SignData structure’s data.

HRESULT SignData( [out] VARIANT *pVal);


17.09.2021 Page 57 of 125

get Image property

See the separat description of property Image for interface

IPadSignotecSignatureDevice.

Fetches the current signature saved as a TIFF image (with no supplementary

biometric data) from the internal memory. Only available once Capture() has


Calling FreeHandle(), or SaveSignature() and SaveSignatureEx()with the

parameter bDeleteImage = true deletes the TIFF image from the internal

memory. This also invalidates any previously fetched global handle to the image,

as the handle is also released.

Note: Once (get_)Image() has been called successfully and the image data has

been used, the user MUST call the FreeHandle() method to release the globally

allocated memory. The developer should NOT use GlobalFree() to release the

global handle.

VARIANT

(VT_I4)

[out]

*phTIFFImage [in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of Typ VT_I4 (Long-Wert)

that stores a global handle (HGLOBAL) to the TIFF

image (signature).

HRESULT Image( [out] VARIANT *pVal);

get PadData property

The use of this method is no longer recommended.

Please use the newer SignData signature format instead. This method is only

included and documented for compatibility reasons (i.e., with older programs).

Fetches the signature data in raw format (PadData) and returns this as a

character string (zero-terminated). The raw format contains the signature

coordinates and the time values for them, amongst other things.

Only available once Capture() has been called successfully.

Note: This property doesn’t deliver the raw formatted data in the interface

IPadSignotecSignatureDevice. It delivers the SignDate as a BASE64 encoded String.

VARIANT

(VT_BSTR)

[out]

*pstrPadData [in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of Typ VT_BSTR that

stores a zero-terminated Wide-Char-Zeichenkette

(BSTR) with the PadData data.

HRESULT PadData( [out] VARIANT *pVal);

Capture method

Starts a sequence for capturing the signature data from the respective

hardware. When called successfully, the SignData data structure in the internal

memory is filled up and is subsequently available for further processing. This

applies to the other available data structures too (such as Image and PadData).


17.09.2021 Page 58 of 125

When this method is called the hardware is initialised (all hardware types) and a

modal dialog box appears. The user is prompted to enter a signature in the

dialog box and is requested to confirm once the signature has been captured.

When devices have an LCD, the LCD additionally displays a prompt and a signing

line (there are limits as to how much this can be modified in this component).

Since version 7.0.0.271 of this component the confirmation of the signature is

also possible via the LCD of the device (interactive signature process).

In the event of an error (e.g., no hardware connected or hardware not

configured correctly) or an abort (e.g., at the request of the user or because the

signature provided is too short), an error message dialog box provides the user

with a description of the error (on fatal errors) and/or the method returns an

error code (HRESULT). The data structures for the signature then remain empty.

Note: The stroke width of the signature added to the Image property can be

adjusted using the SetPenWidth() method. The stroke width should be set BEFORE

Capture() is called. The stroke width has no influence on the SignData’s biometric

data.

Note: Some hardware devices allow their LCD dialog boxes to be optionally

customised (see the descriptions of the interface-specific methods and

properties).

HRESULT Capture();

SaveSignature method

Saves the captured signature as a TIFF file in the specified file (equivalent of

saving the Image property).

If the ‘bDeleteImage’ parameter value is set to ‘true’, the internally saved image

of the signature is released again immediately after the file write operation has

finished (this image is the equivalent of the Image property). For this purpose

the FreeHandle() method is called internally (see this method's description for

more details).

The SetPenWidth() method can be used to configure the stroke width of the

displayed signature. The stroke width must be set BEFORE Capture() is called.

Note: This method can only be called once Capture()has been called successfully.

Note: If the method was called with ‘bDeleteImage = true’, then the method

cannot be called again. A new signature must first be captured (Aufruf

Capture()).

Note: The image is stored as a monochrome image (1-bit).

BSTR

[in]

bstrFileName Full, absolute path and file name of the TIFF file to be

generated.

bool

[in]

bDeleteImage When set to ‘true’, it calls the FreeHandle() method after

the TIFF image has been saved successfully, and deletes

the internal TIFF image (see FreeHandle()).

HRESULT SaveSignature( [in] BSTR bstrFileName,

[in] bool bDeleteImage);


17.09.2021 Page 59 of 125

SaveSignatureEx method

Saves the captured signature as an image in the specified file.

The ‘nImgType’ parameter value defines the image format for saving the

signature. The following image formats are available:

Image type Image file formats (all 1-bit)

0 TIFF – fax group 4

1 PNG

2 Windows bitmap

3 Windows bitmap (Special

case for the TabletPCs)

With the interface ISignotecCaptureDevice it is possible to leave the captured

signature as an image in the memory. This can be used to access the image

without saving it to a file.

The following imagetypes are used for this:


100 TIFF – fax group 4 as Byte Array

101 PNG as Byte Array

102 Windows bitmap as Byte Array


200 TIFF - Faxgruppe 4 as BASE64 coded String

201 PNG as BASE64 coded String

202 Windows Bitmap as BASE64 coded String

If the ‘bTimeStamp’ parameter is set to ‘true’, a (visual) timestamp is added to

the signature (underneath the signature field).

If the ‘bDeleteImage’ parameter value is set to ‘true’, the internally saved image

of the signature (the equivalent of the Image property) is released again

immediately after the file write operation has finished. For this purpose the

FreeHandle() method is called internally (see this method's description for more

details).

The SetPenWidth() method can be used to adjust the stroke width of the

displayed signature. The stroke width should be set BEFORE Capture() is called.

Note: This method can only be called once Capture() has been called

successfully.

Note: If the method was called with ‘bDeleteImage = true’, then the method

cannot be called again. A new signature must first be captured (Aufruf

Capture()).


BSTR

[in]

bstrFileName Full, absolute path and file name of the image file to be

generated.

int

[in]

nImgType Defines the image file format for saving the captured

signature (see the table above).

BOOL

[in]

bTimeStamp When set to ‘true’, the current date and time are added to

the signature (become part of the image data).


17.09.2021 Page 60 of 125

bool

[in]

bDeleteImage When set to ‘true’, it calls the FreeHandle() method after

the image has been saved successfully, and deletes the

internal output image (see FreeHandle()).

HRESULT SaveSignatureEx( [in] BSTR bstrFilename,

[in] int nImgType,

[in] BOOL bTimeStamp,

[in] BOOL bDeleteImage);

FreeHandle method

Releases the internally saved TIFF image of the captured signature. (This is the

equivalent of the Image() property).

Warning! When this method is called the global handle from the Image()

property becomes invalid and cannot be used again. This also applies to the

SaveSignature() and SaveSignatureEx() methods.

Note: Can only be called once Capture() has been executed successfully.

Note: Should be called before Capture() is called again.

Note: Should only be called after the TIFF image of the signature has been

copied from the global memory area (in case the image needs to be used).

HRESULT FreeHandle();

SetPenWidth method

Sets the stroke width of the signature for the Image property

making the signature either wider or narrower.

Note: Should be set BEFORE Capture() is called.

int

[in]

nPensize Number specifying the stroke width to be used.

Range of values: 1 to 20. Default value = 12.

HRESULT SetPenSize(int nPensize);

SetWindowText method

Sets the text to be displayed in the modal dialog box’s title bar when Capture()

is called (can show the name of the signer, for example).

Default text is ‘signotec’.

BSTR

[in]

bstrText Text for the capture dialog box’s title bar as a zero-

terminated wide-char character string (BSTR).

HRESULT SetWindowText([in] BSTR bstrText);




BSTR

[in]

bstrLicenseKe

y



17.09.2021 Page 61 of 125

HRESULT SetLicenseKey([in] BSTR bstrLicense);

SetImageParameter method

Sets the parameters of the signature image adjustment.

short [in] nResolution Resolution in pixels / inch (ppi)

long [in] nWidth Maximum width of the generated image in

pixels

long [in] nHeight Maximum height of the generated image in

pixels

short [in] nPenWidth Line width in pixels

unsigned

long [in]

penColor Color of the signature

long [in] nOptions Bitmask, which can include one or more

hexadecimal values

HRESULT SetImageParameter([in] short nResolution, [in] long nWidth, [in] long

nHeight, [in] short nPenWidth, [in] unsigned long penColor, [in] long nOptions);

Note: A description of parameters see the description of the method

SignatureSaveAsStreamEx in the signature signotec PAD API documentation. The

method is implemented in only IPadSignotecSignatureDevice interface.

7.9. IPadSignotecSignatureDevice interface – methods and properties

Important note: the interface includes the basic functionality for the signature

capture with signotec signature pads. The full functionality can be achieved only with

free signotec signoPAD API. The signotec signoPAD API can be downloaded from

http://www.signotec.com.

PadID property

Returns an ID for the connected pad. The ID is only unique within its model

range.

Returns the ID as a character string.

Note: Only available once Capture() has been called successfully.

BSTR*

[out]

pPadID After being called, it holds a wide-char character

string containing the PadID.

HRESULT PadID( [out] BSTR* pPadID);

SignDataBase64 property

Fetches all the current signature data base64-encoded (SignData) from the internal

memory (signature with supplementary biometric data). Only available once

Capture() has been called successfully.

BSTR*

[out]

*pSignData [in] Pointer to an empty BSTR

http://www.signotec.com/


17.09.2021 Page 62 of 125

[out] Pointer to a BSTR that holds the SignData

base64-encoded structure’s data.

HRESULT SignDataBase64( [out] BSTR* pSigData);

get Image property

Fetches the current signature saved as a TIFF image (with no supplementary

biometric data) from the internal memory. Only available once Capture() has


The method SaveSignatureEx with parameter nImageType can be called to determine

the type of the return value. For the Base64 string, the parameter nImageType must

be >= 200. The Methote SaveSignatureEx must be called before the use of the

property.

VARIANT

(VT_ARR

AY |

VT_UI1

or

VT_BST)

[out]


[out] Pointer to a VARIANT of type VT_ARRAY |

VT_UI1 for safe array with the TIFF image (signature).

VT_BSTR for a bstr string

HRESULT Image( [out] VARIANT *pVal);

SelectDialog method

Sets the shown modal windows dialog when Capture() is called.

The ‘nIndex’ parameter value specifies which windows dialog will be shown to

the user when Capture() is called.

value for nIndex windows dialog

0 standard dialog

1 extended dialog

The ‘bstrConfirmationtext’ parameter value specifies, which text for confirmation

will be shown beside the checkbox (on extended dialog).

Note: In the moment there are only two dialogs available (0 or 1). The extended

dialog has a ‘Skip’ button, a checkbox and a text field, in which the text to

confirm will be shown. The user has to accept the text displayed on the LCD or

has to check the checkbox on the modal dialog (if small bandwidth mode is

enabled) to be able to complete the signing process.

Note: The ‘bstrConfirmationtext’ parameter value is only interpreted, if the

choosen dialog supports this feature.

Note: Is the parameter „bstrConfirmationtext“ empty, the extended dialog will

be displayed with a „Skip“ button, but no confimation is needed to start the

signature capturing. (Checkbox in dialog is not present, no confirmation text is

displayed on the pad or the dialog).

Note: The text does not automatically adapt to fit the textbox (no automatic

scaling). The developer must therefore ensure that the texts remain readable at all

times.


17.09.2021 Page 63 of 125

Note: The method should be used BEFORE Capture() is called. If there is no call

of SelectDialog() before Capture(), the standard dialog will be displayed.

Hinweis: The method CaptureWithoutDialog() is not working, if

SelectDialog(1) was called before.

short

[in]

nIndex Selects windows dialog (0-1)

BSTR

[in]

bstrConfirmationtext The text which have to be confirmed

(BSTR)

HRESULT SelectDialog ( [in] short nIndex,

[in] BSTR bstrConfirmationtext);

SetComPort method

Manually sets the serial interface (COM port) to be used to which the hardware

(signotec signature pad) is connected.

short

[in]

nPort Number specifying the COM port to be used. Range of

values: 1 to 256.

HRESULT SetComPort( [in] short nPort);

SetPadType method

Sets the connection type and the LCD status for the connected signotec pad via

an internal ID.

The ‘nType’ parameter value (ID) can have the following values:

for signotec Sigma 101 = HSB,

102 = FTDI

for signotec Zeta 105 = HSB,

106 = FTDI

for signotec Omega 111 = HSB,

112 = FTDI

for signotec Gamma 115 = HSB,

116 = FTDI

for signotec Delta 121 = HSB,

122 = FTDI

123 = IP

124 = Pen-Display

for signotec Alpha 131 = HSB,

132 = FTDI,

133 = IP

Note: MUST be set before Capture() is called for the first time.

short

[in]

nType Internal ID specifying the pad type (see the

table above).

HRESULT SetPadType( [in] short nType);

SetButtonPosition method


17.09.2021 Page 64 of 125

Sets the position of the interactive buttons on the LCD of the pads while capturing.

The ‘nButtonPosition’ parameter value (ID) can have the following values:

0 buttons on top

1 buttons at bottom

2 buttons on the left side

3 buttons on the right side

Note: Should be set before Capture() is called for the first time.

Int

[in]

nButtonPosition Position of the buttons (see the table above).

HRESULT SetButtonPosition( [in] int nButtonPosition);

SetOEMKey method

Sets a OEM key, which enables the developer to use the method GetOEMPadData().

The GetOEMPadData() retrieves the captured signature as raw data.


Note: The value for a valid OEM key will be given by the signotec GmbH. Please

contact the support directly if you are interested.

BSTR

[in]

bstrOEMKey Valid key given from the signotec GmbH.

String.

HRESULT SetOEMKey( [in] BSTR bstrOEMKey);

GetOEMPadData method

Retrieves the captured signature as raw data.

Note: Only useable once Capture() has been called successfully.

Hinweis: To use this method a valid OEM-key must have been set before. Use

the method SetOEMKey() for this purpose.

VARIANT

[out]

pVal After being called, it holds a wide-char

character string containing the raw data of

the captured signature. VARIANT is BSTR, of

Type VT_BSTR. The single sets of data are

seperated via a „\n“ (new line).

HRESULT GetOEMPadData( [out] VARIANT* pVal);

SetIPAddress method

Sets a IP Address, to communicate directly to a signotec IPServer.


Note: Please contact the support directly if you are interested.

BSTR

[in]

bstrIPAddress Valid IP Address : Port

Example: “IP=192.168.100.100:1002”


17.09.2021 Page 65 of 125

HRESULT SetIPAddess([in] BSTR bstrIPAddress);

SetLCDText method

Writes freely definable text lines onto a pad’s LCD. The text lines are output

using the ‘Arial’ font. Both the font size and the font style can be modified.

The required text is added by means of a text field whose upper left corner

should be specified in pixels relative to the size of the pad’s LCD. The origin of

the coordinate system is thus the upper left corner of the LCD.

Note: The texts are only displayed on the pad once the Capture() method is

called and then they are deleted from the LCD. This method should therefore be

used before Capture() is called.

Note: The height and width of the text field are determined automatically and

depend on the amount of text to be displayed and the parameters for this. Text

fields may therefore sometimes extend beyond the edge of the pad.

Note: The text does not automatically adapt to fit the text field.

Note: If the font size is less than 12, set the font size 12.

int

[in]

x The X coordinate value for the position at

which the text field will originate.

int

[in]

y The Y coordinate value for the position at

which the text field will originate.

BSTR

[in]

bstrText Text to be displayed on the LCD as a zero-

terminated wide-char character string (BSTR).

int

[in]

nTextSize Font size such as ‘12’, for example. Maximum

and minimum values depend on the font

selected. If the font size is less than 12, set

the font size 12.

bool

[in]

bBold Font style. Bold = 1. Normal = 0.

int

[in]

nIndex Not used

HRESULT SetLCDText ( [in] int x,

[in] int y,

[in] BSTR bstrText,

[in] int nTextSize,

[in] BOOL bBold,

[in] int nIndex);

SetSampleRate method

This method sets the sample rate with which the signature is captured. The default

setting is mode 1 (250 Hz). This mode provides high-quality signature data while at

the same time ensures that the data record is of moderate size. This value can easily

be set to 2 (500 Hz) for high-speed data lines. Likewise, the sampling rate that is

currently set in the device can be adopted.

long

[in]

nSampleRate sample rate with which the signature is

captured, possible values: -1: Take sample rate


17.09.2021 Page 66 of 125

from signature pad, 0: 125 Hz, 1: 250 Hz, 2:

500 Hz

HRESULT SetSampleRate ([in] long nSampleRate);

Important returncodes of the interface IPadSignotecSignatureDevice

0 = No error occurred.

-92 = CaptureWithoutDialog does not work if SelectDialog() changed the

default dialog before.

-93 = Can't find module with the the name SigPlus.ocx! Missing or

renamed?

-94 = Configured pad (in registry or SigPlus.ini) can not be activated

(SetTabletState to One failed).

-95 = SigPlus.ocx internal intergrity test failed.

-96 = SigPlus.ocx is not digitally signed.

-97 = SignTiff can not be instanciated.

-98 = User skipped signature dialog.

-99 = User canceled signature dialog (on pad or on window dialog).

-195 = CaptureWithoutDialog has been called with a non-LCD pad

configured. Not allowed.

-196 = Timeout error (timeout 2) without signature date for

CaptureWithoutDialog.

-197 = Timeout error (timeout 2) with signature date for

CaptureWithoutDialog.

7.10. Interface IPadTabletPC – methods and properties

SelectDialog method

Sets the shown windows dialog when Capture() is called.

The ‘nIndex’ parameter value specifies which windows dialog will be shown to

the user when Capture() is called.

value for nIndex windows dialog

0 standard dialog

1 extended dialog

The ‘bstrConfirmationtext’ parameter value specifies, which text for confirmation

will be shown beside the checkbox (on extended dialog).

Note: In the moment there are only two dialogs available (0 or 1). The extended

dialog has a ‘Skip’ button, a checkbox and a text field, in which the text to

confirm will be shown. The user has to check the checkbox to be able to

complete the signing process.

Note: The ‘bstrConfirmationtext’ parameter value is only interpreted, if the

choosen dialog supports this feature.

Note: The text does not automatically adapt to fit the textbox (no automatic

scaling). The developer must therefore ensure that the texts remain readable at all

times.

Note: The method should be used BEFORE Capture() is called. If there is no call

of SelectDialog() before Capture(), the standard dialog will be displayed.


17.09.2021 Page 67 of 125

short

[in]

nIndex Selects windows dialog (0-1)

BSTR

[in]

bstrConfirmationtext The text which have to be confirmed

(BSTR)

HRESULT SelectDialog ( [in] short nIndex,

[in] BSTR bstrConfirmationtext);


17.09.2021 Page 68 of 125

8. SignoUtilities.dll component: Help functions for pad searching, pad configuration and pad use

This component includes various additional functions that mainly concern the use of

signature pads. The most important of these is the search and identification feature

for the parameters of the connected signature pads (via serial interface, USB and

HSB).

Warning! This component has a dependency with the ‘objsafe.tlb’ type library.

Although this is also copied into the DLL directory during the installation, the

developer must still manually register the type library in the system by calling

Regtlib.exe <PFAD>\objsafe.tlb

on the terminal (prompt).

Note: Regtlib.exe was included in the Microsoft Visual Studio 6.0 IDE and has been

removed without a replacement in later editions (VS .NET, VS2005, VS2008,

VS2010).


The component SignoUtilities.dll has the following dependencies.

1. Native dependency is the Dll MSVBVM60.DLL. The Dll could be installed with

Microsoft Visual Basic Virtual Machine 6.0.

2. The COM dependencies are the Dlls/OCXs signutil.dll, signoHelp.dll, and

STPadCapt.ocx. Before the component SignoUtilities.dll is instantiated, the

Dlls/OCXs must be registered. In the command line, run the command regsvr32

for the Dlls/OCXs.

8.1. Definition of the PadUtil interface

interface SignoUtilities.PadUtil : IDispatch



Interface CLSID

PadUtil 7747A087-5781-47D2-A297-3CC7CF924546



(VB).


PadUtil SignoUtilities.PadUtil


Set_PadType method

The Set_PadType method is used to configure a pad in the system. Information is

stored in the registry under:


17.09.2021 Page 69 of 125

HKEY_LOCAL_MACHINE\software\signotec\signing tool\options\

BSTR PadName PadName, support is currently provided for the following

pads:

all signotec devices, tablet PC.

short PadType Support is currently provided for the following pad types:

Tablet-PC = 7

signotec Sigma HSB = 101

signotec Sigma FTDI = 102

signotec Zeta HSB = 105

signotec Zeta FTDI = 106

signotec Omega HSB = 111

signotec Omega FTDI = 112

signotec Omega RealSeries = 113

signotec Gamma HSB = 115

signotec Gamma FTDI = 116

signotec Delta HSB = 121

signotec Delta FTDI = 122

signotec Delta IP = 123

signotec Delta Pen-Display = 124

signotec Alpha HSB = 131

signotec Alpha FTDI = 132

signotec Alpha IP = 133

short PadConnection Connection type:

RS232 + RS232 WTS = 0

USB = 2

HSB = 6

short HasLCD Must be set to 1 when a pad has an LCD.

short IsSE Must be set to 0.

short Comport Optional value for specifying the COM port for RS232 pads.

long Set_PadType ( BSTR *padname,

short *PadType,

short *PadConnection,

short *HasLCD,

short *IsSe,

short *comport);

Return values:

0 = OK

-1 = The current user does not have administrator rights.

-2 = There is no valid Sigplus.ini in the Windows directory.

-3 = The current user doesn’t have the right to write into the SigPlus.ini in the

Windows directory

Get_PadType method

The Get_PadType method identifies the pad that is configured in the system.

BSTR PadName Returns the configured pad.

short padType Returns the configured pad type.

7 = Tablet-PC

101 = signotec Sigma HSB

102 = signotec Sigma FTDI


17.09.2021 Page 70 of 125

105 = signotec Zeta HSB

106 = signotec Zeta FTDI

111 = signotec Omega HSB

112 = signotec Omega FTDI

113 = signotec Omega RealSeries

115 = signotec Gamma HSB

116 = signotec Gamma FTDI

121 = signotec Delta HSB

122 = signotec Delta FTDI

123 = signotec Delta IP

124 = signotec Delta Pen-Display

131 = signotec Alpha HSB

132 = signotec Alpha FTDI

133 = signotec Alpha IP


0 = RS232 + RS232 WTS

2 = USB

6 = HSB

short HasLCD 1 = LCD present.

0 = No LCD.

short IsSE 1 = SE-generation

0 = No SE-generation pad.

short comport Optional value for specifying the COM port for RS232 pads.

void Get_PadType( BSTR *padname,

short *PadType,


short *HasLCD,

short *IsSe,

short *comport);

Set_TwainSetting method

The Set_TwainSetting method is used to store the pad type and the output

resolution for the TWAIN emulation driver.

Note: The values will be stored per user in the registry under the key

“HKEY_CURRENT_USER\Software\signotec\TwainConfig“.

long PadType TabletPC = 9

















17.09.2021 Page 71 of 125


long Resolution Resolution for the output. Range 0-2

0 = 100 dpi

1 = 200 dpi

2 = 300 dpi

void Set_TwainSetting( [in] long PadType,

[in] long Resolution);

Set_TwainSettings2 method

The Set_TwainSettings2 method is used to store different values for the TWAIN

emulation driver.



long PadType see Set_TwainSetting


0 = 100 dpi

1 = 200 dpi

2 = 300 dpi

long nRotation Clockwise rotation of the output in degree. Range: 0-360

long nFixedWidth Width in pixel, to which the output should be fix scaled.

Range: 0-20000. If the values is 0 there will be no scaling.

long nFixedHeigth Heigth in pixel, to which the output should be fix scaled.


long nPenWidth Pen width of the signature in the outout (virtual ink).

Range: 1-10.

HRESULT Set_TwainSettings2( [in] long nPadType,

[in] long nResolution,

[in] long nRotation,

[in] long nFixedWidth,

[in] long nFixedHeigth,

[in] long nPenWidth);

Set_TwainSettings3 method

The Set_TwainSettings3 method is used to store different values for the TWAIN

emulation driver.



long PadType see Set_TwainSetting


0 = 100 dpi

1 = 200 dpi

2 = 300 dpi



Range: 0-20000. If the values is 0 there will be no

scaling.


17.09.2021 Page 72 of 125



scaling.


Range: 1-10.

long nButtonPosition Set the position of the interactive buttons on the LCD of

the pads (signotec pads Delta, Gamma, Omega, Sigma

and Alpha only). Range: 0-3

0 = Top

1 = Bottpn

2 = Left

3 = Right

long nComPort ComPort on which the pad is connected (for serial/FTDI

devices). Range 1-256.

HRESULT Set_TwainSettings2( [in] long nPadType,

[in] long nResolution,

[in] long nRotation,

[in] long nFixedWidth,

[in] long nFixedHeigth,

[in] long nPenWidth,

[in] long nButtonPosition,

[in] long nComPort);

get_TwainSetting method

The get_TwainSetting method retrieves the stored values of the pad type and the

output resolution for the TWAIN emulation driver.

Note: The values are stored per user in the registry under the key


long PadType 9 = TabletPC

101 = signotec Sigma HSB

102 = signotec Sigma FTDI

105 = signotec Zeta HSB

106 = signotec Zeta FTDI

111 = signotec Omega HSB

112 = signotec Omega FTDI

113 = signotec Omega RealSeries

115 = signotec Gamma HSB

116 = signotec Gamma FTDI

121 = signotec Delta HSB

122 = signotec Delta FTDI

123 = signotec Delta IP

124 = signotec Delta Pen-Display

131 = signotec Alpha HSB

132 = signotec Alpha FTDI

133 = signotec Alpha IP


0 = 100 dpi

1 = 200 dpi

2 = 300 dpi


17.09.2021 Page 73 of 125

void get_TwainSetting( [out] long PadType,

[out] long Resolution);

Get_TwainSettings2 method

The Get_TwainSettings2 method retrieves different stored values for the TWAIN

emulation driver.



long PadType see get_TwainSetting


0 = 100 dpi

1 = 200 dpi

2 = 300 dpi







Range: 1-10.

HRESULT Get_TwainSettings2( [out] long nPadType,

[out] long nResolution,

[out] long nRotation,

[out] long nFixedWidth,

[out] long nFixedHeigth,

[out] long nPenWidth);

Get_TwainSettings3 method

The Get_TwainSettings3 method retrieves different stored values for the TWAIN

emulation driver.



long PadType see get_TwainSetting


0 = 100 dpi

1 = 200 dpi

2 = 300 dpi




scaling.



scaling.


Range: 1-10.


17.09.2021 Page 74 of 125

long nButtonPosition Set the position of the interactive buttons on the LCD of

the pads (signotec pads Delta, Gamma, Omega, Sigma

and Alpha only). Range: 0-3

0 = Top

1 = Bottpn

2 = Left

3 = Right

long nComPort ComPort on which the pad is connected (for serial/FTDI

devices). Range 1-256.

HRESULT Get_TwainSettings3( [out] long nPadType,

[out] long nResolution,

[out] long nRotation,

[out] long nFixedWidth,

[out] long nFixedHeigth,

[out] long nPenWidth,

[out] long nButtonPosition,

[out] long nComPort);

PadCheck method

The PadCheck method checks whether a pad that has been configured in the system

is present (reads whether registry keys have been set).

BSTR padname PadName, support is currently provided for the following

pads:

All signotec pads; Tablet-PC;

short PadType Support is currently provided for the following pad types:

Tablet-PC = 7


















RS232 + RS232 WTS = 0

USB = 2

HSB = 6

short HasLCD Must be set to 0.

short IsSe Must be set to 0.

short comport Optional value for specifying the COM port for RS232 pads.

long PadCheck( BSTR *padname,


17.09.2021 Page 75 of 125

short *PadType,


short *HasLCD,

short *IsSe,

short *comport);

Return parameters:

0 = The configured pad exists.

1 = The configured pad does not exist.

2 = A pad was found. However, the pad that was found does not match the

configuration.

3 = The pad type cannot be automatically identified. A pad that cannot be identified is

connected to the system.

4 = Pad type is not supported.

The following pads can be automatically identified at present:

signotec devices: Delta, Gamma, Omega, Sigma and Alpha.

PadSearch method

The PadSearch method searches for a signature pad in the system (i.e. the

interfaces of the calling computer).

short comport COM ports that are to be checked for a pad.

0 = All available COM ports up to port 15.

> 0 Specifies the port to be checked.

short lowbaudrate 0 = 115200, 38400 and 19200.

1 = 115200

short SetPad 0 = Returns only the pad as a string.

1 = Enters the pad in the system.

short ScanConnection 0 = COM, USB + HSB

1 = COM

2 = USB + HSB

short AllPadtyps 1 = All pad types.

CString PadSearch( short comport,

short lowbaudrate,

short SetPad,

short ScanConnection,

short AllPadtyps);

Note: The return value (string) holds the information for the identified signature pad

that is required for entering with the Set_PadType method.

Example: ‘1x5;5;6;1;0;0’.

Structure: PadName, PadType, PadConnection, HasLCD, IsSe, Comport.

The following pads can be automatically identified at present:

signotec devices: Delta, Gamma, Omega, Sigma and Alpha.

Note: PadSearch returns ‘unknown’ when it finds a pad that cannot be identified.


17.09.2021 Page 76 of 125

GetFontSmoothing method

The GetFontSmoothing method checks whether any type of internal font smoothing is

applied by the calling system before texts are displayed.

BOOL GetFontSmoothing();

Return values:

0 = No type of font smoothing enabled.

1 = At least one type of font smoothing is enabled.

DisableFontSmoothing method

The DisableFontSmoothing method disables all types of internal font smoothing on

the calling system.

Note: We strongly recommend that developers disable all internal font

smoothing before outputting texts onto an LCD. It should be enabled again

afterwards.

void DisableFontSmoothing();

GetFontSmoothing method

The EnableFontSmoothing method enables internal font smoothing on the calling

system again.

void EnableFontSmoothing()


17.09.2021 Page 77 of 125

9. signview.dll component: Displaying captured signature data

This component serves to visualise the captured signatures and accompanying

signature data.

The component is a control element, which is based on the ATL (Active Template

Library) and should be integrated as a visual control. It manages without any MFC

(Microsoft Foundation Class ) functions.

A signature is displayed on the control element immediately after its signature

data has been loaded into the component’s memory.


The component signview.dll has the following dependencies.

1. The COM dependency is the Dll signtiff.dll. Before the component signview.dll is


regsvr32 signtiff.dll.

9.1. Definition of the ISignDraw interface

interface ISignDraw : IDispatch



Interface IID

ISignDraw A20DFCCF-1F54-4132-BA09-D1D68380FC4F


Interface CLSID

ISignDraw D6E501F4-E6F7-4B07-90CA-E18775D86E01



(VB).


ISignDraw SignViewLibCtl.SignDraw


put SignData property

For setting the signature to be displayed in SignData format.

Loads the signature into the component’s internal memory.

The signature is subsequently displayed on the visual element of the component.

Note: Can only ever load one signature.

Note: The SignData should not RSA encrypted (from the component SignPDF3.dll,

see separate documentation).


17.09.2021 Page 78 of 125

VARIANT

(VT_ARRAY)

[in]

newVal VARIANT with a Subtyp VT_ARRAY.

The array holds the SignData data

structure.

HRESULT SignData( [in] VARIANT newVal);

put PadData property

The use of this method is no longer recommended.

Please use the newer SignData signature format instead. This method is only

included and documented for compatibility reasons (i.e., with older programs).

For setting the signature to be displayed in PadData format.

Loads the signature into the component’s internal memory.

The signature is subsequently displayed on the visual element of the component.

BSTR

[in]

newVal Zero-terminated wide-char character string (BSTR) that stores

the PadData data.

HRESULT PadData( [in] BSTR newVal);

put PenWidth property

Adjusts the signature stroke width for the entire component.

short

[in]

newVal Number specifying the stroke width to be used.

Range of values: 1 to 100. Default value = 4.

HRESULT PenWidth( [in] short newVal);

SetDrawingMode method

Sets the component’s display mode.

Available modes:

Mode Image file formats (all 1-bit)

0 Display signature without taking into account the time values in the

signature data (instant rendering).

1 Display signature taking into account the time values in the

signature data (rendering at ‘real-time speed’, i.e., the speed at

which the signer entered their signature).

2 Display signature in debug mode without taking into account the

time values in the signature data (shows the pressure flow and fill

rate of the pen in simplified form).

Note: The default value is 0 (no real-time rendering).

Note: Must be set before the SignData (or PadData) is set.

long

[in]

lModeVal Sets the display mode (see the table above).

HRESULT SetDrawingMode( [in] long lModeVal);


17.09.2021 Page 79 of 125

Clear method

Deletes the displayed signature and all accompanying data (SignData or

PadData) from the component’s memory. Also clears the control element’s

display.

HRESULT Clear();

ApiLicenseKey method


Enables various functions and disables the demo stamps. The signdata (or paddata)

from signotec signature pads don't need any licens. The demo stamp will not be

shown.

BSTR

[in]

bstrLicenseKe

y


HRESULT ApiLicenseKey ( [in] BSTR bstrLicense);


17.09.2021 Page 80 of 125

10. signutil.dll component: Converting TIFF documents to PDF documents and various other additional functions

The principal task of the SignUtil.dll component is to convert TIFF documents (including

multi-page documents) to PDF 1.3 documents. During this process the TIFF images are

embedded in the PDF as PDF-compliant images. This takes place in the IPdfConv

interface. The other interfaces defined in this component perform various help tasks

(e.g., Blowfish encoding, converting PadData into SignData, etc.).

10.1. Definition of the IPdfConv interface

interface IPdfConv: IDispatch

10.2. Interface ID allocation


Interface IID

IPdfConv EEE1D425-8E8F-48CD-8198-00320E0B7637


Interface CLSID

IPdfConv 3A4448D9-3C5B-4576-99D0-ADF62F5854C4



(VB).


IPdfConv SIGNUTILLib.PdfConv


TIFF2Pdf method

BSTR

[in]

bstrTiffnameIn Full, absolute path and name of the TIFF

document to be converted as a wide-char

character string.

BSTR

[in]

bstrPdfNameOut Full, absolute path and name of the PDF

document to be generated as a wide-char

character string.

HRESULT Tiff2Pdf( [in] BSTR bstrTiffNameIn,

[in] BSTR bstrPdfNameOut);





17.09.2021 Page 81 of 125

BSTR

[in]

bstrLicenseKe

y

Company licence key as a character

string.


10.5. Definition of the IDataConv interface

interface IDataConv: IDispatch



Interface IID

IDataConv 5AC83EFF-D070-46CE-87EA-3DAD6FC5C34A


Interface CLSID

IDataConv 68EDCA10-F381-4161-ACFC-B71010C7D795



(VB).


IDataConv SIGNUTILLib.DataConv


CreateSignData method

Advanced component function. Intended for internal use only.

Generates a SignData data block from a specified PadData data block.

The pad’s internal ID (nPadType) must be provided.

BSTR

[in]

bstrPadData Zero-terminated wide-char character string

(BSTR) holding the PadData data.

int

[in]

nPadType The pad’s internal ID.

VARIANT

(VT_ARRA

Y) [out]

*pvarSignData [in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of type VT_ARRAY

that holds the data of the SignData structure.

HRESULT CreateSignData( [in] BSTR bstrPadData,

[in] int nPadType,

[out] VARIANT *pvarSignData);

SaveSignature method



17.09.2021 Page 82 of 125

Saves a signature from the specified SignData data structure as an image in the

required file.

The ‘nType’ parameter value defines the image format for saving the signature.

The following image formats are available:

Image

type

Image file formats (all 1-

bit)

0 TIFF – fax group 4.

1 PNG.

2 Windows bitmap.


VARIANT

(VT_ARRAY)

[in]

varSignData VARIANT of type VT_ARRAY that holds the data of

the SignData structure.

BSTR [in] bstrFilename Full, absolute path and file name of the image file

to be generated.

int

[in]

nImageType Defines the image file format for saving the captured

signature (see the table above).

HRESULT SaveSignature( [in] VARIANT varSignData,

[in] BSTR bstrFilename,

[in] int nImageType);

10.9. Definition of the ICheckAlgo interface

interface ICheckAlgo: IDispatch



Interface IID

ICheckAlgo DDF5D978-7117-4D67-9471-5EE0FACBB04D


Interface CLSID

ICheckAlgo A049B9FA-897E-4E98-AEE5-805F551FDBCB



(VB).


ICheckAlgo SIGNUTILLib.CheckAlgo



17.09.2021 Page 83 of 125

VerifyAccount method


Checks that a specified account number is valid.

int

[in]

nAlgo Intended for internal use

only.

BSTR

[in]

strAccount Intended for internal use

only.

BSTR

[in]

strBC Intended for internal use

only.

BSTR

[in]

strWeightTable Intended for internal use

only.

int

[in]

nModulo Intended for internal use

only.

HRESULT VerifyAccount( [in] int nAlgo,

[in] BSTR strAccount,

[in] BSTR strBC,

[in] BSTR strWeightTable,

[in] int nModulo);

10.13. Definition of the IBlowFish interface

interface IBlowFish: IDispatch



Interface IID

IBlowFish 8619F5C1-B226-4AA9-BED7-C2594DD17465


Interface CLSID

IBlowFish DA8EDBB6-8452-40F5-931C-5310F31BE069



(VB).


IBlowFish SIGNUTILLib.BlowFish


Initalize method

Initialises the Blowfish algorithm with the specified hexadecimal key (password).


17.09.2021 Page 84 of 125

BSTR

[in]

bstrKey Key (password) for this encoding session as a wide-char

character string (BSTR). Maximum key length is 56 bytes.

HRESULT Initialize( [in] BSTR bstrKey);

Encode method

Uses the Blowfish algorithm to encode the specified text.

Note: Only functions once Initialize() has been called successfully..

BSTR

[in]

bstrInput Text to be encoded (plain text) as a wide-char character

string (BSTR).

BSTR

[out]

*bstrOutput After being called, it holds the encoded text (ciphered

text) as a wide-char character string (BSTR).

HRESULT Encode( BSTR bstrInput,

BSTR *bstrOutput);

Decode method

Uses the Blowfish algorithm to decode the specified text.

Note: Only functions once Initialize() has been called successfully.

BSTR

[in]

bstrInput Encoded text (ciphered text) as a wide-char character

string (BSTR).

BSTR

[out]

*bstrOutpu

t

After being called, it holds the decoded text (plain text)

as a wide-char character string (BSTR).

HRESULT Decode( BSTR bstrInput,

BSTR *bstrOutput);

10.17. Definition of the IJavaScript interface

interface IJavaScript: IDispatch



Interface IID

IJavaScript 6EEA3303-AE64-429F-8816-0C4FCD2FD0B7


Interface CLSID

IJavaScript F70DEF9E-A690-44BD-AEB3-14520CF243A1



(VB).


17.09.2021 Page 85 of 125


IJavaScript SIGNUTILLib.JavaScript


GetJSEngineName method


Fetches the name of the JavaScript engine available in the system.

Note: One JavaScript engine should be available.

BSTR

[out]

*

bstrEngineName

After being called, it holds the name of the

JavaScript engine as a wide-char character string

(BSTR).

HRESULT GetJSEngineName( BSTR *bstrEngineName);

10.21. Definition of the Interface ISTComm

interface ISTComm: IDispatch



Interface IID

ISTComm ABD6E77A-C683-4A4E-8E02-634B11E929A6


Interface CLSID

ISTComm A75821C9-EA65-4ACF-8980-EA8B00FAA190



(VB).


ISTComm SIGNUTILLib.STComm


GetComPortList method


Gets all COM-ports (RS232 interfaces) from the system which are available at

execution time.

You can choose from which(nComPortStart) to which (nComPortStop) COM-port

number the scan should be applied.


17.09.2021 Page 86 of 125

The parameter ‘pvarComPortList‘ will be filled with a VARIANT of type string

(VT_BTSR) after the call finished. The string contains all available COM-ports

seperated by semicolons.

The return value is a HRESULT, all values smaller then Zero indicates an error.

int [in] nComPortStart COM-port number to start from. 1-256.

int [in] nComPortStop COM-port number to stop. 1-256.

VARIANT

(VT_BSTR)

[out]

*pvarComPortList [in] Pointer to an empty VARIANT.

[out] After being called, VARIANT holds a

string (VT_BSTR) with all available COM-ports.

int [in] nMode Chooses the format of the string in

pvarComPortList.

1 = “COM: x; COM: y; …“

0 = “x; y; …“

HRESULT GetComPortList ( int nComPortStart,

int nComPortStop,

VARIANT *pvarComPortList,

int nMode);


17.09.2021 Page 87 of 125

11. signdoc.dll component: Signing TIFF documents and other functions

Single-page and multi-page TIFF documents can be signed with the help of this

module. Up to nine signatures can be attached to each page of a document.

After each signing operation a security checksum is calculated internally. This

checksum makes it possible to detect whether a document has been tampered

with since it was signed.

This component is an extension of the component signtiff.dll and uses many of the

methods of signtiff.dll. It is therefore dependent on the signtiff.dll.

11.1. Definition of the IDocFun interface

interface IDocFun : IDispatch

11.2. Interface CLSID allocation


Interface CLSID

IDocFun 9369FC2F-8B57-452D-AB69-294B0C14F4F4


The following declarations must be made when instantiating under Visual Basic

(VB).


IDocFun SignDocLib.DocFun


get SignedDocument property

Fetches the signed TIFF document currently stored in the internal memory and

returns this in the parameter value as a handle to a TIFF image in fax group 4.

Only functions once SignDocument2() has been called successfully.

VARIANT

[VT_I4]

[out]


[out] After being called, VARIANT holds a global

handle to a TIFF image (signed TIFF document).

HRESULT SignedDocument( [out] VARIANT *pVal);

get MD5Checksum property

Returns the MD5 checksum calculated for the (signed) TIFF document currently

stored in the internal memory as a string (16 bytes is the equivalent of

128 bits).

VARIANT

(VT_BSTR)

*pMD5Checksum [in] Pointer to an empty VARIANT.


17.09.2021 Page 88 of 125

[out] [out] After being called, VARIANT holds the

document’s checksum.

HRESULT MD5Checksum( [out] VARIANT *pVal);

SetDocPage method

This method sets the page that is to be worked with internally for multi-page

documents (for example, to attach signatures or extract meta data and so on).

The page number is set globally and is valid for all TIFF documents until the

page is set again.

This method is not required for single-page documents. The pages are counted

from 1 and the first page is preselected by default during the instantiation.

int

[in]

nPage The page to be selected for multi-TIFF documents, beginning with

1.

HRESULT SetDocPage( [in] int nPage);

SignDocument method

This method has been replaced by the SignDocument2 method.

Please sign all documents using the new method. This method is only

included and documented for compatibility reasons (i.e., with older

programs).

Electronically attaches a previously captured signature to a specified position in

a TIFF document (with supplementary data). Up to ten signatures can be

attached to each page of the document. The TIFF tags documented above are

used for the supplementary data. Once the method has been called successfully,

the MD5 checksum is recalculated internally for the whole document and can

then be fetched.

VARIANT

(VT_I4)

[in]

hTIFFDocument Global handle (HGLOBAL) to a TIFF image

(TIFF document), stored as a long value in a

VARIANT of type VT_I4.

VARIANT

(VT_I4)

[in]

hTIFFSignature Global handle (HGLOBAL) to a TIFF image

(signature), stored as a long value in a


VARIANT

(VT_I4)

[in]

varDocInfo VARIANT of type VT_I4 holding a long value as

an ID (meta data). Optional value.

VARIANT

(VT_ARRAY)

[in]

hSignDataBlock VARIANT of type VT_ARRAY that holds the

data of the SignData structure.

VARIANT

(VT_ARRAY)

[in]

varRectSignature VARIANT of type VT_ARRAY holding a

proprietary rectangle structure for the position

of the signature.

HRESULT SignDocument( [in] VARIANT hDocument,

[in] VARIANT hSignature,

[in] VARIANT varDocInfo,

[in] VARIANT hSignDataBlock,

[in] VARIANT varArrayData);


17.09.2021 Page 89 of 125

SignDocument2 method


a TIFF document (with supplementary data).

The signature is fitted into a signature field whose corners are specified in pixels

relative to the size of the TIFF document. The origin of the coordinate system is

the upper left corner of the TIFF document.

Once the method has been called successfully the SignedDocument() method can

be used to fetch the signed document.

An MD5 checksum is also calculated internally for the signed document and is

available for further use, if required.

Note: The signature is always attached to the currently selected page of the TIFF

document (see SetDocPage()). Up to ten signatures can be attached to each page

of a document, however, only one document ID can be added to each page. The

TIFF tags documented above are used for the supplementary data (ID, SignData

and so on). The TagPosition variable is used for indexing the signatures and

their meta data.

VARIANT

(VT_I4)

[in]

hDocument Global handle (HGLOBAL) to a TIFF image (TIFF

document), stored as a long value in a VARIANT

of type VT_I4.

VARIANT

(VT_I4)

[in]

hSignature Global handle (HGLOBAL) to a TIFF image



VARIANT

(VT_I4)

[in]


an ID for the whole page (meta data). Optional

value.

VARIANT

(VT_ARRAY)

[in]

hSignDataBlock VARIANT of type VT_ARRAY that holds the data

of the SignData structure.

int

[in]

xPos1 X coordinate for the upper left corner of the

signature field in pixels.

int

[in]

yPos1 Y coordinate for the upper left corner of the


int

[in]

xPos2 X coordinate for the lower right corner of the


int

[in]

yPos2 Y coordinate for the lower right corner of the


BSTR

[in]

bstrUID User ID as a string. Optional value.

BSTR

[in]

bstrName User name as a string. Optional value.

int

[in]

nTagPosition Index of the meta data TIFF tag in which the

signature’s accompanying supplementary data

(SignData, etc.) is written. (Per page, range of

values: 0 to 9).

HRESULT SignDocument2( [in] VARIANT hDocument,




[in] int xPos1,

[in] int yPos1,


17.09.2021 Page 90 of 125

[in] int xPos2,

[in] int yPos2,

[in] BSTR bstrUID,

[in] BSTR bstrName,

[in] int nTagPosition);

CreateMD5Checksum method

Generates an internal checksum for the whole TIFF document that is passed.

This can be subsequently fetched by calling MD5Checksum().

VARIANT

(VT_I4)

[in]


document), stored as a long value in a VARIANT of type

VT_I4.

HRESULT CreateMD5Checksum( [in] VARIANT hDocument);


Determines the number of signatures already attached to the currently selected

page of a TIFF document (see SetDocPage()).

VARIANT

(VT_I4)

[in]


document), stored as a long value in a VARIANT of

type VT_I4.

long

[out]

*plVal After being called, it holds the number of

signatures already attached to this page of the TIFF

document.

HRESULT GetReferenceCount( [in] VARIANT hDocument,

[out] long *plVal);

GetSigReference method

The signature and meta data (SignData, etc.) attached to the currently selected

page of a TIFF document can be requested again via its TIFF tag index

(TagPosition). The data stored in the selected TIFF tag is written to the

parameter values. If these are not set (optional values), they are returned as

empty character strings or are returned with a value of 0 (document ID).

VARIANT

(VT_I4)

[in]

hDocument Global handle (HGLOBAL) to a TIFF image



VARIANT

(VT_ARRAY)

[out]

*phSignDataBlock [in] Pointer to an empty VARIANT.



BSTR

[out]

*bstrUID User ID as a string. Optional value.

BSTR

[out]

*bstrName User name as a string. Optional value.

VARIANT

(VT_I4)

[out]

*varDocInfo [in] Pointer to an empty VARIANT.

[out] Document ID as a long value, stored in

a VARIANT of type VT_I4. Optional value.

int

[in]

nTagPosition Index of the meta data TIFF tag that holds

the signature’s accompanying supplementary


17.09.2021 Page 91 of 125

data (SignData, etc.). (Per page, range of

values: 0 to 9).

HRESULT GetSigReference( [in] VARIANT hDocument,

[out] VARIANT *phSignDataBlock,

[out] BSTR* bstrUID,

[out] BSTR* bstrName,

[out] VARIANT *varDocInfo,


GetSigRect method

The signature field coordinates of a signature attached to the currently selected

page of a TIFF document can be requested again via their TIFF tag index

(TagPosition).

The stored coordinates are returned in pixels. They are relative to the size of the

TIFF document and start at the document’s upper left corner.

The returned coordinates represent the values for the upper left corner and the

lower right corner of the signature field.

VARIANT

(VT_I4)

[in]



type VT_I4.

int

[out]

*pxPos1 X coordinate for the upper left corner of the signature

field in pixels.

int

[out]

*pyPos1 Y coordinate for the upper left corner of the signature

field in pixels.

int

[out]

*pxPos2 X coordinate for the lower right corner of the


int

[out]

*pyPos2 Y coordinate for the lower right corner of the signature

field in pixels.

int

[in]

nTagPosition Index of the meta data TIFF tag that holds the

signature field’s accompanying data.

(Per page, range of values: 0 to 9).

HRESULT GetSigRect( [in] VARIANT hDocument,

[out] int *pxPos1,

[out] int *pyPos1,

[out] int *pxPos2,

[out] int *pyPos2,

[in] int nTagPos);

GetDocInfoID method

Fetches the document ID of the currently selected page of the TIFF document, if

this was previously defined using SignDocument2().

If the function returns a negative value (HRESULT), there is no ID and the

second parameter value (pInfoID) is set to 0.

VARIANT

(VT_I4)

[in]



VT_I4.

long

[out]

*pInfoID Returns an ID that was previously defined for the

selected page.

HRESULT GetDocInfoID( [in] VARIANT hDocument,

[out] long *pInfoID);


17.09.2021 Page 92 of 125

GetDocResolution method

Determines the resolution (in DPI) of the currently selected page of the passed

TIFF document.

VARIANT

(VT_I4)

[in]



type VT_I4.

int

[out]

*pXTIFFResol After being called, it holds the horizontal resolution

of the document in DPI (X axis).

int

[out]

*pYTIFFResol After being called, it holds the vertical resolution of

the document in DPI (Y axis).

HRESULT GetDocResolution( [in] VARIANT hDocument,

[out] int *pXTIFFResol,

[out] int *pYTIFFResol);

GetDocSize method

Determines the size (in pixels) of the currently selected page of the passed TIFF

document.

VARIANT

(VT_I4)

[in]



VT_I4.

int

[out]

*pXWidth After being called, it holds the width of the document in

pixels.

int

[out]

*pYHeight After being called, it holds the height of the document

in pixels.

HRESULT GetDocSize( [in] VARIANT hDocument,

[out] int *pXWidth,

[out] int *pYHeight);

InvalidateSignatory method

Strikes through the selected signature (TagPosition) on the currently selected

page with a dagger (in its signature field).

The modified TIFF document is returned in the second parameter value (global

handle) and must be subsequently released by the developer (GlobalFree). Does

not modify the originally passed document.

Note: This method does not purely modify the appearance of the signature; the

modified document’s checksum is also different from the original. Even if only

one signature is invalidated, the whole document becomes invalid. This method

is therefore most suitable for striking through all the signatures in a document in

order to render the document invalid and also make this visually clear to the

user.

VARIANT

(VT_I4)

[in]

hDocument Global handle to a TIFF image (TIFF

document), stored as a long value in a


VARIANT

(VT_I4)

[out]

*phChangedDocument [in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of type VT_I4

that holds a global handle (HGLOBAL) to the

modified TIFF image (TIFF document) (as a

long value).


17.09.2021 Page 93 of 125

int

[in]

nTagPosition Index of the meta data TIFF tag for the

signature that is to be modified.


HRESULT InvalidateSignatory( [in] VARIANT hDocument,

[out] VARIANT *phChangedDocument,

[in] int nTagPos);

InvalidateDocument method

Marks the complete passed TIFF document as invalid. Strikes through each page

of the document with a dagger and also adds informational text to each page.




VARIANT

(VT_I4)

[in]




VARIANT

(VT_I4)

[out]

*phInvalidDocumen

t

[in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of type VT_I4 that

holds a global handle (HGLOBAL) to the


long value).

BSTR

[in]

bstrInvalidText Text indicating the document’s invalidity, which

is to be added to each page.

HRESULT InvalidateDocument( [in] VARIANT hDocument,

[out] VARIANT *phInvalidDocument,

[in] BSTR bstrInvalidText);

DrawText method

Sets the passed, freely selectable text at the specified position in a document.

The text is fitted into a text field, whose corners are specified in pixels relative

to the size of the TIFF document. The origin of the coordinate system is the

upper left corner of the TIFF document.




Note: The font to be used must be set using the SetTextFont() method before

DrawText is called.

This method should not be applied to TIFF documents that have already been

signed, as this will render them invalid.

VARIANT

(VT_I4)

[in]




VARIANT

(VT_I4)

[out]





17.09.2021 Page 94 of 125


long value).

int

[in]


text field in pixels.

int

[in]



int

[in]



int

[in]



BSTR

[in]

bstrText Text to be set at the specified position as a

character string.

long

[in]

lFlags Defines the text’s orientation.

0 = Horizontal text. 1 = Vertical text.

HRESULT DrawText( [in] VARIANT hDocument,


[in] int xPos1,

[in] int yPos1,

[in] int xPos2,

[in] int yPos2,

[in] BSTR bstrText,

[in] long lFlags);

SetTextFont method

Sets the required font and the formatting options for the text to be inserted

using the DrawText() method.

Note: Must be called before DrawText() is called.

BSTR

[in]

bstrFontName Full name of the font required (must be available on the

operating computer) such as ‘Courier’.

int

[in]

nFontSize Font size for the specified font such as ‘12’, for example.

Maximum and minimum values depend on the font

selected.

int

[in]

nWeight Stroke width of the text. Values range between 1 and

999. For instance, NORMAL = ‘400’, BOLD = ‘700’ and

THIN = ‘100’.

int

[in]

nItalic Specifies whether the text should be italicised (Italian

style). Values: 1 = enabled, 0 = disabled.

int

[in]

nUnderline Specifies whether the text should be underlined. Values:

1 = enabled, 0 = disabled.

HRESULT SetTextFont( [in] BSTR bstrFontName,

[in] int nFontSize,

[in] int nWeight,

[in] int nItalic,

[in] int nUnderline);

GetPrinterSpoolerDocCount method

Returns the current number of print jobs in the selected printer’s queue

(spooler).


17.09.2021 Page 95 of 125

BSTR

[in]

bstrPrinterName Name of the installed printer whose spooler is to be

queried.

int

[out]

*nJobCount After being called, it holds the number of jobs in the

spooler.

int

[out]

*nStatus After being called, it holds the query status. 0 = OK.

Any other value indicates an error.

HRESULT SetTextFont( [in] BSTR bstrPrinterName,

[out] int *nJobCount,

[out] int *nStatus);

ApiLicenseKey method



BSTR

[in]

bstrLicenseKe

y

Company licence key as a character

string.

HRESULT ApiLicenseKey ( [in] BSTR bstrLicense);

DeleteDocumentPage method

Deletes the specified page from a multi-page TIFF document.




Note: Pages are counted from 1.



VARIANT

(VT_I4)

[in]




VARIANT

(VT_I4)

[out]





long value).

int

[in]

nPage Specifies the page to be deleted from the

document. Value must be at least 1.

HRESULT DeleteDocumentPage( [in] VARIANT hDocument,


[in] int nPage);

ChangeDocumentResolution method

Changes the physical resolution of a TIFF document and the DPI information in

the TIFF tags. The values for the horizontal and vertical resolution are normally

the same.





17.09.2021 Page 96 of 125

Note: This method can only reduce the existing resolution.



VARIANT

(VT_I4)

[in]




VARIANT

(VT_I4)

[out]





long value).

int

[in]

nNewXResolution Required horizontal resolution in DPI (X

direction) e.g., 200.

int

[in]

nNewYResolution Required vertical resolution in DPI (Y


HRESULT ChangeDocumentResolution( [in] VARIANT hDocument,


[in] int nXResolution,

[in] int nYResolution);

VerifyTIFFDocument method

Checks the specified TIFF document stored in a file to make sure it is intact by

comparing the checksum (CS) stored in the document with the current (recently

generated) checksum for the document.

Returns an appropriate status code indicating the result of the check as a

parameter value.

VARIANT

(VT_I4)

[in]



type VT_I4.

long

[out]

*plStatus After being called, it holds a status code indicating

the result of the check.

0 = OK, checksums are identical.

1 = Invalid, checksums are different.

2 = No CS found in the document.

3 = Not a TIFF document.

HRESULT VerifyTIFFDocument( [int] VARIANT hDocument,

[in] long *plStatus);


17.09.2021 Page 97 of 125

12. signtiff.dll component: Direct TIFF image functions

A variety of actions and modifications can be applied directly to TIFF images

(normally TIFF documents) with the help of this component.

All the TIFF document functions from the ‘signdoc.dll’ component and other

components are based on and use this component. When a required function is

missing from the document functions of these other components, the user can

supplement this missing function with the aid of the TIFF image functions in this

component.

This component depends on the libtif35.dll.

12.1. Definition of the ITIFFLib interface

interface ITIFFLib : IDispatch

12.2. Interface CLSID allocation


Interface CLSID

ITIFFLib 308293D8-52B0-49B3-9191-0DE86E87E71F


The following declarations must be made when instantiating under Visual Basic

(VB).


ITIFFLib SIGNTIFFLib.TIFFLib


BmpToTIFF method

Converts a (locally generated) filled Windows bitmap (HBITMAP) to a TIFF image

in fax group 4. The user may also specify the resolution they require (in DPI).


VARIANT

(VT_I4)

[in]

varBmp Bitmap handle (HBITMAP) to a BMP image (TIFF


VT_I4.

VARIANT

(VT_I4)

[out]

*pvarTIFF [in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of type VT_I4 that holds a

global handle (HGLOBAL) to the generated TIFF image

(TIFF document) (as a long value).

int

[in]

nXResol Required value for the horizontal resolution of the TIFF

image to be generated (in DPI).

int

[in]

nYResol Required value for the vertical resolution of the TIFF

image to be generated (in DPI).


17.09.2021 Page 98 of 125

HRESULT BmpToTIFF( [in] VARIANT varBmp,

[out] VARIANT *pvarTIFF,

[in] int nXResol,

[in] int nYResol);

TIFFToDib method

Converts a TIFF image in fax group 4 to a Windows bitmap in DIB format

(device-independent bitmap).

Note: The second parameter value is actually an HGLOBAL and the data must be

extracted as described in 4.8.1

VARIANT

(VT_I4)

[in]

varTIFF Global handle (HGLOBAL) to a TIFF image, stored as a long

value in a VARIANT of type VT_I4.

VARIANT

(VT_I4)

[out]

*pvarDi

b



global handle (HGLOBAL) to the generated BMP image (DIB

format) (as a long value).

HRESULT TIFFToDib( [in] VARIANT varTIFF,

[out] VARIANT *pvarDib);

TIFFToPng method

Converts a TIFF image in fax group 4 to an image in PNG format (Portable

Network Graphic).



VARIANT

(VT_I4)

[in]

varTIFF Global handle (HGLOBAL) to a TIFF image, stored as a

long value in a VARIANT of type VT_I4.

VARIANT

(VT_I4)

[out]

*pvarPn

g



global handle (HGLOBAL) to the generated PNG image (as

a long value).

HRESULT TIFFToPng( [in] VARIANT varTIFF,

[out] VARIANT *pvarPng);

DibToPng method


Converts a Windows bitmap in DIB format (BITMAPINFOHEADER+DIB data block)

to a TIFF image in fax group 4.

A list of rectangles indicating which image sections need to be converted must

be passed in a third parameter value (the format of this list is not documented

here). Only converts the image sections that are specified. At least one

rectangle must be passed.


17.09.2021 Page 99 of 125



VARIANT

(VT_I4)

[in]

varDib Global handle (HGLOBAL) to a BMP image

(BITMAPINFOHEADER+DIB data), stored as a long

value in a VARIANT of type VT_I4.

VARIANT

(VT_I4)

[out]

*varPng [in] Pointer to an empty VARIANT.


byte structure (HGLOBAL) to the generated PNG image

(as a long value).

VARIANT

(VT_I4)

[in]

varClipRect

s

Global handle (HGLOBAL) to a proprietary list of

rectangles (image sections) that are to be converted

to PNG format. Stored as a long value in a VARIANT of

type VT_I4.

HRESULT DibToPng( [in] VARIANT varDib,

[out] VARIANT *pvarPng,

[in] VARIANT varClipRects);

GetDocumentCompression method


Returns the type of compression used in the specified TIFF document as an

integer value (defined in the libtiff).

VARIANT

(VT_I4)

[in]

varDocument Global handle (HGLOBAL) to a TIFF image, stored

as a long value in a VARIANT of type VT_I4.

int

[in]

*pXTiffCompress

ion

After being called, it holds an integer value

specifying the compression rate.

HRESULT GetDocumentCompression( [in] VARIANT varDocument,

[in] int *pXTiffCompression);

TiffToTiff method


Converts a TIFF image to a TIFF image with the specified compression type.

VARIANT

(VT_I4)

[in]

varTiffIn Global handle (HGLOBAL) to a TIFF image, stored as

a long value in a VARIANT of type VT_I4.

VARIANT

(VT_I4)

[out]

*pvarTiffOut [in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of type VT_I4 that holds

a global handle (HGLOBAL) to the generated TIFF

image (TIFF document) (as a long value).

int

[in]

nCompression Compression type required for the new TIFF image

(values defined in the libtiff).

HRESULT TiffToTiff( [in] VARIANT varTiffIn,

[out] VARIANT *pvarTiffOut,

[in] int nCompression);


17.09.2021 Page 100 of 125


Determines the number of signatures already attached to the currently selected

page of a TIFF document (see SetPage()).

VARIANT

(VT_I4)

[in]



type VT_I4.

long

[out]

*plVal After being called, it holds the number of


document.

HRESULT GetReferenceCount( [in] VARIANT hDocument,

[out] long *plVal);

GetSigReference method

The signature and meta data (SignData, etc.) attached to the currently selected

page of a TIFF document can be requested again via its TIFF tag index

(TagPosition). The data stored in the selected TIFF tag is written to the

parameter values. If these are not set (optional values), they are returned as

empty character strings or are returned with a value of 0 (document ID).

VARIANT

(VT_I4)

[in]




VARIANT

(VT_ARRAY)

[out]

*phSignDataBlock [in] Pointer to an empty VARIANT.



BSTR

[out]

*bstrUID User ID as a string. Optional value.

BSTR

[out]

*bstrName User name as a string. Optional value.

VARIANT

(VT_I4)

[out]

*varDocInfo [in] Pointer to an empty VARIANT.

[out] Document ID as a long value, stored in

a VARIANT of type VT_I4. Optional value.

int

[in]

nTagPosition Index of the meta data TIFF tag that holds

the signature’s accompanying supplementary

data (SignData, etc.). (Per page, range of

values: 0 to 9).

HRESULT GetSigReference( [in] VARIANT hDocument,

[out] VARIANT *phSignDataBlock,

[out] BSTR *bstrUID,

[out] BSTR *bstrName,

[out] VARIANT *varDocInfo,


GetSigRect method

The signature field coordinates of a signature attached to the currently selected

page of a TIFF document can be requested again via their TIFF tag index

(TagPosition).

The stored coordinates are returned in pixels. They are relative to the size of the

TIFF document and start at the document’s upper left corner.


17.09.2021 Page 101 of 125

The returned coordinates represent the values for the upper left corner and the

lower right corner of the signature field.

VARIANT

(VT_I4)

[in]



type VT_I4.

int

[out]

*pxPos1 X coordinate for the upper left corner of the signature

field in pixels.

int

[out]

*pyPos1 Y coordinate for the upper left corner of the signature

field in pixels.

int

[out]

*pxPos2 X coordinate for the lower right corner of the


int

[out]

*pyPos2 Y coordinate for the lower right corner of the signature

field in pixels.

int

[in]

nTagPosition Index of the meta data TIFF tag that holds the

signature field’s accompanying data.


HRESULT GetSigRect( [in] VARIANT hDocument,

[out] int *pxPos1,

[out] int *pyPos1,

[out] int *pxPos2,

[out] int *pyPos2,

[in] int nTagPos);

SetPage method

This method sets the page that is to be worked with internally for multi-page

documents (for example, to attach signatures or extract meta data and so on).

The page number is set globally and is valid for all TIFF documents until the

page is set again.

This method is not required for single-page documents. The pages are counted

from 1 and the first page is preselected by default during the instantiation.

int

[in]

nPage The page to be selected for multi-TIFF documents, beginning with

1.

HRESULT SetPage( [in] int nPage);

SignDocument method

This method has been replaced by the SignDocument2 method.

Please sign all documents using the new method. This method is only

included and documented for compatibility reasons (i.e., with older

programs).



The modified TIFF document is returned in the last parameter value (global




document (see SetPage()).


17.09.2021 Page 102 of 125


Note: The TIFF tags documented above are used for the supplementary data.

VARIANT

(VT_I4)

[in]

hTIFFDocument Global handle (HGLOBAL) to a TIFF image



VARIANT

(VT_I4)

[in]

hTIFFSignature Global handle (HGLOBAL) to a TIFF image



VARIANT

(VT_I4)

[in]


an ID (meta data). Optional value.

VARIANT

(VT_ARRAY)

[in]



VARIANT

(VT_ARRAY)

[in]

varRectSignature VARIANT of type VT_ARRAY holding a

proprietary rectangle structure for the position

of the signature.

VARIANT

(VT_I4)

[out]

pSignedDoc [in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of type VT_I4 (long

value) that holds a global handle (HGLOBAL)

to the signed TIFF image (TIFF document).

HRESULT SignDocument( [in] VARIANT hDocument,




[in] VARIANT varArrayData,

[out] VARIANT pSignedDoc);

SignDocument2 method



The signature is fitted into a signature field whose corners are specified in pixels

relative to the size of the TIFF document. The origin of the coordinate system is

the upper left corner of the TIFF document.

The signed TIFF document is returned in the penultimate parameter value

(global handle) and must be subsequently released by the developer

(GlobalFree). Does not modify the originally passed document.


document (see SetPage()).

Note: Up to nine signatures can be attached to each page of a document,

however, only one document ID can be added to each page.

Note: The TIFF tags documented above are used for the supplementary data

(ID, SignData and so on). The TagPosition variable is used for indexing the

signatures and their meta data.

VARIANT

(VT_I4)

[in]


document), stored as a long value in a VARIANT

of type VT_I4.


17.09.2021 Page 103 of 125

VARIANT

(VT_I4)

[in]

hSignature Global handle (HGLOBAL) to a TIFF image



VARIANT

(VT_I4)

[in]


an ID for the whole page (meta data). Optional

value.

VARIANT

(VT_ARRAY)

[in]



int

[in]



int

[in]



int

[in]



int

[in]



BSTR

[in]

bstrUID User ID as a string. Optional value.

BSTR

[in]

bstrName User name as a string. Optional value.

VARIANT

(VT_I4)

[out]

pSignedDoc [in] Pointer to an empty VARIANT.

[out] Pointer to a VARIANT of type VT_I4 (long

value) that holds a global handle (HGLOBAL) to

the signed TIFF image (TIFF document).

int

[in]

nTagPosition Index of the meta data TIFF tag in which the

signature’s accompanying supplementary data

(SignData, etc.) is written. (Per page, range of

values: 0 to 9).

HRESULT SignDocument2( [in] VARIANT hDocument,




[in] int xPos1,

[in] int yPos1,

[in] int xPos2,

[in] int yPos2,

[in] BSTR bstrUID,

[in] BSTR bstrName,

[out] VARIANT pSignedDoc


GetDocInfoID method



If the function returns a negative value (HRESULT), there is no ID and the

second parameter value (pInfoID) is set to 0.

VARIANT

(VT_I4)

[in]



VT_I4.

long

[out]

*pInfoID Returns an ID that was previously defined for the

selected page.


17.09.2021 Page 104 of 125

HRESULT GetDocInfoID( [in] VARIANT hDocument,

[out] long *pInfoID);

GetDocInfo method



If the function returns a negative value (HRESULT), no ID is present.

Note: In contrast to the method GetDocInfoID this method will return the document

ID in the second handover parameter (phDocInfo) as a VARIANT of type VT_I4 (long

value). The value for the document ID is the same for both methods.

VARIANT

(VT_I4)

[in]



type VT_I4.

VARIANT

(VT_I4)

[out]

*phDocInfo After being called, it holds the number of


document. In a VARIANT of type VT_I4 (long value).

HRESULT GetDocInfo( [in] VARIANT hDocument,

[out] VARIANT *phDocInfo);

GetDocumentResolution method

Determines the resolution (in DPI) of the currently selected page of the passed

TIFF document.

VARIANT

(VT_I4)

[in]

hDoc Global handle (HGLOBAL) to a TIFF image (TIFF


VT_I4.

int

[out]

*pXResol After being called, it holds the horizontal resolution of the

document in DPI (X axis).

int

[out]

*pYResol After being called, it holds the vertical resolution of the

document in DPI (Y axis).

HRESULT GetDocumentResolution( [in] VARIANT hDoc,

[out] int *pXResol,

[out] int *pYResol);

GetDocumentSize method

Determines the size (in pixels) of the currently selected page of the passed TIFF

document.

VARIANT

(VT_I4)

[in]

hDoc Global handle (HGLOBAL) to a TIFF image (TIFF


VT_I4.

int

[out]

*pXWidth After being called, it holds the width of the document in

pixels.

int

[out]

*pYHeigh

t

After being called, it holds the height of the document in

pixels.

HRESULT GetDocumentSize( [in] VARIANT hDoc,


17.09.2021 Page 105 of 125

[out] int *pXWidth,

[out] int *pYHeight);

InvalidateSignatory method

Strikes through the selected signature (TagPosition) on the currently selected

page with a dagger (in its signature field).




Note: This method does not purely modify the appearance of the signature; the

modified document’s checksum is also different from the original. Even if only

one signature is invalidated, the whole document becomes invalid. This method

is therefore most suitable for striking through all the signatures in a document in

order to render the document invalid and also make this visually clear to the

user.

VARIANT

(VT_I4)

[in]

hDocument Global handle to a TIFF image (TIFF



VARIANT

(VT_I4)

[out]





long value).

int

[in]

nTagPosition Index of the meta data TIFF tag for the

signature that is to be modified.


HRESULT InvalidateSignatory( [in] VARIANT hDocument,


[in] int nPos);

InvalidateDocument method

Marks the complete passed TIFF document as invalid. Strikes through each page

of the document with a dagger and also adds informational text to each page.




VARIANT

(VT_I4)

[in]




VARIANT

(VT_I4)

[out]

*phInvalidDocumen

t


[out] Pointer to a VARIANT of type VT_I4 that

holds a global handle (HGLOBAL) to the


long value).

BSTR

[in]

bstrInvalidText Text indicating the document’s invalidity, which

is to be added to each page.

HRESULT InvalidateDocument( [in] VARIANT hDocument,

[out] VARIANT *phInvalidDocument,


17.09.2021 Page 106 of 125

[in] BSTR bstrInvalidText);

DrawText method

Sets the passed, freely selectable text at the specified position in a document.

The text is fitted into a text field, whose corners are specified in pixels relative

to the size of the TIFF document. The origin of the coordinate system is the

upper left corner of the TIFF document.




Note: The font to be used must be set using the SetTextFont() method before

DrawText is called.



VARIANT

(VT_I4)

[in]




VARIANT

(VT_I4)

[out]





long value).

int

[in]



int

[in]



int

[in]



int

[in]



BSTR

[in]

bstrText Text to be set at the specified position as a

character string.

long

[in]

lFlags Defines the text’s orientation.

0 = Horizontal text. 1 = Vertical text.

HRESULT DrawText( [in] VARIANT hDocument,


[in] int xPos1,

[in] int yPos1,

[in] int xPos2,

[in] int yPos2,

[in] BSTR bstrText,

[in] long lFlags);

SetTextFont method

Sets the required font and the formatting options for the text to be inserted

using the DrawText() method.

Note: Must be called before DrawText() is called.


17.09.2021 Page 107 of 125

BSTR

[in]

bstrFontName Full name of the font required (must be available on the

operating computer) such as ‘Courier’.

int

[in]

nFontSize Font size for the specified font such as ‘12’, for example.

Maximum and minimum values depend on the font

selected.

int

[in]

nWeight Stroke width of the text. Values range between 1 and

999. For instance, NORMAL = ‘400’, BOLD = ‘700’ and

THIN = ‘100’.

int

[in]

nItalic Specifies whether the text should be italicised (Italian

style). Values: 1 = enabled, 0 = disabled.

int

[in]

nUnderline Specifies whether the text should be underlined. Values:

1 = enabled, 0 = disabled.

HRESULT SetTextFont( [in] BSTR bstrFontName,

[in] int nFontSize,

[in] int nWeight,

[in] int nItalic,

[in] int nUnderline);




BSTR

[in]

bstrLicenseKey Company licence key as a character

string.


DeleteDocumentPage method

Deletes the specified page from a multi-page TIFF document.




Note: Pages are counted from 1.



VARIANT

(VT_I4)

[in]




VARIANT

(VT_I4)

[out]





long value).

int

[in]

nPage Specifies the page to be deleted from the

document. Value must be at least 1.

HRESULT DeleteDocumentPage( [in] VARIANT hDocument,


[in] int nPage);


17.09.2021 Page 108 of 125

ChangeDocumentResolution method

Changes the physical resolution of a TIFF document and the DPI information in

the TIFF tags. The values for the horizontal and vertical resolution are normally

the same.







VARIANT

(VT_I4)

[in]




VARIANT

(VT_I4)

[out]





long value).

int

[in]

nNewXResolution Required horizontal resolution in DPI (X


int

[in]

nNewYResolution Required vertical resolution in DPI (Y


HRESULT ChangeDocumentResolution( [in] VARIANT hDocument,


[in] int nXResolution,

[in] int nYResolution);

VerifyTIFFDocument method

Checks the specified TIFF document stored in a file to make sure it is intact by

comparing the checksum (CS) stored in the document with the current (recently

generated) checksum for the document.

Returns an appropriate status code indicating the result of the check as a

parameter value.

VARIANT

(VT_I4)

[in]



type VT_I4.

long

[out]

*plStatus After being called, it holds a status code indicating

the result of the check.

0 = OK, checksums are identical.

1 = Invalid, checksums are different.

2 = No CS found in the document.

3 = Not a TIFF document.

HRESULT VerifyTIFFDocument( [int] VARIANT hDocument,

[in] long *plStatus);


17.09.2021 Page 109 of 125

13. scalebmp.dll component: Reducing the size of Windows bitmaps

This component serves to resize Windows bitmap files.


The component scalebmp.dll has the following dependencies

1. Native dependencies are the DLLs MFC42.DLL and MSVCRT.DLL. The DLLs

could be installed with MFC 6.0.

13.1. Definition of the IResizeBmp interface

interface IResizeBmp : IDispatch



Interface IID

IResizeBmp D98D4EA2-6ED2-433C-B871-3DDB342B8AA8


Interface CLSID

IResizeBmp 2D5DF989-8AE1-497B-9912-3E32C4CA6B54



(VB).


IResizeBmp SCALEBMPLib.ResizeBmp


Resize method:

Scales down a Windows bitmap file by the scaling factor provided and saves the

result in the specified target file.

The ‘fFloat’ parameter value specifies the scaling factor.

Note: This method can only reduce the size of a bitmap.

BSTR

[in]

strInfilename Source file name and path.

BSTR

[in]

strOutfilenam

e

Target file name and path.

Double

[in]

fScale Scaling factor.

Range of values: 0.10 to

0.90

HRESULT Resize( [in] BSTR strInfilename,

[in] BSTR strOutfilename,


17.09.2021 Page 110 of 125

[in] float fScale);


17.09.2021 Page 111 of 125

Appendix

14. signotec SignoAPI component files

The file names of the single components for the signoAPI

Components Installation path

ldf_jb2.dll [INSTALLDIR]Dll

libtif35.dll [INSTALLDIR]Dll

scalebmp.dll [INSTALLDIR]Dll

signcap.dll [INSTALLDIR]Dll

signdoc.dll [INSTALLDIR]Dll

signlib.dll [INSTALLDIR]Dll

signoMobileCapture.dll [INSTALLDIR]Dll

signoSignatureUtils.dll [INSTALLDIR]Dll

SignoUtilities.dll [INSTALLDIR]Dll

SignPDF2.dll [INSTALLDIR]Dll

SignPDF3.dll [INSTALLDIR]Dll

signtiff.dll [INSTALLDIR]Dll

signutil.dll [INSTALLDIR]Dll

signview.dll [INSTALLDIR]Dll

STImgCtl.ocx [INSTALLDIR]Dll

STPadCapt.ocx [INSTALLDIR]Dll

STPadLib.dll [INSTALLDIR]Dll

STPdfLib18.dll [INSTALLDIR]Dll

stsgnlib.dll [INSTALLDIR]Dll

15. Important files required by the SignoAPI (dependencies)

Other files are supplied in addition to the SignoAPI components documented above. These

files are essential for ensuring that the SignoAPI’s components function properly.

Files Installation path

gdiplus.dll [INSTALLDIR]Dll

atl.dll [SystemFolder]

comdlg32.ocx [SystemFolder]

MSCOMCTL.OCX [SystemFolder]

MSCOMM32.OCX [SystemFolder]

msvbvm60.dll [SystemFolder]

SHLWAPI.DLL [SystemFolder]

winhttp.dll [SystemFolder]

16. Other files

In addition to the files mentioned above, other files are supplied that are required for

configuring the signoAPI, demo applications and documentation.


17.09.2021 Page 112 of 125

Files and Directories Installation path

SignoAPI Documentation -

English.pdf

[INSTALLDIR]signoAPI\Documentation

signoAPI SignPDF3

Documentation EN.pdf


signoAPI STImgCtl



signoMobileCapture API Win



SignoAPI Dokumentation -

Deutsch.pdf

[INSTALLDIR]signoAPI\Dokumentation

signoAPI SignPDF3

Dokumentation DE.pdf


signoAPI STImgCtl



signoMobileCapture API Win



SignPDF3.ini [CommonFilesFolder]signotec\Config

STPad.ini [CommonFilesFolder]signotec\Config

STPadStores.ini [CommonFilesFolder]signotec\Config

Access [INSTALLDIR]signoAPI\Demo Sourcecode\Access

HTML [INSTALLDIR]signoAPI\Demo Sourcecode\HTML

InfoPath [INSTALLDIR]signoAPI\Demo Sourcecode\InfoPath

Lotus Notes [INSTALLDIR]signoAPI\Demo Sourcecode\Lotus Notes

SignoAPIDigSigMemDemoC

Sharp

[INSTALLDIR]signoAPI\Demo Sourcecode\SignPDF-

Demo\CSharp\SignoAPIDigSigMemDemoCSharp\SignoAP

IDigSigMemDemoCSharp

STImgCtlDemoCSharp [INSTALLDIR]signoAPI\Demo Sourcecode\STImgCtl-

Demo\CSharp\STImgCtlDemoCSharp\STImgCtlDemoCSh

arp

signoMobileCaptureCOMDe

mo

[INSTALLDIR]signoAPI\Demo

Sourcecode\signoMobileCaptureCOMDemo

signoMobileCaptureCSharp

Demo

[INSTALLDIR]signoAPI\Demo

Sourcecode\signoMobileCaptureCSharpDemo

17. Further information

17.1. Register

Some files must be registered using the „RegSvr32.exe“ from WINSYSDIR.

Example:

x86:

%systemroot%\SysWoW64\regsvr32.exe "signcap.dll"

x64:

regsvr32.exe "SignPDF3.dll"

Often this requires ADMINISTRATOR privileges.

Note: Programs to build setups are often able to regsiter the files for you.


17.09.2021 Page 113 of 125

17.2. Dependencies

Some files have dependencies to other files from the SignoAPI.

This means you have to register one file BEFORE another or the register process will fail.

Some components are only loadable if there dependencies are registered.

Other files need external DLLs or OCX-files.

In example the signtiff.dll needs the libtif35.dll to be present in the same directory for

register.

We advise you to copy all SignoAPI files first into one directory and then start to register the

files.

17.3. Hardware dependencies

If you use just one series of signature pads you can reduce the number of the needed files

for the not needed drivers of the signature pads.

18. The signcap.ini configuration file

An optional configuration file can be provided for the ‘signcap.dll’ component so that

advanced functions can be controlled. This file must have the name ‘signcap.ini’ and

it must be located in the same directory as the component’s registered DLL.

18.1. Entries

The following additional configurations are possible at present:

‘EXTENDEDSIGLENGTH’ in the ‘Option’ section

Switches off the automatic maximum length checking that takes place after a

signature has been captured. This makes it possible to use a pad to capture very long

signatures that would otherwise be rejected as invalid. Possible values are ‘NO (long

signatures not permitted) and ‘YES’ (long signatures permitted). Default value is ‘NO’.

‘CAPTUREWITHOUTDIALOGTIMEOUT’ in the ‘Option’ section

Sets the CaptureWithoutDialog() function’s second timeout.

This second timeout specifies how long the signer can lift the pen between entering

the individual parts/characters of their signature, before the capture process

terminates automatically. Can only be configured here. Range of values: 1001 to

49999 (milliseconds). Default value is 4000.

USEOLDSTYLESIGLINES“ in the ‘Option’ section

Should be used, when the pad is connected via a low bandwidth connection with high

latency. Possible values are ‘NO and ‘YES’. Default value is ‘NO’.

„LOGGING“ in the ‘Option’ section


17.09.2021 Page 114 of 125

Causes the component to trace out a debug LOG file. The file is always written to the

%USERPROFILE% directory as „SignCap_<DATE>.log“. <DATE> will be replaced with

the actual date. Possible values are ‘NO and ‘YES’. Default value is ‘NO’.

18.2. Structure

A sample INI file (structure):

;Filename: signcap.ini

;Version: 7.00.004

;Desc: Configuration file to preset settings for some

; functions in signcap.dll. Must be placed byside the

; signcab.dll.

;Status: Optional, if INI-file is not present, standard values

; will be used.

;DefaultValues: All values are optinal and not active by default

[Option]

;sehr langsames Schreiben auf dem Pad erlauben

EXTENDEDSIGLENGTH=YES

;zweites Timeout bei CaptureWithoutDialog verändern. Standard ist 1500

CAPTUREWITHOUTDIALOGTIMEOUT=3000

;Keine Bitmaps für die Signaturlinien benutzen, nur einfache Linie.

;Gedacht für Schmalbandverbindungen

USEOLDSTYLESIGLINES=YES

;Aktiviert das Debuglogging. Ausgabe erfolgt in eine

;“SignCap_<DATUM>.log" im %USERPROFILE% Verzeichnis

LOGGING=YES


17.09.2021 Page 115 of 125

19. Table listing the resolutions of the input devices' LCDs

The following table lists the resolutions (in pixels) of the various signature pads’

LCDs:

Model Width Height

signotec Sigma LCD 320 160

signotec Zeta LCD 320 200

signotec Omega LCD 640 480

signotec Gamma LCD 800 480

signotec Delta LCD 1280 800

signotec Alpha LCD 768 1366

The following table, which is derived from the table above, lists the X and Y values

that are possible when the LCDs are controlled in the components’ respective

methods:

Model X Y

signotec Sigma LCD 0-319 0-159

signotec Zeta LCD 0-319 0-199

signotec Omega LCD 0-639 0-479

signotec Gamma LCD 0-799 0-479

signotec Delta LCD 0-1279 0-799

signotec Alpha LCD 0-767 0-1365

The origin (0,0) of all the coordinate systems for the pads’ LCDs is the upper left

corner of the LCD.


17.09.2021 Page 116 of 125

20. Code snippets

Here are several small examples (code snippets) showing how individual functions

from various components can be implemented in different programming languages.

The example code snippets are listed under the respective components.

Note: In addition to the short examples provided here, the SignoAPI also includes

complete executable sample programs for Visual Basic, C++ and JavaScript. As these

sample applications are documented elsewhere, we do not take a close look at them

here.

20.1. Methods from signview.dll:

20.1.1. Displaying a signature in Visual Basic

In the following simplified example a pad signature from the SignCap component

is rendered in real time immediately after signing has taken place.

Dim pad As SIGNCAPLib.PadBlue

set pad = New PadBlue

pad.Capture

SignDraw1.SetDrawingMode 1

SignDraw1.SignData = pad.SignData

or

SignDraw1.PadData = pad.PadData

20.2. Methods from signutil.Dll:

20.2.1. Converting a TIFF to a PDF in Visual Basic

SignUtil.TIFF2Pdf „c:\data\Dokument1.tif“, “e:\pdfdata\Dokument1.pdf”

20.3. Methods from bmpscale.dll:

20.3.1. Reducing the size of bitmaps in Visual Basic

Dim strBmpOrg As String

Dim strBmpSmall As String

Dim dblResizeFactor As Double

strBmpOrg = "c:\data\signatur.bmp"

strBmpSmall= "c:\data\ signatur_klein.bmp"

' specify image resize factor. Range: 0.10 to 0.90

dblResizeFactor = 0.40

Set scaleBMP = CreateObject( "Scalebmp.ResizeBmp" )

Call scaleBMP.resize(strBmpOrg, strBmpSmall, dblResizeFactor)

20.4. Methods from SignPDF2.dll:


17.09.2021 Page 117 of 125

20.4.1. Attaching a signature in Visual Basic

Dim pad As SIGNCAPLib.SignotecSignatureDevice

Dim pdf As SIGNPDFLib.SignPdf

'generate interface instances

set pad = New SignotecSignatureDevice

set pdf = New SignPdf

'capture signature with pad

pad.Capture

'if OK, pad.Image holds a TIFF handle

'save as a TIFF in fax group 4 (optional)

pad.SaveSignatureEx( ‘c:\UDaten\unterschrift.tif’, 0, FALSE, TRUE);

'embed signature on page 3 of PDF document

'also add name and timestamp underneath the signature

pdf. SignPdfDocument ( pad.PadID,

’c:\pdfdocs\12022004AF.pdf’,

pad.SignData,

200,

400,

300,

450,

3, “Max Mustermann”, 1);

'release interfaces

set pad = Nothing

set pdf = Nothing

20.4.2. Reading out signatures in Visual Basic

Dim pdf As SIGNPDFLib. ISignPdf

Dim lCount as long

Dim lPage as long

Dim varSignData as variant

Dim i

'Interface Instanz erzeugen

set pdf = New ISignPdf

' Gesamt Anzahl Signaturen aus PDF-Dokument abfragen

pdf.GetReferenceCount "c:\temp\test2.pdf", lCount

For i = 0 To i < lCount

pdf.GetReference "c:\temp\test2.pdf", i, varSignData, lPage

MsgBox "Signatur auf Seite: " + CStr(lPage)

Next i

set pdf = Nothing


17.09.2021 Page 118 of 125

20.5. Methods from stsgnlib.dll:

20.5.1. Inserting SGN entries in Visual Basic

Inserts 3 positions on pages 1, 2 and 6 of a PDF document.

Then reads the positions out again.

Dim sgntst As STSGNLIBLib.SgnDoc

Set sgntst = New SgnDoc

Dim lCount as long

Dim strInfo As String

sgntst.AddSgnPos "c:\dok\123.pdf", 1, 1, 380, 700, 550, 730, "Berater"

sgntst.AddSgnPos "c:\dok\123.pdf", 2, 1, 80, 400, 250, 430,

"Unterschrift2"

sgntst.AddSgnPos "c:\dok\123.pdf", 6, 1, 280, 530, 450, 550,

"Unterschrift3"

sgntst.GetSgnCount " c:\dok\123.pdf ", lCount

MsgBox "Gesamtanzahl: " + CStr(lCount)

For i = 1 To lCount

sgntst.GetSgnPos " c:\dok\123.pdf ", i, nPage, nOption, x1, y1,

x2, y2, strInfo

MsgBox "Seite :" + CStr(nPage) + " x1: " + CStr(x1) + " y1: "

+ CStr(y1) + " x2: " + CStr(x2) + " y2: " + CStr(y2) +

" Bezeichnung: " + strInfo

Next i

21. PDF form fields

The components „STImgCtl.ocx“ and „SignPDF2.dll“ can deal with PDF documents that

contain PDF form fields. „StImgCtl.ocx“ offers the possibility to enable the form field

mode and this allows the user to input data directly into PDF form fields through

masks. Details about the STImgCtl.ocx can be found in the corresponding separate

documentation.

„SignPDF2.dll“ allows the automated reading and writing of PDF form field data,

through the „ImportFormfieldData()“ and „ExportFormfieldData()“ methods.

21.1. XML export structure for form field data

When form field data is exported using the ‘ExportFormfieldData()’ method from

the ‘SignPDF2.dll’ component, an XML-coded character string is generated. This

character string can then be used to preassign or fill in the form fields with the

help of the ‘ImportFormfieldData()’ method. The following example shows how this

XML-coded character string is structured:

21.2. XML example (structure):

<?xml version="1.0" encoding="ISO-8859-1" ?>

<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">

<fields>

<field name="B1000">


17.09.2021 Page 119 of 125

<value>signoapi</value>

<flags>4</flags>

<desc>Geschäftsnummer</desc>

<type>1</type>

<page>1</page>

<readonly>0</readonly>

<visible>1</visible>

</field>

<field name="F0018">

<value>Beratung</value>

<flags>4</flags>

<subname01>Off</subname01>

<subname02>Beratung</subname02>

<subname03>produktspezifische Information</subname03>

<desc>Auswahl: Beratung/produktspezifische

Information</desc>

<type>4</type>

<page>1</page>



</field>

<field name="K0002">

<value>Ja</value>

<flags>4</flags>

<checked>Ja</checked>

<unchecked>Off</unchecked>

<desc>Ankreuzer: Allgemeine Informationen</desc>

<type>3</type>

<page>1</page>



</field>

<field name="K0001">

<value>Ja</value>

<flags>4</flags>

<checked>Ja</checked>

<unchecked>Off</unchecked>

<desc>Ankreuzer: Anlage</desc>

<type>3</type>

<page>1</page>



</field>

</fields>

</xfdf>

Besides the freely selectable entries, there are several entries that can only have

certain values.

21.3. Additional entires for form fields

Form field editable state.

n = 1 = write protected/read only

n = 0 = editable

<readonly>n</readonly>


17.09.2021 Page 120 of 125

Form field visibility state.

n = 1 = visible

n = 0 = invisible

<visible>n</visible>

Page in the PDF, on which the form field is present.

n = Number of page (1 – n)

<page>n</page>

Note: Form field flags are only imported and exported when the third parameter of

ExportFormfieldData() or ImportFormfieldData() is set to 100.

21.4. Definition of entries for the form field flags (Tag: <flags>)

These flags only are only valid for the visual parent element for the form field

Structure: <flags>n</flags>

Value for n in hex Form field flag

0x0001 Invisible

0x0002 Hidden

0x0004 Printable

0x0008 NoZoom

0x0010 NoRotate

0x0020 NoView

0x0040 ReadOnly

0x0080 Locked

0x0100 ToggleNoView

These flags can be combined. Example: <flags>6</flags> means that the form field is

Hidden (2) and Printable (4).

Note: Form field flags are only imported and exported when the third parameter of

ExportFormfieldData() or ImportFormfieldData() is set to 100.

Note: To be able to export form fields with identically names the third parameter

„option“ must be set to 101 (See above). This has no effect on import.

Note: To write-protect form fields, the additional entry <readonly> must be used (see

above).

Note: To influence the visibility of form fields, the additional entry <visible> must be

used (see above).

21.5. Definition of entries for the field types (Tag: <type>)

Defines the type of the form field.

Structure: <type>n</type>

Value for n Form field type

1 TEXT

3 CHECKBOX


17.09.2021 Page 121 of 125

4 RADIOBUTTON

21.6. Code snippet

Here is a code snippet for exporting and importing form field data.

Visual Basic EXPORT example: ----------------------

dim strXML as string

On Error Resume Next

signpdf2.ExportFormfieldData "c:\data\Muster.pdf", strXML, 0

If Err.Number Then

MsgBox Err.Description

Else

MsgBox strXML

Open "c:\data\MusterExport.xml" For Binary As #1

Put #1, , strXML

Close #1

End If

Visual Basic IMPORT example: ----------------------

dim strXML as string


Open "c:\data\MusterExport.xml" For Binary As #1

strXML = Space(LOF(1))

Get #1, , strXML

Close #1


signpdf2.ImportFormfieldData "c:\data\Muster.pdf", strXML, 0

If Err.Number Then

MsgBox Err.Description

Else

MsgBox strXML

End If


17.09.2021 Page 122 of 125

22. Used XML structures in the component SignPDF2

22.1. XML structure to set the timestamp in the signature field

For the methods SignPdfDocument, SignPdfDocumentVBS,

SignPdfDocumentHttp and SignPdfDocumentHttp2 it is possible to set the

parameter „nModeTimestamp“ to the value 100. This causes the methods to format

the apperance and the content of the timestamp in the signature field, if a XML-coded

string is given as parameter „strText”.

The string „strText“ have to be structured as follows:

<?xml version="1.0" encoding="ISO-8859-1" ?>

<SIGNATURE_INFO>

<TimeStamp>

<Text>18th Feb. 2009 - 9 hour 20 minutes</Text>

<Color>FF0000</Color>

</TimeStamp>

<CustomText>

<Text>John Doe</Text>

<Color>0000FF</Color>

</CustomText>

<Signature>

<Color>808080</Color>

<Alignment>0</Alignment>

</Signature>

</SIGNATURE_INFO>

Element <Timestamp/Text>

This element can be any free formated string. It should contain the exact time (the

timestamp) of the signature. The timestamp appears in the lower array of the

signature.

Element <Timestamp/Color>

This element influence the color of the timestamp.

The example use the RGB value „808080“. This corresponds to a shade of grey.

The RGB value has to be a hexadecimal number.

FF0000 = red,

00FF00 = green

0000FF = blue

808080 = gray

Any other colour combination is possible here.

Element <CustomText/Text> (optional)

This element can be a second free formated string, which appears in the lower array

of the signature. This can be i.e. the name of the signer.

Element <CustomText/Color>

This element influence the color of the second string. See also element

<Timestamp/Color>.


17.09.2021 Page 123 of 125

Element <Signature/Color> (optional)

This element holds the colour used for the signature line.

The example holds the RGB value ‘808080’. This corresponds to a shade of grey.

The colour is defined as a hexadecimal RGB value.

FF0000 = red

00FF00 = green

0000FF = blue

808080 = grey

Any other colour combination is possible here.

Element <Signature/Alignment> (optional)

This element holds the value of the alignment for the signature inside the signature

field, if the signature is smaller then the field.

Possible values:

0 = Right aligned

1 = Left aligned

0 = Centered


17.09.2021 Page 124 of 125

23. signotec SGN tags

The meta data for a PDF document’s signature fields is stored in the PDF document using

PDF-compliant tags.

All SGN entries are formatted as follows:

„/sgnXXXX {YYYY ZZZZ}“

‘XXXX’ stands for a defined keyword and ‘YYYY’ stands for the value that is to be

assigned to this tag, while ZZZZ represents further values, if required (each value is

separated by a space character).

Example:

/sgnsignature_1 {1 0 200 300 200 120}

(Meaning: /sgnsignature_n {Page Option x1 y1 x2 y2})

23.1. Inserting SGN tags in PostScript files

The meta data for attaching signatures can also be set early on in the pre-press file

(PostScript file) instead of in the finished PDF document. The SGN tags are subsequently

available in the correct form after the PDF file has been generated using PDF Distiller.

The following example shows how this meta data can be inserted into a PostScript file:

The section highlighted in blue must be inserted after the ‘%%BeginProlog’ tag in the

PostScript file.

%%BeginProlog

/pdfmark where <----- include from here in EPS or PS file

{pop} {userdict /pdfmark /cleartomark load put} ifelse

[/Title (signotec entry)

/Author (signotec)

/Subject (signotec-sgn)

/Keywords (/sgnsignature_1 {1 1 231 249 446 335}

/sgnsignature_2 {2 1 331 349 546 435}

/sgnbenutzerid {benutzer007}

/sgnkontoinhaber {John Doe}

/sgnkontonummer {0123456789}

/sgnkundennummer {12345}

/sgnformulartyp {99}

/sgnprozessid {4711}

/sgngeschaeftsart {1}) ----- until here

/Creator (signotec)

/Producer (signotec)

/DOCINFO pdfmark

usw.


17.09.2021 Page 125 of 125

24. signotec TIFF tags

When the ‘SignDocument2’ method from the ‘signdoc.dll’ component is used,

entries are made in the TIFF document (the TIFF file), which are based on free, non-

standard TIFF tags.

Here is a definition for the TIFF tags used:

#define SIGNOTEC_TAG_BASE 61234

// crypted and compressed signature references

#define TIFFTAG_SIGNOTEC_BIN_0 SIGNOTEC_TAG_BASE

#define TIFFTAG_SIGNOTEC_BIN_1 SIGNOTEC_TAG_BASE + 1









#define TIFFTAG_SIGNOTEC_MULTI SIGNOTEC_TAG_BASE + 16

#define TIFFTAG_SIGNOTEC_UINT32 SIGNOTEC_TAG_BASE + 17

#define TIFFTAG_SIGNOTEC_ASCII SIGNOTEC_TAG_BASE + 18