1b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/* 2b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru********************************************************************** 359d709d503bab6e2b61931737e662dd293b40578ccornelius* Copyright (C) 1999-2013, International Business Machines 4b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru* Corporation and others. All Rights Reserved. 5b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru********************************************************************** 6b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv.h: 7b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * External APIs for the ICU's codeset conversion library 8b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Bertrand A. Damiba 9b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 10b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Modification History: 11b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 12b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Date Name Description 13b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 04/04/99 helena Fixed internal header inclusion. 14b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 05/11/00 helena Added setFallback and usesFallback APIs. 15b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 06/29/2000 helena Major rewrite of the callback APIs. 16b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 12/07/2000 srl Update of documentation 17b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 18b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 19b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 20b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \file 21b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \brief C API: Character conversion 22b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 23b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <h2>Character Conversion C API</h2> 24b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 25b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>This API is used to convert codepage or character encoded data to and 26b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * from UTF-16. You can open a converter with {@link ucnv_open() }. With that 27b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * converter, you can get its properties, set options, convert your data and 28b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * close the converter.</p> 29b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 30b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>Since many software programs recogize different converter names for 31b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * different types of converters, there are other functions in this API to 32b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * iterate over the converter aliases. The functions {@link ucnv_getAvailableName() }, 33b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * {@link ucnv_getAlias() } and {@link ucnv_getStandardName() } are some of the 34b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * more frequently used alias functions to get this information.</p> 35b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 36b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>When a converter encounters an illegal, irregular, invalid or unmappable character 37b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * its default behavior is to use a substitution character to replace the 38b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * bad byte sequence. This behavior can be changed by using {@link ucnv_setFromUCallBack() } 39b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * or {@link ucnv_setToUCallBack() } on the converter. The header ucnv_err.h defines 40b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * many other callback actions that can be used instead of a character substitution.</p> 41b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 42b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>More information about this API can be found in our 43b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <a href="http://icu-project.org/userguide/conversion.html">User's 44b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Guide</a>.</p> 45b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 46b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 47b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#ifndef UCNV_H 48b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_H 49b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 50b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#include "unicode/ucnv_err.h" 51b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#include "unicode/uenum.h" 5250294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho#include "unicode/localpointer.h" 53b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 54b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#ifndef __USET_H__ 55b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 56b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 57b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * USet is the C API type for Unicode sets. 58b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It is forward-declared here to avoid including the header file if related 59b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conversion APIs are not used. 60b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * See unicode/uset.h 61b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 62b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getUnicodeSet 63b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.6 64b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 65b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Querustruct USet; 66b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** @stable ICU 2.6 */ 67b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Querutypedef struct USet USet; 68b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 69b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#endif 70b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 71b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#if !UCONFIG_NO_CONVERSION 72b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 73b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_CDECL_BEGIN 74b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 75b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** Maximum length of a converter name including the terminating NULL @stable ICU 2.0 */ 76b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_MAX_CONVERTER_NAME_LENGTH 60 77b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** Maximum length of a converter name including path and terminating NULL @stable ICU 2.0 */ 78b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_MAX_FULL_FILE_NAME_LENGTH (600+UCNV_MAX_CONVERTER_NAME_LENGTH) 79b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 80b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** Shift in for EBDCDIC_STATEFUL and iso2022 states @stable ICU 2.0 */ 81b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_SI 0x0F 82b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** Shift out for EBDCDIC_STATEFUL and iso2022 states @stable ICU 2.0 */ 83b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_SO 0x0E 84b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 85b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 86b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Enum for specifying basic types of converters 87b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getType 88b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 89b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 90b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Querutypedef enum { 91b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 92b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UNSUPPORTED_CONVERTER = -1, 93b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 94b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_SBCS = 0, 95b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 96b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_DBCS = 1, 97b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 98b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_MBCS = 2, 99b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 100b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LATIN_1 = 3, 101b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 102b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UTF8 = 4, 103b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 104b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UTF16_BigEndian = 5, 105b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 106b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UTF16_LittleEndian = 6, 107b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 108b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UTF32_BigEndian = 7, 109b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 110b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UTF32_LittleEndian = 8, 111b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 112b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_EBCDIC_STATEFUL = 9, 113b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 114b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_ISO_2022 = 10, 115b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 116b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 117b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_1 = 11, 118b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 119b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_2, 120b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 121b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_3, 122b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 123b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_4, 124b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 125b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_5, 126b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 127b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_6, 128b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 129b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_8, 130b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 131b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_11, 132b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 133b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_16, 134b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 135b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_17, 136b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 137b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_18, 138b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 139b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_19, 140b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 141b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_LMBCS_LAST = UCNV_LMBCS_19, 142b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 143b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_HZ, 144b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 145b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_SCSU, 146b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 147b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_ISCII, 148b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 149b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_US_ASCII, 150b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.0 */ 151b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UTF7, 152b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.2 */ 153b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_BOCU1, 154b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.2 */ 155b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UTF16, 156b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.2 */ 157b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UTF32, 158b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.2 */ 159b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_CESU8, 160b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho /** @stable ICU 2.4 */ 161b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_IMAP_MAILBOX, 16254dcd9b6a06071f647dac967e9e267abb9410720Craig Cornelius /** @stable ICU 4.8 */ 163b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho UCNV_COMPOUND_TEXT, 164b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 165b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru /* Number of converter types for which we have conversion routines. */ 166b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_NUMBER_OF_SUPPORTED_CONVERTER_TYPES 167b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru} UConverterType; 168b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 169b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 170b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Enum for specifying which platform a converter ID refers to. 171b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The use of platform/CCSID is not recommended. See ucnv_openCCSID(). 172b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 173b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getPlatform 174b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_openCCSID 175b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getCCSID 176b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 177b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 178b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Querutypedef enum { 179b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_UNKNOWN = -1, 180b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_IBM = 0 181b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru} UConverterPlatform; 182b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 183b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 184b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Function pointer for error callback in the codepage to unicode direction. 185b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Called when an error has occured in conversion to unicode, or on open/close of the callback (see reason). 186b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param context Pointer to the callback's private data 187b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param args Information about the conversion in progress 188b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param codeUnits Points to 'length' bytes of the concerned codepage sequence 189b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param length Size (in bytes) of the concerned codepage sequence 190b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param reason Defines the reason the callback was invoked 191b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode ICU error code in/out parameter. 192b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For converter callback functions, set to a conversion error 193b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * before the call, and the callback may reset it to U_ZERO_ERROR. 194b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setToUCallBack 195b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see UConverterToUnicodeArgs 196b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 197b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 198b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Querutypedef void (U_EXPORT2 *UConverterToUCallback) ( 199b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const void* context, 200b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterToUnicodeArgs *args, 201b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *codeUnits, 202b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t length, 203b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterCallbackReason reason, 204b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 205b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 206b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 207b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Function pointer for error callback in the unicode to codepage direction. 208b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Called when an error has occured in conversion from unicode, or on open/close of the callback (see reason). 209b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param context Pointer to the callback's private data 210b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param args Information about the conversion in progress 211b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param codeUnits Points to 'length' UChars of the concerned Unicode sequence 212b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param length Size (in bytes) of the concerned codepage sequence 213b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param codePoint Single UChar32 (UTF-32) containing the concerend Unicode codepoint. 214b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param reason Defines the reason the callback was invoked 215b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode ICU error code in/out parameter. 216b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For converter callback functions, set to a conversion error 217b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * before the call, and the callback may reset it to U_ZERO_ERROR. 218b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setFromUCallBack 219b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 220b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 221b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Querutypedef void (U_EXPORT2 *UConverterFromUCallback) ( 222b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const void* context, 223b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterFromUnicodeArgs *args, 224b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const UChar* codeUnits, 225b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t length, 226b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UChar32 codePoint, 227b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterCallbackReason reason, 228b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 229b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 230b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_CDECL_END 231b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 232b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 233b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Character that separates converter names from options and options from each other. 234b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 235b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 236b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 237b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_OPTION_SEP_CHAR ',' 238b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 239b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 240b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * String version of UCNV_OPTION_SEP_CHAR. 241b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 242b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 243b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 244b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_OPTION_SEP_STRING "," 245b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 246b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 247b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Character that separates a converter option from its value. 248b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 249b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 250b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 251b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_VALUE_SEP_CHAR '=' 252b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 253b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 254b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * String version of UCNV_VALUE_SEP_CHAR. 255b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 256b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 257b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 258b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_VALUE_SEP_STRING "=" 259b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 260b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 261b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Converter option for specifying a locale. 262b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For example, ucnv_open("SCSU,locale=ja", &errorCode); 263b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * See convrtrs.txt. 264b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 265b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 266b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 267b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 268b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_LOCALE_OPTION_STRING ",locale=" 269b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 270b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 271b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Converter option for specifying a version selector (0..9) for some converters. 272b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * For example, 273b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * \code 274b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * ucnv_open("UTF-7,version=1", &errorCode); 275b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * \endcode 276b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * See convrtrs.txt. 277b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 278b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 279b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.4 280b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 281b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_VERSION_OPTION_STRING ",version=" 282b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 283b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 284b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Converter option for EBCDIC SBCS or mixed-SBCS/DBCS (stateful) codepages. 285b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Swaps Unicode mappings for EBCDIC LF and NL codes, as used on 286b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * S/390 (z/OS) Unix System Services (Open Edition). 287b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For example, ucnv_open("ibm-1047,swaplfnl", &errorCode); 288b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * See convrtrs.txt. 289b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 290b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 291b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.4 292b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 293b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_SWAP_LFNL_OPTION_STRING ",swaplfnl" 294b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 295b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 296b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Do a fuzzy compare of two converter/alias names. 297b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The comparison is case-insensitive, ignores leading zeroes if they are not 298b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * followed by further digits, and ignores all but letters and digits. 299b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Thus the strings "UTF-8", "utf_8", "u*T@f08" and "Utf 8" are exactly equivalent. 300b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * See section 1.4, Charset Alias Matching in Unicode Technical Standard #22 301b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * at http://www.unicode.org/reports/tr22/ 302b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 303b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param name1 a converter name or alias, zero-terminated 304b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param name2 a converter name or alias, zero-terminated 305b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return 0 if the names match, or a negative value if the name1 306b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * lexically precedes name2, or a positive value if the name1 307b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * lexically follows name2. 308b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 309b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 310b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int U_EXPORT2 311b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_compareNames(const char *name1, const char *name2); 312b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 313b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 314b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 315b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Creates a UConverter object with the name of a coded character set specified as a C string. 316b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The actual name will be resolved with the alias file 317b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * using a case-insensitive string comparison that ignores 318b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * leading zeroes and all non-alphanumeric characters. 319b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * E.g., the names "UTF8", "utf-8", "u*T@f08" and "Utf 8" are all equivalent. 320b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (See also ucnv_compareNames().) 321b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If <code>NULL</code> is passed for the converter name, it will create one with the 322b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * getDefaultName return value. 323b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 324b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>A converter name for ICU 1.5 and above may contain options 325b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * like a locale specification to control the specific behavior of 326b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the newly instantiated converter. 327b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The meaning of the options depends on the particular converter. 328b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If an option is not defined for or recognized by a given converter, then it is ignored.</p> 329b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 330b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>Options are appended to the converter name string, with a 331b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <code>UCNV_OPTION_SEP_CHAR</code> between the name and the first option and 332b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * also between adjacent options.</p> 333b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 334b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>If the alias is ambiguous, then the preferred converter is used 335b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and the status is set to U_AMBIGUOUS_ALIAS_WARNING.</p> 336b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 337b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>The conversion behavior and names can vary between platforms. ICU may 338b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * convert some characters differently from other platforms. Details on this topic 339b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * are in the <a href="http://icu-project.org/userguide/conversion.html">User's 340b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Guide</a>. Aliases starting with a "cp" prefix have no specific meaning 341b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * other than its an alias starting with the letters "cp". Please do not 342b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * associate any meaning to these aliases.</p> 343b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 344103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * \snippet samples/ucnv/convsamp.cpp ucnv_open 345103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * 346b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converterName Name of the coded character set table. 347b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This may have options appended to the string. 348b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * IANA alias character set names, IBM CCSIDs starting with "ibm-", 349b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Windows codepage numbers starting with "windows-" are frequently 350b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * used for this parameter. See ucnv_getAvailableName and 351b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_getAlias for a complete list that is available. 352b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If this parameter is NULL, the default converter will be used. 353b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR, U_FILE_ACCESS_ERROR</TT> 354b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured 355b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_openU 356b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_openCCSID 357b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getAvailableName 358b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getAlias 359b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getDefaultName 360b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_close 361c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * @see ucnv_compareNames 362b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 363b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 364b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UConverter* U_EXPORT2 365b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_open(const char *converterName, UErrorCode *err); 366b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 367b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 368b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 369b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Creates a Unicode converter with the names specified as unicode string. 370b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The name should be limited to the ASCII-7 alphanumerics range. 371b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The actual name will be resolved with the alias file 372b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * using a case-insensitive string comparison that ignores 373b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * leading zeroes and all non-alphanumeric characters. 374b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * E.g., the names "UTF8", "utf-8", "u*T@f08" and "Utf 8" are all equivalent. 375b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (See also ucnv_compareNames().) 376b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If <TT>NULL</TT> is passed for the converter name, it will create 377b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * one with the ucnv_getDefaultName() return value. 378b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the alias is ambiguous, then the preferred converter is used 379b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and the status is set to U_AMBIGUOUS_ALIAS_WARNING. 380b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 381b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>See ucnv_open for the complete details</p> 382b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param name Name of the UConverter table in a zero terminated 383b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Unicode string 384b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR, 385b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * U_FILE_ACCESS_ERROR</TT> 386b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the created Unicode converter object, or <TT>NULL</TT> if an 387b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * error occured 388b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 389b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_openCCSID 390b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_close 391c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * @see ucnv_compareNames 392b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 393b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 394b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UConverter* U_EXPORT2 395b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_openU(const UChar *name, 396b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 397b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 398b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 399b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Creates a UConverter object from a CCSID number and platform pair. 400b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Note that the usefulness of this function is limited to platforms with numeric 401b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * encoding IDs. Only IBM and Microsoft platforms use numeric (16-bit) identifiers for 402b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * encodings. 403b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 404b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * In addition, IBM CCSIDs and Unicode conversion tables are not 1:1 related. 405b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For many IBM CCSIDs there are multiple (up to six) Unicode conversion tables, and 406b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * for some Unicode conversion tables there are multiple CCSIDs. 407b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Some "alternate" Unicode conversion tables are provided by the 408b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * IBM CDRA conversion table registry. 409b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The most prominent example of a systematic modification of conversion tables that is 410b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * not provided in the form of conversion table files in the repository is 411b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * that S/390 Unix System Services swaps the codes for Line Feed and New Line in all 412b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * EBCDIC codepages, which requires such a swap in the Unicode conversion tables as well. 413b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 414b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Only IBM default conversion tables are accessible with ucnv_openCCSID(). 415b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_getCCSID() will return the same CCSID for all conversion tables that are associated 416b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * with that CCSID. 417b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 418b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Currently, the only "platform" supported in the ICU converter API is UCNV_IBM. 419b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 420b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * In summary, the use of CCSIDs and the associated API functions is not recommended. 421b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 422b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * In order to open a converter with the default IBM CDRA Unicode conversion table, 423b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * you can use this function or use the prefix "ibm-": 424b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \code 425b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * char name[20]; 426b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * sprintf(name, "ibm-%hu", ccsid); 427b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * cnv=ucnv_open(name, &errorCode); 428b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \endcode 429b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 430b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * In order to open a converter with the IBM S/390 Unix System Services variant 431b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * of a Unicode/EBCDIC conversion table, 432b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * you can use the prefix "ibm-" together with the option string UCNV_SWAP_LFNL_OPTION_STRING: 433b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \code 434b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * char name[20]; 435b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * sprintf(name, "ibm-%hu" UCNV_SWAP_LFNL_OPTION_STRING, ccsid); 436b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * cnv=ucnv_open(name, &errorCode); 437b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \endcode 438b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 439b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * In order to open a converter from a Microsoft codepage number, use the prefix "cp": 440b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \code 441b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * char name[20]; 442b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * sprintf(name, "cp%hu", codepageID); 443b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * cnv=ucnv_open(name, &errorCode); 444b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \endcode 445b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 446b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the alias is ambiguous, then the preferred converter is used 447b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and the status is set to U_AMBIGUOUS_ALIAS_WARNING. 448b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 449b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param codepage codepage number to create 450b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param platform the platform in which the codepage number exists 451b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err error status <TT>U_MEMORY_ALLOCATION_ERROR, U_FILE_ACCESS_ERROR</TT> 452b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the created Unicode converter object, or <TT>NULL</TT> if an error 453b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * occured. 454b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 455b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_openU 456b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_close 457b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getCCSID 458b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getPlatform 459b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see UConverterPlatform 460b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 461b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 462b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UConverter* U_EXPORT2 463b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_openCCSID(int32_t codepage, 464b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterPlatform platform, 465b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode * err); 466b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 467b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 468b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>Creates a UConverter object specified from a packageName and a converterName.</p> 469b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 470b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>The packageName and converterName must point to an ICU udata object, as defined by 471b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <code> udata_open( packageName, "cnv", converterName, err) </code> or equivalent. 472b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Typically, packageName will refer to a (.dat) file, or to a package registered with 473b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * udata_setAppData(). Using a full file or directory pathname for packageName is deprecated.</p> 474b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 475b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>The name will NOT be looked up in the alias mechanism, nor will the converter be 476b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * stored in the converter cache or the alias table. The only way to open further converters 477b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * is call this function multiple times, or use the ucnv_safeClone() function to clone a 478b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 'master' converter.</p> 479b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 480b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>A future version of ICU may add alias table lookups and/or caching 481b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * to this function.</p> 482b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 483b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>Example Use: 484b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <code>cnv = ucnv_openPackage("myapp", "myconverter", &err);</code> 485b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * </p> 486b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 487b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param packageName name of the package (equivalent to 'path' in udata_open() call) 488b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converterName name of the data item to be used, without suffix. 489b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err outgoing error status <TT>U_MEMORY_ALLOCATION_ERROR, U_FILE_ACCESS_ERROR</TT> 490b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured 491b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see udata_open 492b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 493b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_safeClone 494b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_close 495b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.2 496b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 497b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UConverter* U_EXPORT2 498b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_openPackage(const char *packageName, const char *converterName, UErrorCode *err); 499b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 500b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 501b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Thread safe converter cloning operation. 502b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For most efficient operation, pass in a stackBuffer (and a *pBufferSize) 503b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * with at least U_CNV_SAFECLONE_BUFFERSIZE bytes of space. 504b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the buffer size is sufficient, then the clone will use the stack buffer; 505b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * otherwise, it will be allocated, and *pBufferSize will indicate 506b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the actual size. (This should not occur with U_CNV_SAFECLONE_BUFFERSIZE.) 507b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 508b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * You must ucnv_close() the clone in any case. 509b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 510b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If *pBufferSize==0, (regardless of whether stackBuffer==NULL or not) 511b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * then *pBufferSize will be changed to a sufficient size 512b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * for cloning this converter, 513b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * without actually cloning the converter ("pure pre-flighting"). 514b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 515b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If *pBufferSize is greater than zero but not large enough for a stack-based 516b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * clone, then the converter is cloned using newly allocated memory 517b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and *pBufferSize is changed to the necessary size. 518b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 519b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the converter clone fits into the stack buffer but the stack buffer is not 520b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * sufficiently aligned for the clone, then the clone will use an 521b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * adjusted pointer and use an accordingly smaller buffer size. 522b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 523b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv converter to be cloned 52459d709d503bab6e2b61931737e662dd293b40578ccornelius * @param stackBuffer <em>Deprecated functionality as of ICU 52, use NULL.</em><br> 52559d709d503bab6e2b61931737e662dd293b40578ccornelius * user allocated space for the new clone. If NULL new memory will be allocated. 526b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If buffer is not large enough, new memory will be allocated. 527b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Clients can use the U_CNV_SAFECLONE_BUFFERSIZE. This will probably be enough to avoid memory allocations. 52859d709d503bab6e2b61931737e662dd293b40578ccornelius * @param pBufferSize <em>Deprecated functionality as of ICU 52, use NULL or 1.</em><br> 52959d709d503bab6e2b61931737e662dd293b40578ccornelius * pointer to size of allocated space. 530b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param status to indicate whether the operation went on smoothly or there were errors 531b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * An informational status value, U_SAFECLONE_ALLOCATED_WARNING, 532b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * is used if any allocations were necessary. 533b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * However, it is better to check if *pBufferSize grew for checking for 534b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * allocations because warning codes can be overridden by subsequent 535b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * function calls. 536b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return pointer to the new clone 537b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 538b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 539b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UConverter * U_EXPORT2 540b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_safeClone(const UConverter *cnv, 541b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru void *stackBuffer, 542b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t *pBufferSize, 543b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *status); 544b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 54559d709d503bab6e2b61931737e662dd293b40578ccornelius#ifndef U_HIDE_DEPRECATED_API 54659d709d503bab6e2b61931737e662dd293b40578ccornelius 547b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 548b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \def U_CNV_SAFECLONE_BUFFERSIZE 549b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Definition of a buffer size that is designed to be large enough for 550b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * converters to be cloned with ucnv_safeClone(). 55159d709d503bab6e2b61931737e662dd293b40578ccornelius * @deprecated ICU 52. Do not rely on ucnv_safeClone() cloning into any provided buffer. 552b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 553b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define U_CNV_SAFECLONE_BUFFERSIZE 1024 554b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 55559d709d503bab6e2b61931737e662dd293b40578ccornelius#endif /* U_HIDE_DEPRECATED_API */ 55659d709d503bab6e2b61931737e662dd293b40578ccornelius 557b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 558b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Deletes the unicode converter and releases resources associated 559b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * with just this instance. 560b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Does not free up shared converter tables. 561b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 562b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the converter object to be deleted 563b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_open 564b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_openU 565b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_openCCSID 566b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 567b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 568b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 569b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_close(UConverter * converter); 570b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 57150294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho#if U_SHOW_CPLUSPLUS_API 57250294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 57350294ead5e5d23f5bbfed76e00e6b510bd41eee1clairehoU_NAMESPACE_BEGIN 57450294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 57550294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho/** 57650294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * \class LocalUConverterPointer 57750294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * "Smart pointer" class, closes a UConverter via ucnv_close(). 57850294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * For most methods see the LocalPointerBase base class. 57950294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * 58050294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * @see LocalPointerBase 58150294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho * @see LocalPointer 58227f654740f2a26ad62a5c155af9199af9e69b889claireho * @stable ICU 4.4 58350294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho */ 58450294ead5e5d23f5bbfed76e00e6b510bd41eee1clairehoU_DEFINE_LOCAL_OPEN_POINTER(LocalUConverterPointer, UConverter, ucnv_close); 58550294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 58650294ead5e5d23f5bbfed76e00e6b510bd41eee1clairehoU_NAMESPACE_END 58750294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 58850294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho#endif 58950294ead5e5d23f5bbfed76e00e6b510bd41eee1claireho 590b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 591b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Fills in the output parameter, subChars, with the substitution characters 592b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * as multiple bytes. 593b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If ucnv_setSubstString() set a Unicode string because the converter is 594b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * stateful, then subChars will be an empty string. 595b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 596b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 597b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param subChars the subsitution characters 598b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param len on input the capacity of subChars, on output the number 599b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * of bytes copied to it 600b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err the outgoing error status code. 601b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the substitution character array is too small, an 602b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned. 603b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setSubstString 604b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setSubstChars 605b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 606b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 607b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 608b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getSubstChars(const UConverter *converter, 609b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru char *subChars, 610b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int8_t *len, 611b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 612b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 613b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 614b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Sets the substitution chars when converting from unicode to a codepage. The 615b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * substitution is specified as a string of 1-4 bytes, and may contain 616b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <TT>NULL</TT> bytes. 617b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The subChars must represent a single character. The caller needs to know the 618b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * byte sequence of a valid character in the converter's charset. 619b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For some converters, for example some ISO 2022 variants, only single-byte 620b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * substitution characters may be supported. 621b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The newer ucnv_setSubstString() function relaxes these limitations. 622b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 623b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 624b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param subChars the substitution character byte sequence we want set 625b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param len the number of bytes in subChars 626b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err the error status code. <TT>U_INDEX_OUTOFBOUNDS_ERROR </TT> if 627b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * len is bigger than the maximum number of bytes allowed in subchars 628b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setSubstString 629b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getSubstChars 630b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 631b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 632b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 633b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_setSubstChars(UConverter *converter, 634b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *subChars, 635b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int8_t len, 636b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 637b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 638b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 639b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Set a substitution string for converting from Unicode to a charset. 640b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The caller need not know the charset byte sequence for each charset. 641b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 642b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Unlike ucnv_setSubstChars() which is designed to set a charset byte sequence 643b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * for a single character, this function takes a Unicode string with 644b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * zero, one or more characters, and immediately verifies that the string can be 645b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * converted to the charset. 646b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If not, or if the result is too long (more than 32 bytes as of ICU 3.6), 647b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * then the function returns with an error accordingly. 648b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 649b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Also unlike ucnv_setSubstChars(), this function works for stateful charsets 650b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * by converting on the fly at the point of substitution rather than setting 651b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * a fixed byte sequence. 652b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 653b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv The UConverter object. 654b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param s The Unicode string. 655b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param length The number of UChars in s, or -1 for a NUL-terminated string. 656b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err Pointer to a standard ICU error code. Its input value must 657b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * pass the U_SUCCESS() test, or else the function returns 658b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * immediately. Check for U_FAILURE() on output or use with 659b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * function chaining. (See User Guide for details.) 660b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 661b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setSubstChars 662b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getSubstChars 663b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 3.6 664b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 665b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 666b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_setSubstString(UConverter *cnv, 667b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const UChar *s, 668b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t length, 669b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 670b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 671b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 672b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Fills in the output parameter, errBytes, with the error characters from the 673b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * last failing conversion. 674b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 675b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 676b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param errBytes the codepage bytes which were in error 677b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param len on input the capacity of errBytes, on output the number of 678b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * bytes which were copied to it 679b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err the error status code. 680b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the substitution character array is too small, an 681b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned. 682b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 683b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 684b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 685b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getInvalidChars(const UConverter *converter, 686b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru char *errBytes, 687b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int8_t *len, 688b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 689b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 690b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 691b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Fills in the output parameter, errChars, with the error characters from the 692b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * last failing conversion. 693b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 694b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 695b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param errUChars the UChars which were in error 696b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param len on input the capacity of errUChars, on output the number of 697b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * UChars which were copied to it 698b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err the error status code. 699b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the substitution character array is too small, an 700b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <TT>U_INDEX_OUTOFBOUNDS_ERROR</TT> will be returned. 701b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 702b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 703b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 704b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getInvalidUChars(const UConverter *converter, 705b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UChar *errUChars, 706b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int8_t *len, 707b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 708b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 709b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 710b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Resets the state of a converter to the default state. This is used 711b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * in the case of an error, to restart a conversion from a known default state. 712b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It will also empty the internal output buffers. 713b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 714b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 715b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 716b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 717b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_reset(UConverter *converter); 718b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 719b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 720b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Resets the to-Unicode part of a converter state to the default state. 721b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This is used in the case of an error to restart a conversion to 722b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Unicode to a known default state. It will also empty the internal 723b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * output buffers used for the conversion to Unicode codepoints. 724b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 725b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 726b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 727b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 728b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_resetToUnicode(UConverter *converter); 729b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 730b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 731b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Resets the from-Unicode part of a converter state to the default state. 732b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This is used in the case of an error to restart a conversion from 733b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Unicode to a known default state. It will also empty the internal output 734b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * buffers used for the conversion from Unicode codepoints. 735b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 736b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 737b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 738b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 739b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_resetFromUnicode(UConverter *converter); 740b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 741b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 742b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the maximum number of bytes that are output per UChar in conversion 743b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * from Unicode using this converter. 744b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The returned number can be used with UCNV_GET_MAX_BYTES_FOR_STRING 745b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * to calculate the size of a target buffer for conversion from Unicode. 746b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 747b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Note: Before ICU 2.8, this function did not return reliable numbers for 748b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * some stateful converters (EBCDIC_STATEFUL, ISO-2022) and LMBCS. 749b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 750b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This number may not be the same as the maximum number of bytes per 751b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * "conversion unit". In other words, it may not be the intuitively expected 752b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * number of bytes per character that would be published for a charset, 753b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and may not fulfill any other purpose than the allocation of an output 754b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * buffer of guaranteed sufficient size for a given input length and converter. 755b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 756b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Examples for special cases that are taken into account: 757b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - Supplementary code points may convert to more bytes than BMP code points. 758b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This function returns bytes per UChar (UTF-16 code unit), not per 759b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Unicode code point, for efficient buffer allocation. 760b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - State-shifting output (SI/SO, escapes, etc.) from stateful converters. 761b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - When m input UChars are converted to n output bytes, then the maximum m/n 762b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * is taken into account. 763b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 764b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The number returned here does not take into account 765b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (see UCNV_GET_MAX_BYTES_FOR_STRING): 766b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - callbacks which output more than one charset character sequence per call, 767b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * like escape callbacks 768b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - initial and final non-character bytes that are output by some converters 769b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (automatic BOMs, initial escape sequence, final SI, etc.) 770b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 771b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Examples for returned values: 772b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - SBCS charsets: 1 773b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - Shift-JIS: 2 774b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - UTF-16: 2 (2 per BMP, 4 per surrogate _pair_, BOM not counted) 775b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - UTF-8: 3 (3 per BMP, 4 per surrogate _pair_) 776b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - EBCDIC_STATEFUL (EBCDIC mixed SBCS/DBCS): 3 (SO + DBCS) 777b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - ISO-2022: 3 (always outputs UTF-8) 778b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - ISO-2022-JP: 6 (4-byte escape sequences + DBCS) 779b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - ISO-2022-CN: 8 (4-byte designator sequences + 2-byte SS2/SS3 + DBCS) 780b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 781b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter The Unicode converter. 782b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return The maximum number of bytes per UChar that are output by ucnv_fromUnicode(), 783b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * to be used together with UCNV_GET_MAX_BYTES_FOR_STRING for buffer allocation. 784b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 785b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see UCNV_GET_MAX_BYTES_FOR_STRING 786b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getMinCharSize 787b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 788b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 789b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int8_t U_EXPORT2 790b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getMaxCharSize(const UConverter *converter); 791b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 792b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 793b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Calculates the size of a buffer for conversion from Unicode to a charset. 794b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The calculated size is guaranteed to be sufficient for this conversion. 795b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 796b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It takes into account initial and final non-character bytes that are output 797b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * by some converters. 798b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It does not take into account callbacks which output more than one charset 799b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * character sequence per call, like escape callbacks. 800b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The default (substitution) callback only outputs one charset character sequence. 801b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 802b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param length Number of UChars to be converted. 803b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param maxCharSize Return value from ucnv_getMaxCharSize() for the converter 804b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * that will be used. 805b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return Size of a buffer that will be large enough to hold the output bytes of 806b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * converting length UChars with the converter that returned the maxCharSize. 807b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 808b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getMaxCharSize 809b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.8 810b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 811b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#define UCNV_GET_MAX_BYTES_FOR_STRING(length, maxCharSize) \ 812b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru (((int32_t)(length)+10)*(int32_t)(maxCharSize)) 813b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 814b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 815b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the minimum byte length for characters in this codepage. 816b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This is usually either 1 or 2. 817b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 818b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the minimum number of bytes allowed by this particular converter 819b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getMaxCharSize 820b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 821b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 822b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int8_t U_EXPORT2 823b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getMinCharSize(const UConverter *converter); 824b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 825b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 826b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the display name of the converter passed in based on the Locale 827b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * passed in. If the locale contains no display name, the internal ASCII 828b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * name will be filled in. 829b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 830b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter. 831b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param displayLocale is the specific Locale we want to localised for 832b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param displayName user provided buffer to be filled in 833b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param displayNameCapacity size of displayName Buffer 834b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err error status code 835b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return displayNameLength number of UChar needed in displayName 836b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getName 837b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 838b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 839b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 840b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getDisplayName(const UConverter *converter, 841b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *displayLocale, 842b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UChar *displayName, 843b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t displayNameCapacity, 844b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 845b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 846b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 847b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gets the internal, canonical name of the converter (zero-terminated). 848b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The lifetime of the returned string will be that of the converter 849b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * passed to this function. 850b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 851b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err UErrorCode status 852b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the internal name of the converter 853b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getDisplayName 854b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 855b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 856b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const char * U_EXPORT2 857b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getName(const UConverter *converter, UErrorCode *err); 858b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 859b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 860b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gets a codepage number associated with the converter. This is not guaranteed 861b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * to be the one used to create the converter. Some converters do not represent 862b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * platform registered codepages and return zero for the codepage number. 863b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The error code fill-in parameter indicates if the codepage number 864b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * is available. 865b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Does not check if the converter is <TT>NULL</TT> or if converter's data 866b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * table is <TT>NULL</TT>. 867b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 868b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Important: The use of CCSIDs is not recommended because it is limited 869b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * to only two platforms in principle and only one (UCNV_IBM) in the current 870b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ICU converter API. 871b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Also, CCSIDs are insufficient to identify IBM Unicode conversion tables precisely. 872b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For more details see ucnv_openCCSID(). 873b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 874b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 875b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err the error status code. 876b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return If any error occurrs, -1 will be returned otherwise, the codepage number 877b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * will be returned 878b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_openCCSID 879b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getPlatform 880b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 881b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 882b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 883b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getCCSID(const UConverter *converter, 884b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 885b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 886b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 887b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gets a codepage platform associated with the converter. Currently, 888b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * only <TT>UCNV_IBM</TT> will be returned. 889b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Does not test if the converter is <TT>NULL</TT> or if converter's data 890b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * table is <TT>NULL</TT>. 891b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 892b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err the error status code. 893b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return The codepage platform 894b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 895b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 896b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UConverterPlatform U_EXPORT2 897b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getPlatform(const UConverter *converter, 898b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 899b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 900b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 901b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gets the type of the converter 902b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * e.g. SBCS, MBCS, DBCS, UTF8, UTF16_BE, UTF16_LE, ISO_2022, 903b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * EBCDIC_STATEFUL, LATIN_1 904b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter a valid, opened converter 905b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the type of the converter 906b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 907b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 908b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UConverterType U_EXPORT2 909b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getType(const UConverter * converter); 910b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 911b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 912b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gets the "starter" (lead) bytes for converters of type MBCS. 913b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Will fill in an <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> if converter passed in 914b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * is not MBCS. Fills in an array of type UBool, with the value of the byte 915b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * as offset to the array. For example, if (starters[0x20] == TRUE) at return, 916b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * it means that the byte 0x20 is a starter byte in this converter. 917b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Context pointers are always owned by the caller. 918b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 919b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter a valid, opened converter of type MBCS 920b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param starters an array of size 256 to be filled in 921b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err error status, <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> if the 922b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * converter is not a type which can return starters. 923b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getType 924b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 925b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 926b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 927b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getStarters(const UConverter* converter, 928b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UBool starters[256], 929b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode* err); 930b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 931b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 932b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 933b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Selectors for Unicode sets that can be returned by ucnv_getUnicodeSet(). 934b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getUnicodeSet 935b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.6 936b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 937b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Querutypedef enum UConverterUnicodeSet { 938b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru /** Select the set of roundtrippable Unicode code points. @stable ICU 2.6 */ 939b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_ROUNDTRIP_SET, 940b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru /** Select the set of Unicode code points with roundtrip or fallback mappings. @stable ICU 4.0 */ 941c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru UCNV_ROUNDTRIP_AND_FALLBACK_SET, 942b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru /** Number of UConverterUnicodeSet selectors. @stable ICU 2.6 */ 943b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UCNV_SET_COUNT 944b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru} UConverterUnicodeSet; 945b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 946b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 947b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 948b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the set of Unicode code points that can be converted by an ICU converter. 949b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 950c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * Returns one of several kinds of set: 951c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * 952c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * 1. UCNV_ROUNDTRIP_SET 953c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * 954b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The set of all Unicode code points that can be roundtrip-converted 955c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * (converted without any data loss) with the converter (ucnv_fromUnicode()). 956b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This set will not include code points that have fallback mappings 957b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * or are only the result of reverse fallback mappings. 958c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * This set will also not include PUA code points with fallbacks, although 959c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * ucnv_fromUnicode() will always uses those mappings despite ucnv_setFallback(). 960b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * See UTR #22 "Character Mapping Markup Language" 961b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * at http://www.unicode.org/reports/tr22/ 962b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 963b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This is useful for example for 964b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - checking that a string or document can be roundtrip-converted with a converter, 965b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * without/before actually performing the conversion 966b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - testing if a converter can be used for text for typical text for a certain locale, 967b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * by comparing its roundtrip set with the set of ExemplarCharacters from 968b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ICU's locale data or other sources 969b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 970c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * 2. UCNV_ROUNDTRIP_AND_FALLBACK_SET 971c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * 972c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * The set of all Unicode code points that can be converted with the converter (ucnv_fromUnicode()) 973c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * when fallbacks are turned on (see ucnv_setFallback()). 974c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * This set includes all code points with roundtrips and fallbacks (but not reverse fallbacks). 975c69afcec261fc345fda8daf46f0ea6b4351dc777Jean-Baptiste Queru * 976b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * In the future, there may be more UConverterUnicodeSet choices to select 977b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * sets with different properties. 978b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 979b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv The converter for which a set is requested. 980b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param setFillIn A valid USet *. It will be cleared by this function before 981b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the converter's specific set is filled into the USet. 982b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param whichSet A UConverterUnicodeSet selector; 983b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * currently UCNV_ROUNDTRIP_SET is the only supported value. 984b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode ICU error code in/out parameter. 985b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Must fulfill U_SUCCESS before the function call. 986b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 987b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see UConverterUnicodeSet 988b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see uset_open 989b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see uset_close 990b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.6 991b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 992b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 993b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getUnicodeSet(const UConverter *cnv, 994b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru USet *setFillIn, 995b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterUnicodeSet whichSet, 996b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 997b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 998b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 999b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gets the current calback function used by the converter when an illegal 1000b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * or invalid codepage sequence is found. 1001b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Context pointers are always owned by the caller. 1002b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1003b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the unicode converter 1004b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param action fillin: returns the callback function pointer 1005b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param context fillin: returns the callback's private void* context 1006b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setToUCallBack 1007b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1008b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1009b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1010b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getToUCallBack (const UConverter * converter, 1011b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterToUCallback *action, 1012b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const void **context); 1013b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1014b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1015b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gets the current callback function used by the converter when illegal 1016b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * or invalid Unicode sequence is found. 1017b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Context pointers are always owned by the caller. 1018b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1019b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the unicode converter 1020b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param action fillin: returns the callback function pointer 1021b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param context fillin: returns the callback's private void* context 1022b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setFromUCallBack 1023b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1024b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1025b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1026b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getFromUCallBack (const UConverter * converter, 1027b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterFromUCallback *action, 1028b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const void **context); 1029b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1030b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1031b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Changes the callback function used by the converter when 1032b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * an illegal or invalid sequence is found. 1033b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Context pointers are always owned by the caller. 1034b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Predefined actions and contexts can be found in the ucnv_err.h header. 1035b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1036b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the unicode converter 1037b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param newAction the new callback function 1038b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param newContext the new toUnicode callback context pointer. This can be NULL. 1039b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param oldAction fillin: returns the old callback function pointer. This can be NULL. 1040b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param oldContext fillin: returns the old callback's private void* context. This can be NULL. 1041b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err The error code status 1042b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getToUCallBack 1043b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1044b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1045b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1046b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_setToUCallBack (UConverter * converter, 1047b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterToUCallback newAction, 1048b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const void* newContext, 1049b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterToUCallback *oldAction, 1050b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const void** oldContext, 1051b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode * err); 1052b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1053b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1054b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Changes the current callback function used by the converter when 1055b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * an illegal or invalid sequence is found. 1056b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Context pointers are always owned by the caller. 1057b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Predefined actions and contexts can be found in the ucnv_err.h header. 1058b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1059b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the unicode converter 1060b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param newAction the new callback function 1061b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param newContext the new fromUnicode callback context pointer. This can be NULL. 1062b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param oldAction fillin: returns the old callback function pointer. This can be NULL. 1063b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param oldContext fillin: returns the old callback's private void* context. This can be NULL. 1064b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err The error code status 1065b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getFromUCallBack 1066b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1067b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1068b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1069b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_setFromUCallBack (UConverter * converter, 1070b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterFromUCallback newAction, 1071b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const void *newContext, 1072b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterFromUCallback *oldAction, 1073b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const void **oldContext, 1074b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode * err); 1075b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1076b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1077b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Converts an array of unicode characters to an array of codepage 1078b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * characters. This function is optimized for converting a continuous 1079b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * stream of data in buffer-sized chunks, where the entire source and 1080b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * target does not fit in available buffers. 1081b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1082b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The source pointer is an in/out parameter. It starts out pointing where the 1083b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conversion is to begin, and ends up pointing after the last UChar consumed. 1084b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1085b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Target similarly starts out pointer at the first available byte in the output 1086b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * buffer, and ends up pointing after the last byte written to the output. 1087b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1088b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The converter always attempts to consume the entire source buffer, unless 1089b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (1.) the target buffer is full, or (2.) a failing error is returned from the 1090b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * current callback function. When a successful error status has been 1091b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * returned, it means that all of the source buffer has been 1092b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * consumed. At that point, the caller should reset the source and 1093b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * sourceLimit pointers to point to the next chunk. 1094b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1095b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * At the end of the stream (flush==TRUE), the input is completely consumed 1096b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * when *source==sourceLimit and no error code is set. 1097b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The converter object is then automatically reset by this function. 1098b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (This means that a converter need not be reset explicitly between data 1099b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * streams if it finishes the previous stream without errors.) 1100b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1101b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This is a <I>stateful</I> conversion. Additionally, even when all source data has 1102b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * been consumed, some data may be in the converters' internal state. 1103b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Call this function repeatedly, updating the target pointers with 1104b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the next empty chunk of target in case of a 1105b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <TT>U_BUFFER_OVERFLOW_ERROR</TT>, and updating the source pointers 1106b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * with the next chunk of source when a successful error status is 1107b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * returned, until there are no more chunks of source data. 1108b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 1109b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param target I/O parameter. Input : Points to the beginning of the buffer to copy 1110b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * codepage characters to. Output : points to after the last codepage character copied 1111b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * to <TT>target</TT>. 1112b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param targetLimit the pointer just after last of the <TT>target</TT> buffer 1113b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param source I/O parameter, pointer to pointer to the source Unicode character buffer. 1114b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceLimit the pointer just after the last of the source buffer 1115b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param offsets if NULL is passed, nothing will happen to it, otherwise it needs to have the same number 1116b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * of allocated cells as <TT>target</TT>. Will fill in offsets from target to source pointer 1117b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * e.g: <TT>offsets[3]</TT> is equal to 6, it means that the <TT>target[3]</TT> was a result of transcoding <TT>source[6]</TT> 1118b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For output data carried across calls, and other data without a specific source character 1119b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (such as from escape sequences or callbacks) -1 will be placed for offsets. 1120b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param flush set to <TT>TRUE</TT> if the current source buffer is the last available 1121b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * chunk of the source, <TT>FALSE</TT> otherwise. Note that if a failing status is returned, 1122b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * this function may have to be called multiple times with flush set to <TT>TRUE</TT> until 1123b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the source buffer is consumed. 1124b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err the error status. <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> will be set if the 1125b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * converter is <TT>NULL</TT>. 1126b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <code>U_BUFFER_OVERFLOW_ERROR</code> will be set if the target is full and there is 1127b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * still data to be written to the target. 1128b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUChars 1129b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convert 1130b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getMinCharSize 1131b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setToUCallBack 1132b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1133b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1134b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1135b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_fromUnicode (UConverter * converter, 1136b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru char **target, 1137b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *targetLimit, 1138b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const UChar ** source, 1139b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const UChar * sourceLimit, 1140b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t* offsets, 1141b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UBool flush, 1142b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode * err); 1143b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1144b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1145b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Converts a buffer of codepage bytes into an array of unicode UChars 1146b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * characters. This function is optimized for converting a continuous 1147b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * stream of data in buffer-sized chunks, where the entire source and 1148b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * target does not fit in available buffers. 1149b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1150b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The source pointer is an in/out parameter. It starts out pointing where the 1151b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conversion is to begin, and ends up pointing after the last byte of source consumed. 1152b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1153b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Target similarly starts out pointer at the first available UChar in the output 1154b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * buffer, and ends up pointing after the last UChar written to the output. 1155b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It does NOT necessarily keep UChar sequences together. 1156b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1157b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The converter always attempts to consume the entire source buffer, unless 1158b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (1.) the target buffer is full, or (2.) a failing error is returned from the 1159b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * current callback function. When a successful error status has been 1160b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * returned, it means that all of the source buffer has been 1161b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * consumed. At that point, the caller should reset the source and 1162b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * sourceLimit pointers to point to the next chunk. 1163b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1164b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * At the end of the stream (flush==TRUE), the input is completely consumed 1165b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * when *source==sourceLimit and no error code is set 1166b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The converter object is then automatically reset by this function. 1167b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (This means that a converter need not be reset explicitly between data 1168b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * streams if it finishes the previous stream without errors.) 1169b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1170b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This is a <I>stateful</I> conversion. Additionally, even when all source data has 1171b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * been consumed, some data may be in the converters' internal state. 1172b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Call this function repeatedly, updating the target pointers with 1173b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the next empty chunk of target in case of a 1174b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <TT>U_BUFFER_OVERFLOW_ERROR</TT>, and updating the source pointers 1175b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * with the next chunk of source when a successful error status is 1176b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * returned, until there are no more chunks of source data. 1177b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter the Unicode converter 1178b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param target I/O parameter. Input : Points to the beginning of the buffer to copy 1179b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * UChars into. Output : points to after the last UChar copied. 1180b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param targetLimit the pointer just after the end of the <TT>target</TT> buffer 1181b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param source I/O parameter, pointer to pointer to the source codepage buffer. 1182b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceLimit the pointer to the byte after the end of the source buffer 1183b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param offsets if NULL is passed, nothing will happen to it, otherwise it needs to have the same number 1184b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * of allocated cells as <TT>target</TT>. Will fill in offsets from target to source pointer 1185b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * e.g: <TT>offsets[3]</TT> is equal to 6, it means that the <TT>target[3]</TT> was a result of transcoding <TT>source[6]</TT> 1186b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For output data carried across calls, and other data without a specific source character 1187b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (such as from escape sequences or callbacks) -1 will be placed for offsets. 1188b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param flush set to <TT>TRUE</TT> if the current source buffer is the last available 1189b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * chunk of the source, <TT>FALSE</TT> otherwise. Note that if a failing status is returned, 1190b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * this function may have to be called multiple times with flush set to <TT>TRUE</TT> until 1191b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the source buffer is consumed. 1192b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err the error status. <TT>U_ILLEGAL_ARGUMENT_ERROR</TT> will be set if the 1193b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * converter is <TT>NULL</TT>. 1194b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <code>U_BUFFER_OVERFLOW_ERROR</code> will be set if the target is full and there is 1195b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * still data to be written to the target. 1196b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUChars 1197b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convert 1198b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getMinCharSize 1199b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setFromUCallBack 1200b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getNextUChar 1201b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1202b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1203b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1204b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_toUnicode(UConverter *converter, 1205b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UChar **target, 1206b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const UChar *targetLimit, 1207b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char **source, 1208b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *sourceLimit, 1209b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t *offsets, 1210b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UBool flush, 1211b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *err); 1212b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1213b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1214b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Convert the Unicode string into a codepage string using an existing UConverter. 1215b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The output string is NUL-terminated if possible. 1216b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1217b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This function is a more convenient but less powerful version of ucnv_fromUnicode(). 1218b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It is only useful for whole strings, not for streaming conversion. 1219b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1220b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The maximum output buffer capacity required (barring output from callbacks) will be 1221b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * UCNV_GET_MAX_BYTES_FOR_STRING(srcLength, ucnv_getMaxCharSize(cnv)). 1222b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1223b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv the converter object to be used (ucnv_resetFromUnicode() will be called) 1224b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param src the input Unicode string 1225b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param srcLength the input string length, or -1 if NUL-terminated 1226b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param dest destination string buffer, can be NULL if destCapacity==0 1227b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param destCapacity the number of chars available at dest 1228b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode normal ICU error code; 1229b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * common error codes that may be set by this function include 1230b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * U_BUFFER_OVERFLOW_ERROR, U_STRING_NOT_TERMINATED_WARNING, 1231b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * U_ILLEGAL_ARGUMENT_ERROR, and conversion errors 1232b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the length of the output string, not counting the terminating NUL; 1233b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * if the length is greater than destCapacity, then the string will not fit 1234b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and a buffer of the indicated length would need to be passed in 1235b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUnicode 1236b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convert 1237b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see UCNV_GET_MAX_BYTES_FOR_STRING 1238b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1239b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1240b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 1241b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_fromUChars(UConverter *cnv, 1242b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru char *dest, int32_t destCapacity, 1243b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const UChar *src, int32_t srcLength, 1244b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 1245b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1246b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1247b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Convert the codepage string into a Unicode string using an existing UConverter. 1248b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The output string is NUL-terminated if possible. 1249b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1250b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This function is a more convenient but less powerful version of ucnv_toUnicode(). 1251b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It is only useful for whole strings, not for streaming conversion. 1252b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1253b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The maximum output buffer capacity required (barring output from callbacks) will be 1254b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 2*srcLength (each char may be converted into a surrogate pair). 1255b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1256b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv the converter object to be used (ucnv_resetToUnicode() will be called) 1257b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param src the input codepage string 1258b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param srcLength the input string length, or -1 if NUL-terminated 1259b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param dest destination string buffer, can be NULL if destCapacity==0 1260b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param destCapacity the number of UChars available at dest 1261b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode normal ICU error code; 1262b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * common error codes that may be set by this function include 1263b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * U_BUFFER_OVERFLOW_ERROR, U_STRING_NOT_TERMINATED_WARNING, 1264b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * U_ILLEGAL_ARGUMENT_ERROR, and conversion errors 1265b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the length of the output string, not counting the terminating NUL; 1266b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * if the length is greater than destCapacity, then the string will not fit 1267b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and a buffer of the indicated length would need to be passed in 1268b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUnicode 1269b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convert 1270b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1271b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1272b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 1273b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_toUChars(UConverter *cnv, 1274b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UChar *dest, int32_t destCapacity, 1275b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *src, int32_t srcLength, 1276b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 1277b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1278b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1279b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Convert a codepage buffer into Unicode one character at a time. 1280b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The input is completely consumed when the U_INDEX_OUTOFBOUNDS_ERROR is set. 1281b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1282b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Advantage compared to ucnv_toUnicode() or ucnv_toUChars(): 1283b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - Faster for small amounts of data, for most converters, e.g., 1284b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * US-ASCII, ISO-8859-1, UTF-8/16/32, and most "normal" charsets. 1285b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (For complex converters, e.g., SCSU, UTF-7 and ISO 2022 variants, 1286b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * it uses ucnv_toUnicode() internally.) 1287b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - Convenient. 1288b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1289b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Limitations compared to ucnv_toUnicode(): 1290b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - Always assumes flush=TRUE. 1291b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This makes ucnv_getNextUChar() unsuitable for "streaming" conversion, 1292b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * that is, for where the input is supplied in multiple buffers, 1293b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * because ucnv_getNextUChar() will assume the end of the input at the end 1294b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * of the first buffer. 1295b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - Does not provide offset output. 1296b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1297b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It is possible to "mix" ucnv_getNextUChar() and ucnv_toUnicode() because 1298b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_getNextUChar() uses the current state of the converter 1299b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (unlike ucnv_toUChars() which always resets first). 1300b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * However, if ucnv_getNextUChar() is called after ucnv_toUnicode() 1301b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * stopped in the middle of a character sequence (with flush=FALSE), 1302b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * then ucnv_getNextUChar() will always use the slower ucnv_toUnicode() 1303b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * internally until the next character boundary. 1304b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (This is new in ICU 2.6. In earlier releases, ucnv_getNextUChar() had to 1305b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * start at a character boundary.) 1306b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1307b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Instead of using ucnv_getNextUChar(), it is recommended 1308b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * to convert using ucnv_toUnicode() or ucnv_toUChars() 1309b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and then iterate over the text using U16_NEXT() or a UCharIterator (uiter.h) 1310b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * or a C++ CharacterIterator or similar. 1311b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This allows streaming conversion and offset output, for example. 1312b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1313b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p>Handling of surrogate pairs and supplementary-plane code points:<br> 1314b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * There are two different kinds of codepages that provide mappings for surrogate characters: 1315b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <ul> 1316b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <li>Codepages like UTF-8, UTF-32, and GB 18030 provide direct representations for Unicode 1317b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * code points U+10000-U+10ffff as well as for single surrogates U+d800-U+dfff. 1318b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Each valid sequence will result in exactly one returned code point. 1319b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If a sequence results in a single surrogate, then that will be returned 1320b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * by itself, even if a neighboring sequence encodes the matching surrogate.</li> 1321b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <li>Codepages like SCSU and LMBCS (and UTF-16) provide direct representations only for BMP code points 1322b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * including surrogates. Code points in supplementary planes are represented with 1323b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * two sequences, each encoding a surrogate. 1324b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For these codepages, matching pairs of surrogates will be combined into single 1325b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * code points for returning from this function. 1326b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (Note that SCSU is actually a mix of these codepage types.)</li> 1327b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * </ul></p> 1328b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1329b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param converter an open UConverter 1330b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param source the address of a pointer to the codepage buffer, will be 1331b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * updated to point after the bytes consumed in the conversion call. 1332b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceLimit points to the end of the input buffer 1333b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param err fills in error status (see ucnv_toUnicode) 1334b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <code>U_INDEX_OUTOFBOUNDS_ERROR</code> will be set if the input 1335b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * is empty or does not convert to any output (e.g.: pure state-change 1336b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * codes SI/SO, escape sequences for ISO 2022, 1337b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * or if the callback did not output anything, ...). 1338b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This function will not set a <code>U_BUFFER_OVERFLOW_ERROR</code> because 1339b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the "buffer" is the return code. However, there might be subsequent output 1340b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * stored in the converter object 1341b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * that will be returned in following calls to this function. 1342b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return a UChar32 resulting from the partial conversion of source 1343b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUnicode 1344b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUChars 1345b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convert 1346b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1347b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1348b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UChar32 U_EXPORT2 1349b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getNextUChar(UConverter * converter, 1350b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char **source, 1351b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char * sourceLimit, 1352b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode * err); 1353b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1354b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1355b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Convert from one external charset to another using two existing UConverters. 1356b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Internally, two conversions - ucnv_toUnicode() and ucnv_fromUnicode() - 1357b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * are used, "pivoting" through 16-bit Unicode. 1358b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1359b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Important: For streaming conversion (multiple function calls for successive 1360b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * parts of a text stream), the caller must provide a pivot buffer explicitly, 1361b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and must preserve the pivot buffer and associated pointers from one 1362b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * call to another. (The buffer may be moved if its contents and the relative 1363b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * pointer positions are preserved.) 1364b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1365b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * There is a similar function, ucnv_convert(), 1366b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * which has the following limitations: 1367b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - it takes charset names, not converter objects, so that 1368b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - two converters are opened for each call 1369b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - only single-string conversion is possible, not streaming operation 1370b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - it does not provide enough information to find out, 1371b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * in case of failure, whether the toUnicode or 1372b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the fromUnicode conversion failed 1373b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1374b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * By contrast, ucnv_convertEx() 1375b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - takes UConverter parameters instead of charset names 1376b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - fully exposes the pivot buffer for streaming conversion and complete error handling 1377b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1378b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_convertEx() also provides further convenience: 1379b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - an option to reset the converters at the beginning 1380b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (if reset==TRUE, see parameters; 1381b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * also sets *pivotTarget=*pivotSource=pivotStart) 1382b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - allow NUL-terminated input 1383b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (only a single NUL byte, will not work for charsets with multi-byte NULs) 1384b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (if sourceLimit==NULL, see parameters) 1385b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - terminate with a NUL on output 1386b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (only a single NUL byte, not useful for charsets with multi-byte NULs), 1387b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * or set U_STRING_NOT_TERMINATED_WARNING if the output exactly fills 1388b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the target buffer 1389b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - the pivot buffer can be provided internally; 1390b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * possible only for whole-string conversion, not streaming conversion; 1391b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * in this case, the caller will not be able to get details about where an 1392b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * error occurred 1393b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (if pivotStart==NULL, see below) 1394b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1395b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The function returns when one of the following is true: 1396b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - the entire source text has been converted successfully to the target buffer 1397b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - a target buffer overflow occurred (U_BUFFER_OVERFLOW_ERROR) 1398b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - a conversion error occurred 1399b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (other U_FAILURE(), see description of pErrorCode) 1400b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1401b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Limitation compared to the direct use of 1402b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_fromUnicode() and ucnv_toUnicode(): 1403b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_convertEx() does not provide offset information. 1404b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1405b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Limitation compared to ucnv_fromUChars() and ucnv_toUChars(): 1406b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_convertEx() does not support preflighting directly. 1407b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1408b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Sample code for converting a single string from 1409b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * one external charset to UTF-8, ignoring the location of errors: 1410b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1411b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \code 1412b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * int32_t 1413b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * myToUTF8(UConverter *cnv, 1414b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * const char *s, int32_t length, 1415b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * char *u8, int32_t capacity, 1416b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * UErrorCode *pErrorCode) { 1417b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * UConverter *utf8Cnv; 1418b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * char *target; 1419b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1420b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * if(U_FAILURE(*pErrorCode)) { 1421b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * return 0; 1422b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * } 1423b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1424b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * utf8Cnv=myGetCachedUTF8Converter(pErrorCode); 1425b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * if(U_FAILURE(*pErrorCode)) { 1426b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * return 0; 1427b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * } 1428b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1429b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * if(length<0) { 1430b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * length=strlen(s); 1431b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * } 1432b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * target=u8; 1433b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * ucnv_convertEx(utf8Cnv, cnv, 1434b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * &target, u8+capacity, 1435b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * &s, s+length, 1436b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * NULL, NULL, NULL, NULL, 1437b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * TRUE, TRUE, 1438b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * pErrorCode); 1439b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1440b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * myReleaseCachedUTF8Converter(utf8Cnv); 1441b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1442b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * // return the output string length, but without preflighting 1443b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * return (int32_t)(target-u8); 1444b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * } 1445b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * \endcode 1446b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1447b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param targetCnv Output converter, used to convert from the UTF-16 pivot 1448b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * to the target using ucnv_fromUnicode(). 1449b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceCnv Input converter, used to convert from the source to 1450b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the UTF-16 pivot using ucnv_toUnicode(). 1451b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param target I/O parameter, same as for ucnv_fromUChars(). 1452b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Input: *target points to the beginning of the target buffer. 1453b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Output: *target points to the first unit after the last char written. 1454b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param targetLimit Pointer to the first unit after the target buffer. 1455b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param source I/O parameter, same as for ucnv_toUChars(). 1456b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Input: *source points to the beginning of the source buffer. 1457b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Output: *source points to the first unit after the last char read. 1458b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceLimit Pointer to the first unit after the source buffer. 1459b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pivotStart Pointer to the UTF-16 pivot buffer. If pivotStart==NULL, 1460b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * then an internal buffer is used and the other pivot 1461b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * arguments are ignored and can be NULL as well. 1462b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pivotSource I/O parameter, same as source in ucnv_fromUChars() for 1463b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conversion from the pivot buffer to the target buffer. 1464b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pivotTarget I/O parameter, same as target in ucnv_toUChars() for 1465b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conversion from the source buffer to the pivot buffer. 1466b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It must be pivotStart<=*pivotSource<=*pivotTarget<=pivotLimit 1467b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and pivotStart<pivotLimit (unless pivotStart==NULL). 1468b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pivotLimit Pointer to the first unit after the pivot buffer. 1469b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param reset If TRUE, then ucnv_resetToUnicode(sourceCnv) and 1470b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_resetFromUnicode(targetCnv) are called, and the 1471b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * pivot pointers are reset (*pivotTarget=*pivotSource=pivotStart). 1472b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param flush If true, indicates the end of the input. 1473b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Passed directly to ucnv_toUnicode(), and carried over to 1474b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_fromUnicode() when the source is empty as well. 1475b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode ICU error code in/out parameter. 1476b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Must fulfill U_SUCCESS before the function call. 1477b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * U_BUFFER_OVERFLOW_ERROR always refers to the target buffer 1478b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * because overflows into the pivot buffer are handled internally. 1479b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Other conversion errors are from the source-to-pivot 1480b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conversion if *pivotSource==pivotStart, otherwise from 1481b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the pivot-to-target conversion. 1482b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1483b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convert 1484b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromAlgorithmic 1485b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toAlgorithmic 1486b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUnicode 1487b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUnicode 1488b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUChars 1489b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUChars 1490b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.6 1491b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1492b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1493b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_convertEx(UConverter *targetCnv, UConverter *sourceCnv, 1494b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru char **target, const char *targetLimit, 1495b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char **source, const char *sourceLimit, 1496b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UChar *pivotStart, UChar **pivotSource, 1497b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UChar **pivotTarget, const UChar *pivotLimit, 1498b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UBool reset, UBool flush, 1499b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 1500b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1501b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1502b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Convert from one external charset to another. 1503b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Internally, two converters are opened according to the name arguments, 1504b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * then the text is converted to and from the 16-bit Unicode "pivot" 1505b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * using ucnv_convertEx(), then the converters are closed again. 1506b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1507b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This is a convenience function, not an efficient way to convert a lot of text: 1508b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * ucnv_convert() 1509b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - takes charset names, not converter objects, so that 1510b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - two converters are opened for each call 1511b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - only single-string conversion is possible, not streaming operation 1512b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - does not provide enough information to find out, 1513b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * in case of failure, whether the toUnicode or 1514b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the fromUnicode conversion failed 1515b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - allows NUL-terminated input 1516b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (only a single NUL byte, will not work for charsets with multi-byte NULs) 1517b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (if sourceLength==-1, see parameters) 1518b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - terminate with a NUL on output 1519b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (only a single NUL byte, not useful for charsets with multi-byte NULs), 1520b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * or set U_STRING_NOT_TERMINATED_WARNING if the output exactly fills 1521b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the target buffer 1522b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - a pivot buffer is provided internally 1523b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1524b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The function returns when one of the following is true: 1525b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - the entire source text has been converted successfully to the target buffer 1526b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and either the target buffer is terminated with a single NUL byte 1527b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * or the error code is set to U_STRING_NOT_TERMINATED_WARNING 1528b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - a target buffer overflow occurred (U_BUFFER_OVERFLOW_ERROR) 1529b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and the full output string length is returned ("preflighting") 1530b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * - a conversion error occurred 1531b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (other U_FAILURE(), see description of pErrorCode) 1532b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1533b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param toConverterName The name of the converter that is used to convert 1534b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * from the UTF-16 pivot buffer to the target. 1535b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param fromConverterName The name of the converter that is used to convert 1536b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * from the source to the UTF-16 pivot buffer. 1537b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param target Pointer to the output buffer. 1538b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param targetCapacity Capacity of the target, in bytes. 1539b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param source Pointer to the input buffer. 1540b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceLength Length of the input text, in bytes, or -1 for NUL-terminated input. 1541b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode ICU error code in/out parameter. 1542b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Must fulfill U_SUCCESS before the function call. 1543b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return Length of the complete output text in bytes, even if it exceeds the targetCapacity 1544b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and a U_BUFFER_OVERFLOW_ERROR is set. 1545b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1546b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convertEx 1547b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromAlgorithmic 1548b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toAlgorithmic 1549b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUnicode 1550b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUnicode 1551b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUChars 1552b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUChars 1553b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getNextUChar 1554b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1555b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1556b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 1557b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_convert(const char *toConverterName, 1558b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *fromConverterName, 1559b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru char *target, 1560b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t targetCapacity, 1561b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *source, 1562b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t sourceLength, 1563b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 1564b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1565b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1566b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Convert from one external charset to another. 1567b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Internally, the text is converted to and from the 16-bit Unicode "pivot" 1568b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * using ucnv_convertEx(). ucnv_toAlgorithmic() works exactly like ucnv_convert() 1569b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * except that the two converters need not be looked up and opened completely. 1570b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1571b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The source-to-pivot conversion uses the cnv converter parameter. 1572b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The pivot-to-target conversion uses a purely algorithmic converter 1573b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * according to the specified type, e.g., UCNV_UTF8 for a UTF-8 converter. 1574b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1575b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Internally, the algorithmic converter is opened and closed for each 1576b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * function call, which is more efficient than using the public ucnv_open() 1577b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * but somewhat less efficient than only resetting an existing converter 1578b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and using ucnv_convertEx(). 1579b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1580b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This function is more convenient than ucnv_convertEx() for single-string 1581b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conversions, especially when "preflighting" is desired (returning the length 1582b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * of the complete output even if it does not fit into the target buffer; 1583b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * see the User Guide Strings chapter). See ucnv_convert() for details. 1584b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1585b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param algorithmicType UConverterType constant identifying the desired target 1586b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * charset as a purely algorithmic converter. 1587b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Those are converters for Unicode charsets like 1588b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * UTF-8, BOCU-1, SCSU, UTF-7, IMAP-mailbox-name, etc., 1589b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * as well as US-ASCII and ISO-8859-1. 1590b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv The converter that is used to convert 1591b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * from the source to the UTF-16 pivot buffer. 1592b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param target Pointer to the output buffer. 1593b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param targetCapacity Capacity of the target, in bytes. 1594b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param source Pointer to the input buffer. 1595b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceLength Length of the input text, in bytes 1596b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode ICU error code in/out parameter. 1597b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Must fulfill U_SUCCESS before the function call. 1598b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return Length of the complete output text in bytes, even if it exceeds the targetCapacity 1599b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and a U_BUFFER_OVERFLOW_ERROR is set. 1600b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1601b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromAlgorithmic 1602b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convert 1603b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convertEx 1604b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUnicode 1605b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUnicode 1606b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUChars 1607b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUChars 1608b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.6 1609b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1610b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 1611b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_toAlgorithmic(UConverterType algorithmicType, 1612b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverter *cnv, 1613b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru char *target, int32_t targetCapacity, 1614b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *source, int32_t sourceLength, 1615b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 1616b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1617b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1618b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Convert from one external charset to another. 1619b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Internally, the text is converted to and from the 16-bit Unicode "pivot" 1620b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * using ucnv_convertEx(). ucnv_fromAlgorithmic() works exactly like ucnv_convert() 1621b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * except that the two converters need not be looked up and opened completely. 1622b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1623b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The source-to-pivot conversion uses a purely algorithmic converter 1624b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * according to the specified type, e.g., UCNV_UTF8 for a UTF-8 converter. 1625b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The pivot-to-target conversion uses the cnv converter parameter. 1626b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1627b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Internally, the algorithmic converter is opened and closed for each 1628b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * function call, which is more efficient than using the public ucnv_open() 1629b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * but somewhat less efficient than only resetting an existing converter 1630b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and using ucnv_convertEx(). 1631b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1632b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This function is more convenient than ucnv_convertEx() for single-string 1633b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conversions, especially when "preflighting" is desired (returning the length 1634b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * of the complete output even if it does not fit into the target buffer; 1635b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * see the User Guide Strings chapter). See ucnv_convert() for details. 1636b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1637b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv The converter that is used to convert 1638b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * from the UTF-16 pivot buffer to the target. 1639b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param algorithmicType UConverterType constant identifying the desired source 1640b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * charset as a purely algorithmic converter. 1641b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Those are converters for Unicode charsets like 1642b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * UTF-8, BOCU-1, SCSU, UTF-7, IMAP-mailbox-name, etc., 1643b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * as well as US-ASCII and ISO-8859-1. 1644b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param target Pointer to the output buffer. 1645b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param targetCapacity Capacity of the target, in bytes. 1646b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param source Pointer to the input buffer. 1647b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceLength Length of the input text, in bytes 1648b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode ICU error code in/out parameter. 1649b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Must fulfill U_SUCCESS before the function call. 1650b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return Length of the complete output text in bytes, even if it exceeds the targetCapacity 1651b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and a U_BUFFER_OVERFLOW_ERROR is set. 1652b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1653b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromAlgorithmic 1654b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convert 1655b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_convertEx 1656b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUnicode 1657b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUnicode 1658b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_fromUChars 1659b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_toUChars 1660b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.6 1661b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1662b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 1663b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_fromAlgorithmic(UConverter *cnv, 1664b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UConverterType algorithmicType, 1665b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru char *target, int32_t targetCapacity, 1666b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *source, int32_t sourceLength, 1667b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 1668b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1669b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1670b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Frees up memory occupied by unused, cached converter shared data. 1671b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1672b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the number of cached converters successfully deleted 1673b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_close 1674b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1675b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1676b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 1677b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_flushCache(void); 1678b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1679b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1680b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the number of available converters, as per the alias file. 1681b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1682b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return the number of available converters 1683b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getAvailableName 1684b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1685b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1686b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 1687b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_countAvailable(void); 1688b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1689b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1690b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gets the canonical converter name of the specified converter from a list of 1691b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * all available converters contaied in the alias file. All converters 1692b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * in this list can be opened. 1693b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1694b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param n the index to a converter available on the system (in the range <TT>[0..ucnv_countAvaiable()]</TT>) 1695b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return a pointer a string (library owned), or <TT>NULL</TT> if the index is out of bounds. 1696b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_countAvailable 1697b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1698b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1699b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const char* U_EXPORT2 1700b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getAvailableName(int32_t n); 1701b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1702b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1703b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns a UEnumeration to enumerate all of the canonical converter 1704b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * names, as per the alias file, regardless of the ability to open each 1705b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * converter. 1706b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1707b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return A UEnumeration object for getting all the recognized canonical 1708b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * converter names. 1709b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getAvailableName 1710b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see uenum_close 1711b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see uenum_next 1712b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.4 1713b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1714b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UEnumeration * U_EXPORT2 1715b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_openAllNames(UErrorCode *pErrorCode); 1716b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1717b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1718b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gives the number of aliases for a given converter or alias name. 1719b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the alias is ambiguous, then the preferred converter is used 1720b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and the status is set to U_AMBIGUOUS_ALIAS_WARNING. 1721b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This method only enumerates the listed entries in the alias file. 1722b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param alias alias name 1723b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode error status 1724b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return number of names on alias list for given alias 1725b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1726b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1727b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE uint16_t U_EXPORT2 1728b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_countAliases(const char *alias, UErrorCode *pErrorCode); 1729b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1730b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1731b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gives the name of the alias at given index of alias list. 1732b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This method only enumerates the listed entries in the alias file. 1733b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the alias is ambiguous, then the preferred converter is used 1734b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and the status is set to U_AMBIGUOUS_ALIAS_WARNING. 1735b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param alias alias name 1736b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param n index in alias list 1737b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode result of operation 1738b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return returns the name of the alias at given index 1739b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_countAliases 1740b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1741b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1742b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const char * U_EXPORT2 1743b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getAlias(const char *alias, uint16_t n, UErrorCode *pErrorCode); 1744b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1745b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1746b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Fill-up the list of alias names for the given alias. 1747b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This method only enumerates the listed entries in the alias file. 1748b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * If the alias is ambiguous, then the preferred converter is used 1749b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and the status is set to U_AMBIGUOUS_ALIAS_WARNING. 1750b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param alias alias name 1751b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param aliases fill-in list, aliases is a pointer to an array of 1752b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <code>ucnv_countAliases()</code> string-pointers 1753b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (<code>const char *</code>) that will be filled in. 1754b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The strings themselves are owned by the library. 1755b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode result of operation 1756b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1757b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1758b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1759b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getAliases(const char *alias, const char **aliases, UErrorCode *pErrorCode); 1760b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1761b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1762b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Return a new UEnumeration object for enumerating all the 1763b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * alias names for a given converter that are recognized by a standard. 1764b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This method only enumerates the listed entries in the alias file. 1765b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The convrtrs.txt file can be modified to change the results of 1766b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * this function. 1767b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The first result in this list is the same result given by 1768b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <code>ucnv_getStandardName</code>, which is the default alias for 1769b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * the specified standard name. The returned object must be closed with 1770b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <code>uenum_close</code> when you are done with the object. 1771b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1772b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param convName original converter name 1773b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param standard name of the standard governing the names; MIME and IANA 1774b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * are such standards 1775b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode The error code 1776b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return A UEnumeration object for getting all aliases that are recognized 1777b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * by a standard. If any of the parameters are invalid, NULL 1778b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * is returned. 1779b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getStandardName 1780b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see uenum_close 1781b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see uenum_next 1782b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.2 1783b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1784b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UEnumeration * U_EXPORT2 1785b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_openStandardNames(const char *convName, 1786b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru const char *standard, 1787b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 1788b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1789b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1790b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gives the number of standards associated to converter names. 1791b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return number of standards 1792b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1793b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1794b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE uint16_t U_EXPORT2 1795b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_countStandards(void); 1796b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1797b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1798b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Gives the name of the standard at given index of standard list. 1799b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param n index in standard list 1800b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode result of operation 1801b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return returns the name of the standard at given index. Owned by the library. 1802b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1803b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1804b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const char * U_EXPORT2 1805b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getStandard(uint16_t n, UErrorCode *pErrorCode); 1806b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1807b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1808b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns a standard name for a given converter name. 1809b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p> 1810b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Example alias table:<br> 1811b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conv alias1 { STANDARD1 } alias2 { STANDARD1* } 1812b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p> 1813b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Result of ucnv_getStandardName("conv", "STANDARD1") from example 1814b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * alias table:<br> 1815b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <b>"alias2"</b> 1816b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1817b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param name original converter name 1818b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param standard name of the standard governing the names; MIME and IANA 1819b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * are such standards 1820b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode result of operation 1821b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return returns the standard converter name; 1822b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * if a standard converter name cannot be determined, 1823b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * then <code>NULL</code> is returned. Owned by the library. 1824b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1825b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1826b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const char * U_EXPORT2 1827b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getStandardName(const char *name, const char *standard, UErrorCode *pErrorCode); 1828b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1829b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1830b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This function will return the internal canonical converter name of the 1831b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * tagged alias. This is the opposite of ucnv_openStandardNames, which 1832b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * returns the tagged alias given the canonical name. 1833b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p> 1834b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Example alias table:<br> 1835b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * conv alias1 { STANDARD1 } alias2 { STANDARD1* } 1836b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p> 1837b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Result of ucnv_getStandardName("alias1", "STANDARD1") from example 1838b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * alias table:<br> 1839b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <b>"conv"</b> 1840b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1841b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return returns the canonical converter name; 1842b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * if a standard or alias name cannot be determined, 1843b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * then <code>NULL</code> is returned. The returned string is 1844b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * owned by the library. 1845b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getStandardName 1846b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.4 1847b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1848b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const char * U_EXPORT2 1849b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getCanonicalName(const char *alias, const char *standard, UErrorCode *pErrorCode); 1850b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1851b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1852b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the current default converter name. If you want to open 1853b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * a default converter, you do not need to use this function. 1854b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * It is faster if you pass a NULL argument to ucnv_open the 1855b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * default converter. 1856b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1857b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * If U_CHARSET_IS_UTF8 is defined to 1 in utypes.h then this function 1858b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * always returns "UTF-8". 1859b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * 1860b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return returns the current default converter name. 1861b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Storage owned by the library 1862b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setDefaultName 1863b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1864b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1865b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const char * U_EXPORT2 1866b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_getDefaultName(void); 1867b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1868103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius#ifndef U_HIDE_SYSTEM_API 1869b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1870b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This function is not thread safe. DO NOT call this function when ANY ICU 1871b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * function is being used from more than one thread! This function sets the 1872b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * current default converter name. If this function needs to be called, it 1873b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * should be called during application initialization. Most of the time, the 1874b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * results from ucnv_getDefaultName() or ucnv_open with a NULL string argument 1875b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * is sufficient for your application. 1876b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * 1877b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * If U_CHARSET_IS_UTF8 is defined to 1 in utypes.h then this function 1878b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * does nothing. 1879b0ac937921a2c196d8b9da665135bf6ba01a1ccfJean-Baptiste Queru * 1880b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param name the converter name to be the default (must be known by ICU). 1881b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_getDefaultName 1882b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @system 1883b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1884b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1885b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1886b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_setDefaultName(const char *name); 1887103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius#endif /* U_HIDE_SYSTEM_API */ 1888b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1889b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1890b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Fixes the backslash character mismapping. For example, in SJIS, the backslash 1891b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * character in the ASCII portion is also used to represent the yen currency sign. 1892b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * When mapping from Unicode character 0x005C, it's unclear whether to map the 1893b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * character back to yen or backslash in SJIS. This function will take the input 1894b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * buffer and replace all the yen sign characters with backslash. This is necessary 1895b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * when the user tries to open a file with the input buffer on Windows. 1896b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This function will test the converter to see whether such mapping is 1897b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * required. You can sometimes avoid using this function by using the correct version 1898b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * of Shift-JIS. 1899b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1900b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv The converter representing the target codepage. 1901b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param source the input buffer to be fixed 1902b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceLen the length of the input buffer 1903b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_isAmbiguous 1904b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1905b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1906b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1907b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_fixFileSeparator(const UConverter *cnv, UChar *source, int32_t sourceLen); 1908b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1909b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1910b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Determines if the converter contains ambiguous mappings of the same 1911b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * character or not. 1912b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv the converter to be tested 1913b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return TRUE if the converter contains ambiguous mapping of the same 1914b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * character, FALSE otherwise. 1915b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1916b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1917b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UBool U_EXPORT2 1918b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_isAmbiguous(const UConverter *cnv); 1919b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1920b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1921b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Sets the converter to use fallback mappings or not. 1922b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Regardless of this flag, the converter will always use 1923b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * fallbacks from Unicode Private Use code points, as well as 1924b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * reverse fallbacks (to Unicode). 1925b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For details see ".ucm File Format" 1926b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * in the Conversion Data chapter of the ICU User Guide: 1927b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * http://www.icu-project.org/userguide/conversion-data.html#ucmformat 1928b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1929b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv The converter to set the fallback mapping usage on. 1930b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param usesFallback TRUE if the user wants the converter to take advantage of the fallback 1931b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * mapping, FALSE otherwise. 1932b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1933b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_usesFallback 1934b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1935b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE void U_EXPORT2 1936b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_setFallback(UConverter *cnv, UBool usesFallback); 1937b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1938b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1939b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Determines if the converter uses fallback mappings or not. 1940b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * This flag has restrictions, see ucnv_setFallback(). 1941b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1942b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv The converter to be tested 1943b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return TRUE if the converter uses fallback, FALSE otherwise. 1944b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.0 1945b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @see ucnv_setFallback 1946b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1947b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE UBool U_EXPORT2 1948b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_usesFallback(const UConverter *cnv); 1949b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1950b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1951b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Detects Unicode signature byte sequences at the start of the byte stream 1952b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and returns the charset name of the indicated Unicode charset. 1953b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * NULL is returned when no Unicode signature is recognized. 1954b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The number of bytes in the signature is output as well. 1955b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1956b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The caller can ucnv_open() a converter using the charset name. 1957b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * The first code unit (UChar) from the start of the stream will be U+FEFF 1958b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * (the Unicode BOM/signature character) and can usually be ignored. 1959b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1960b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * For most Unicode charsets it is also possible to ignore the indicated 1961b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * number of initial stream bytes and start converting after them. 1962b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * However, there are stateful Unicode charsets (UTF-7 and BOCU-1) for which 1963b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * this will not work. Therefore, it is best to ignore the first output UChar 1964b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * instead of the input signature bytes. 1965b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * <p> 1966b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Usage: 1967103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * \snippet samples/ucnv/convsamp.cpp ucnv_detectUnicodeSignature 1968b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * 1969b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param source The source string in which the signature should be detected. 1970b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param sourceLength Length of the input string, or -1 if terminated with a NUL byte. 1971b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param signatureLength A pointer to int32_t to receive the number of bytes that make up the signature 1972b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * of the detected UTF. 0 if not detected. 1973b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Can be a NULL pointer. 1974b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param pErrorCode ICU error code in/out parameter. 1975b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Must fulfill U_SUCCESS before the function call. 1976b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return The name of the encoding detected. NULL if encoding is not detected. 1977b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 2.4 1978b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1979b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE const char* U_EXPORT2 1980b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_detectUnicodeSignature(const char* source, 1981b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t sourceLength, 1982b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru int32_t *signatureLength, 1983b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru UErrorCode *pErrorCode); 1984b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1985b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 1986b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the number of UChars held in the converter's internal state 1987b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * because more input is needed for completing the conversion. This function is 1988b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * useful for mapping semantics of ICU's converter interface to those of iconv, 1989b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and this information is not needed for normal conversion. 1990b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv The converter in which the input is held 1991b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param status ICU error code in/out parameter. 1992b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Must fulfill U_SUCCESS before the function call. 1993b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return The number of UChars in the state. -1 if an error is encountered. 1994b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 3.4 1995b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 1996b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 1997b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_fromUCountPending(const UConverter* cnv, UErrorCode* status); 1998b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 1999b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/** 2000b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Returns the number of chars held in the converter's internal state 2001b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * because more input is needed for completing the conversion. This function is 2002b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * useful for mapping semantics of ICU's converter interface to those of iconv, 2003b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * and this information is not needed for normal conversion. 2004b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param cnv The converter in which the input is held as internal state 2005b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @param status ICU error code in/out parameter. 2006b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * Must fulfill U_SUCCESS before the function call. 2007b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @return The number of chars in the state. -1 if an error is encountered. 2008b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru * @stable ICU 3.4 2009b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru */ 2010b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste QueruU_STABLE int32_t U_EXPORT2 2011b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queruucnv_toUCountPending(const UConverter* cnv, UErrorCode* status); 2012b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 2013b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho/** 2014b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * Returns whether or not the charset of the converter has a fixed number of bytes 2015b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * per charset character. 2016b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * An example of this are converters that are of the type UCNV_SBCS or UCNV_DBCS. 2017b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * Another example is UTF-32 which is always 4 bytes per character. 2018b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * A Unicode code point may be represented by more than one UTF-8 or UTF-16 code unit 2019b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * but a UTF-32 converter encodes each code point with 4 bytes. 2020b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * Note: This method is not intended to be used to determine whether the charset has a 2021b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * fixed ratio of bytes to Unicode codes <i>units</i> for any particular Unicode encoding form. 2022b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * FALSE is returned with the UErrorCode if error occurs or cnv is NULL. 2023b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param cnv The converter to be tested 2024b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @param status ICU error code in/out paramter 2025b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho * @return TRUE if the converter is fixed-width 2026103e9ffba2cba345d0078eb8b8db33249f81840aCraig Cornelius * @stable ICU 4.8 2027b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho */ 202854dcd9b6a06071f647dac967e9e267abb9410720Craig CorneliusU_STABLE UBool U_EXPORT2 2029b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2clairehoucnv_isFixedWidth(UConverter *cnv, UErrorCode *status); 2030b26ce3a7367e4ed2ee7ddddcdc3f3d3377a455c2claireho 2031b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#endif 2032b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru 2033b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru#endif 2034b13da9df870a61b11249bf741347908dbea0edd8Jean-Baptiste Queru/*_UCNV*/ 2035