SignPDF3 – Methods and Properties | signotec Knowledge Base

If you cannot find a method here, it may be deprecated and should no longer be used. An overview of deprecated methods can be found here.

AnalyzePdfDocumentMemory method

This method can be used to obtain information about a document that is needed for a correct signature. Furthermore, the method corrects the document as needed so that it can be signed without any errors. It is recommended to call this method once for every document at the beginning and then to use this document with any changes that have been made for all other method calls.

void AnalyzePdfDocumentMemory(ref object pvarPdfArray, ref string bstrXMLResultData);

C++

HRESULT AnalyzePdfDocumentMemory(VARIANT* pvarPdfArray, BSTR bstrXMLResultData);

Parameter	In	Out	Possible Values	Description
pvarPdfArray	✔️	✔️	PDF as a byte array	Contents of the PDF When returned, contains the changed document, if any changes have been made, or else the original document
bstrXMLResultData		✔️	XML string	Information about the PDF document

Parameter

Out

Possible

Values

Description

pvarPdfArray

✔️

PDF as a byte array

Contents of the PDF

When returned, contains the changed document, if any changes have been made, or else the original document

bstrXMLResultData

✔️

XML string

Information about the PDF document

SignPdfDocumentMemory method

Electronic signing of a DigSig field in a PDF document using the signature data provided. The signature data and signature image must be transferred from a previous signature capture, and the signature data must be in signotec’s own SignData format.

The captured signature and biometrics are entered into the DigSig field, which is uniquely identified by its name. If the name of the field does not yet exist, it will be created. In this case, the position information must be set.

For a DigSig field to be signed, two certificates must be passed to the methods. The first must be a PKCS12 certificate with the private key for digitally signing the document according to the DigSig specifications. And the second must be a public X.509 certificate or a PKCS12 certificate with the public key for encrypting the signotec supplementary data (encryption of the biometrics). If a PKCS12 certificate is used, the password must be passed in the parameter "bstrCryptBioCertPassword".

void SignPdfDocumentMemory (
                            string bstrPadID,
                            ref object pvarPdfArray,
                            object varSignDataArray,
                            string bstrSigfieldTitle,
                            object varSignCertArray,
                            string bstrSignCertPassword,
                            object varCryptBioCertArray,
                            string bstrCryptBioCertPassword,
                            string bstrXMLSignatureData,
                            object varImageArray,
                            int lOptions,
                            ref int plReserved
                            );

C++

HRESULT SignPdfDocumentMemory (
                               BSTR bstrPadID,
                               VARIANT* pvarPdfArray,
                               VARIANT varSignDataArray,
                               BSTR bstrSigfieldTitle,
                               VARIANT varSignCertArray,
                               BSTR bstrSignCertPassword,
                               VARIANT varCryptBioCertArray,
                               BSTR bstrCryptBioCertPassword,
                               BSTR bstrXMLSignatureData,
                               VARIANT varImageArray,
                               long lOptions,
                               long* plReserved
                               );

