sl@0: /*
sl@0: **********************************************************************
sl@0: *   Copyright (C) 1999-2004, International Business Machines
sl@0: *   Corporation and others.  All Rights Reserved.
sl@0: **********************************************************************
sl@0: *
sl@0: *   uconv_cnv.h:
sl@0: *   defines all the low level conversion functions
sl@0: *   T_UnicodeConverter_{to,from}Unicode_$ConversionType
sl@0: *
sl@0: * Modification History:
sl@0: *
sl@0: *   Date        Name        Description
sl@0: *   05/09/00    helena      Added implementation to handle fallback mappings.
sl@0: *   06/29/2000  helena      Major rewrite of the callback APIs.
sl@0: */
sl@0: 
sl@0: #ifndef UCNV_CNV_H
sl@0: #define UCNV_CNV_H
sl@0: 
sl@0: #include "unicode/utypes.h"
sl@0: 
sl@0: #if !UCONFIG_NO_CONVERSION
sl@0: 
sl@0: #include "unicode/ucnv.h"
sl@0: #include "unicode/ucnv_err.h"
sl@0: #include "unicode/uset.h"
sl@0: #include "uset_imp.h"
sl@0: 
sl@0: U_CDECL_BEGIN
sl@0: 
sl@0: /* this is used in fromUnicode DBCS tables as an "unassigned" marker */
sl@0: #define missingCharMarker 0xFFFF
sl@0: 
sl@0: /*
sl@0:  * #define missingUCharMarker 0xfffe
sl@0:  *
sl@0:  * commented out because there are actually two values used in toUnicode tables:
sl@0:  * U+fffe "unassigned"
sl@0:  * U+ffff "illegal"
sl@0:  */
sl@0: 
sl@0: /** Forward declaration, see ucnv_bld.h */
sl@0: struct UConverterSharedData;
sl@0: typedef struct UConverterSharedData UConverterSharedData;
sl@0: 
sl@0: /* function types for UConverterImpl ---------------------------------------- */
sl@0: 
sl@0: /* struct with arguments for UConverterLoad and ucnv_load() */
sl@0: typedef struct {
sl@0:     int32_t size;               /* sizeof(UConverterLoadArgs) */
sl@0:     int32_t nestedLoads;        /* count nested ucnv_load() calls */
sl@0:     int32_t reserved;           /* reserved - for good alignment of the pointers */
sl@0:     uint32_t options;
sl@0:     const char *pkg, *name;
sl@0: } UConverterLoadArgs;
sl@0: 
sl@0: typedef void (*UConverterLoad) (UConverterSharedData *sharedData,
sl@0:                                 UConverterLoadArgs *pArgs,
sl@0:                                 const uint8_t *raw, UErrorCode *pErrorCode);
sl@0: typedef void (*UConverterUnload) (UConverterSharedData *sharedData);
sl@0: 
sl@0: typedef void (*UConverterOpen) (UConverter *cnv, const char *name, const char *locale,uint32_t options, UErrorCode *pErrorCode);
sl@0: typedef void (*UConverterClose) (UConverter *cnv);
sl@0: 
sl@0: typedef enum UConverterResetChoice {
sl@0:     UCNV_RESET_BOTH,
sl@0:     UCNV_RESET_TO_UNICODE,
sl@0:     UCNV_RESET_FROM_UNICODE
sl@0: } UConverterResetChoice;
sl@0: 
sl@0: typedef void (*UConverterReset) (UConverter *cnv, UConverterResetChoice choice);
sl@0: 
sl@0: /*
sl@0:  * Converter implementation function(s) for ucnv_toUnicode().
sl@0:  * If the toUnicodeWithOffsets function pointer is NULL,
sl@0:  * then the toUnicode function will be used and the offsets will be set to -1.
sl@0:  *
sl@0:  * Must maintain state across buffers. Use toUBytes[toULength] for partial input
sl@0:  * sequences; it will be checked in ucnv.c at the end of the input stream
sl@0:  * to detect truncated input.
sl@0:  * Some converters may need additional detection and may then set U_TRUNCATED_CHAR_FOUND.
sl@0:  *
sl@0:  * The toUnicodeWithOffsets must write exactly as many offset values as target
sl@0:  * units. Write offset values of -1 for when the source index corresponding to
sl@0:  * the output unit is not known (e.g., the character started in an earlier buffer).
sl@0:  * The pArgs->offsets pointer need not be moved forward.
sl@0:  *
sl@0:  * At function return, either one of the following conditions must be true:
sl@0:  * - U_BUFFER_OVERFLOW_ERROR and the target is full: target==targetLimit
sl@0:  * - another error code with toUBytes[toULength] set to the offending input
sl@0:  * - no error, and the source is consumed: source==sourceLimit
sl@0:  *
sl@0:  * The ucnv.c code will handle the end of the input (reset)
sl@0:  * (reset, and truncation detection) and callbacks.
sl@0:  */
sl@0: typedef void (*UConverterToUnicode) (UConverterToUnicodeArgs *, UErrorCode *);
sl@0: 
sl@0: /*
sl@0:  * Same rules as for UConverterToUnicode.
sl@0:  * A lead surrogate is kept in fromUChar32 across buffers, and if an error
sl@0:  * occurs, then the offending input code point must be put into fromUChar32
sl@0:  * as well.
sl@0:  */
sl@0: typedef void (*UConverterFromUnicode) (UConverterFromUnicodeArgs *, UErrorCode *);
sl@0: 
sl@0: /*
sl@0:  * Converter implementation function for ucnv_getNextUChar().
sl@0:  * If the function pointer is NULL, then the toUnicode function will be used.
sl@0:  *
sl@0:  * Will be called at a character boundary (toULength==0).
sl@0:  * May return with
sl@0:  * - U_INDEX_OUTOFBOUNDS_ERROR if there was no output for the input
sl@0:  *   (the return value will be ignored)
sl@0:  * - U_TRUNCATED_CHAR_FOUND or another error code (never U_BUFFER_OVERFLOW_ERROR!)
sl@0:  *   with toUBytes[toULength] set to the offending input
sl@0:  *   (the return value will be ignored)
sl@0:  * - return UCNV_GET_NEXT_UCHAR_USE_TO_U, without moving the source pointer,
sl@0:  *   to indicate that the ucnv.c code shall call the toUnicode function instead
sl@0:  * - return a real code point result
sl@0:  *
sl@0:  * Unless UCNV_GET_NEXT_UCHAR_USE_TO_U is returned, the source bytes must be consumed.
sl@0:  *
sl@0:  * The ucnv.c code will handle the end of the input (reset)
sl@0:  * (except for truncation detection!) and callbacks.
sl@0:  */
sl@0: typedef UChar32 (*UConverterGetNextUChar) (UConverterToUnicodeArgs *, UErrorCode *);
sl@0: 
sl@0: typedef void (*UConverterGetStarters)(const UConverter* converter,
sl@0:                                       UBool starters[256],
sl@0:                                       UErrorCode *pErrorCode);
sl@0: 
sl@0: /* If this function pointer is null or if the function returns null
sl@0:  * the name field in static data struct should be returned by 
sl@0:  * ucnv_getName() API function
sl@0:  */
sl@0: typedef const char * (*UConverterGetName) (const UConverter *cnv);
sl@0: 
sl@0: /**
sl@0:  * Write the codepage substitution character.
sl@0:  * If this function is not set, then ucnv_cbFromUWriteSub() writes
sl@0:  * the substitution character from UConverter.
sl@0:  * For stateful converters, it is typically necessary to handle this
sl@0:  * specificially for the converter in order to properly maintain the state.
sl@0:  */
sl@0: typedef void (*UConverterWriteSub) (UConverterFromUnicodeArgs *pArgs, int32_t offsetIndex, UErrorCode *pErrorCode);
sl@0: 
sl@0: /**
sl@0:  * For converter-specific safeClone processing
sl@0:  * If this function is not set, then ucnv_safeClone assumes that the converter has no private data that changes
sl@0:  * after the converter is done opening.
sl@0:  * If this function is set, then it is called just after a memcpy() of
sl@0:  * converter data to the new, empty converter, and is expected to set up
sl@0:  * the initial state of the converter.  It is not expected to increment the
sl@0:  * reference counts of the standard data types such as the shared data.
sl@0:  */
sl@0: typedef UConverter * (*UConverterSafeClone) (const UConverter   *cnv, 
sl@0:                                              void               *stackBuffer,
sl@0:                                              int32_t            *pBufferSize, 
sl@0:                                              UErrorCode         *status);
sl@0: 
sl@0: /**
sl@0:  * Fills the set of Unicode code points that can be converted by an ICU converter.
sl@0:  * The API function ucnv_getUnicodeSet() clears the USet before calling
sl@0:  * the converter's getUnicodeSet() implementation; the converter should only
sl@0:  * add the appropriate code points to allow recursive use.
sl@0:  * For example, the ISO-2022-JP converter will call each subconverter's
sl@0:  * getUnicodeSet() implementation to consecutively add code points to
sl@0:  * the same USet, which will result in a union of the sets of all subconverters.
sl@0:  *
sl@0:  * For more documentation, see ucnv_getUnicodeSet() in ucnv.h.
sl@0:  */
sl@0: typedef void (*UConverterGetUnicodeSet) (const UConverter *cnv,
sl@0:                                          const USetAdder *sa,
sl@0:                                          UConverterUnicodeSet which,
sl@0:                                          UErrorCode *pErrorCode);
sl@0: 
sl@0: UBool CONVERSION_U_SUCCESS (UErrorCode err);
sl@0: 
sl@0: /**
sl@0:  * UConverterImpl contains all the data and functions for a converter type.
sl@0:  * Its function pointers work much like a C++ vtable.
sl@0:  * Many converter types need to define only a subset of the functions;
sl@0:  * when a function pointer is NULL, then a default action will be performed.
sl@0:  *
sl@0:  * Every converter type must implement toUnicode, fromUnicode, and getNextUChar,
sl@0:  * otherwise the converter may crash.
sl@0:  * Every converter type that has variable-length codepage sequences should
sl@0:  * also implement toUnicodeWithOffsets and fromUnicodeWithOffsets for
sl@0:  * correct offset handling.
sl@0:  * All other functions may or may not be implemented - it depends only on
sl@0:  * whether the converter type needs them.
sl@0:  *
sl@0:  * When open() fails, then close() will be called, if present.
sl@0:  */
sl@0: struct UConverterImpl {
sl@0:     UConverterType type;
sl@0: 
sl@0:     UConverterLoad load;
sl@0:     UConverterUnload unload;
sl@0: 
sl@0:     UConverterOpen open;
sl@0:     UConverterClose close;
sl@0:     UConverterReset reset;
sl@0: 
sl@0:     UConverterToUnicode toUnicode;
sl@0:     UConverterToUnicode toUnicodeWithOffsets;
sl@0:     UConverterFromUnicode fromUnicode;
sl@0:     UConverterFromUnicode fromUnicodeWithOffsets;
sl@0:     UConverterGetNextUChar getNextUChar;
sl@0: 
sl@0:     UConverterGetStarters getStarters;
sl@0:     UConverterGetName getName;
sl@0:     UConverterWriteSub writeSub;
sl@0:     UConverterSafeClone safeClone;
sl@0:     UConverterGetUnicodeSet getUnicodeSet;
sl@0: };
sl@0: 
sl@0: extern const UConverterSharedData
sl@0:     _MBCSData, _Latin1Data,
sl@0:     _UTF8Data, _UTF16BEData, _UTF16LEData, _UTF32BEData, _UTF32LEData,
sl@0:     _ISO2022Data, 
sl@0:     _LMBCSData1,_LMBCSData2, _LMBCSData3, _LMBCSData4, _LMBCSData5, _LMBCSData6,
sl@0:     _LMBCSData8,_LMBCSData11,_LMBCSData16,_LMBCSData17,_LMBCSData18,_LMBCSData19,
sl@0:     _HZData,_ISCIIData, _SCSUData, _ASCIIData,
sl@0:     _UTF7Data, _Bocu1Data, _UTF16Data, _UTF32Data, _CESU8Data, _IMAPData;
sl@0: 
sl@0: U_CDECL_END
sl@0: 
sl@0: /** Always use fallbacks from codepage to Unicode */
sl@0: #define TO_U_USE_FALLBACK(useFallback) TRUE
sl@0: #define UCNV_TO_U_USE_FALLBACK(cnv) TRUE
sl@0: 
sl@0: /** Use fallbacks from Unicode to codepage when cnv->useFallback or for private-use code points */
sl@0: #define IS_PRIVATE_USE(c) ((uint32_t)((c)-0xe000)<0x1900 || (uint32_t)((c)-0xf0000)<0x20000)
sl@0: #define FROM_U_USE_FALLBACK(useFallback, c) ((useFallback) || IS_PRIVATE_USE(c))
sl@0: #define UCNV_FROM_U_USE_FALLBACK(cnv, c) FROM_U_USE_FALLBACK((cnv)->useFallback, c)
sl@0: 
sl@0: /**
sl@0:  * Magic number for ucnv_getNextUChar(), returned by a
sl@0:  * getNextUChar() implementation to indicate to use the converter's toUnicode()
sl@0:  * instead of the native function.
sl@0:  * @internal
sl@0:  */
sl@0: #define UCNV_GET_NEXT_UCHAR_USE_TO_U -9
sl@0: 
sl@0: U_CFUNC void
sl@0: ucnv_getCompleteUnicodeSet(const UConverter *cnv,
sl@0:                    const USetAdder *sa,
sl@0:                    UConverterUnicodeSet which,
sl@0:                    UErrorCode *pErrorCode);
sl@0: 
sl@0: U_CFUNC void
sl@0: ucnv_getNonSurrogateUnicodeSet(const UConverter *cnv,
sl@0:                                const USetAdder *sa,
sl@0:                                UConverterUnicodeSet which,
sl@0:                                UErrorCode *pErrorCode);
sl@0: 
sl@0: U_CFUNC void
sl@0: ucnv_fromUWriteBytes(UConverter *cnv,
sl@0:                      const char *bytes, int32_t length,
sl@0:                      char **target, const char *targetLimit,
sl@0:                      int32_t **offsets,
sl@0:                      int32_t sourceIndex,
sl@0:                      UErrorCode *pErrorCode);
sl@0: U_CFUNC void
sl@0: ucnv_toUWriteUChars(UConverter *cnv,
sl@0:                     const UChar *uchars, int32_t length,
sl@0:                     UChar **target, const UChar *targetLimit,
sl@0:                     int32_t **offsets,
sl@0:                     int32_t sourceIndex,
sl@0:                     UErrorCode *pErrorCode);
sl@0: 
sl@0: U_CFUNC void
sl@0: ucnv_toUWriteCodePoint(UConverter *cnv,
sl@0:                        UChar32 c,
sl@0:                        UChar **target, const UChar *targetLimit,
sl@0:                        int32_t **offsets,
sl@0:                        int32_t sourceIndex,
sl@0:                        UErrorCode *pErrorCode);
sl@0: 
sl@0: #endif
sl@0: 
sl@0: #endif /* UCNV_CNV */