Main Page   Class Hierarchy   Compound List   File List   Header Files   Sources   Compound Members   File Members  

ucnv.h

00001 /*
00002 **********************************************************************
00003 *   Copyright (C) 1999, International Business Machines
00004 *   Corporation and others.  All Rights Reserved.
00005 **********************************************************************
00006  *  ucnv.h:
00007  *  External APIs for the ICU's codeset conversion library
00008  *  Bertrand A. Damiba
00009  *
00010  * Modification History:
00011  *
00012  *   Date        Name        Description
00013  *   04/04/99    helena      Fixed internal header inclusion.
00014  *   05/11/00    helena      Added setFallback and usesFallback APIs.
00015  *   06/29/2000  helena      Major rewrite of the callback APIs.
00016  */
00017 
00025 #ifndef UCNV_H
00026 #define UCNV_H
00027 
00028 /* Forward declaring the UConverter structure */
00029 struct UConverter;
00030 typedef struct UConverter UConverter;
00031 
00032 #include "unicode/utypes.h"
00033 #include "unicode/ucnv_err.h"
00034 
00035 U_CDECL_BEGIN
00036 
00037 /*maximum length of the converter names */
00038 #define UCNV_MAX_CONVERTER_NAME_LENGTH 60
00039 #define UCNV_MAX_FULL_FILE_NAME_LENGTH (600+UCNV_MAX_CONVERTER_NAME_LENGTH)
00040 
00041 #define  UCNV_SI 0x0F           /*Shift in for EBDCDIC_STATEFUL and iso2022 states */
00042 #define  UCNV_SO 0x0E           /*Shift out for EBDCDIC_STATEFUL and iso2022 states */
00043 
00044 typedef enum {
00045     UCNV_UNSUPPORTED_CONVERTER = -1,
00046     UCNV_SBCS = 0,
00047     UCNV_DBCS = 1,
00048     UCNV_MBCS = 2,
00049     UCNV_LATIN_1 = 3,
00050     UCNV_UTF8 = 4,
00051     UCNV_UTF16_BigEndian = 5,
00052     UCNV_UTF16_LittleEndian = 6,
00053     UCNV_EBCDIC_STATEFUL = 7,
00054     UCNV_ISO_2022 = 8,
00055     
00056     UCNV_LMBCS_1 = 9,
00057     UCNV_LMBCS_2, 
00058     UCNV_LMBCS_3,               
00059     UCNV_LMBCS_4,
00060     UCNV_LMBCS_5,
00061     UCNV_LMBCS_6,
00062     UCNV_LMBCS_8,
00063     UCNV_LMBCS_11,
00064     UCNV_LMBCS_16,
00065     UCNV_LMBCS_17,
00066     UCNV_LMBCS_18,
00067     UCNV_LMBCS_19,
00068     UCNV_LMBCS_LAST = UCNV_LMBCS_19,
00069 
00070     /* Number of converter types for which we have conversion routines. */
00071     UCNV_NUMBER_OF_SUPPORTED_CONVERTER_TYPES = UCNV_LMBCS_LAST+1
00072    
00073 } UConverterType;
00074 
00075 typedef enum {
00076     UCNV_UNKNOWN = -1,
00077     UCNV_IBM = 0
00078 } UConverterPlatform;
00079 
00080 typedef void (*UConverterToUCallback) (
00081                   void* context,
00082                   UConverterToUnicodeArgs *args,
00083                   const char *codePoints,
00084                   int32_t length,
00085                   UConverterCallbackReason reason,
00086                                   UErrorCode *);
00087 
00088 typedef void (*UConverterFromUCallback) (
00089                     void* context,
00090                     UConverterFromUnicodeArgs *args,
00091                     const UChar* codeUnits,
00092                     int32_t length,
00093                     UChar32 codePoint, /* HSYS: why can't just use the macros on the code units? */
00094                     UConverterCallbackReason reason,
00095                                     UErrorCode *);
00096 
00097 U_CDECL_END
00098 
00103 #define UCNV_OPTION_SEP_CHAR ','
00104 
00106 #define UCNV_OPTION_SEP_STRING ","
00107 
00112 #define UCNV_VALUE_SEP_CHAR '='
00113 
00115 #define UCNV_VALUE_SEP_STRING "="
00116 
00121 #define UCNV_LOCALE_OPTION_STRING ",locale="
00122 
00151 U_CAPI
00152 UConverter* U_EXPORT2 ucnv_open   (const char *converterName, UErrorCode * err);
00153 
00154 
00172 U_CAPI UConverter* U_EXPORT2 ucnv_openU (const UChar * name,
00173                                          UErrorCode * err);
00174 
00175 
00176 
00190 U_CAPI UConverter* U_EXPORT2 ucnv_openCCSID (int32_t codepage,
00191                                            UConverterPlatform platform,
00192                        UErrorCode * err);
00193 
00194 
00204 U_CAPI void  U_EXPORT2 ucnv_close (UConverter * converter);
00205 
00206 
00207 
00222 U_CAPI void U_EXPORT2
00223     ucnv_getSubstChars (const UConverter * converter,
00224                         char *subChars,
00225                         int8_t * len,
00226                         UErrorCode * err);
00227 
00241 U_CAPI void U_EXPORT2
00242     ucnv_setSubstChars (UConverter * converter,
00243                         const char *subChars,
00244                         int8_t len,
00245                         UErrorCode * err);
00246 
00247 
00248 
00262 U_CAPI void U_EXPORT2
00263     ucnv_getInvalidChars (const UConverter * converter,
00264                           char *errBytes,
00265                           int8_t * len,
00266                           UErrorCode * err);
00267 
00268 
00282 U_CAPI void U_EXPORT2
00283     ucnv_getInvalidUChars (const UConverter * converter,
00284                            UChar *errUChars,
00285                            int8_t * len,
00286                            UErrorCode * err);
00287 
00296 U_CAPI void U_EXPORT2
00297     ucnv_reset (UConverter * converter);
00298 
00306 U_CAPI int8_t U_EXPORT2
00307     ucnv_getMaxCharSize (const UConverter * converter);
00308 
00309 
00318 U_CAPI int8_t U_EXPORT2
00319     ucnv_getMinCharSize (const UConverter * converter);
00320 
00321 
00336 U_CAPI
00337   int32_t U_EXPORT2 ucnv_getDisplayName (const UConverter * converter,
00338                                const char *displayLocale,
00339                                UChar * displayName,
00340                                int32_t displayNameCapacity,
00341                                UErrorCode * err);
00342 
00353 U_CAPI
00354   const char * U_EXPORT2 ucnv_getName (const UConverter * converter, UErrorCode * err);
00355 
00356 
00369 U_CAPI int32_t U_EXPORT2
00370     ucnv_getCCSID (const UConverter * converter,
00371                    UErrorCode * err);
00372 
00382 U_CAPI UConverterPlatform U_EXPORT2
00383     ucnv_getPlatform (const UConverter * converter,
00384                       UErrorCode * err);
00385 
00393 U_CAPI UConverterType U_EXPORT2
00394 ucnv_getType (const UConverter * converter);
00395 
00409 U_CAPI void U_EXPORT2 ucnv_getStarters(const UConverter* converter, 
00410                                      UBool starters[256],
00411                                      UErrorCode* err);
00412 
00413 
00423 U_CAPI void U_EXPORT2
00424     ucnv_getToUCallBack (const UConverter * converter,
00425                          UConverterToUCallback *action,
00426                          void **context);
00427 
00437 U_CAPI void U_EXPORT2
00438     ucnv_getFromUCallBack (const UConverter * converter,
00439                            UConverterFromUCallback *action,
00440                            void **context);
00441 
00454 U_CAPI void U_EXPORT2
00455     ucnv_setToUCallBack (UConverter * converter,
00456                          UConverterToUCallback newAction,
00457                          void* newContext,
00458              UConverterToUCallback *oldAction,
00459                          void** oldContext,
00460                          UErrorCode * err);
00461 
00474 U_CAPI void U_EXPORT2
00475     ucnv_setFromUCallBack (UConverter * converter,
00476                            UConverterFromUCallback newAction,
00477                            void *newContext,
00478                            UConverterFromUCallback *oldAction,
00479                void **oldContext,
00480                            UErrorCode * err);
00481 
00482 
00517 U_CAPI
00518   void U_EXPORT2 ucnv_fromUnicode (UConverter * converter,
00519                          char **target,
00520                          const char *targetLimit,
00521                          const UChar ** source,
00522                          const UChar * sourceLimit,
00523                          int32_t* offsets,
00524                          UBool flush,
00525                          UErrorCode * err);
00526 
00527 
00558 U_CAPI
00559   void U_EXPORT2 ucnv_toUnicode (UConverter * converter,
00560                        UChar ** target,
00561                        const UChar * targetLimit,
00562                        const char **source,
00563                        const char *sourceLimit,
00564                        int32_t* offsets,
00565                        UBool flush,
00566                        UErrorCode * err);
00567 
00568 
00593 U_CAPI
00594   int32_t U_EXPORT2 ucnv_fromUChars (const UConverter * converter,
00595                            char *target,
00596                            int32_t targetCapacity,
00597                            const UChar * source,
00598                int32_t sourceLength,
00599                            UErrorCode * err);
00600 
00601 
00602 
00603 
00604 
00632 U_CAPI
00633   int32_t U_EXPORT2 ucnv_toUChars (const UConverter * converter,
00634                          UChar * target,
00635                          int32_t targetCapacity,
00636                          const char *source,
00637                          int32_t sourceSize,
00638                          UErrorCode * err);
00639 
00640 /********************************
00641  * Will convert a codepage buffer one character at a time.
00642  * This function was written to be efficient when transcoding small amounts of data at a time.
00643  * In that case it will be more efficient than \Ref{ucnv_toUnicode}.
00644  * When converting large buffers use \Ref{ucnv_toUnicode}.
00645  *@param converter an open UConverter
00646  *@param source the address of a pointer to the codepage buffer, will be updated to point after
00647  *the bytes consumed in the conversion call.
00648  *@param points to the end of the input buffer
00649  *@param err fills in error status (see ucnv_toUnicode)
00650  * <code>U_INDEX_OUTOFBOUNDS_ERROR</code> will be set if the input is empty or does not convert
00651  * to any output (e.g.: pure state-change codes SI/SO, escape sequences for ISO 2022,
00652  * callback did not output anything, ...).
00653  * This function will not set a <code>U_BUFFER_OVERFLOW_ERROR</code> because the "buffer" is
00654  * the return code. However, there might be subsequent output stored in the converter object
00655  * that will be returned in following calls to this function.
00656  *@return a UChar32 resulting from the partial conversion of source
00657  *@see ucnv_toUnicode
00658  *@see ucnv_toUChars
00659  *@see ucnv_convert
00660  *@stable
00661  */
00662 U_CAPI
00663   UChar32 U_EXPORT2 ucnv_getNextUChar (UConverter * converter,
00664                            const char **source,
00665                            const char *sourceLimit,
00666                            UErrorCode * err);
00667 
00668 
00669 /**************************
00670 * Will convert a sequence of bytes from one codepage to another.
00671 * This is <STRONG>NOT AN EFFICIENT</STRONG> way to transcode.
00672 * use \Ref{ucnv_toUnicode} and \Ref{ucnv_fromUnicode} for efficiency
00673 * @param toConverterName: The name of the converter that will be used to encode the output buffer
00674 * @param fromConverterName: The name of the converter that will be used to decode the input buffer
00675 * @param target: Pointer to the output buffer to write to
00676 * @param targetCapacity: on input contains the capacity of target
00677 * @param source: Pointer to the input buffer
00678 * @param sourceLength: on input contains the capacity of source
00679 * @param err: fills in an error status
00680 * <code>U_BUFFER_OVERFLOW_ERROR</code> will be set if the target is full and there is still input left in the source.
00681 * @return  will be filled in with the number of bytes needed in target
00682 * @see ucnv_fromUnicode
00683 * @see ucnv_toUnicode
00684 * @see ucnv_fromUChars
00685 * @see ucnv_toUChars
00686 * @see ucnv_getNextUChar
00687 * @draft backslash versus Yen sign in shift-JIS
00688 */
00689 U_CAPI
00690   int32_t U_EXPORT2 ucnv_convert (const char *toConverterName,
00691                         const char *fromConverterName,
00692                         char *target,
00693                         int32_t targetCapacity,
00694                         const char *source,
00695                         int32_t sourceLength,
00696                         UErrorCode * err);
00697 
00706 U_CAPI int32_t U_EXPORT2 ucnv_flushCache (void);
00707 
00708 
00717 U_CAPI
00718   const char * U_EXPORT2 ucnv_getAvailableName (int32_t n);
00719 
00727 U_CAPI int32_t U_EXPORT2 ucnv_countAvailable (void);
00728 
00729 
00739 U_CAPI uint16_t
00740 ucnv_countAliases(const char *alias, UErrorCode *pErrorCode);
00741 
00752 U_CAPI const char *
00753 ucnv_getAlias(const char *alias, uint16_t n, UErrorCode *pErrorCode);
00754 
00766 U_CAPI void
00767 ucnv_getAliases(const char *alias, const char **aliases, UErrorCode *pErrorCode);
00768 
00774 U_CAPI uint16_t
00775 ucnv_countStandards(void);
00776 
00784 U_CAPI const char *
00785 ucnv_getStandard(uint16_t n, UErrorCode *pErrorCode);
00786 
00798 U_CAPI const char *ucnv_getStandardName(const char *name, const char *standard, UErrorCode *pErrorCode);
00799 
00809 U_CAPI const char * U_EXPORT2 ucnv_getDefaultName (void);
00810 
00818 U_CAPI void U_EXPORT2 ucnv_setDefaultName (const char *name);
00819 
00831 U_CAPI void U_EXPORT2 ucnv_fixFileSeparator(const UConverter *cnv, UChar* source, int32_t sourceLen);
00832 
00840 U_CAPI UBool U_EXPORT2 ucnv_isAmbiguous(const UConverter *cnv);
00841 
00849 U_CAPI void U_EXPORT2 ucnv_setFallback(UConverter *cnv, UBool usesFallback);
00850 
00856 U_CAPI UBool U_EXPORT2 ucnv_usesFallback(const UConverter *cnv);
00857 
00858 #endif
00859 /*_UCNV*/
00860 
00861 

Generated at Wed Aug 16 16:05:36 2000 for ICU1.6 by doxygen 1.0.0 written by Dimitri van Heesch, © 1997-1999