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