/*

**********************************************************************

*   Copyright (C) 1999-2005, International Business Machines

*   Corporation and others.  All Rights Reserved.

**********************************************************************

 *  ucnv.h:

 *  External APIs for the ICU's codeset conversion library

 *  Bertrand A. Damiba

 *

 * Modification History:

 *

 *   Date        Name        Description

 *   04/04/99    helena      Fixed internal header inclusion.

 *   05/11/00    helena      Added setFallback and usesFallback APIs.

 *   06/29/2000  helena      Major rewrite of the callback APIs.

 *   12/07/2000  srl         Update of documentation

 */

/**

 * \file

 * \brief C API: Character conversion 

 *

 * <h2>Character Conversion C API</h2>

 *

 * <p>This API is used to convert codepage or character encoded data to and

 * from UTF-16. You can open a converter with {@link ucnv_open() }. With that

 * converter, you can get its properties, set options, convert your data and

 * close the converter.</p>

 *

 * <p>Since many software programs recogize different converter names for

 * different types of converters, there are other functions in this API to

 * iterate over the converter aliases. The functions {@link ucnv_getAvailableName() },

 * {@link ucnv_getAlias() } and {@link ucnv_getStandardName() } are some of the

 * more frequently used alias functions to get this information.</p>

 *

 * <p>When a converter encounters an illegal, irregular, invalid or unmappable character

 * its default behavior is to use a substitution character to replace the

 * bad byte sequence. This behavior can be changed by using {@link ucnv_setFromUCallBack() }

 * or {@link ucnv_setToUCallBack() } on the converter. The header ucnv_err.h defines

 * many other callback actions that can be used instead of a character substitution.</p>

 *

 * <p>More information about this API can be found in our 

 * <a href="http://icu.sourceforge.net/userguide/conversion.html">User's

 * Guide</a>.</p>

 */

#ifndef UCNV_H

#define UCNV_H

#include "unicode/ucnv_err.h"

#include "unicode/uenum.h"

#ifndef __USET_H__

/**

 * USet is the C API type for Unicode sets.

 * It is forward-declared here to avoid including the header file if related

 * conversion APIs are not used.

 * See unicode/uset.h

 *

 * @see ucnv_getUnicodeSet

 * @stable ICU 2.6

 */

struct USet;

/** @stable ICU 2.6 */

typedef struct USet USet;

#endif

#if !UCONFIG_NO_CONVERSION

U_CDECL_BEGIN

/** Maximum length of a converter name including the terminating NULL @stable ICU 2.0 */

#define UCNV_MAX_CONVERTER_NAME_LENGTH 60

/** Maximum length of a converter name including path and terminating NULL @stable ICU 2.0 */

#define UCNV_MAX_FULL_FILE_NAME_LENGTH (600+UCNV_MAX_CONVERTER_NAME_LENGTH)

/** Shift in for EBDCDIC_STATEFUL and iso2022 states @stable ICU 2.0 */

#define  UCNV_SI 0x0F

/** Shift out for EBDCDIC_STATEFUL and iso2022 states @stable ICU 2.0 */

#define  UCNV_SO 0x0E

/**

 * Enum for specifying basic types of converters

 * @see ucnv_getType

 * @stable ICU 2.0

 */

typedef enum {

    UCNV_UNSUPPORTED_CONVERTER = -1,

    UCNV_SBCS = 0,

    UCNV_DBCS = 1,

    UCNV_MBCS = 2,

    UCNV_LATIN_1 = 3,

    UCNV_UTF8 = 4,

    UCNV_UTF16_BigEndian = 5,

    UCNV_UTF16_LittleEndian = 6,

    UCNV_UTF32_BigEndian = 7,

    UCNV_UTF32_LittleEndian = 8,

    UCNV_EBCDIC_STATEFUL = 9,

    UCNV_ISO_2022 = 10,

    UCNV_LMBCS_1 = 11,

    UCNV_LMBCS_2, 

    UCNV_LMBCS_3,

    UCNV_LMBCS_4,

    UCNV_LMBCS_5,

    UCNV_LMBCS_6,

    UCNV_LMBCS_8,

    UCNV_LMBCS_11,

    UCNV_LMBCS_16,

    UCNV_LMBCS_17,

    UCNV_LMBCS_18,

    UCNV_LMBCS_19,

    UCNV_LMBCS_LAST = UCNV_LMBCS_19,

    UCNV_HZ,

    UCNV_SCSU,

    UCNV_ISCII,

    UCNV_US_ASCII,

    UCNV_UTF7,

    UCNV_BOCU1,

    UCNV_UTF16,

    UCNV_UTF32,

    UCNV_CESU8,

    UCNV_IMAP_MAILBOX,

    /* Number of converter types for which we have conversion routines. */

    UCNV_NUMBER_OF_SUPPORTED_CONVERTER_TYPES

} UConverterType;