Parameter	In	Out	Possible Values		Description
bstrPadInfo	✔️		string		Information about the signature device used for signature capture
pvarPdfArray	✔️	✔️	PDF as a byte array		Contents of the PDF
varSignDataArray	✔️		SignData as byte array		The biometric data block to be entered
bstrSigfieldTitle	✔️		string, Length > 1		Unique name of the DigSig field to be signed If the document does not contain a field with this name, a new field is created. If the field has already been signed, the function fails.
varSignCertArray	✔️		Certificate content as byte array		Data array of the PKCS12 certificate with the private key for digitally signing the document (for DigSig mechanism)
bstrSignCertPassword	✔️		string		Password for varSignCertArray
varCryptBioCertArray	✔️		Certificate content as byte array		Data array of a public X.509 certificate or a PKCS12 certificate with the public key for encrypting the biometric data
varCryptBioCertArray	✔️		Invalid format		The signature certificate is used.
bstrCryptBioCertPassword	✔️		string		Password for varCryptBioCertArray (optional)
bstrXMLSignatureData	✔️		XML string		Additional information to be entered
varImageArray	✔️		Image content as byte array		Signature image that is entered into the PDF document For PDF/A-1b conformity, the signature image must not contain an alpha channel.
lOptions	✔️		Combination of:		Bit mask
				0x00	Do not sign document with PDF/A compliance
				0x01	Sign document in accordance with PDF/A-1b Must not be set at the same time as 0x02.
				0x02	Sign document in accordance with PDF/A-2b Must not be set at the same time as 0x01.
				0x04	Lock all form fields Must not be set at the same time as 0x08.
				0x08	Only lock filled-in form fields Must not be set at the same time as 0x04. Checkboxes and radio buttons are always considered filled in. Form fields from any existing ‘signature field lock dictionary’ are always locked.
				0x10	Use visible reference system (recommended)
plReserved	✔️	✔️		0	Reserved

PreparePdfDocumentMemory method

Preparation for the electronic signing of a DigSig field in a PDF document using the signature data provided.

The signature data and signature image must be transferred from a previous signature capture, and the signature data must be in signotec’s own SignData format. They are encrypted either before the method is called in the pad or within the method; accordingly, the ID of the pad certificate or the certificate to be used must be specified for the varCryptBioCertArrayOrRefString parameter.

A public X.509 certificate or a PKCS12 certificate with the public key is used to encrypt the signotec additional data (biometric encryption). If a PKCS12 certificate is used, the password must be passed in the parameter "bstrCryptBioCertPassword".

In the PDF document, a placeholder for later entry of the digital signature is prepared and its position is determined. The prepared PDF document in a byte array and the position of the placeholder are returned.

After the method has been called, a hash needs to be created by means of the byte array with the prepared PDF document and signed. This results in a digital signature being created. The generated signature must then be written as a hexadecimal string in place of the placeholder in the PDF document.

void PreparePdfDocumentMemory(
                              string bstrPadID,
                              ref object pvarPdfArray,
                              object varSignDataArray,
                              string bstrSigfieldTitle,
                              object varSignCertArray,
                              object varCryptBioCertArrayOrRefString,
                              string bstrCryptBioCertPassword,
                              string bstrXMLSignatureData,
                              object varImageArray,
                              ref object pvarDocHashArray,
                              ref int plDocSignaturePosition,
                              int lOptions,
                              ref int plReserved
                              );

C++

HRESULT PreparePdfDocumentMemory(
                                 BSTR bstrPadID,
                                 VARIANT* pvarPdfArray,
                                 VARIANT varSignDataArray,
                                 BSTR bstrSigfieldTitle,
                                 VARIANT varSignCertArray,
                                 VARIANT varCryptBioCertArrayOrRefString,
                                 BSTR bstrCryptBioCertPassword,
                                 BSTR bstrXMLSignatureData,
                                 VARIANT varImageArray,
                                 VARIANT* pvarDocHashArray,
                                 long* plDocSignaturePosition,
                                 long lOptions,
                                 long* plReserved
                                 );

Parameter	In	Out	Possible Values		Description
bstrPadInfo	✔️		string		Information about the signature device used for signature capture
pvarPdfArray	✔️	✔️	PDF as a byte array		Contents of the PDF
varSignDataArray	✔️		SignData as byte array		The biometric data block to be entered
bstrSigfieldTitle	✔️		string, Length > 1		Unique name of the DigSig field to be signed If the document does not contain a field with this name, a new field is created. If the field has already been signed, the function fails.
varSignCertArray	✔️		Certificate as byte array		Data array of X.509 certificate with the public key to determine its properties
varCryptBioCertArrayOrRefString	✔️		Certificate as byte array		Public X.509 certificate or PKCS12 certificate with the public key for encrypting biometric data
			String object		ID of the pad certificate (after encryption in the pad)
			Invalid format		The signature certificate is used.
