Create SignDocDocument objects. More...

Public Member Functions
	~SignDocDocumentLoader ()
	Destructor. More...

	!SignDocDocumentLoader ()
	Finalizer. More...

	SignDocDocumentLoader ()
	Constructor. More...

SignDocDocument	loadFromMemory (out ReturnCode aReturnCode, byte[] aData)
	Load a document from memory. More...

SignDocDocument	loadFromFile (out ReturnCode aReturnCode, string aPath, bool aWritable)
	Load a document from a file. More...

SignDocDocument	createPDF (out ReturnCode aReturnCode, int aMajor, int aMinor)
	Create an empty PDF document. More...

SignDocDocument	createPDFA (out ReturnCode aReturnCode, int aMajor, int aMinor, string aConformance, byte[] aICC)
	Create an empty PDF/A document. More...

DocumentType	ping (InputStream aStream)
	Check if a document is supported by this handler. More...

DocumentType	pingMemory (byte[] aBlob)
	Check if a document is supported by this handler. More...

bool	loadFontConfigFile (string aPath)
	Load font configuration from a file. More...

bool	loadFontConfigEnvironment (string aName)
	Load font configuration from files specified by an environment variable. More...

bool	loadFontConfigStream (InputStream aStream, string aDirectory)
	Load font configuration from a stream. More...

bool	loadFontConfigBlob (byte[] aBlob, string aDirectory)
	Load font configuration from a blob. More...

bool	loadPdfFontConfigFile (string aPath)
	Load font configuration for rendering PDF documents from a file. More...

bool	loadPdfFontConfigEnvironment (string aName)
	Load font configuration for rendering PDF documents from files specified by an environment variable. More...

bool	loadPdfFontConfigStream (InputStream aStream, string aDirectory)
	Load font configuration for rendering PDF documents from a stream. More...

bool	loadPdfFontConfigBlob (byte[] aBlob, string aDirectory)
	Load font configuration for rendering PDF documents from a blob. More...

string[]	getFailedFontFiles ()
	Get the pathnames of font files that failed to load for the most recent loadFontConfig() or loadPdfFontConfig() call. More...

bool	loadTrustedCertificatesFromFile (string aPath)
	Load trusted root CA certifcates from a file. More...

bool	loadTrustedCertificatesFromStream (InputStream aStream)
	Load trusted root CA certifcates from a stream. More...

bool	loadTrustedCertificatesFromMemory (byte[] aBlob)
	Load trusted root CA certifcates from a blob. More...

void	setFlags (DocumentLoaderFlags aFlags)
	Set flags modifying the behavior of this SignDocDocumentLoader object and of the SignDocDocument objects created by it. More...

bool	initLogging (string aLevel, string aPathname, bool aSetEnv)
	Initialize logging. More...

string	getErrorMessage ()
	Get an error message for the last function call. More...

Static Public Member Functions
static bool	setLicenseKey (byte[] aKey, string aProduct, string aVersion, byte[] aToken)
	Initialize license management with license key. More...

static bool	setLicenseKey2 (string aKey, string aProduct, string aVersion, byte[] aToken)
	Initialize license management with license key. More...

static int	getRemainingDays (RemainingDays aWhat)
	Get the number of days until the license will expire. More...

static byte[]	generateLicenseToken (string aProduct)
	Generate a license token for other SDKs also covered by the license key passed to setLicenseKey(). More...

static string	getVersionNumber ()
	Get the version number of SignDoc SDK. More...

static string	getComponentVersionNumber (string aComponent)
	Get the version number of a SignDoc SDK component. More...

static int	getLicenseTextCount ()
	Get the number of license texts. More...

static string	getLicenseText (int aIndex)
	Get a license text. More...

Detailed Description

Create SignDocDocument objects.

Use getErrorMessage() to get more information after a function call failed.

As the error message is stored in this object, each thread should have its own instance of SignDocDocumentLoader or synchronization should be used.

Unless you need differently configured SignDocDocumentLoader objects, you should have only one SignDocDocumentLoader object per process (but see above). Loading font configuration files can be expensive, in particular if many fonts have to be scanned.

Constructor & Destructor Documentation

~SignDocDocumentLoader ( )

Destructor.

!SignDocDocumentLoader ( )

Finalizer.

SignDocDocumentLoader ( )

Constructor.

Member Function Documentation

