/*----------------------------------------------------------------------------
    %%File: msencode.h
    %%Unit: fechmap
    %%Contact: jpick

    External header file for MsEncode character conversion module.
----------------------------------------------------------------------------*/

#ifndef MSENCODE_H
#define MSENCODE_H
    
    
// ----------------------------------------------------------------------------
//
// Error Returns
// 
// ----------------------------------------------------------------------------

//
// Return Type for API Functions
//
typedef int CCE;
    
//
// Error:       cceSuccess
// Explanation: Function succeeded (no error).
//
#define cceSuccess                       0

//
// Error:       cceRequestedStop
// Explanation: Function succeeded (no error).  Caller 
//              requested function to be run in iterator mode 
//              (stop on each character or stop on ASCII) and 
//              function is making requested stop.  (Stream 
//              conversion functions only).
//
#define cceRequestedStop                (-1)

//
// Error:       cceInsufficientBuffer
// Explanation: Buffer provided to function is too small.
//
#define cceInsufficientBuffer           (-2)

//
// Error:       cceInvalidFlags
// Explanation: An invalid flag or combination of flags was 
//              given to function.
//
#define cceInvalidFlags                 (-3)

//
// Error:       cceInvalidParameter
// Explanation: Invalid parameter passed to function (null 
//              pointer, invalid encoding specified, etc.).
//
#define cceInvalidParameter             (-4)

//
// Error:       cceRead
// Explanation: User read-callback function failed.
//
#define cceRead                         (-5)

//
// Error:       cceWrite
// Explanation: User write-callback function failed.
//
#define cceWrite                        (-6)

//
// Error:       cceUnget
// Explanation: User unget-callback function failed.
//
#define cceUnget                        (-7)

//
// Error:       cceNoCodePage
// Explanation: Requested encoding requires an installed
//              code page (NLS file) for conversion.  That
//              file is not installed.
//
#define cceNoCodePage                   (-8)

//
// Error:       cceEndOfInput
// Explanation: Unexpected end-of-input occurred within a 
//              multi-byte character in conversion function.
//              (Returned only if user requested errors for
//              invalid characters).
//
#define cceEndOfInput                   (-9)

//
// Error:       cceNoTranslation
// Explanation: Character in input stream or string has no 
//              equivalent Unicode (multi-byte to Unicode) or
//              multi-byte (Unicode to multi-byte) character.
//              (Returned only if user requested errors for
//              invalid characters).
//
#define cceNoTranslation                (-10)

//
// Error:       cceInvalidChar
// Explanation: Converter found a single or multi-byte character
//              that is outside the legal range for the given
//              encoding.  (Returned only if user requested 
//              errors for invalid characters).
//
#define cceInvalidChar                  (-11)

//
// Error:       cceAmbiguousInput
// Explanation: CceDetectInputCode(), only.  Data matches more
//              than one of the supported encodings types.
//              (Returned only if function told to not resolve
//              ambiguity).
//
#define cceAmbiguousInput               (-12)

//
// Error:       cceUnknownInput
// Explanation: CceDetectInputCode(), only.  Data matches none
//              of the supported encoding types.
//
#define cceUnknownInput                 (-13)

//
// Error:       cceMayBeAscii
// Explanation: CceDetectInputCode(), only.  Technically, data
//              matches at least one of the supported encoding
//              types, but may not be a true match.  (For example,
//              an ASCII file with only a few scattered extended
//              characters).  (Returned only if function told to
//              resolve ambiguity).
//
//              This is not an error, only a flag to the calling
//              application.  CceDetectInputCode() will still set
//              the encoding type if it returns this value.
//
#define cceMayBeAscii                   (-14)

//
// Error:       cceInternal
// Explanation: Unrecoverable internal error.
//
#define cceInternal                     (-15)

//
// Error:       cceConvert
// Explanation: Unexpected DBCS function conversion error.
//
#define cceConvert                      (-16)

//
// Error:       cceEncodingNotImplemented
// Explanation: Temporary integration error.  Requested encoding
//              is not implemented.
//
#define cceEncodingNotImplemented       (-100)

//
// Error:       cceFunctionNotImplemented
// Explanation: Temporary integration error.  Function
//              is not implemented.
//
#define cceFunctionNotImplemented       (-101)



// ----------------------------------------------------------------------------
//
// General Definitions for Modules Using these Routines
// 
// ----------------------------------------------------------------------------