bstrCryptBioCertPassword	✔️		string		Password for varCryptBioCertArrayOrRefString is only used if a PKCS#12 certificate was passed in the parameter
bstrXMLSignatureData	✔️		XML string		Additional information to be entered
varImageArray	✔️		Image content as byte array		Signature image that is entered into the PDF document For PDF/A-1b conformity, the signature image must not contain an alpha channel.
pvarDocHashArray		✔️	Byte array		Data to be signed The hash of this data must be signed and written into the document.
plDocSignaturePosition		✔️	>0		Offset of the signature placeholder in the PDF document The signed hash (digital signature) must be written into the document in this position to conclude the signing of the DigSig field
lOptions	✔️		Combination of:		Bit mask
				0x00	Do not sign document with PDF/A compliance
				0x01	Sign document in accordance with PDF/A-1b Must not be set at the same time as 0x02.
				0x02	Sign document in accordance with PDF/A-2b Must not be set at the same time as 0x01.
				0x04	Lock all form fields Must not be set at the same time as 0x08.
				0x08	Only lock form fields that have been filled Must not be set at the same time as 0x04. Checkboxes and radio buttons are always considered filled in. Form fields from any existing ‘signature field lock dictionary’ are always locked.
				0x10	Use visible reference system (recommended)
plReserved	✔️	✔️	0		Reserved

PreparePDFDocumentSigningMemory method

Preparation for electronic signing of a DigSig field in a PDF document.
In the PDF document, a placeholder for later entry of the digital signature is prepared and its position is determined. The prepared PDF document in a byte array and the position of the placeholder are returned.

void PreparePDFDocumentSigningMemory(
                                     ref object pvarPdfArray,
                                     string bstrSigfieldTitle,
                                     string bstrXMLSignatureData,
                                     object varImageArray,
                                     ref object pvarDocHashArray,
                                     ref int plDocSignaturePosition,
                                     int lOptions,
                                     ref int plReserved
                                     );

C++

HRESULT PreparePDFDocumentSigningMemory(
                                        VARIANT* pvarPdfArray,
                                        BSTR bstrSigfieldTitle,
                                        BSTR bstrXMLSignatureData,
                                        VARIANT varImageArray,
                                        VARIANT* pvarDocHashArray,
                                        long* plDocSignaturePosition,
                                        long lOptions,
                                        long* plReserved
                                        );

Parameter	In	Out	Possible Values		Description
pvarPdfArray	✔️	✔️	PDF as a byte array		PDF in a variant
bstrSigfieldTitle	✔️		string, Length > 1		Unique name of the DigSig field to be signed
bstrXMLSignatureData	✔️		XML string		Additional information to be entered
varImageArray	✔️		Image content as byte array		Signature image that is entered into the PDF document For PDF/A-1b conformity, the signature image must not contain an alpha channel.
varImageArray	✔️		empty		No signature image will be inserted. PDF/A-1b compliance requires a signature image, so a single white pixel is inserted.
pvarDocHashArray		✔️	Byte array		Data to be signed The hash of this data must be signed and written into the document.
plDocSignaturePosition		✔️	>0		Offset of the signature placeholder in the PDF document The signed hash (digital signature) must be written into the document in this position to conclude the signing of the DigSig field.
lOptions	✔️		Combination of:		Bit mask
				0x00	Do not sign document with PDF/A compliance
				0x01	Sign document in accordance with PDF/A-1b Must not be set at the same time as 0x02.
				0x02	Sign document in accordance with PDF/A-2b Must not be set at the same time as 0x01.
				0x04	Lock all form fields Must not be set at the same time as 0x08.
				0x08	Only lock form fields that have been filled Must not be set at the same time as 0x04. Checkboxes and radio buttons are always considered filled in. Form fields from any existing ‘signature field lock dictionary’ are always locked.
				0x10	Use visible reference system (recommended)