SignDocDocument createPDF	(	out ReturnCode	aReturnCode,
		int	aMajor,
		int	aMinor
	)

Create an empty PDF document.

The PDF document is invalid until you add at least one page. SignDocDocument.addSignature() cannot be used until the document has been saved.

Parameters

[out]	aReturnCode	The return code, ReturnCode.OK iff successful.
[in]	aMajor	Major PDF version, must be 1 or 2.
[in]	aMinor	Minor PDF version, must be 0 through 7 (if aMajor is 1) or 0 (if aMajor is 2).

Returns: A new SignDocDocument object representing the document. After use, SignDocDocument.closeDocument() should be called to free up native resources as soon as possible. null on error.

See also: createPDFA()

SignDocDocument createPDFA	(	out ReturnCode	aReturnCode,
		int	aMajor,
		int	aMinor,
		string	aConformance,
		byte[]	aICC
	)

Create an empty PDF/A document.

The PDF document is invalid until you add at least one page. SignDocDocument.addSignature() cannot be used until the document has been saved.

Parameters

[out]	aReturnCode	The return code, ReturnCode.OK iff successful.
[in]	aMajor	Major PDF version, must be 1.
[in]	aMinor	Minor PDF version, must be 0 through 7.
[in]	aConformance	PDF/A conformance. This string must consist of two characters: A digit (1 through 3) specifying the part of PDF/A the document shall conform to. A letter ('A' or 'B' if the digit is '1', 'A', 'B', or 'U' of the digit is '2' or '3') specifying the PDF/A conformance. For instance, use "2B" for PDF/A-2b.
[in]	aICC	The ICC profile of the PDF/A output intent or empty if no output intent shall be added to the document.

Returns: A new SignDocDocument object representing the document. After use, SignDocDocument.closeDocument() should be called to free up native resources as soon as possible. null on error.

See also: createPDF()

static byte [] generateLicenseToken ( string aProduct )

static

Generate a license token for other SDKs also covered by the license key passed to setLicenseKey().

Parameters

[in] aProduct The name of the product which shall be able to use the license key without providing a product version.

Returns: The token. null on error.

See also: setLicenseKey()

static string getComponentVersionNumber ( string aComponent )

static

Get the version number of a SignDoc SDK component.

Parameters

[in] aComponent The component. Currently supported are "sppdf", "splm2", and "spooc".

Returns: The version number consisting of 3 or 4 integers separated by dots, .e.g., "1.9.27". null on error.

See also: getVersionNumber()

string getErrorMessage ( )

Get an error message for the last function call.

Returns: A string describing the reason for the failure of the last function call. The string is empty if the last call succeeded.

string [] getFailedFontFiles ( )

Get the pathnames of font files that failed to load for the most recent loadFontConfig*() or loadPdfFontConfig*() call.

This includes files that could not be found and files that could not be loaded. In the former case, the pathname may contain wildcard characters.

Note that loadFontConfig*() and loadPdfFontConfig() no longer fail if a specified font file cannot be found or loaded.

Returns: The pathnames of font files that failed to load.

Note: The WinRT component returns null instead of an empty array.

See also: loadFontConfigEnvironment(), loadFontConfigFile(), loadFontConfigEnvironment(), loadFontConfigStream(), loadPdfFontConfigBlob(), loadPdfFontConfigEnvironment(), loadPdfFontConfigFile(), loadPdfFontConfigEnvironment(), loadPdfFontConfigStream()

static string getLicenseText ( int aIndex )

static

Get a license text.

SignDoc SDK includes several Open Source components. You can retrieve the license texts one by one.

Parameters

[in] aIndex The zero-based index of the license text.

Returns: The license text. Lines are terminated by LF characters. If aIndex is invalid, null will be returned.

See also: getLicenseTextCount()

static int getLicenseTextCount ( )

static

Get the number of license texts.

SignDoc SDK includes several Open Source components. You can retrieve the license texts one by one.

Returns: The number of license texts.

See also: getLicenseText()

static int getRemainingDays ( RemainingDays aWhat )

static

Get the number of days until the license will expire.

Parameters

[in] aWhat Select which expiry date shall be used (RemainingDays.Product or RemainingDays.Signing).

Returns: -1 if the license has already expired or is invalid, 0 if the license will expire today, a positive value for the number of days the license is still valid. For licenses without expiry date, that will be several millions of days.

