Straightforward C14N  0.9.0
Performs the C14N transformation of a straightforward XML document
Macros | Functions
diSc14n.h File Reference

The C/C++ interface to the diSc14n.dll library. More...

Macros

#define SC14N_DIG_DEFAULT   0
 Use default digest algorithm (SHA-1)
 
#define SC14N_DIG_SHA1   0
 Use SHA-1 digest algorithm (default)
 
#define SC14N_DIG_SHA256   0x2000
 Use SHA-256 digest algorithm.
 
#define SC14N_MAX_DIGEST_CHARS   44
 Maximum number of characters in base64-encoded hash digest value.
 
#define SC14N_MAX_ERROR_CHARS   4073
 Maximum number of characters in an error message.
 
#define SC14N_TRAN_ENTIRE   0
 Transform the entire document.
 
#define SC14N_TRAN_EXCLUDEBYID   0x11
 Exclude the element with the given Id.
 
#define SC14N_TRAN_EXCLUDEBYTAG   0x01
 Exclude the element with the given tag name.
 
#define SC14N_TRAN_SUBSETBYID   0x12
 Transform the subset with the given Id.
 
#define SC14N_TRAN_SUBSETBYTAG   0x02
 Transform the subset with the given tag name.
 

Functions

long C14N_File2Digest (char *szOut, long nOutChars, const char *szInputFile, const char *szNameOrId, const char *szReserved, long nOptions)
 Computes digest value of C14N transformation (file-to-digest). More...
 
long C14N_File2File (const char *szOutputFile, const char *szInputFile, const char *szNameOrId, const char *szReserved, long nOptions)
 Performs C14N transformation of XML document (file-to-file). More...
 
long C14N_File2String (char *szOut, long nOutChars, const char *szInputFile, const char *szNameOrId, const char *szReserved, long nOptions)
 Performs C14N transformation of XML document (file-to-memory). More...
 
long C14N_String2Digest (char *szOut, long nOutChars, const void *lpDataIn, long nDataLen, const char *szNameOrId, const char *szReserved, long nOptions)
 Computes digest value of C14N transformation (memory-to-digest). More...
 
long C14N_String2String (char *szOut, long nOutChars, const void *lpDataIn, long nDataLen, const char *szNameOrId, const char *szReserved, long nOptions)
 Performs C14N transformation of XML document (memory-to-memory). More...
 
long SC14N_Err_ErrorLookup (char *szOut, long nOutChars, long nErrCode)
 Looks up description for error code. More...
 
long SC14N_Err_LastError (char *szOut, long nOutChars)
 Retrieves the last error message (if available). More...
 
long SC14N_Gen_CompileTime (char *szOut, long nOutChars)
 Gets date and time the core DLL module was last compiled. More...
 
long SC14N_Gen_LicenceType (void)
 Gets licence type. More...
 
long SC14N_Gen_ModuleName (char *szOut, long nOutChars, long nOptions)
 Gets full path name of core DLL module. More...
 
long SC14N_Gen_Platform (char *szOut, long nOutChars)
 Gets platform on which the core DLL is running ("Win32" or "Win64"). More...
 
long SC14N_Gen_Version (void)
 Gets version number of the core DLL. More...
 

Detailed Description

The C/C++ interface to the diSc14n.dll library.

Canonical XML Version 1.0
All C14N transformations here use "inclusive canonicalization" without comments from Canonical XML Version 1.0 with identifier
http://www.w3.org/TR/2001/REC-xml-c14n-20010315
Supported XML encodings
Input is expected to be a well-formed XML document. Supported XML encodings are UTF-8, ISO-8859-1 and US-ASCII.
Output to szOut buffer
Functions that provide output in szOut require the buffer to be pre-dimensioned (i.e. allocated) to at least the specified length nOutChars PLUS one extra for the null-terminating byte. These functions always return the total length in bytes of the string they tried to create. To find the required length, pass a NULL szOut or zero nOutChars argument, then add one to the result for the required buffer size.

For example:

char *xmlfile = "test.xml";
long nchars;
char *lpszOut;
// Find out how many bytes we need
nchars = C14N_File2String(NULL, 0, xmlfile, 0);
if (nchars <= 0) error();
// Pre-dimension, i.e allocate memory for string buffer
lpszOut = malloc(nchars+1); // NB +1
if (!lpszOut) error();
nchars = C14N_File2String(lpszOut, nchars, xmlfile, 0);
// ...
// do something with lpszOut...
// ...
free(lpszOut);

