Sc14n 3.1.0

Functions | Enumerations | Constants | Index

basSc14n.bas File Reference

The VBA/VB6 interface to the diSc14n.dll library.

New in v3.0:

The "~2" functions: sc14nFile2File2, sc14nFile2Bytes2, sc14nBytes2Bytes2, sc14nFile2Digest2, sc14nBytes2Digest2. These have a better interface using enumerations and more useful defaults than the original functions.
In-built UTF-8 encoding/decoding functions sc14nUtf8BytesFromString, sc14nUtf8BytesToString.

Functions

sc14nBytes2Bytes: Perform C14N transformation of XML document (memory-to-memory, deprecated). More...
sc14nBytes2Bytes2: Perform C14N transformation of XML document (memory-to-memory). More...
sc14nBytes2Digest: Compute digest value of C14N transformation (memory-to-digest, deprecated). More...
sc14nBytes2Digest2: Compute digest value of C14N transformation (memory-to-digest). More...
sc14nBytesLength: Get length of byte array. More...
sc14nErrErrorLookup: Look up description for error code. More...
sc14nErrLastError: Retrieve the last error message (if available). More...
sc14nFile2Bytes: Perform C14N transformation of XML document (file-to-memory, deprecated). More...
sc14nFile2Bytes2: Perform C14N transformation of XML document (file-to-memory). More...
sc14nFile2Digest: Compute digest value of C14N transformation (file-to-digest, deprecated). More...
sc14nFile2Digest2: Compute digest value of C14N transformation (file-to-digest). More...
sc14nFile2File: Perform C14N transformation of XML document (file-to-file, deprecated). More...
sc14nFile2File2: Perform C14N transformation of XML document (file-to-file). More...
sc14nGenCompileTime: Get date and time the core DLL module was last compiled. More...
sc14nGenLicenceType: Get licence type as a string. More...
sc14nGenModuleName: Get full path name of core DLL module. More...
sc14nGenPlatform: Get platform for which the core DLL is compiled More...
SC14N_Gen_Version: Get version number of core native DLL. More...
sc14nUtf8BytesFromString: Convert a VBA "Unicode" string to a UTF-8-encoded byte array. More...
sc14nUtf8BytesToString: Convert a byte array containing UTF-8-encoded data to a VBA "Unicode" string. More...

Function Descriptions

sc14nBytes2Bytes

Perform C14N transformation of XML document (memory-to-memory, deprecated).

Syntax

[VBA]