plReserved	✔️	✔️	0		Reserved

GetReferenceCountMemory method

Determines the number of DigSig fields that are present (all or only those that are filled in) on the specified page of the specified PDF document.

void GetReferenceCountMemory(
                             object varPdfArray,
                             int nPage,
                             ref int plCount,
                             int nOption
                             );

C++

HRESULT GetReferenceCountMemory(
                                VARIANT varPdfArray,
                                int nPage,
                                long* plCount,
                                int nOption
                                );

Parameter	In	Out	Possible Values	Description
pvarPdfArray	✔️		PDF as a byte array	PDF in a variant
nPage	✔️		>=1	Specify which page to search on
nPage	✔️		-1	Search entire document
plCount		✔️	>=0	Number of DigSig fields found
nOption	✔️		0	Only count filled-in fields
nOption	✔️		1	Count all fields

GetReferenceMemory method

Extracts the supplementary data from a signed DigSig field in the specified PDF document. The DigSig field is identified via its specified unique name.

For documents in which the biometric data were encrypted in the PC, all supplementary data are encrypted. In such documents, this method can only be called with the correct private key. An integrity check can only be carried out on the basis of the decrypted data.

For documents in which the biometric data were encrypted in the signature device, not all supplementary data are encrypted. In such documents, this method can be called even without a private key, and an integrity check can be carried out on the basis of the contained RSA signature even without decryption. In this case, the method does not return a SignData structure, and not all elements are filled in the returned XML structure.

void GetReferenceMemory(
                        object varPdfArray,
                        int nReserved,
                        string bstrSigfieldTitle,
                        object varPFXCertArray,
                        string bstrPFXPassword,
                        ref object pvarSigndata,
                        string pbstrXMLResultData,
                        int nOption
                        );

C++

HRESULT GetReferenceMemory(
                           VARIANT varPdfArray,
                           int nReserved,
                           BSTR bstrSigfieldTitle,
                           VARIANT varPFXCertArray,
                           BSTR bstrPFXPassword,
                           VARIANT* pvarSigndata,
                           BSTR* pbstrXMLResultData,
                           int nOption
                           );

Parameter	In	Out	Possible Values	Description
pvarPdfArray	✔️	✔️	PDF as a byte array	PDF in a variant
nReserved	✔️		0	Reserved
bstrSigfieldTitle	✔️		string, Length > 1	Unique name of the DigSig field to be read
varPFXCertArray	✔️		Certificate content as byte array	PKCS#12 certificate with the private key for decrypting the biometric data Optional; not necessary for biometric data encrypted in the signature device if only integrity is to be checked
bstrPFXPassword	✔️		string	Password for varPFXCertArray
pvarSigndata		✔️	SignData as byte array	Signature data
pbstrXMLResultData		✔️	XML string	Information about the signature process
nOption	✔️		0	The integrity of the biometric data is not verified.
nOption	✔️		1	The integrity of the biometric data is verified.

VerifyPdfDocumentMemory method

Extracts and decrypts the digital signature data from the signed DigSig fields in the specified PDF document and verifies that the fields are valid and intact.

This method does not return the encrypted biometric data of previously signed DigSig fields. This encrypted information can only be obtained using the GetReferenceMemory method and the corresponding certificate.

void VerifyPdfDocumentMemory(
                             object varPdfArray,
                             ref string pbstrXMLResultData,
                             ref int plOptions
                             );

C++

HRESULT VerifyPdfDocumentMemory(
                                VARIANT varPdfArray,
                                BSTR* pbstrXMLResultData,
                                long* plOptions
                                );

Parameter	In	Out	Possible Values		Description
pvarPdfArray	✔️	✔️	PDF as a byte array		Contents of the PDF
pbstrXMLResultData		✔️	XML string		Information about the signed DigSig fields
plOptions	✔️	✔️	Combination of:		Bit mask
				0x02	The signature certificate is not verified and the XML structure does not contain its information; instead the certificate and possibly its chain in the CertificateData node are verified, so the check can be carried out independently.
				0x10	Use visible reference system (recommended)