#define MSENAPI                 PASCAL
#define MSENCBACK               PASCAL
#define EXPIMPL(type)           type MSENAPI
#define EXPDECL(type)           extern type MSENAPI

// In case these are not already defined
//
#ifndef FAR
#ifdef _WIN32
#define FAR     __far
#else
#define FAR
#endif
#endif

typedef unsigned char UCHAR;
typedef UCHAR *PUCHAR;
typedef UCHAR FAR *LPUSTR;
typedef const UCHAR FAR *LPCUSTR;

#ifndef UNIX // IEUNIX uses 4 bytes WCHAR, these are already defined in winnt.h
typedef unsigned short WCHAR;
typedef WCHAR *PWCHAR;
typedef WCHAR FAR *LPWSTR;
typedef const WCHAR FAR *LPCWSTR;
#endif

//
// Character encoding types supported by this module.
//
typedef enum _cenc
    {
    ceNil = -1,
    ceEucCn = 0,
    ceEucJp,
    ceEucKr,
    ceIso2022Jp,
    ceIso2022Kr,
    ceBig5,
    ceGbk,
    ceHz,
    ceShiftJis,
    ceWansung,
    ceUtf7,
    ceUtf8,
    ceCount,
    };

typedef short CEnc;
    
//
// Encoding "families" (for CceDetectInputCode() preferences).
//
typedef enum _efam
    {
    efNone = 0,
    efDbcs,
    efEuc,
    efIso2022,
    efUtf8,
    } EFam;

//
// API private/reserved structure.  For most API functions,
// this structure must be zero-filled by calling application.
// See converter function documentation, below, for more
// information.
//
#define cdwReserved     4
typedef struct _ars
    {
    DWORD rgdw[cdwReserved];
    } ARS;

// For GetProcAddress()
typedef void (MSENAPI *PFNMSENCODEVER)(WORD FAR *, WORD FAR *);

// ----------------------------------------------------------------------------
//
// Input Code Auto-Detection Routine
// 
// ----------------------------------------------------------------------------

//
// Configuration Flags for Auto Detection Routine
// 
//   grfDetectResolveAmbiguity
//       The default is to return cceAmbiguousInput if the auto
//       detection code cannot definitely determine the encoding
//       of the input stream.  If this flag is set, the function
//       will use optional user preferences and the system code 
//       page to pick an encoding (note that in this case, the
//       "lpfGuess" flag will be set to fTrue upon return).
// 
//   grfDetectUseCharMapping
//       The default action of the auto-detection code is to 
//       parse the input against the known encoding types.  Legal 
//       character sequences are not analyzed for anything 
//       beyond syntactic correctness.  If this flag is set, 
//       auto-detect will map recognized sequences to flush out
//       invalid characters.
//
//       This option will cause auto-detection to run more 
//       slowly, but also yield more accurate results.
// 
//   grfDetectIgnoreEof
//       Because auto-detect parses byte sequences against the
//       the known encoding types, end-of-input in the middle of a 
//       sequence is obviously an error.  If the calling application
//       will artificially limit the sample size, set this flag
//       to ignore such end-of-input errors.
//
#define grfDetectResolveAmbiguity       0x1
#define grfDetectUseCharMapping         0x2
#define grfDetectIgnoreEof              0x4

//
// Entry Point -- Attempt to Detect the Encoding
//
//    Return cceAmbiguousInput if input is ambiguous or cceUnknownInput
//    if encoding type matches none of the known types.
//
//    Detected encoding is returned in lpCe.  lpfGuess used to return
//    a flag indicating whether or not the function "guessed" at an
//    encoding (chose default from ambiguous state).
//
//    User preferences for encoding family (efPref) and code page
//    (nPrefCp) are optional, even if caller chooses to have
//    this function attempt to resolve ambiguity.  If either has
//    the value 0, they will be ignored.
//
EXPDECL(CCE)
CceDetectInputCode(
    IStream   *pstmIn,           // input stream
    DWORD     dwFlags,          // configuration flags
    EFam      efPref,           // optional: preferred encoding family
    int       nPrefCp,          // optional: preferred code page
    UINT      *lpCe,                // set to detected encoding
    BOOL      *lpfGuess         // set to fTrue if function "guessed"
);

#endif          // #ifndef MSENCODE_H