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