Specifying the tag name or Id with szNameOrId
Use the szNameOrId parameter to specify the element of the XML document to include or exclude.

Exactly one element will be excluded or included. Tag names and Id values are case sensitive. It is an error (NO_DATA_ERROR) if no matching element is found.

// Example 1. Excludes the first element with the tag name <Signature>
r = C14N_File2File("c14nfile1.txt", "input.xml", "Signature", "", SC14N_TRAN_EXCLUDEBYTAG);
// Example 2. Finds and transforms the first element with the tag name <SignedInfo>
r = C14N_File2File("c14nfile2.txt", "input.xml", "SignedInfo", "", SC14N_TRAN_SUBSETBYTAG);
// Example 3. Finds and transforms the third element with the tag name <Data>
r = C14N_File2File("c14nfile3.txt", "input.xml", "Data[3]", "", SC14N_TRAN_SUBSETBYTAG);
// Example 4. Finds and transforms the element with attribute Id="foo"
r = C14N_File2File("c14nfile4.txt", "input.xml", "foo", "", SC14N_TRAN_SUBSETBYID);
// Example 5. Finds and transforms the element with attribute ID="bar"
r = C14N_File2File("c14nfile5.txt", "input.xml", "ID=bar", "", SC14N_TRAN_SUBSETBYID);
// Example 6. Excludes element with attribute Id="thesig"
r = C14N_File2File("c14nfile6.txt", "input.xml", "thesig", "", SC14N_TRAN_EXCLUDEBYID);

Function Documentation

long C14N_File2Digest ( char *  szOut,
long  nOutChars,
const char *  szInputFile,
const char *  szNameOrId,
const char *  szReserved,
long  nOptions 
)

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

Parameters
[out]szOutBuffer to receive digest value output
[in]nOutCharsLength of output buffer in bytes
[in]szInputFileName of input file containing XML document to be processed
[in]szNameOrIdTo specify the tag name or Id. See Specifying the tag name or Id.
[in]szReservedFor future use. Use "" or NULL.
[in]nOptionsOption flags. Select one of:
SC14N_TRAN_ENTIRE (0) to transform the entire document (default)
SC14N_TRAN_EXCLUDEBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_EXCLUDEBYID 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 (0) to use SHA-1 algorithm (default) or
SC14N_DIG_SHA256 to use SHA-256.
Returns
Number of characters in or required for output string; or a negative error code .
Remarks
The output is always encoded in base64. The maximum length is SC14N_MAX_HASH_CHARS.
long C14N_File2File ( const char *  szOutputFile,
const char *  szInputFile,
const char *  szNameOrId,
const char *  szReserved,
long  nOptions 
)

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

Parameters
[in]szOutputFileName of output file to create (will be overwritten if exists)
[in]szInputFileName of input file containing XML document to be processed
[in]szNameOrIdTo specify the tag name or Id. See Specifying the tag name or Id.
[in]szReservedFor future use. Use "" or NULL.
[in]nOptionsOption flags. Select one of:
SC14N_TRAN_ENTIRE (0) to transform the entire document (default)
SC14N_TRAN_EXCLUDEBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_EXCLUDEBYID to exclude the element with Id specified in szNameOrId
SC14N_TRAN_SUBSETBYID to transform subset with Id specified in szNameOrId
Returns
Zero (0) on success or a negative error code .
long C14N_File2String ( char *  szOut,
long  nOutChars,
const char *  szInputFile,
const char *  szNameOrId,
const char *  szReserved,
long  nOptions 
)

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

Parameters
[out]szOutBuffer to receive output as UTF-8 encoded bytes
[in]nOutCharsLength of output buffer in bytes
[in]szInputFileName of input file containing XML document to be processed
[in]szNameOrIdTo specify the tag name or Id. See Specifying the tag name or Id.
[in]szReservedFor future use. Use "" or NULL.
[in]nOptionsOption flags. Select one of:
SC14N_TRAN_ENTIRE (0) to transform the entire document (default)
SC14N_TRAN_EXCLUDEBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_EXCLUDEBYID to exclude the element with Id specified in szNameOrId
SC14N_TRAN_SUBSETBYID to transform subset with Id specified in szNameOrId
Returns
Number of characters in or required for output string; or a negative error code .
Remarks
The output is always UTF-8-encoded.
long C14N_String2Digest ( char *  szOut,
long  nOutChars,
const void *  lpDataIn,
long  nDataLen,
const char *  szNameOrId,
const char *  szReserved,
long  nOptions 
)

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

