/* $Id: diFirmaSat.h $ */

/* Copyright (C) 2006-7 DI Management Services Pty Limited. 
   All rights reserved. <www.di-mgt.com.au> <www.cryptosys.net>

   Last updated:
   $Date: 2007-08-05 07:56 $
   $Revision: 1.0.0 $
*/

#ifndef DIFIRMASAT_H_
#define DIFIRMASAT_H_ 1

/* __stdcall convention required for Win32 DLL only */
#if defined(unix) || defined (linux) || defined(__linux)
#define _stdcall
#endif  

/* CONSTANTS */
#ifndef SAT_ENCODE_DEFINED_
#define SAT_ENCODE_UTF8   0
#define SAT_ENCODE_LATIN1 1
#define SAT_ENCODE_DEFINED_
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* DIAGNOSTIC FUNCTIONS */
long _stdcall SAT_Version(void);
long _stdcall SAT_CompileTime(char *szOutput, long nOutChars);
long _stdcall SAT_ModuleName(char *szOutput, long nOutChars, long reserved);
long _stdcall SAT_PKIVersion(void);
long _stdcall SAT_PKICompileTime(char *szOutput, long nOutChars);
long _stdcall SAT_PKIModuleName(char *szOutput, long nOutChars, long reserved);
long _stdcall SAT_LastError(char *szErrMsg, long nMsgLen);
long _stdcall SAT_ErrorLookup(char *szErrMsg, long nMsgLen, long nErrCode);

/* SAT XML FUNCTIONS */
long _stdcall SAT_MakePipeStringFromXml(char *szOut, long nOutChars, const char *szXmlFile, long nOptions);
/*
INPUT:  XML file. 
OUTPUT: "Piped" string.
RETURNS: Number of bytes in output string(*) or a negative error code.
OPTIONS: None.
*/

long _stdcall SAT_MakeSignatureFromXml(char *szOut, long nOutChars, const char *szXmlFile,
    const char *szKeyFile, const char *szPassword);
/*
INPUT: XML file, encrypted key file, password
OUTPUT: Signature string in base64 ready for insertion as "Sello" field in XML.
RETURNS: Number of bytes in output string(*) or a negative error code.
*/

long _stdcall SAT_ValidateXml(const char *szXmlFile, long nOptions);
/*
INPUT: XML file.
OUTPUT: "OK" or "validation fails" if file is (is not) correctly-formed SAT XML format.
RETURNS: Zero on success or a negative error code.
OPTIONS: None.
REMARKS: This just validates the XML, not the signature.
*/

long _stdcall SAT_VerifySignature(const char *szXmlFile, const char *szCertFile, long nOptions);
/*
INPUT: XML file, [optional certificate file]
OUTPUT: "OK" or "verification fails" if signature is (is not) valid. 
RETURNS: Zero on success or a negative error code.
OPTIONS: None.
REMARKS: If the XML file contains a `Certificado' field, then that certificate will be used;
otherwise the user must specify a separate certificate file.
*/

long _stdcall SAT_SignXml(const char *szOutputFile, const char *szInputXmlFile,
    const char *szKeyFile, const char *szPassword, const char *szCertFile, long nOptions);
/*
INPUT: XML file with empty `Sello' and [optional] `Certificado' fields, key filename, password,
[certificate file].
OUTPUT: New XML file with Sello [and Certificado] strings completed.
RETURNS: Zero on success or a negative error code.
OPTIONS: None.
REMARKS: Any existing file will be over-written without warning.
If a certificate file is specified AND an empty `Certificado' field exists, the
Certificado string will be completed in the output XML file.
*/

long _stdcall SAT_GetXmlAttribute(char *szOut, long nOutChars, const char *szXmlFile,
    const char *szAttribute, const char *szElement);
/*
INPUT: XML file, attribute name, element name.
OUTPUT: String containing attribute data.
RETURNS: Number of bytes in output string(*) or a negative error code.
REMARKS: Attribute and element names are case-sensitive.
*/

/*
(*) NOTE:
Functions that provide output in `szOut' return the number of bytes in the output
string EXCLUDING the NULL terminating byte.
Passing a NULL `szOut' or zero `nOutChars' will return the required number of bytes.
All output is UTF-8 encoded. 
For example:
    long nChars;
    char *lpszOut;
    nChars = SAT_MakePipeStringFromXml(NULL, 0, xmlfile, 0);
    if (nChars <= 0) error();
    lpszOut = malloc(nChars+1);  // NB +1
    nChars = SAT_MakePipeStringFromXml(lpszOut, nChars, xmlfile, 0);
    ...
*/

#ifdef __cplusplus
}
#endif

#endif /* DIFIRMASAT_H_ */