/**

 * Enum for specifying which platform a converter ID refers to.

 * The use of platform/CCSID is not recommended. See ucnv_openCCSID().

 *

 * @see ucnv_getPlatform

 * @see ucnv_openCCSID

 * @see ucnv_getCCSID

 * @stable ICU 2.0

 */

typedef enum {

    UCNV_UNKNOWN = -1,

    UCNV_IBM = 0

} UConverterPlatform;

/**

 * Function pointer for error callback in the codepage to unicode direction.

 * Called when an error has occured in conversion to unicode, or on open/close of the callback (see reason).

 * @param context Pointer to the callback's private data

 * @param args Information about the conversion in progress

 * @param codeUnits Points to 'length' bytes of the concerned codepage sequence

 * @param length Size (in bytes) of the concerned codepage sequence

 * @param reason Defines the reason the callback was invoked

 * @param pErrorCode    ICU error code in/out parameter.

 *                      For converter callback functions, set to a conversion error

 *                      before the call, and the callback may reset it to U_ZERO_ERROR.

 * @see ucnv_setToUCallBack

 * @see UConverterToUnicodeArgs

 * @stable ICU 2.0

 */

typedef void (U_EXPORT2 *UConverterToUCallback) (

                  const void* context,

                  UConverterToUnicodeArgs *args,

                  const char *codeUnits,

                  int32_t length,

                  UConverterCallbackReason reason,

                  UErrorCode *pErrorCode);

/**

 * Function pointer for error callback in the unicode to codepage direction.

 * Called when an error has occured in conversion from unicode, or on open/close of the callback (see reason).

 * @param context Pointer to the callback's private data

 * @param args Information about the conversion in progress

 * @param codeUnits Points to 'length' UChars of the concerned Unicode sequence

 * @param length Size (in bytes) of the concerned codepage sequence

 * @param codePoint Single UChar32 (UTF-32) containing the concerend Unicode codepoint.

 * @param reason Defines the reason the callback was invoked

 * @param pErrorCode    ICU error code in/out parameter.

 *                      For converter callback functions, set to a conversion error

 *                      before the call, and the callback may reset it to U_ZERO_ERROR.

 * @see ucnv_setFromUCallBack

 * @stable ICU 2.0

 */

typedef void (U_EXPORT2 *UConverterFromUCallback) (

                    const void* context,

                    UConverterFromUnicodeArgs *args,

                    const UChar* codeUnits,

                    int32_t length,

                    UChar32 codePoint,

                    UConverterCallbackReason reason,

                    UErrorCode *pErrorCode);

U_CDECL_END

/**

 * Character that separates converter names from options and options from each other.

 * @see ucnv_open

 * @stable ICU 2.0

 */

#define UCNV_OPTION_SEP_CHAR ','

/**

 * String version of UCNV_OPTION_SEP_CHAR. 

 * @see ucnv_open

 * @stable ICU 2.0

 */

#define UCNV_OPTION_SEP_STRING ","

/**

 * Character that separates a converter option from its value.

 * @see ucnv_open

 * @stable ICU 2.0

 */

#define UCNV_VALUE_SEP_CHAR '='

/**

 * String version of UCNV_VALUE_SEP_CHAR. 

 * @see ucnv_open

 * @stable ICU 2.0

 */

#define UCNV_VALUE_SEP_STRING "="

/**

 * Converter option for specifying a locale.

 * For example, ucnv_open("SCSU,locale=ja", &errorCode);

 * See convrtrs.txt.

 *

 * @see ucnv_open

 * @stable ICU 2.0

 */

