SigObj

SigObj

The SigObj object encapsulates a captured handwritten signature. When populated it contains a wealth of data that fully describes both the static and dynamic characteristic of a signature and the context in which the signature was captured. A Signature object can be bound (at the moment of capture) to the host document or other data set to provide a means of determining whether or not any changes have been made subsequently, either maliciously or unintentionally.

Summary

Method
CheckIntegrity
CheckSignedData
Clear
GetProperty
Picture
ReadEncodedBitmap
Render
RenderBitmap
RenderRect
SetProperty

Property
AdditionalData
CrossedOut
ExtraData
Height
Ink
IsCaptured
SigData
SigText
When
Who
Why
Width

Methods

CheckIntegrity

Checks the integrity of the Signature object to detect whether it has been tampered with since signing.

IntegrityStatus CheckIntegrity( Key )
Parameters
Key	Optional Key object. If not supplied, the code uses Key type MD5 by default.
Return Value
IntegrityStatus
IntegrityOK	Data has not changed since signature capture.
IntegrityFail	Data has changed since signature capture.
IntegrityMissing	Signature integrity value not found.
IntegrityWrongType	Signature was captured using a different integrity check version.

CheckSignedData

Checks for a match between a given hash and that provided when the signature was captured. If the signature is bound to a hash (ie. the What argument of the DynamicCapture or SigCtl Capture method was set), then this function checks the signed data against that from which the supplied hash was derived. This method is called by SigCtlXHTML.CheckHostDocument() which supplies the necessary Hash.

SignedData CheckSignedData( Hash )
Parameters
Hash	Hash object, to be compared with that provided when the signature was captured.
Return Value
SignedData
DataGood	The supplied hash matches that provided when the signature was captured, confirming that both Hash objects are derived from the same data set.
DataNoHash	No hash was specified when the signature was captured (or the object does not contain a signature).
DataBadType	The supplied hash is of a different type (HashType Enum) than the one used when the signature was captured.
DataBadHash	The supplied hash value does not match that provided when the signature was captured, indicating the two Hash objects are derived from different data sets.

Clear

Clears all signature data and thus reinitializes the Signature object.

void Clear()
Parameters
None
Return Value
None

GetProperty

Returns the current value of a property.

Variant GetProperty(Name)
Parameters
Name	The name of the property to retrieve.
Return Value
Variant
Current Value	The current value of the named property. Empty if no value has been set.

Supported Property Names

Supported Property Names
DataGood	The supplied hash matches that provided when the signature was captured, thus both Hash objects have been derived from the same data set.
IsEncrypted	No hash was specified when the signature was captured (or the object does not contain a signature).
CanEncrypt	TRUE if a password or public key has been set. If the SigObj already contains sig data, or if it is subsequently set (via SigData, SigText, Capture etc), it will be encrypted.
CanDecrypt	TRUE if a password or private key has been set. Sig data encrypted (with the appropriate password or public key) can be set and will be decrypted.

Picture

Renders an image of the signature, creating a Windows Picture object. Optionally encodes the signature data in the generated image using steganographic techniques.

Variant Picture(dimensionX, dimensionY, mimeType, inkWidth, inkColor, backgroundColor, paddingX, paddingY, flags)
Parameters
See RenderBitmap.	As RenderBitmap hardcoded for RenderOutputPicture
Return Value
Variant Function Dependent, see RenderBitmap	Picture returned as specified by Flags.

ReadEncodedBitmap

Reads the encoded SigObj data from an image file, picture object, base-64 encoded string or binary data which was created using RenderBitmap().

ReadEncodedBitmap(data)
Parameters
data	Encoded signature data in one of the following formats: String pathname of an image file or base-64 encoded string. Strings containing these characters are assumed to be filenames: ':', '\', or '.'. Otherwise, the string is assumed to be one of the following: Base-64 encoded image data Picture Windows Picture object Byte Array binary image data
Return Value
ReadEncodedBitmapResult
ReadEncodedBitmapOK	The Signature data was decoded successfully.
ReadEncodedBitmapNotImage	The Bitmap is not a supported image type.
ReadEncodedBitmapSigDataNotFound	Encoded signature data was not found in the image.

RenderBitmap

Renders an image of the signature, creating an image file or returning the binary data. Optionally encodes the SigObj data in the generated image using steganography.

