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