static string getVersionNumber ( )

static

Get the version number of SignDoc SDK.

Returns: The version number consisting of 3 integers separated by dots, .e.g., "1.16.7". null on error.

See also: getComponentVersionNumber()

bool initLogging	(	string	aLevel,
		string	aPathname,
		bool	aSetEnv
	)

Initialize logging.

This function returns false if the log file cannot be opened. This function initializes logging for all threads of the current process.

Parameters

[in]	aLevel	The logging level: "0" (log nothing) through "5" (log everything), optionally followed by "T" to log process and thread IDs.
[in]	aPathname	The pathname of the log file.
[in]	aSetEnv	true to set the SPDEBUG and SPDEBUGDIR environment variables from aLevel and aPathname, respectively. This will happen only if the log file is opened successfully.

Returns: true if successful, false on error.

bool loadFontConfigBlob	(	byte[]	aBlob,
		string	aDirectory
	)

Load font configuration from a blob.

Suitable fonts are required for putting text containing characters that cannot be encoded using WinAnsiEncoding into text fields, FreeText annotations, DigSig appearances, watermarks, and pages of PDF documents. See section Font Configuration.

The font configuration applies to all SignDocDocument objects created by this object.

Use getFailedFontFiles() after calling this function to get the pathnames of any fonts that could not be loaded.

Parameters

[in]	aBlob	A blob containing the XML document.
[in]	aDirectory	If non-empty, relative font pathnames will be relative to this directory. The directory must exist and must be readable. If empty, relative font pathnames will make this function fail.

Returns: true if successful, false on error.

See also: getFailedFontFiles(), loadFontConfigBlob(), loadFontConfigEnvironment(), loadFontConfigStream()

bool loadFontConfigEnvironment ( string aName )

Load font configuration from files specified by an environment variable.

Suitable fonts are required for putting text containing characters that cannot be encoded using WinAnsiEncoding into text fields, FreeText annotations, DigSig appearances, watermarks, and pages of PDF documents. See section Font Configuration.

Under Windows, directories are separated by semicolons. Under Unix, directories are separated by colons.

The font configuration applies to all SignDocDocument objects created by this object.

Use getFailedFontFiles() after calling this function to get the pathnames of any fonts that could not be loaded.

Parameters

[in] aName The name of the environment variable.

Returns: true if successful, false on error.

See also: getFailedFontFiles(), loadFontConfigBlob(), loadFontConfigFile(), loadFontConfigStream()

bool loadFontConfigFile ( string aPath )

Load font configuration from a file.

Suitable fonts are required for putting text containing characters that cannot be encoded using WinAnsiEncoding into text fields, FreeText annotations, DigSig appearances, watermarks, and pages of PDF documents. See section Font Configuration.

The font configuration applies to all SignDocDocument objects created by this object.

Use getFailedFontFiles() after calling this function to get the pathnames of any fonts that could not be loaded.

Parameters

[in] aPath The pathname of the file.

Returns: true if successful, false on error.

See also: getFailedFontFiles(), loadFontConfigBlob(), loadFontConfigEnvironment(), loadFontConfigStream()

bool loadFontConfigStream	(	InputStream	aStream,
		string	aDirectory
	)

Load font configuration from a stream.

Suitable fonts are required for putting text containing characters that cannot be encoded using WinAnsiEncoding into text fields, FreeText annotations, DigSig appearances, watermarks, and pages of PDF documents. See section Font Configuration.

The font configuration applies to all SignDocDocument objects created by this object.

Use getFailedFontFiles() after calling this function to get the pathnames of any fonts that could not be loaded.

Parameters

[in]	aStream	The font configuration will be read from this stream. This function reads the input completely, it doesn't stop at the end tag.
[in]	aDirectory	If non-empty, relative font pathnames will be relative to this directory. The directory must exist and must be readable. If empty, relative font pathnames will make this function fail.

Returns: true if successful, false on error.

See also: getFailedFontFiles(), loadFontConfigBlob(), loadFontConfigEnvironment(), loadFontConfigStream()

SignDocDocument loadFromFile	(	out ReturnCode	aReturnCode,
		string	aPath,
		bool	aWritable
	)

Load a document from a file.

Signing the document will overwrite the document, but see string parameter "OutputPath" of SignDocSignatureParameters.