variant RenderBitmap(outputFilename, dimensionX, dimensionY, mimeType, inkWidth, inkColor, backgroundColor, paddingX, paddingY, flags)
Parameters
outputFilename	Pathname of the file in which to save the image. May be null or empty if output type specified by flags is not RenderOutputFilename.
dimensionX, dimensionY	Dimensions specified as DPI (dots per inch) or Pixels. Negative value = DPI (the signature is not scaled) Positive value = Pixels (the signature is scaled to fit the area)
mimeType	Specifies the image format as one of: image/bmp image/tiff image/png
inkWidth	Specifies the signature ink width in mm.
inkColor, backgroundColor	Signature ink and background colors in OLE_COLOR format.
paddingX, paddingY	Padding around the signature image, added to both the left and right for paddingX, and both the top and bottom for paddingY. Dimensions are specified as mm or Pixels. Negative value = mm Positive value = Pixels
flags	A combination of RBFlags values. A single value from each mandatory group must be included. Output Group (mandatory): RenderOutputBase64Return - base-64 encoded string RenderOutputBinaryReturn - bitmap as binary data RenderOutputFilename - write bitmap to file RenderOutputPictureReturn - bitmap as Picture object Colour Selection Group (mandatory): RenderColor1BPPRender - 1-bit monochrome RenderColor24BPPRender - 24-bit pixel colour RenderColor32BPPRender - 32-bit pixel colour Image Format Flags (optional): RenderBackgroundTransparent - Make background transparent (32 BPP only, uses Alpha channel) RenderColorAntiAliasRender - Render colour image with antialiasing (24 and 32 BPP only) Image Extension (optional): RenderEncodeData - Embed signature data within image RenderWatermarkInclude - Include watermark to indicate presence of encoded data Other (optional): RenderClippedCrop - Crop signature image, omitting parts outside the capture window RenderRelative - Render signature image relative to original capture window
Return Value
Variant function dependent
Filename	No return value
Binary	Byte array containing the image file contents
Base64	String containing base-64 representation of image file data
Picture	Windows Picture object (as an IDispatch interface pointer)

RenderRect

Renders an image of the signature within a given rectangle on a specified device context.

void RenderRect(hDCTarg, hDCRef, Left, Top, Right, Bottom, InkWidth, InkColor, Option, Zoom, Rotation)
Parameters
hDCTarg	Handle to output device context (as a LONG).
hDCRef	Handle to reference device context (as a LONG). May be the same as hDCTarg.
Left, Top, Right, Bottom	Integer values defining the bounding rectangle in which the signature is to be rendered.
InkWidth	Float value specifying width, in mm, of pen used to draw signature. Defaults to 0.7mm. Scales with zoom. Example: If InkWidth = 0.7 and Zoom = 200, the actual width will be 1.4mm.
InkColor	OLE_COLOR value specifying the color of the pen used to draw the signature. Default is black.
Option	DisplayMode value specifying the scaling mode of the rendered signature: DspForceFit - Scale signature to exactly fit the bounding rectangle. DspUseZoom - Scale signature according to the Zoom argument. DspBestFit - Reduce size of signature to fit area if it is too big; otherwise, show at true size. Default is DspForceFit.
Zoom	Percentage by which the signature image is scaled. Ignored if Option = DspForceFit. Default is 100%.
Rotation	Short value specifying the angle (in degrees) through which the signature image is rotated anticlockwise. If 'Option' is DspUseZoom and the value of 'Zoom' results in a signature larger than the given rectangle then the signature image is not clipped. Default is 0. (Currently ignored.)
Return Value
None

SetProperty

Sets the value of a named additional property, overriding a value set in the registry.

SetProperty(Name, Value)
Parameters
Name	String. Name of the property.
Value	Value to assign to the property.
Return Value
Boolean
True: Name exists and value is valid. False: Failed to set property.

Properties

General Properties

