1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ******************************************************************************* 5 * 6 * Copyright (C) 2008-2011, International Business Machines 7 * Corporation, Google and others. All Rights Reserved. 8 * 9 ******************************************************************************* 10 */ 11 /* 12 * Author : eldawy@google.com (Mohamed Eldawy) 13 * ucnvsel.h 14 * 15 * Purpose: To generate a list of encodings capable of handling 16 * a given Unicode text 17 * 18 * Started 09-April-2008 19 */ 20 21 #ifndef __ICU_UCNV_SEL_H__ 22 #define __ICU_UCNV_SEL_H__ 23 24 #include "unicode/utypes.h" 25 26 #if !UCONFIG_NO_CONVERSION 27 28 #include "unicode/uset.h" 29 #include "unicode/utf16.h" 30 #include "unicode/uenum.h" 31 #include "unicode/ucnv.h" 32 #include "unicode/localpointer.h" 33 34 /** 35 * \file 36 * 37 * A converter selector is built with a set of encoding/charset names 38 * and given an input string returns the set of names of the 39 * corresponding converters which can convert the string. 40 * 41 * A converter selector can be serialized into a buffer and reopened 42 * from the serialized form. 43 */ 44 45 /** 46 * @{ 47 * The selector data structure 48 */ 49 struct UConverterSelector; 50 typedef struct UConverterSelector UConverterSelector; 51 /** @} */ 52 53 /** 54 * Open a selector. 55 * If converterListSize is 0, build for all available converters. 56 * If excludedCodePoints is NULL, don't exclude any code points. 57 * 58 * @param converterList a pointer to encoding names needed to be involved. 59 * Can be NULL if converterListSize==0. 60 * The list and the names will be cloned, and the caller 61 * retains ownership of the original. 62 * @param converterListSize number of encodings in above list. 63 * If 0, builds a selector for all available converters. 64 * @param excludedCodePoints a set of code points to be excluded from consideration. 65 * That is, excluded code points in a string do not change 66 * the selection result. (They might be handled by a callback.) 67 * Use NULL to exclude nothing. 68 * @param whichSet what converter set to use? Use this to determine whether 69 * to consider only roundtrip mappings or also fallbacks. 70 * @param status an in/out ICU UErrorCode 71 * @return the new selector 72 * 73 * @stable ICU 4.2 74 */ 75 U_STABLE UConverterSelector* U_EXPORT2 76 ucnvsel_open(const char* const* converterList, int32_t converterListSize, 77 const USet* excludedCodePoints, 78 const UConverterUnicodeSet whichSet, UErrorCode* status); 79 80 /** 81 * Closes a selector. 82 * If any Enumerations were returned by ucnv_select*, they become invalid. 83 * They can be closed before or after calling ucnv_closeSelector, 84 * but should never be used after the selector is closed. 85 * 86 * @see ucnv_selectForString 87 * @see ucnv_selectForUTF8 88 * 89 * @param sel selector to close 90 * 91 * @stable ICU 4.2 92 */ 93 U_STABLE void U_EXPORT2 94 ucnvsel_close(UConverterSelector *sel); 95 96 #if U_SHOW_CPLUSPLUS_API 97 98 U_NAMESPACE_BEGIN 99 100 /** 101 * \class LocalUConverterSelectorPointer 102 * "Smart pointer" class, closes a UConverterSelector via ucnvsel_close(). 103 * For most methods see the LocalPointerBase base class. 104 * 105 * @see LocalPointerBase 106 * @see LocalPointer 107 * @stable ICU 4.4 108 */ 109 U_DEFINE_LOCAL_OPEN_POINTER(LocalUConverterSelectorPointer, UConverterSelector, ucnvsel_close); 110 111 U_NAMESPACE_END 112 113 #endif 114 115 /** 116 * Open a selector from its serialized form. 117 * The buffer must remain valid and unchanged for the lifetime of the selector. 118 * This is much faster than creating a selector from scratch. 119 * Using a serialized form from a different machine (endianness/charset) is supported. 120 * 121 * @param buffer pointer to the serialized form of a converter selector; 122 * must be 32-bit-aligned 123 * @param length the capacity of this buffer (can be equal to or larger than 124 * the actual data length) 125 * @param status an in/out ICU UErrorCode 126 * @return the new selector 127 * 128 * @stable ICU 4.2 129 */ 130 U_STABLE UConverterSelector* U_EXPORT2 131 ucnvsel_openFromSerialized(const void* buffer, int32_t length, UErrorCode* status); 132 133 /** 134 * Serialize a selector into a linear buffer. 135 * The serialized form is portable to different machines. 136 * 137 * @param sel selector to consider 138 * @param buffer pointer to 32-bit-aligned memory to be filled with the 139 * serialized form of this converter selector 140 * @param bufferCapacity the capacity of this buffer 141 * @param status an in/out ICU UErrorCode 142 * @return the required buffer capacity to hold serialize data (even if the call fails 143 * with a U_BUFFER_OVERFLOW_ERROR, it will return the required capacity) 144 * 145 * @stable ICU 4.2 146 */ 147 U_STABLE int32_t U_EXPORT2 148 ucnvsel_serialize(const UConverterSelector* sel, 149 void* buffer, int32_t bufferCapacity, UErrorCode* status); 150 151 /** 152 * Select converters that can map all characters in a UTF-16 string, 153 * ignoring the excluded code points. 154 * 155 * @param sel a selector 156 * @param s UTF-16 string 157 * @param length length of the string, or -1 if NUL-terminated 158 * @param status an in/out ICU UErrorCode 159 * @return an enumeration containing encoding names. 160 * The returned encoding names and their order will be the same as 161 * supplied when building the selector. 162 * 163 * @stable ICU 4.2 164 */ 165 U_STABLE UEnumeration * U_EXPORT2 166 ucnvsel_selectForString(const UConverterSelector* sel, 167 const UChar *s, int32_t length, UErrorCode *status); 168 169 /** 170 * Select converters that can map all characters in a UTF-8 string, 171 * ignoring the excluded code points. 172 * 173 * @param sel a selector 174 * @param s UTF-8 string 175 * @param length length of the string, or -1 if NUL-terminated 176 * @param status an in/out ICU UErrorCode 177 * @return an enumeration containing encoding names. 178 * The returned encoding names and their order will be the same as 179 * supplied when building the selector. 180 * 181 * @stable ICU 4.2 182 */ 183 U_STABLE UEnumeration * U_EXPORT2 184 ucnvsel_selectForUTF8(const UConverterSelector* sel, 185 const char *s, int32_t length, UErrorCode *status); 186 187 #endif /* !UCONFIG_NO_CONVERSION */ 188 189 #endif /* __ICU_UCNV_SEL_H__ */ 190