Parameters
[out]szOutBuffer to receive digest value output
[in]nOutCharsLength of output buffer in bytes
[in]lpDataInPointer to XML data to be processed
[in]nDataLenLength of input data in bytes
[in]szNameOrIdTo specify the tag name or Id. See Specifying the tag name or Id.
[in]szReservedFor future use. Use "" or NULL.
[in]nOptionsOption flags. Select one of:
SC14N_TRAN_ENTIRE (0) to transform the entire document (default)
SC14N_TRAN_EXCLUDEBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_EXCLUDEBYID 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 (0) to use SHA-1 algorithm (default) or
SC14N_DIG_SHA256 to use SHA-256.
Returns
Number of characters in or required for output string; or a negative error code .
Remarks
The output is always encoded in base64. The maximum length is SC14N_MAX_HASH_CHARS.
long C14N_String2String ( char *  szOut,
long  nOutChars,
const void *  lpDataIn,
long  nDataLen,
const char *  szNameOrId,
const char *  szReserved,
long  nOptions 
)

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

Parameters
[out]szOutBuffer to receive output as UTF-8 encoded bytes
[in]nOutCharsLength of output buffer in bytes
[in]lpDataInPointer to XML data to be processed
[in]nDataLenLength of input data in bytes
[in]szNameOrIdTo specify the tag name or Id. See Specifying the tag name or Id.
[in]szReservedFor future use. Use "" or NULL.
[in]nOptionsOption flags. Select one of:
SC14N_TRAN_ENTIRE (0) to transform the entire document (default)
SC14N_TRAN_EXCLUDEBYTAG to exclude the element with tag name specified in szNameOrId
SC14N_TRAN_SUBSETBYTAG to transform subset with tag name specified in szNameOrId
SC14N_TRAN_EXCLUDEBYID to exclude the element with Id specified in szNameOrId
SC14N_TRAN_SUBSETBYID to transform subset with Id specified in szNameOrId
Returns
Zero (0) on success or a negative error code .
Remarks
The output is always UTF-8-encoded.
long SC14N_Err_ErrorLookup ( char *  szOut,
long  nOutChars,
long  nErrCode 
)

Looks up description for error code.

Parameters
[out]szOutBuffer to receive output string
[in]nOutCharsMaximum length of output string in bytes
[in]nErrCodeValue of error code to lookup (may be positive or negative)
Returns
Number of characters in or required for output string; or a negative error code .
long SC14N_Err_LastError ( char *  szOut,
long  nOutChars 
)

Retrieves the last error message (if available).

Parameters
[out]szOutBuffer to receive output string
[in]nOutCharsMaximum length of output string in bytes. Will not exceed SC14N_MAX_ERROR_CHARS.
Returns
Number of characters in or required for output string; or a negative error code .
Remarks
Call this function to find out more information about the last error. Not all functions set this.
long SC14N_Gen_CompileTime ( char *  szOut,
long  nOutChars 
)

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

Parameters
[out]szOutBuffer to receive output string
[in]nOutCharsMaximum length of output string in bytes
Returns
Number of characters in or required for output string; or a negative error code .
long SC14N_Gen_LicenceType ( void  )

Gets licence type.

Returns
ASCII value of the licence type: 'D'=Developer, 'T'=Trial
Remarks
Note the Australian/English spelling of "Licence".
long SC14N_Gen_ModuleName ( char *  szOut,
long  nOutChars,
long  nOptions 
)

Gets full path name of core DLL module.

Parameters
[out]szOutBuffer to receive output string
[in]nOutCharsMaximum length of output string in bytes.
[in]nOptionsNot used. Specify zero.
Returns
Number of characters in or required for output string; or a negative error code
long SC14N_Gen_Platform ( char *  szOut,
long  nOutChars 
)

Gets platform on which the core DLL is running ("Win32" or "Win64").

Parameters
[out]szOutBuffer to receive output string
[in]nOutCharsMaximum length of output string in bytes
Returns
Number of characters in or required for output string; or a negative error code .
long SC14N_Gen_Version ( void  )

Gets version number of the core DLL.

Returns
Version number as an integer in the form major*10000+minor*100+revision e.g. DLL file version 1.2.x.3 will return 10203
Copyright © 2017 D.I. Management Services Pty Limited ABN 78 083 210 584 Australia. All rights reserved. <www.di-mgt.com.au/> Generated on Tue Jul 11 2017 20:05:24 by Doxygen 1.8.3.1.