#define UCNV_LOCALE_OPTION_STRING ",locale="

/**

 * Converter option for specifying a version selector (0..9) for some converters.

 * For example, ucnv_open("UTF-7,version=1", &errorCode);

 * See convrtrs.txt.

 *

 * @see ucnv_open

 * @stable ICU 2.4

 */

#define UCNV_VERSION_OPTION_STRING ",version="

/**

 * Converter option for EBCDIC SBCS or mixed-SBCS/DBCS (stateful) codepages.

 * Swaps Unicode mappings for EBCDIC LF and NL codes, as used on

 * S/390 (z/OS) Unix System Services (Open Edition).

 * For example, ucnv_open("ibm-1047,swaplfnl", &errorCode);

 * See convrtrs.txt.

 *

 * @see ucnv_open

 * @stable ICU 2.4

 */

#define UCNV_SWAP_LFNL_OPTION_STRING ",swaplfnl"

/**

 * Do a fuzzy compare of a two converter/alias names.  The comparison

 * is case-insensitive.  It also ignores the characters '-', '_', and

 * ' ' (dash, underscore, and space).  Thus the strings "UTF-8",

 * "utf_8", and "Utf 8" are exactly equivalent.

 * 

 * @param name1 a converter name or alias, zero-terminated

 * @param name2 a converter name or alias, zero-terminated

 * @return 0 if the names match, or a negative value if the name1

 * lexically precedes name2, or a positive value if the name1

 * lexically follows name2.

 * @stable ICU 2.0

 */

U_STABLE int U_EXPORT2

ucnv_compareNames(const char *name1, const char *name2);

/**

 * Creates a UConverter object with the names specified as a C string.

 * The actual name will be resolved with the alias file

 * using a case-insensitive string comparison that ignores

 * the delimiters '-', '_', and ' ' (dash, underscore, and space).

 * E.g., the names "UTF8", "utf-8", and "Utf 8" are all equivalent.

 * If <code>NULL</code> is passed for the converter name, it will create one with the

 * getDefaultName return value.

 *

 * <p>A converter name for ICU 1.5 and above may contain options

 * like a locale specification to control the specific behavior of

 * the newly instantiated converter.

 * The meaning of the options depends on the particular converter.

 * If an option is not defined for or recognized by a given converter, then it is ignored.</p>

 *

 * <p>Options are appended to the converter name string, with a

 * <code>UCNV_OPTION_SEP_CHAR</code> between the name and the first option and

 * also between adjacent options.</p>

 *

 * <p>If the alias is ambiguous, then the preferred converter is used

 * and the status is set to U_AMBIGUOUS_ALIAS_WARNING.</p>

 *

 * <p>The conversion behavior and names can vary between platforms. ICU may

 * convert some characters differently from other platforms. Details on this topic

 * are in the <a href="http://icu.sourceforge.net/userguide/conversion.html">User's

 * Guide</a>.</p>

 *

 * @param converterName Name of the uconv table, may have options appended

 * @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR, U_FILE_ACCESS_ERROR</TT>

 * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured

 * @see ucnv_openU

 * @see ucnv_openCCSID

 * @see ucnv_close

 * @stable ICU 2.0

 */

U_STABLE UConverter* U_EXPORT2 

ucnv_open(const char *converterName, UErrorCode *err);

/**

 * Creates a Unicode converter with the names specified as unicode string. 

 * The name should be limited to the ASCII-7 alphanumerics range.

 * The actual name will be resolved with the alias file

 * using a case-insensitive string comparison that ignores

 * the delimiters '-', '_', and ' ' (dash, underscore, and space).

 * E.g., the names "UTF8", "utf-8", and "Utf 8" are all equivalent.

 * If <TT>NULL</TT> is passed for the converter name, it will create 

 * one with the ucnv_getDefaultName() return value.

 * If the alias is ambiguous, then the preferred converter is used

 * and the status is set to U_AMBIGUOUS_ALIAS_WARNING.

 * @param name : name of the uconv table in a zero terminated 

 *        Unicode string

 * @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR, 

 *        U_FILE_ACCESS_ERROR</TT>

 * @return the created Unicode converter object, or <TT>NULL</TT> if an 

 *        error occured

 * @see ucnv_open

 * @see ucnv_openCCSID

 * @see ucnv_close

 * @see ucnv_getDefaultName

 * @stable ICU 2.0

 */