You can open FDF files that reference a PDF file; the referenced PDF file will be opened and the FDF file will be applied to the loaded copy (using SetFieldFlags.FontFail). If the pathname of the referenced PDF file is not an absolute pathname, it will be interpreted as being relative to the directory containing the FDF file.

The file will remain open until the document is saved or the SignDocDocument object is closed or destroyed.

Parameters

[out]	aReturnCode	The return code, ReturnCode.OK iff successful.
[in]	aPath	Pathname of the document file.
[in]	aWritable	Open for writing (used for signing TIFF documents in place, ignored for PDF documents).

Returns: A new SignDocDocument object representing the document. After use, SignDocDocument.closeDocument() should be called to free up native resources as soon as possible. null on error.

See also: loadFromMemory(), SignDocDocument.applyFdf(), SignDocSignatureParameters.setInteger()

SignDocDocument loadFromMemory	(	out ReturnCode	aReturnCode,
		byte[]	aData
	)

Load a document from memory.

Parameters

[out]	aReturnCode	The return code, ReturnCode.OK iff successful.
[in]	aData	Blob representing the document. The data must not be modified.

Returns: A new SignDocDocument object representing the document. After use, SignDocDocument.closeDocument() should be called to free up native resources as soon as possible. null on error.

See also: loadFromFile()

bool loadPdfFontConfigBlob	(	byte[]	aBlob,
		string	aDirectory
	)

Load font configuration for rendering PDF documents from a blob.

Additional fonts may be required for rendering PDF documents. The font configuration for rendering PDF documents contains mappings from font names to font files. See section Font Configuration.

The font configuration for rendering PDF documents is global, ie, it affects all PDF documents, no matter by which SignDocDocumentLoader object they have been created.

Use getFailedFontFiles() after calling this function to get the pathnames of any fonts that could not be loaded.

Parameters

[in]	aBlob	The font configuration will be read from this blob.
[in]	aDirectory	If non-empty, relative font pathnames will be relative to this directory. The directory must exist and must be readable. If empty, relative font pathnames will make this function fail.

Returns: true if successful, false on error.

See also: getFailedFontFiles(), loadPdfFontConfigEnvironment(), loadPdfFontConfigStream()

bool loadPdfFontConfigEnvironment ( string aName )

Load font configuration for rendering PDF documents from files specified by an environment variable.

Additional fonts may be required for rendering PDF documents. The font configuration for rendering PDF documents contains mappings from font names to font files. See section Font Configuration.

The font configuration for rendering PDF documents is global, ie, it affects all PDF documents, no matter by which SignDocDocumentLoader object they have been created.

Under Windows, directories are separated by semicolons. Under Unix, directories are separated by colons.

Use getFailedFontFiles() after calling this function to get the pathnames of any fonts that could not be loaded.

Parameters

[in] aName The name of the environment variable.

Returns: true if successful, false on error.

See also: getFailedFontFiles(), loadPdfFontConfigBlob(), loadPdfFontConfigFile(), loadPdfFontConfigStream()

bool loadPdfFontConfigFile ( string aPath )

Load font configuration for rendering PDF documents from a file.

Additional fonts may be required for rendering PDF documents. The font configuration for rendering PDF documents contains mappings from font names to font files. See section Font Configuration.

The font configuration for rendering PDF documents is global, ie, it affects all PDF documents, no matter by which SignDocDocumentLoader object they have been created.

Use getFailedFontFiles() after calling this function to get the pathnames of any fonts that could not be loaded.

Parameters

[in] aPath The pathname of the file.

Returns: true if successful, false on error.

See also: getFailedFontFiles(), loadPdfFontConfigBlob(), loadPdfFontConfigEnvironment(), loadPdfFontConfigStream()

bool loadPdfFontConfigStream	(	InputStream	aStream,
		string	aDirectory
	)

Load font configuration for rendering PDF documents from a stream.

Additional fonts may be required for rendering PDF documents. The font configuration for rendering PDF documents contains mappings from font names to font files. See section Font Configuration.

The font configuration for rendering PDF documents is global, ie, it affects all PDF documents, no matter by which SignDocDocumentLoader object they have been created.

Use getFailedFontFiles() after calling this function to get the pathnames of any fonts that could not be loaded.

Parameters