Public Function sc14nBytes2Bytes ( _
    lpDataIn() As Byte, _
    nDataLen As Long, _
    Optional szNameOrId As String = "", _
    Optional szParams As String = "", _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

lpDataIn: Byte array containing XML data to be processed.
nDataLen: Length of input data in bytes.
szNameOrId: To specify the tag name or Id.
szParams: InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use "" or vbNullString to ignore.
nOptions: Option flags. Select one of:
SC14N_TRAN_ENTIRE to transform the entire document (default)
SC14N_TRAN_OMITBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_OMITBYID to exclude the element with Id specified in szNameOrId
SC14N_TRAN_SUBSETBYID to transform subset with Id specified in szNameOrId
and optionally add any of the following. Use the Or operator to combine:
SC14N_METHOD_EXCLUSIVE to use exclusive c14n method (default is inclusive c14n method)
SC14N_METHOD_WITHCOMMENTS to include comments in c14n form (#WithComments)
SC14N_OPT_FLATTEN to flatten the XML

Return Value

Byte(): UTF-8-encoded byte array not including a terminating zero.

Remarks

The output is always UTF-8-encoded.

Deprecated

Use sc14nBytes2Bytes2.

sc14nBytes2Bytes2

Perform C14N transformation of XML document (memory-to-memory).

Syntax

[VBA]

Public Function sc14nBytes2Bytes2 ( _
    lpDataIn() As Byte, _
    Optional szNameOrId As String = "", _
    Optional eTran As Tran = Tran.Entire, _
    Optional eTranMethod As TranMethod = TranMethod.Inclusive, _
    Optional szExclParams As String = "", _
    Optional eAdvOpts As AdvOpts = AdvOpts.None _
) As Byte()

Parameters

lpDataIn: Byte array containing XML data to be processed.
szNameOrId: Tag name or Id to include or omit.
eTran: Transformation option Tran (default = Tran.Entire).
eTranMethod: Transformation method TranMethod (default = TranMethod.Inclusive).
szExclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n.
eAdvOpts: Advanced option flags AdvOpts.

Return Value

Byte(): UTF-8-encoded byte array not including a terminating zero.

Remarks

The output is always UTF-8-encoded.

sc14nBytes2Digest

Compute digest value of C14N transformation (memory-to-digest, deprecated).

Syntax

[VBA]

Public Function sc14nBytes2Digest ( _
    lpDataIn() As Byte, _
    nDataLen As Long, _
    Optional szNameOrId As String = "", _
    Optional szParams As String = "", _
    Optional nOptions As Long = 0 _
) As String

Parameters

lpDataIn: Byte array containing XML data to be processed.
nDataLen: Length of input data in bytes.
szNameOrId: To specify the tag name or Id.
szParams: InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use "" or vbNullString to ignore.
nOptions: Option flags. Select one of:
SC14N_TRAN_ENTIRE to transform the entire document (default)
SC14N_TRAN_OMITBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_OMITBYID to exclude the element with Id specified in szNameOrId
SC14N_TRAN_SUBSETBYID to transform subset with Id specified in szNameOrId
and add one of:
SC14N_DIG_SHA1 to use SHA-1 algorithm (default) or
SC14N_DIG_SHA256 to use SHA-256.
SC14N_DIG_SHA384 to use SHA-384.
SC14N_DIG_SHA512 to use SHA-512.
and optionally add any of the following. Use the Or operator to combine:
SC14N_METHOD_EXCLUSIVE to use exclusive c14n method (default is inclusive c14n method)
SC14N_METHOD_WITHCOMMENTS to include comments in c14n form (#WithComments)
SC14N_OPT_FLATTEN to flatten the XML

Return Value

String: Digest value as base64-encoded string, or an empty string on error.

Deprecated

Use sc14nBytes2Digest2.

sc14nBytes2Digest2

Compute digest value of C14N transformation (memory-to-digest).

Syntax

[VBA]

Public Function sc14nBytes2Digest2 ( _
    lpDataIn() As Byte, _
    Optional szNameOrId As String = "", _
    Optional eTran As Tran = Tran.Entire, _
    Optional eDigAlg As DigAlg = DigAlg.Default, _
    Optional eTranMethod As TranMethod = TranMethod.Inclusive, _
    Optional szExclParams As String = "", _
    Optional eAdvOpts As AdvOpts = AdvOpts.None _
) As String

Parameters

lpDataIn: Byte array containing XML data to be processed.
szNameOrId: Tag name or Id to include or omit.
eTran: Transformation option Tran (default = Tran.Entire).
eDigAlg: Digest algorithm DigAlg (default=DigAlg.Sha1).
eTranMethod: Transformation method TranMethod (default = TranMethod.Inclusive).
szExclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n.
eAdvOpts: Advanced option flags AdvOpts.

Return Value

String: Digest value as base64-encoded string, or an empty string on error.

sc14nBytesLength

Get length of byte array.

Syntax

[VBA]

Public Function sc14nBytesLength ( _
    lpBytes() As Byte _
) As Long

Parameters

lpBytes: Input byte array.

Return Value

Long: Length of byte array or zero if uninitialized.

sc14nErrErrorLookup

Look up description for error code.

Syntax

[VBA]

Public Function sc14nErrErrorLookup ( _
    nErrCode As Long _
) As String

Parameters

nErrCode: Value of error code to lookup (may be positive or negative).

Return Value

String: Error message, or empty string if no corresponding error code.

sc14nErrLastError

Retrieve the last error message (if available).

Syntax

[VBA]

Public Function sc14nErrLastError() As String

Return Value

String: String with more information about the last error.

Remarks

Not all functions set this.

sc14nFile2Bytes

Perform C14N transformation of XML document (file-to-memory, deprecated).

Syntax

[VBA]

Public Function sc14nFile2Bytes ( _
    szInputFile As String, _
    Optional szNameOrId As String = "", _
    Optional szParams As String = "", _
    Optional nOptions As Long = 0 _
) As Byte()

Parameters

szInputFile: Name of input file containing XML document to be processed
szNameOrId: To specify the tag name or Id.
szParams: InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use "" or vbNullString to ignore.
nOptions: Option flags. Select one of:
SC14N_TRAN_ENTIRE to transform the entire document (default)
SC14N_TRAN_OMITBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_OMITBYID to exclude the element with Id specified in szNameOrId
SC14N_TRAN_SUBSETBYID to transform subset with Id specified in szNameOrId
and optionally add any of the following. Use the Or operator to combine:
SC14N_METHOD_EXCLUSIVE to use exclusive c14n method (default is inclusive c14n method)
SC14N_METHOD_WITHCOMMENTS to include comments in c14n form (#WithComments)
SC14N_OPT_FLATTEN to flatten the XML

Return Value

Byte(): UTF-8-encoded byte array not including a terminating zero.

Deprecated

Use sc14nFile2Bytes2.

sc14nFile2Bytes2

Perform C14N transformation of XML document (file-to-memory).

Syntax

[VBA]

Public Function sc14nFile2Bytes2 ( _
    szInputFile As String, _
    Optional szNameOrId As String = "", _
    Optional eTran As Tran = Tran.Entire, _
    Optional eTranMethod As TranMethod = TranMethod.Inclusive, _
    Optional szExclParams As String = "", _
    Optional eAdvOpts As AdvOpts = AdvOpts.None _
) As Byte()

Parameters

szInputFile: Name of input file containing XML document to be processed.
szNameOrId: Tag name or Id to include or omit.
eTran: Transformation option Tran (default = Tran.Entire).
eTranMethod: Transformation method TranMethod (default = TranMethod.Inclusive).
szExclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n.
eAdvOpts: Advanced option flags AdvOpts.

Return Value

Byte(): UTF-8-encoded byte array not including a terminating zero.

sc14nFile2Digest

Compute digest value of C14N transformation (file-to-digest, deprecated).

Syntax

[VBA]

Public Function sc14nFile2Digest ( _
    szInputFile As String, _
    Optional szNameOrId As String = "", _
    Optional szParams As String = "", _
    Optional nOptions As Long = 0 _
) As String

Parameters

szInputFile: Name of input file containing XML document to be processed
szNameOrId: To specify the tag name or Id.
szParams: InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use "" or vbNullString to ignore.
nOptions: Option flags. Select one of:
SC14N_TRAN_ENTIRE to transform the entire document (default)
SC14N_TRAN_OMITBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_OMITBYID to exclude the element with Id specified in szNameOrId
SC14N_TRAN_SUBSETBYID to transform subset with Id specified in szNameOrId
and add one of:
SC14N_DIG_SHA1 to use SHA-1 algorithm (default) or
SC14N_DIG_SHA256 to use SHA-256.
SC14N_DIG_SHA384 to use SHA-384.
SC14N_DIG_SHA512 to use SHA-512.
and optionally add any of the following. Use the Or operator to combine:
SC14N_METHOD_EXCLUSIVE to use exclusive c14n method (default is inclusive c14n method)
SC14N_METHOD_WITHCOMMENTS to include comments in c14n form (#WithComments)
SC14N_OPT_FLATTEN to flatten the XML

Return Value

String: Digest value as base64-encoded string, or an empty string on error.

Deprecated

Use sc14nFile2Digest2.

sc14nFile2Digest2

Compute digest value of C14N transformation (file-to-digest).

Syntax

[VBA]

Public Function sc14nFile2Digest2 ( _
    szInputFile As String, _
    Optional szNameOrId As String = "", _
    Optional eTran As Tran = Tran.Entire, _
    Optional eDigAlg As DigAlg = DigAlg.Default, _
    Optional eTranMethod As TranMethod = TranMethod.Inclusive, _
    Optional szExclParams As String = "", _
    Optional eAdvOpts As AdvOpts = AdvOpts.None _
) As String

Parameters

szInputFile: Name of input file containing XML document to be processed.
szNameOrId: Tag name or Id to include or omit.
eTran: Transformation option Tran (default = Tran.Entire).
eDigAlg: Digest algorithm DigAlg (default=DigAlg.Sha1).
eTranMethod: Transformation method TranMethod (default = TranMethod.Inclusive).
szExclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n.
eAdvOpts: Advanced option flags AdvOpts.

Return Value

String: Digest value as base64-encoded string, or an empty string on error.

sc14nFile2File

Perform C14N transformation of XML document (file-to-file, deprecated).

Syntax

[VBA]

Public Function sc14nFile2File ( _
    szOutputFile As String, _
    szInputFile As String, _
    Optional szNameOrId As String = "", _
    Optional szParams As String = "", _
    Optional nOptions As Long = 0 _
) As Long

Parameters

szOutputFile: Name of output file to create (will be overwritten if exists).
szInputFile: Name of input file containing XML document to be processed.
szNameOrId: To specify the tag name or Id.
szParams: InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use "" or vbNullString to ignore.
nOptions: Option flags. Select one of:
SC14N_TRAN_ENTIRE to transform the entire document (default)
SC14N_TRAN_OMITBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_OMITBYID to exclude the element with Id specified in szNameOrId
SC14N_TRAN_SUBSETBYID to transform subset with Id specified in szNameOrId
and optionally add any of the following. Use the Or operator to combine:
SC14N_METHOD_EXCLUSIVE to use exclusive c14n method (default is inclusive c14n method)
SC14N_METHOD_WITHCOMMENTS to include comments in c14n form (#WithComments)
SC14N_OPT_FLATTEN to flatten the XML

Return Value

Long: Zero (0) on success, or a nonzero error code (use sc14nErrErrorLookup to check).

Deprecated

Use sc14nFile2File2.

sc14nFile2File2

Perform C14N transformation of XML document (file-to-file).

Syntax

[VBA]

Public Function sc14nFile2File2 ( _
    szOutputFile As String, _
    szInputFile As String, _
    Optional szNameOrId As String = "", _
    Optional eTran As Tran = Tran.Entire, _
    Optional eTranMethod As TranMethod = TranMethod.Inclusive, _
    Optional szExclParams As String = "", _
    Optional eAdvOpts As AdvOpts = AdvOpts.None _
) As Long

Parameters

szOutputFile: Name of output file to create (will be overwritten if exists).
szInputFile: Name of input file containing XML document to be processed.
szNameOrId: Tag name or Id to include or omit.
eTran: Transformation option Tran (default = Tran.Entire).
eTranMethod: Transformation method TranMethod (default = TranMethod.Inclusive).
szExclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n.
eAdvOpts: Advanced option flags AdvOpts.

Return Value

Long: Zero (0) on success, or a nonzero error code (use sc14nErrErrorLookup to check).

sc14nGenCompileTime

Get date and time the core DLL module was last compiled.

Syntax

[VBA]

Public Function sc14nGenCompileTime() As String

Return Value

String: String containing date and time.

sc14nGenLicenceType

Get licence type as a string.

Syntax

[VBA]

Public Function sc14nGenLicenceType() As String

Return Value

String: "D" = Developer "T" = Trial.

sc14nGenModuleName

Get full path name of core DLL module.

Syntax

[VBA]

Public Function sc14nGenModuleName() As String

Return Value

String: String containing path name.

sc14nGenPlatform

Get platform for which the core DLL is compiled

Syntax

[VBA]

Public Function sc14nGenPlatform() As String

Return Value

String: String containing Win32 or Win64.

SC14N_Gen_Version

Get version number of core native DLL.

Syntax

[VBA]

Public Declare Function SC14N_Gen_Version() As Long

Return Value

Long: Version number as an integer in form Major*10000 + Minor*100 + Release. For example, version 2.10.3 would return 21003.

Remarks

[This function is an external procedure in library diSc14n.dll.]

sc14nUtf8BytesFromString

Convert a VBA "Unicode" string to a UTF-8-encoded byte array.

Syntax

[VBA]

Public Function sc14nUtf8BytesFromString ( _
    strInput As String _
) As Byte()

Parameters

strInput: String to be encoded.

Return Value

Byte(): Byte array containing UTF-8-encoded string.

sc14nUtf8BytesToString

Convert a byte array containing UTF-8-encoded data to a VBA "Unicode" string.

Syntax

[VBA]

Public Function sc14nUtf8BytesToString ( _
    lpUtf8Array() As Byte _
) As String

Parameters

lpUtf8Array: Byte array to be decoded.

Return Value

String: Standard VBA "Unicode" string containing the decoded characters. Illegal UTF-8 sequences are replaced with "?".

Enumerations

Enum AdvOpts - Advanced option flags.
Enum DigAlg - Digest Algorithm.
Enum Tran - Transformation options to specify the document part to be canonicalized.
Enum TranMethod - Transformation methods.

Enum AdvOpts

Advanced option flags.

Syntax

[VBA]

Public Enum AdvOpts

Members

	Member name	Description
	None	No options.
	Flatten	Flatten the XML - remove all ignorable whitespace between tags.

Enum DigAlg

Digest Algorithm.

Syntax

[VBA]

Public Enum DigAlg

Members

	Member name	Description
	Default	Use default digest algorithm (SHA-1).
	Sha1	Use SHA-1 digest algorithm (default).
	Sha256	Use SHA-256 digest algorithm.
	Sha384	Use SHA-384 digest algorithm.
	Sha512	Use SHA-512 digest algorithm.

Enum Tran

Transformation options to specify the document part to be canonicalized.

Syntax

[VBA]

Public Enum Tran

Members

	Member name	Description
	Entire	Transform the entire document.
	OmitByTag	Omit the element with the given tag name.
	OmitById	Omit the element with the given Id.
	SubsetByTag	Transform the subset with the given tag name.
	SubsetById	Transform the subset with the given Id.

Enum TranMethod

Transformation methods.

Syntax

[VBA]

Public Enum TranMethod

Members

	Member name	Description
	Inclusive	Inclusive C14N without comments from RFC 3076.
	Exclusive	Exclusive C14N without comments from RFC 3741.
	InclusiveWithComments	Inclusive C14N with comments from RFC 3076.
	ExclusiveWithComments	Exclusive C14N with comments from RFC 3741.

Constants

Public Const SC14N_DIG_DEFAULT As Long = 0: Use default digest algorithm (SHA-1).
Public Const SC14N_DIG_SHA1 As Long = 0: Use SHA-1 digest algorithm (default).
Public Const SC14N_DIG_SHA256 As Long = &H2000: Use SHA-256 digest algorithm.
Public Const SC14N_DIG_SHA384 As Long = &H3000: Use SHA-384 digest algorithm.
Public Const SC14N_DIG_SHA512 As Long = &H5000: Use SHA-512 digest algorithm.
Public Const SC14N_METHOD_EXCLUSIVE As Long = &H100: Use exclusive c14n method [RFC 3741].
Public Const SC14N_METHOD_INCLUSIVE As Long = 0: Use inclusive c14n method [RFC 3076] (default).
Public Const SC14N_METHOD_WITHCOMMENTS As Long = &H800: Include comments in c14n form (#WithComments).
Public Const SC14N_OPT_FLATTEN As Long = &H10000: Flatten the XML - remove all ignorable whitespace between tags.
Public Const SC14N_TRAN_ENTIRE As Long = 0: Transform the entire document.
Public Const SC14N_TRAN_OMITBYID As Long = &H11: Omit the element with the given Id.
Public Const SC14N_TRAN_OMITBYTAG As Long = &H1: Omit the element with the given tag name.
Public Const SC14N_TRAN_SUBSETBYID As Long = &H12: Transform the subset with the given Id.
Public Const SC14N_TRAN_SUBSETBYTAG As Long = &H2: Transform the subset with the given tag name.

Index

Functions | Enumerations | Constants