GetDSFieldInfoMemory method

Extracts the data from all the DigSig fields in the specified PDF document and displays the details for these fields.

void GetDSFieldInfoMemory(
                          object varPdfArray,
                          ref string pbstrXMLResultData,
                          int nOptions
                          );

C++

HRESULT GetDSFieldInfoMemory(
                             VARIANT varPdfArray,
                             BSTR* pbstrXMLResultData,
                             int nOptions
                             );

Parameter	In	Out	Possible Values		Description
pvarPdfArray	✔️	✔️	PDF as a byte array		Contents of the PDF
pbstrXMLResultData		✔️	XML string		Information about the signed DigSig fields
nOptions	✔️		Combination of:		Bit mask
				0x01	Do not check the validity of signed signature fields
				0x02	The signature certificate is not verified and the XML structure does not contain its information; instead the certificate and possibly its chain in the CertificateData node are verified, so the check can be carried out independently.
				0x10	Use visible reference system (recommended)

VerifyCertificateMemory method

Checks the certificate and returns its status.

void VerifyCertificateMemory(
                             object varCertArray,
                             string bstrOptionalPFXPassword,
                             int nReserved,
                             ref int plCertStatus
                             );

C++

HRESULT VerifyCertificateMemory(
                                VARIANT varCertArray,
                                BSTR bstrOptionalPFXPassword,
                                int nReserved,
                                long* plCertStatus
                                );

Parameter	In	Out	Possible Values		Description
varCertArray	✔️		Certificate as byte array		Contents of the certificate
bstrOptionalPFXPassword	✔️		string		Password for the certificate (optional)
nReserved	✔️		0		Reserved
plCertStatus		✔️	<=0		Certificate status
				0	Certificate is valid
				-1	Certificate is invalid
				-2	File is not a certificate
				-4	Invalid password
				-5	Certificate does not contain a public key
				-7	The certificate’s duration of validity has expired
				-99	Unknown error

CreateDSFieldMemory method

Creates an empty, unsigned signature field.

void CreateDSFieldMemory(
                         ref object pvarPdfArray,
                         string bstrTitle,
                         int nPage,
                         double dX,
                         double dY,
                         double dWidth,
                         double dHeight,
                         int nFlags
                         );

C++

HRESULT CreateDSFieldMemory(
                            VARIANT* pvarPdfArray,
                            BSTR bstrTitle,
                            int nPage,
                            double dX,
                            double dY,
                            double dWidth,
                            double dHeight,
                            int nFlags
                            );

Parameter	In	Out	Possible Values		Description
pvarPdfArray	✔️	✔️	PDF as a byte array		PDF in a variant
bstrTitle	✔️		string, Length > 1		Unique name of the signature field in the PDF document
nPage	✔️		>=1		Page of the PDF where the new signature field is created
dX	✔️		>=0		X coordinate of the top left corner of the new signature field The origin of the coordinate system is in the top left corner of the PDF, unless otherwise defined via nFlags.
dY	✔️		>=0		Y coordinate of the top left corner of the new signature field. The origin of the coordinate system is in the top left corner of the PDF, unless otherwise defined via nFlags.
dWidth	✔️		>0		Width of the new signature field
dHeight	✔️		>0		Height of the new signature field
nFlags	✔️		Combination of:		Bit mask
				0x01	The signature field is defined as "required", making it a mandatory field.
				0x10	Use visible reference system (recommended)

DrawTextBoxPdfDocumentMemory method

Inserts a freely selectable text into an existing PDF document. In addition to the text content, you can select the position and page, font, font size, font colour, and font style.

The entered text is not outlined and is transparent to prevent it from covering up other texts. The text is entered as a character string, not as an image. If the width of the specified text box is too small for the length of the text, text wrapping is performed automatically. The font size is not automatically adjusted to the size of the text box. If the space required for the text exceeds the size of the text box, the part of the text that cannot be displayed will be cut off.

