icuSources/common/unicode/ucnvsel.h

   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  */
  47 struct UConverterSelector;
  48 typedef 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  */
  73 U_STABLE UConverterSelector* U_EXPORT2
  74 ucnvsel_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  */
  91 U_STABLE void U_EXPORT2
  92 ucnvsel_close(UConverterSelector *sel);
  93
  94 #if U_SHOW_CPLUSPLUS_API
  95
  96 U_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  */
 107 U_DEFINE_LOCAL_OPEN_POINTER(LocalUConverterSelectorPointer, UConverterSelector, ucnvsel_close);
 108
 109 U_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  */
 128 U_STABLE UConverterSelector* U_EXPORT2
 129 ucnvsel_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  */
 145 U_STABLE int32_t U_EXPORT2
 146 ucnvsel_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  */
 163 U_STABLE UEnumeration * U_EXPORT2
 164 ucnvsel_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  */
 181 U_STABLE UEnumeration * U_EXPORT2
 182 ucnvsel_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__ */