U_STABLE UConverter* U_EXPORT2 

ucnv_openU(const UChar *name,

           UErrorCode *err);

/**

 * Creates a UConverter object from a CCSID number and platform pair.

 * Note that the usefulness of this function is limited to platforms with numeric

 * encoding IDs. Only IBM and Microsoft platforms use numeric (16-bit) identifiers for

 * encodings.

 *

 * In addition, IBM CCSIDs and Unicode conversion tables are not 1:1 related.

 * For many IBM CCSIDs there are multiple (up to six) Unicode conversion tables, and

 * for some Unicode conversion tables there are multiple CCSIDs.

 * Some "alternate" Unicode conversion tables are provided by the

 * IBM CDRA conversion table registry.

 * The most prominent example of a systematic modification of conversion tables that is

 * not provided in the form of conversion table files in the repository is

 * that S/390 Unix System Services swaps the codes for Line Feed and New Line in all

 * EBCDIC codepages, which requires such a swap in the Unicode conversion tables as well.

 *

 * Only IBM default conversion tables are accessible with ucnv_openCCSID().

 * ucnv_getCCSID() will return the same CCSID for all conversion tables that are associated

 * with that CCSID.

 *

 * Currently, the only "platform" supported in the ICU converter API is UCNV_IBM.

 *

 * In summary, the use of CCSIDs and the associated API functions is not recommended.

 *

 * In order to open a converter with the default IBM CDRA Unicode conversion table,

 * you can use this function or use the prefix "ibm-":

 * \code

 *     char name[20];

 *     sprintf(name, "ibm-%hu", ccsid);

 *     cnv=ucnv_open(name, &errorCode);

 * \endcode

 *

 * In order to open a converter with the IBM S/390 Unix System Services variant

 * of a Unicode/EBCDIC conversion table,

 * you can use the prefix "ibm-" together with the option string UCNV_SWAP_LFNL_OPTION_STRING:

 * \code

 *     char name[20];

 *     sprintf(name, "ibm-%hu" UCNV_SWAP_LFNL_OPTION_STRING, ccsid);

 *     cnv=ucnv_open(name, &errorCode);

 * \endcode

 *

 * In order to open a converter from a Microsoft codepage number, use the prefix "cp":

 * \code

 *     char name[20];

 *     sprintf(name, "cp%hu", codepageID);

 *     cnv=ucnv_open(name, &errorCode);

 * \endcode

 *

 * If the alias is ambiguous, then the preferred converter is used

 * and the status is set to U_AMBIGUOUS_ALIAS_WARNING.

 *

 * @param codepage codepage number to create

 * @param platform the platform in which the codepage number exists

 * @param err error status <TT>U_MEMORY_ALLOCATION_ERROR, U_FILE_ACCESS_ERROR</TT>

 * @return the created Unicode converter object, or <TT>NULL</TT> if an error

 *   occured.

 * @see ucnv_open

 * @see ucnv_openU

 * @see ucnv_close

 * @see ucnv_getCCSID

 * @see ucnv_getPlatform

 * @see UConverterPlatform

 * @stable ICU 2.0

 */

U_STABLE UConverter* U_EXPORT2

ucnv_openCCSID(int32_t codepage,

               UConverterPlatform platform,

               UErrorCode * err);

/**

 * <p>Creates a UConverter object specified from a packageName and a converterName.</p>

 * 

 * <p>The packageName and converterName must point to an ICU udata object, as defined by

 *   <code> udata_open( packageName, "cnv", converterName, err) </code> or equivalent.

 * Typically, packageName will refer to a (.dat) file, or to a package registered with

 * udata_setAppData(). Using a full file or directory pathname for packageName is deprecated.</p>

 * 

 * <p>The name will NOT be looked up in the alias mechanism, nor will the converter be

 * stored in the converter cache or the alias table. The only way to open further converters

 * is call this function multiple times, or use the ucnv_safeClone() function to clone a 

 * 'master' converter.</p>

 *

 * <p>A future version of ICU may add alias table lookups and/or caching

 * to this function.</p>

 * 

 * <p>Example Use:

 *      <code>cnv = ucnv_openPackage("myapp", "myconverter", &err);</code>

 * </p>

 *

 * @param packageName name of the package (equivalent to 'path' in udata_open() call)

 * @param converterName name of the data item to be used, without suffix.

 * @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR, U_FILE_ACCESS_ERROR</TT>

 * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured

 * @see udata_open

 * @see ucnv_open

 * @see ucnv_safeClone

 * @see ucnv_close

 * @stable ICU 2.2

 */