Property Name	Type	Description
AdditionalData (CaptData)	Variant	Returns additional data collected at capture time. CaptData is an Enum that specifies the capture-related data to return. The requested data is returned as a string or an empty variant if the object does not contain signature data or the signature does not include the requested data type. (Read-only)
CrossedOut	Boolean	Returns TRUE if the signature has been invalidated by changes to the document and appears crossed out. (Read-only)
ExtraData (Key)	String	Allows the client to store additional data within the signature object after capture. The data is stored with a key and value. All ExtraData key-value pairs are protected by the signature object integrity hash. When read, all values are returned in a single string formatted as key=value;key=value;.
Height	Int	Returns the height of the bounding rectangle of the signature in 0.01mm units. Returns 0 if the object does not contain signature data. (Read-only)
Ink	String	Signature data in a form compatible with the ActiveX interface of CIC InkTools, allowing interoperation between the Signature Component and CIC InkTools. Signature data may be exchanged by copying the string value to and from a CIC Ink control via its Ink property.
IsCaptured	Boolean	Returns True if the object contains signature data. However, IsCaptured = True does not necessarily imply that other properties such as When, Who, and Why are valid. (Read-only)
SigData	Variant (containing Byte())	Binary signature data as an array of bytes. This can be used to save the signature data to and restore it from a file or database.
SigText	String	Binary signature data as a string, base-64 encoded or hexadecimal. The format is determined by the get_SigText registry setting when read.
When (TimeZone)	DateTime	Returns the time and date of signature capture. Returns 0 if no signature data exists or if the signature data does not contain a capture time. The TimeZone parameter is an Enum that specifies the time zone to use (local time or GMT/UTC). The default is TimeLocal. (Read-only)
Who	String	Returns the name of the signatory, as specified during capture. Returns an empty string if the signature data does not contain a signatory name (e.g., if the object was initialized using the Ink property). (Read-only)
Why	String	Returns the reason for signing, as specified during capture. Returns an empty string if the signature data does not contain a reason for signing (e.g., if the object was initialized using the Ink property). (Read-only)
Width	Int	Returns the width of the bounding rectangle of the signature in 0.01mm units. Returns 0 if the object does not contain signature data. (Read-only)

---

Properties supported by GetProperty/SetProperty

Name	Get/Set	Type	Description
Licence	Get/Set	String	String containing the license used for signature capture.
Component_FileVersion	Get	String	Component version, e.g., "4.5.2.210".
Complexity	Get	Double	Signature complexity, a value between 0 and 1, e.g., 0.5343597732.
ExtraDataIntegrity	Get/Set	KeyType	KeyType used to verify the integrity of ExtraData.
Integrity_CAPICOM_ICertificates	Get	Certificates	If the signature was captured with a Key of KeyType KeyCAPICOM, returns a collection of one or more Certificate objects.
Integrity_KeyType	Get	KeyType	KeyType used in signature capture.
RenderClipped	Get/Set	Boolean	True to clip the output to what was seen within the capture window.
SignedData_HashType	Get	HashType	HashType enumerator used by the hash object.
UILanguage	Get/Set	String	Selects the language used in the signature capture dialog from: de, el, en, es, fr, it, ja, ko, nl, pl, pt-BR, ru, zh-CN, zh-TW. The codes conform to the ISO language codes expanded here: http://www.lingoes.net/en/translator/langcode.htm. The codes match the language folders installed as part of the Signature SDK in: C:\Program Files (x86)\Common Files\WacomGSS. To select a language, set the property value to a language code, e.g.: obj.setProperty("UILanguage", "it"); The language code is not case-sensitive.
Where	Get	String	Returns the location at which the signature was captured (if set via DynamicCapture.SetProperty).

For the following values see the section Signature Data Encryption.

IsEncrypted	Get	Boolean	TRUE if the SigObj contains encrypted signature data that has not (yet) been decrypted.
CanEncrypt	Get	Boolean	TRUE if a password or public key has been set. If the SigObj already contains signature data or will be subsequently set, it will be encrypted.
CanDecrypt	Get	Boolean	TRUE if a password or private key has been set. Signature data encrypted with the appropriate password or public key can be decrypted.
EncryptionPassword	Set	String	String containing the symmetric encryption key.
EncryptionPublicKey	Set	String	String containing the asymmetric public key.
EncryptionPublicKeyFile	Set	String	String containing the filename of the asymmetric public key.
EncryptionPrivateKey	Set	String	String containing the asymmetric private key.
EncryptionPrivateKeyFile	Set	String	String containing the filename of the asymmetric private key.