source: NonGTP/Xerces/xercesc/util/Transcoders/Iconv400/iconv_cnv.hpp @ 188

Revision 188, 15.2 KB checked in by mattausch, 19 years ago (diff)

added xercesc to support

Line 
1/*
2 * The Apache Software License, Version 1.1
3 *
4 * Copyright (c) 1999-2001 The Apache Software Foundation.  All rights
5 * reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright
12 *    notice, this list of conditions and the following disclaimer.
13 *
14 * 2. Redistributions in binary form must reproduce the above copyright
15 *    notice, this list of conditions and the following disclaimer in
16 *    the documentation and/or other materials provided with the
17 *    distribution.
18 *
19 * 3. The end-user documentation included with the redistribution,
20 *    if any, must include the following acknowledgment:
21 *       "This product includes software developed by the
22 *        Apache Software Foundation (http://www.apache.org/)."
23 *    Alternately, this acknowledgment may appear in the software itself,
24 *    if and wherever such third-party acknowledgments normally appear.
25 *
26 * 4. The names "Xerces" and "Apache Software Foundation" must
27 *    not be used to endorse or promote products derived from this
28 *    software without prior written permission. For written
29 *    permission, please contact apache\@apache.org.
30 *
31 * 5. Products derived from this software may not be called "Apache",
32 *    nor may "Apache" appear in their name, without prior written
33 *    permission of the Apache Software Foundation.
34 *
35 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
39 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
46 * SUCH DAMAGE.
47 * ====================================================================
48 *
49 * This software consists of voluntary contributions made by many
50 * individuals on behalf of the Apache Software Foundation, and was
51 * originally based on software copyright (c) 1999, International
52 * Business Machines, Inc., http://www.ibm.com .  For more information
53 * on the Apache Software Foundation, please see
54 * <http://www.apache.org/>.
55 */
56
57/**
58 * $Log: iconv_cnv.hpp,v $
59 * Revision 1.2  2002/11/04 15:14:33  tng
60 * C++ Namespace Support.
61 *
62 * Revision 1.1.1.1  2002/02/01 22:22:36  peiyongz
63 * sane_include
64 *
65 * Revision 1.1  2001/06/25 16:19:34  tng
66 * Rename iconv_cnv.h to iconv_cnv.hpp.  AS400 changes by Linda Swan.
67 *
68 * Revision 1.1  2000/02/10 18:08:28  abagchi
69 * Initial checkin
70 *
71 */
72
73#ifndef UCNV_H
74#define UCNV_H
75
76#include "utypes.h"
77
78XERCES_CPP_NAMESPACE_BEGIN
79
80/**
81 * Creates a UConverter object with the names specified as a C string.
82 * The actual name will be resolved with the alias file.
83 * if <TT>NULL</TT> is passed for the converter name, it will create one with the
84 * getDefaultName return value.
85 * @param converterName : name of the uconv table
86 * @param err outgoing error status <TT>MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND</TT>
87 * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured
88 * @see ucnv_openU
89 * @see ucnv_openCCSID
90 * @see ucnv_close
91 */
92
93U_CAPI
94UConverter* U_EXPORT2 ucnv_open   (const char *converterName,
95                                   UErrorCode * err);
96
97
98/**
99 * Creates a Unicode converter with the names specified as unicode string. The name should be limited to
100 * the ASCII-7 alphanumerics range. The actual name will be resolved with the alias file.
101 * if <TT>NULL</TT> is passed for the converter name, it will create one with the
102 * getDefaultName return value.
103 * @param converterName : name of the uconv table in a zero terminated Unicode string
104 * @param err outgoing error status <TT>MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND</TT>
105 * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured
106 * @see ucnv_open
107 * @see ucnv_openCCSID
108 * @see ucnv_close
109 */
110U_CAPI UConverter* U_EXPORT2 ucnv_openU (const UChar * name,
111                                       UErrorCode * err);
112
113
114
115/**
116 * Creates a UConverter object using a CCSID number.
117 * @param codepage : codepage # of the uconv table
118 * @param platform : codepage's platform (now only <TT>IBM</TT> supported)
119 * @param err error status <TT>MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND</TT>
120 * @return the created Unicode converter object, or <TT>NULL</TT> if and error occured
121 * @see ucnv_open
122 * @see ucnv_openU
123 * @see ucnv_close
124 */
125
126
127U_CAPI void  U_EXPORT2 ucnv_close (UConverter * converter);
128
129
130
131
132/**
133 * Returns the maximum length of bytes used by a character. This varies between 1 and 4
134 * @param converter the Unicode converter
135 * @return the maximum number of bytes allowed by this particular converter
136 * @see ucnv_getMinCharSize
137 */
138U_CAPI int8_t U_EXPORT2
139    ucnv_getMaxCharSize (const UConverter * converter);
140
141
142/**
143 * Returns the minimum byte length for characters in this codepage. This is either
144 * 1 or 2 for all supported codepages.
145 * @param converter the Unicode converter
146 * @return the minimum number of bytes allowed by this particular converter
147 * @see ucnv_getMaxCharSize
148 */
149U_CAPI int8_t U_EXPORT2
150    ucnv_getMinCharSize (const UConverter * converter);
151
152
153/**
154 * Transcodes an array of unicode characters to an array of codepage characters.
155 * The source pointer is an I/O parameter, it starts out pointing where the function is
156 * to begin transcoding, and ends up pointing after the first sequence of the bytes
157 * that it encounters that are semantically invalid.
158 * if ucnv_setToUCallBack is called with an action other than <TT>STOP</TT>
159 * before a call is made to this API, <TT>consumed</TT> and <TT>source</TT> should point to the same place
160 * (unless <TT>target</TT> ends with an imcomplete sequence of bytes and <TT>flush</TT> is <TT>FALSE</TT>).
161 * the <TT>target</TT> buffer buffer needs to be a least the size of the maximum # of bytes per characters
162 * allowed by the target codepage.
163 * @param converter the Unicode converter
164 * @param converter the Unicode converter
165 * @param target : I/O parameter. Input : Points to the beginning of the buffer to copy
166 *  codepage characters to. Output : points to after the last codepage character copied
167 *  to <TT>target</TT>.
168 * @param targetLimit the pointer to the end of the <TT>target</TT> array
169 * @param source the source Unicode character array
170 * @param sourceLimit the pointer to the end of the source array
171 * @param offsets if NULL is passed, nothing will happen to it, otherwise it needs to have the same number
172 * of allocated cells as <TT>target</TT>. Will fill in offsets from target to source pointer
173 * 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>
174 * For output data carried across calls -1 will be placed for offsets.
175 * @param flush <TT>TRUE</TT> if the buffer is the last buffer of the conversion interation
176 * and the conversion will finish with this call, FALSE otherwise.
177 * @param err the error status.  <TT>ILLEGAL_ARGUMENT_ERROR</TT> will be returned if the
178 * converter is <TT>NULL</TT>.
179 * @see ucnv_fromUChars
180 * @see ucnv_convert
181 * @see ucnv_getMinCharSize
182 * @see ucnv_setToUCallBack
183 */
184
185U_CAPI
186  void U_EXPORT2 ucnv_fromUnicode (UConverter * converter,
187                         char **target,
188                         const char *targetLimit,
189                         const UChar ** source,
190                         const UChar * sourceLimit,
191                         int32_t* offsets,
192                         int flush,
193                         UErrorCode * err);
194
195
196/**
197 * Converts an array of codepage characters into an array of unicode characters.
198 * The source pointer is an I/O parameter, it starts out pointing at the place
199 * to begin translating, and ends up pointing after the first sequence of the bytes
200 * that it encounters that are semantically invalid.
201 * if ucnv_setFromUCallBack is called with an action other than STOP
202 * before a call is made to this API, consumed and source should point to the same place
203 * (unless target ends with an imcomplete sequence of bytes and flush is FALSE).
204 * @param converter the Unicode converter
205 * @param target : I/O parameter. Input : Points to the beginning of the buffer to copy
206 *  Unicode characters to. Output : points to after the last UChar copied to target.
207 * @param targetLimit the pointer to the end of the target array
208 * @param source the source codepage character array
209 * @param sourceLimit the pointer to the end of the source array
210 * @param offsets if NULL is passed, nothing will happen to it, otherwise it needs to have the same number
211 * of allocated cells as <TT>target</TT>. Will fill in offsets from target to source pointer
212 * 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>
213 * For output data carried across calls -1 will be placed for offsets.
214 * @param flush TRUE if the buffer is the last buffer and the conversion will finish
215 * in this call, FALSE otherwise.
216 * @param err the error code status  <TT>ILLEGAL_ARGUMENT_ERROR</TT> will be returned if the
217 * converter is <TT>NULL</TT>, or if <TT>targetLimit</TT> and <TT>sourceLimit</TT> are misaligned.
218 * @see ucnv_toUChars
219 * @see ucnv_getNextUChar
220 * @see ucnv_convert
221 * @see ucnv_setFromUCallBack
222 */
223
224U_CAPI
225  void U_EXPORT2 ucnv_toUnicode (UConverter * converter,
226                       UChar ** target,
227                       const UChar * targetLimit,
228                       const char **source,
229                       const char *sourceLimit,
230                       int32_t* offsets,
231                       int flush,
232                       UErrorCode * err);
233
234
235/**
236 * Transcodes the source Unicode string to the target string in a codepage encoding
237 * with the specified Unicode converter.  For example, if a Unicode to/from JIS
238 * converter is specified, the source string in Unicode will be transcoded to JIS
239 * encoding.  The result will be stored in JIS encoding.
240 * if any problems during conversion are encountered it will SUBSTITUTE with the default (initial)
241 * substitute characters.
242 * This function is a more convenient but less efficient version of \Ref{ucnv_fromUnicode}.
243 * @param converter the Unicode converter
244 * @param source the <TT>source</TT> Unicode string (zero Terminated)
245 * @param target the <TT>target</TT> string in codepage encoding (<STRONG>not zero-terminated</STRONG> because some
246 * codepage do not use '\0' as a string terminator
247 * @param targetCapacity Input the number of bytes available in the <TT>target</TT> buffer
248 * @param err the error status code.
249 * <TT>INDEX_OUTOFBOUNDS_ERROR</TT> will be returned if the
250 * the # of bytes provided are not enough for transcoding.
251 * <TT>ILLEGAL_ARGUMENT_ERROR</TT> is returned if the converter is <TT>NULL</TT> or the source or target string is empty.
252 * <TT>BUFFER_OVERFLOW_ERROR</TT> when <TT>targetSize</TT> turns out to be bigger than <TT>targetCapacity</TT>
253 * @return number of bytes needed in target, regardless of <TT>targetCapacity</TT>
254 * @see ucnv_fromUnicode
255 * @see ucnv_convert
256 */
257U_CAPI
258  int32_t U_EXPORT2 ucnv_fromUChars (const UConverter * converter,
259                           char *target,
260                           int32_t targetCapacity,
261                           const UChar * source,
262                           UErrorCode * err);
263
264
265
266
267
268/**
269 * Transcode the source string in codepage encoding to the target string in
270 * Unicode encoding.  For example, if a Unicode to/from JIS
271 * converter is specified, the source string in JIS encoding will be transcoded
272 * to Unicode and placed into a provided target buffer.
273 * if any problems during conversion are encountered it will SUBSTITUTE with the Unicode REPLACEMENT char
274 * We recomment, the size of the target buffer needs to be at least as long as the maximum # of bytes per char
275 * in this character set.
276 * A zero-terminator will be placed at the end of the target buffer
277 * This function is a more convenient but less efficient version of \Ref{ucnv_toUnicode}.
278 * @param converter the Unicode converter
279 * @param source the source string in codepage encoding
280 * @param target the target string in Unicode encoding
281 * @param targetCapacity capacity of the target buffer
282 * @param sourceSize : Number of bytes in <TT>source</TT> to be transcoded
283 * @param err the error status code
284 * <TT>MEMORY_ALLOCATION_ERROR</TT> will be returned if the
285 * the internal process buffer cannot be allocated for transcoding.
286 * <TT>ILLEGAL_ARGUMENT_ERROR</TT> is returned if the converter is <TT>NULL</TT> or
287 * if the source or target string is empty.
288 * <TT>BUFFER_OVERFLOW_ERROR</TT> when the input buffer is prematurely exhausted and targetSize non-<TT>NULL</TT>.
289 * @return the number of UChar needed in target (including the zero terminator)
290 * @see ucnv_getNextUChar
291 * @see ucnv_toUnicode
292 * @see ucnv_convert
293 */
294U_CAPI
295  int32_t U_EXPORT2 ucnv_toUChars (const UConverter * converter,
296                         UChar * target,
297                         int32_t targetCapacity,
298                         const char *source,
299                         int32_t sourceSize,
300                         UErrorCode * err);
301
302/********************************
303 * Will convert a codepage buffer one character at a time.
304 * This function was written to be efficient when transcoding small amounts of data at a time.
305 * In that case it will be more efficient than \Ref{ucnv_toUnicode}.
306 * When converting large buffers use \Ref{ucnv_toUnicode}.
307 *@param converter an open UConverter
308 *@param source the address of a pointer to the codepage buffer, will be updated to point after
309 *the bytes consumed in the conversion call.
310 *@param points to the end of the input buffer
311 *@param err fills in error status (see ucnv_toUnicode)
312 *@return a UChar resulting from the partial conversion of source
313 *@see ucnv_toUnicode
314 *@see ucnv_toUChars
315 *@see ucnv_convert
316 */
317U_CAPI
318  UChar U_EXPORT2 ucnv_getNextUChar (UConverter * converter,
319                           const char **source,
320                           const char *sourceLimit,
321                           UErrorCode * err);
322
323
324/**************************
325* Will convert a sequence of bytes from one codepage to another.
326* This is <STRONG>NOT AN EFFICIENT</STRONG> way to transcode.
327* use \Ref{ucnv_toUnicode} and \Ref{ucnv_fromUnicode} for efficiency
328* @param toConverterName: The name of the converter that will be used to encode the output buffer
329* @param fromConverterName: The name of the converter that will be used to decode the input buffer
330* @param target: Pointer to the output buffer to write to
331* @param targetCapacity: on input contains the capacity of target
332* @param source: Pointer to the input buffer
333* @param sourceLength: on input contains the capacity of source
334* @param err: fills in an error status
335* @return  will be filled in with the number of bytes needed in target
336* @see ucnv_fromUnicode
337* @see ucnv_toUnicode
338* @see ucnv_fromUChars
339* @see ucnv_toUChars
340* @see ucnv_getNextUChar
341*/
342U_CAPI
343  int32_t U_EXPORT2 ucnv_convert (const char *toConverterName,
344                        const char *fromConverterName,
345                        char *target,
346                        int32_t targetCapacity,
347                        const char *source,
348                        int32_t sourceLength,
349                        UErrorCode * err);
350
351XERCES_CPP_NAMESPACE_END
352
353#endif
354
Note: See TracBrowser for help on using the repository browser.