U_STABLE UConverter* U_EXPORT2 

ucnv_openPackage(const char *packageName, const char *converterName, UErrorCode *err);

/**

 * Thread safe converter cloning operation.

 * For most efficient operation, pass in a stackBuffer (and a *pBufferSize)

 * with at least U_CNV_SAFECLONE_BUFFERSIZE bytes of space.

 * If the buffer size is sufficient, then the clone will use the stack buffer;

 * otherwise, it will be allocated, and *pBufferSize will indicate

 * the actual size. (This should not occur with U_CNV_SAFECLONE_BUFFERSIZE.)

 *

 * You must ucnv_close() the clone in any case.

 *

 * If *pBufferSize==0, (regardless of whether stackBuffer==NULL or not)

 * then *pBufferSize will be changed to a sufficient size

 * for cloning this converter,

 * without actually cloning the converter ("pure pre-flighting").

 *

 * If *pBufferSize is greater than zero but not large enough for a stack-based

 * clone, then the converter is cloned using newly allocated memory

 * and *pBufferSize is changed to the necessary size.

 *

 * If the converter clone fits into the stack buffer but the stack buffer is not

 * sufficiently aligned for the clone, then the clone will use an

 * adjusted pointer and use an accordingly smaller buffer size.

 *

 * @param cnv converter to be cloned

 * @param stackBuffer user allocated space for the new clone. If NULL new memory will be allocated. 

 *  If buffer is not large enough, new memory will be allocated.

 *  Clients can use the U_CNV_SAFECLONE_BUFFERSIZE. This will probably be enough to avoid memory allocations.

 * @param pBufferSize pointer to size of allocated space. pBufferSize must not be NULL.

 * @param status to indicate whether the operation went on smoothly or there were errors

 *  An informational status value, U_SAFECLONE_ALLOCATED_WARNING,

 *  is used if any allocations were necessary.

 *  However, it is better to check if *pBufferSize grew for checking for

 *  allocations because warning codes can be overridden by subsequent

 *  function calls.

 * @return pointer to the new clone

 * @stable ICU 2.0

 */

U_STABLE UConverter * U_EXPORT2 

ucnv_safeClone(const UConverter *cnv, 

               void             *stackBuffer,

               int32_t          *pBufferSize, 

               UErrorCode       *status);

/**

 * \def U_CNV_SAFECLONE_BUFFERSIZE

 * Definition of a buffer size that is designed to be large enough for

 * converters to be cloned with ucnv_safeClone().

 * @stable ICU 2.0

 */

#define U_CNV_SAFECLONE_BUFFERSIZE  1024

/**

 * Deletes the unicode converter and releases resources associated

 * with just this instance.

 * Does not free up shared converter tables.

 *

 * @param converter the converter object to be deleted

 * @see ucnv_open

 * @see ucnv_openU

 * @see ucnv_openCCSID

 * @stable ICU 2.0

 */

U_STABLE void  U_EXPORT2

ucnv_close(UConverter * converter);

/**

 * Fills in the output parameter, subChars, with the substitution characters

 * as multiple bytes.

 *

 * @param converter the Unicode converter

 * @param subChars the subsitution characters

 * @param len on input the capacity of subChars, on output the number 

 * of bytes copied to it

 * @param  err the outgoing error status code.

 * If the substitution character array is too small, an

 * <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned.

 * @see ucnv_setSubstChars

 * @stable ICU 2.0

 */

U_STABLE void U_EXPORT2

ucnv_getSubstChars(const UConverter *converter,

                   char *subChars,

                   int8_t *len,

                   UErrorCode *err);

/**

 * Sets the substitution chars when converting from unicode to a codepage. The

 * substitution is specified as a string of 1-4 bytes, and may contain

 *  <TT>NULL</TT> byte.