The method must not be used on documents that have already been signed, as this would invalidate the previously entered signatures and prevent any further signing.

void DrawTextBoxPdfDocumentMemory(
                                  ref object pvarPdfArray,
                                  string bstrText,
                                  short xPos1,
                                  short yPos1,
                                  short xPos2,
                                  short yPos2,
                                  int nPage,
                                  string bstrFontName,
                                  double dbFontSize,
                                  bool bFontBold,
                                  bool bFontItalic,
                                  bool bUnderline,
                                  uint oleColor,
                                  int nStandardFont
                                  );

C++

HRESULT DrawTextBoxPdfDocumentMemory(
                                     VARIANT* pvarPdfArray,
                                     BSTR bstrText,
                                     short xPos1,
                                     short yPos1,
                                     short xPos2,
                                     short yPos2,
                                     int nPage,
                                     BSTR bstrFontName,
                                     double dbFontSize,
                                     VARIANT_BOOL bFontBold,
                                     VARIANT_BOOL bFontItalic,
                                     VARIANT_BOOL bUnderline,
                                     OLE_COLOR oleColor,
                                     int nStandardFont
                                     );

Parameter	In	Out	Possible Values		Description
pvarPdfArray	✔️	✔️	PDF as a byte array		PDF in a variant
bstrText	✔️		string		Text to be entered
xPos1	✔️		>0		top left corner of the desired text box in points (X coordinate)
yPos1	✔️		>0		top left corner of the desired text box in points (Y coordinate)
xPos2	✔️		>0		bottom right corner of the desired text box in points (X coordinate)
yPos2	✔️		>0		bottom right corner of the desired text box in points (Y coordinate)
nPage	✔️		>=1		Page of document on which the text is to be entered.
bstrFontName	✔️		Wide-char string Length > 1		Name of the font to be used
bstrFontName	✔️		Empty string		nStandardFont is used to define the font
dbFontSize	✔️		>0		Font size
bFontBold	✔️				Only valid if bstrFontName is not empty
				VARIANT_TRUE	Use emphasis style bold
				VARIANT_FALSE	Do not use emphasis style bold
bFontItalic	✔️				Only valid if bstrFontName is not empty
				VARIANT_TRUE	Use emphasis style italics
				VARIANT_FALSE	Do not use emphasis style italics
bUnderline	✔️		VARIANT_TRUE		Use emphasis style underline
bUnderline	✔️		VARIANT_FALSE		Do not use emphasis style underline
oleColor	✔️		OLE_COLOR-Struktur		Colour of the text to be entered (observe sequence of text colour BGR)
nStandardFont	✔️		0 - 13		Font to be used Parameter is ignored if the parameter bstrFontName is not empty
				0	Courier
				1	CourierBold
				2	CourierBoldOblique
				3	CourierOblique
				4	Helvetica
				5	HelveticaBold
				6	HelveticaBoldOblique
				7	HelveticaOblique
				8	TimesRoman
				9	TimesBold
				10	TimesItalic
				11	TimesBoldItalic
				12	Icon
				13	ZapfDingbats

SignaturePlaceholderLength property

Number of characters that are reserved by the methods PreparePdfDocumentMemory and PreparePDFDocumentSigningMemory in the PDF document as placeholder for the signature. The PKCS#7 signature that is then calculated by the calling application must not be any longer than half of this value in bytes and must be written into the placeholder as a hexadecimal string.

If a different size is required, the value must be changed before the method PreparePdfDocumentMemory or PreparePDFDocumentSigningMemory is called.

long SignaturePlaceholderLength

In	Out	Possible Values	Description
✔️	✔️	>0	Length of the placeholder in characters
	8192	Default

Out

Possible

Values

Description

✔️

Length of the placeholder in characters

8192

Default