[in]	aStream	The font configuration will be read from this stream. This function reads the input completely, it doesn't stop at the end tag.
[in]	aDirectory	If non-empty, relative font pathnames will be relative to this directory. The directory must exist and must be readable. If empty, relative font pathnames will make this function fail.

Returns: true if successful, false on error.

See also: getFailedFontFiles(), loadPdfFontConfigBlob(), loadPdfFontConfigEnvironment(), loadPdfFontConfigStream()

bool loadTrustedCertificatesFromFile ( string aPath )

Load trusted root CA certifcates from a file.

The loaded certificates are used for all SignDocDocument objects created by this object. They are used for signature verification and HTTPS connections. For iOS, they replace the system's trusted anchors, for other operating systems, they are used in addition to the operating system's trusted root CA certificates.

The file must contain either a single DER-encoded X.509 certificate or at least one PEM-encoded X.509 certificate.

Calls to loadTrustedCertificatesFromFile(), loadTrustedCertificatesFromMemory() and loadTrustedCertificatesFromStream() are cumulative.

Parameters

[in] aPath The pathname of the file.

Returns: true if successful, false on error.

See also: loadTrustedCertificatesFromMemory(), loadTrustedCertificatesFromStream()

bool loadTrustedCertificatesFromMemory ( byte[] aBlob )

Load trusted root CA certifcates from a blob.

The loaded certificates are used for all SignDocDocument objects created by this object. They are used for signature verification and HTTPS connections. For iOS, they replace the system's trusted anchors, for other operating systems, they are used in addition to the operating system's trusted root CA certificates.

The blob must contain either a single DER-encoded X.509 certificate or at least one PEM-encoded X.509 certificate.

Parameters

[in] aBlob The certificates will be read from this blob.

Returns: true if successful, false on error.

See also: loadTrustedCertificatesFromFile(), loadTrustedCertificatesFromStream()

bool loadTrustedCertificatesFromStream ( InputStream aStream )

Load trusted root CA certifcates from a stream.

The loaded certificates are used for all SignDocDocument objects created by this object. They are used for signature verification and HTTPS connections. For iOS, they replace the system's trusted anchors, for other operating systems, they are used in addition to the operating system's trusted root CA certificates.

The stream must contain either a single DER-encoded X.509 certificate or at least one PEM-encoded X.509 certificate.

Parameters

[in] aStream The certificates will be read from this stream.

Returns: true if successful, false on error.

See also: loadTrustedCertificatesFromFile(), loadTrustedCertificatesFromMemory()

DocumentType ping ( InputStream aStream )

Check if a document is supported by this handler.

Parameters

[in] aStream A seekable stream positioned at the first octet of the document.

Returns: The type of the document, DocumentType.Unknown if the document is not supported.

See also: pingMemory()

DocumentType pingMemory ( byte[] aBlob )

Check if a document is supported by this handler.

Parameters

[in] aBlob A blob containing the document.

Returns: The type of the document, DocumentType.Unknown if the document is not supported.

See also: ping()

void setFlags ( DocumentLoaderFlags aFlags )

Set flags modifying the behavior of this SignDocDocumentLoader object and of the SignDocDocument objects created by it.

Parameters

[in] aFlags The flags: 0 or DocumentLoaderFlags.MapIntoMemory.

static bool setLicenseKey	(	byte[]	aKey,
		string	aProduct,
		string	aVersion,
		byte[]	aToken
	)

static

Initialize license management with license key.

License management must be initialized before the non-static methods of SignDocDocumentLoader can be used.

Parameters

[in]	aKey	The license key as array of bytes.
[in]	aProduct	Should be an empty string.
[in]	aVersion	Should be an empty string.
[in]	aToken	The token as array of bytes. Should be empty.

Returns: true if successful, false on error.

See also: generateLicenseToken(), setLicenseKey2()

static bool setLicenseKey2	(	string	aKey,
		string	aProduct,
		string	aVersion,
		byte[]	aToken
	)

static

Initialize license management with license key.

License management must be initialized before the non-static methods of SignDocDocumentLoader can be used.

Parameters

[in]	aKey	The license key as string.
[in]	aProduct	Should be an empty string.
[in]	aVersion	Should be an empty string.
[in]	aToken	The token as array of bytes. Should be empty.

Returns: true if successful, false on error.

See also: generateLicenseToken(), setLicenseKey()

The documentation for this class was generated from the following file:

SignDocDotNet.cs

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation