iconv_cnv.hpp
上传用户:zhuqijet
上传日期:2013-06-25
资源大小:10074k
文件大小:15k
源码类别:

词法分析

开发平台:

Visual C++

  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.  * $Log: iconv_cnv.hpp,v $
  58.  * Revision 1.2  2002/11/04 15:14:33  tng
  59.  * C++ Namespace Support.
  60.  *
  61.  * Revision 1.1.1.1  2002/02/01 22:22:36  peiyongz
  62.  * sane_include
  63.  *
  64.  * Revision 1.1  2001/06/25 16:19:34  tng
  65.  * Rename iconv_cnv.h to iconv_cnv.hpp.  AS400 changes by Linda Swan.
  66.  *
  67.  * Revision 1.1  2000/02/10 18:08:28  abagchi
  68.  * Initial checkin
  69.  *
  70.  */
  71. #ifndef UCNV_H
  72. #define UCNV_H
  73. #include "utypes.h"
  74. XERCES_CPP_NAMESPACE_BEGIN
  75. /**
  76.  * Creates a UConverter object with the names specified as a C string.
  77.  * The actual name will be resolved with the alias file.
  78.  * if <TT>NULL</TT> is passed for the converter name, it will create one with the
  79.  * getDefaultName return value.
  80.  * @param converterName : name of the uconv table
  81.  * @param err outgoing error status <TT>MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND</TT>
  82.  * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured
  83.  * @see ucnv_openU
  84.  * @see ucnv_openCCSID
  85.  * @see ucnv_close
  86.  */
  87. U_CAPI
  88. UConverter* U_EXPORT2 ucnv_open   (const char *converterName,
  89.    UErrorCode * err);
  90. /**
  91.  * Creates a Unicode converter with the names specified as unicode string. The name should be limited to
  92.  * the ASCII-7 alphanumerics range. The actual name will be resolved with the alias file.
  93.  * if <TT>NULL</TT> is passed for the converter name, it will create one with the
  94.  * getDefaultName return value.
  95.  * @param converterName : name of the uconv table in a zero terminated Unicode string
  96.  * @param err outgoing error status <TT>MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND</TT>
  97.  * @return the created Unicode converter object, or <TT>NULL</TT> if an error occured
  98.  * @see ucnv_open
  99.  * @see ucnv_openCCSID
  100.  * @see ucnv_close
  101.  */
  102. U_CAPI UConverter* U_EXPORT2 ucnv_openU (const UChar * name,
  103.        UErrorCode * err);
  104. /**
  105.  * Creates a UConverter object using a CCSID number.
  106.  * @param codepage : codepage # of the uconv table
  107.  * @param platform : codepage's platform (now only <TT>IBM</TT> supported)
  108.  * @param err error status <TT>MEMORY_ALLOCATION_ERROR, TABLE_NOT_FOUND</TT>
  109.  * @return the created Unicode converter object, or <TT>NULL</TT> if and error occured
  110.  * @see ucnv_open
  111.  * @see ucnv_openU
  112.  * @see ucnv_close
  113.  */
  114. U_CAPI void  U_EXPORT2 ucnv_close (UConverter * converter);
  115. /**
  116.  * Returns the maximum length of bytes used by a character. This varies between 1 and 4
  117.  * @param converter the Unicode converter
  118.  * @return the maximum number of bytes allowed by this particular converter
  119.  * @see ucnv_getMinCharSize
  120.  */
  121. U_CAPI int8_t U_EXPORT2
  122.     ucnv_getMaxCharSize (const UConverter * converter);
  123. /**
  124.  * Returns the minimum byte length for characters in this codepage. This is either
  125.  * 1 or 2 for all supported codepages.
  126.  * @param converter the Unicode converter
  127.  * @return the minimum number of bytes allowed by this particular converter
  128.  * @see ucnv_getMaxCharSize
  129.  */
  130. U_CAPI int8_t U_EXPORT2
  131.     ucnv_getMinCharSize (const UConverter * converter);
  132. /**
  133.  * Transcodes an array of unicode characters to an array of codepage characters.
  134.  * The source pointer is an I/O parameter, it starts out pointing where the function is
  135.  * to begin transcoding, and ends up pointing after the first sequence of the bytes
  136.  * that it encounters that are semantically invalid.
  137.  * if ucnv_setToUCallBack is called with an action other than <TT>STOP</TT>
  138.  * before a call is made to this API, <TT>consumed</TT> and <TT>source</TT> should point to the same place
  139.  * (unless <TT>target</TT> ends with an imcomplete sequence of bytes and <TT>flush</TT> is <TT>FALSE</TT>).
  140.  * the <TT>target</TT> buffer buffer needs to be a least the size of the maximum # of bytes per characters
  141.  * allowed by the target codepage.
  142.  * @param converter the Unicode converter
  143.  * @param converter the Unicode converter
  144.  * @param target : I/O parameter. Input : Points to the beginning of the buffer to copy
  145.  *  codepage characters to. Output : points to after the last codepage character copied
  146.  *  to <TT>target</TT>.
  147.  * @param targetLimit the pointer to the end of the <TT>target</TT> array
  148.  * @param source the source Unicode character array
  149.  * @param sourceLimit the pointer to the end of the source array
  150.  * @param offsets if NULL is passed, nothing will happen to it, otherwise it needs to have the same number
  151.  * of allocated cells as <TT>target</TT>. Will fill in offsets from target to source pointer
  152.  * 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>
  153.  * For output data carried across calls -1 will be placed for offsets.
  154.  * @param flush <TT>TRUE</TT> if the buffer is the last buffer of the conversion interation
  155.  * and the conversion will finish with this call, FALSE otherwise.
  156.  * @param err the error status.  <TT>ILLEGAL_ARGUMENT_ERROR</TT> will be returned if the
  157.  * converter is <TT>NULL</TT>.
  158.  * @see ucnv_fromUChars
  159.  * @see ucnv_convert
  160.  * @see ucnv_getMinCharSize
  161.  * @see ucnv_setToUCallBack
  162.  */
  163. U_CAPI
  164.   void U_EXPORT2 ucnv_fromUnicode (UConverter * converter,
  165.  char **target,
  166.  const char *targetLimit,
  167.  const UChar ** source,
  168.  const UChar * sourceLimit,
  169.  int32_t* offsets,
  170.  int flush,
  171.  UErrorCode * err);
  172. /**
  173.  * Converts an array of codepage characters into an array of unicode characters.
  174.  * The source pointer is an I/O parameter, it starts out pointing at the place
  175.  * to begin translating, and ends up pointing after the first sequence of the bytes
  176.  * that it encounters that are semantically invalid.
  177.  * if ucnv_setFromUCallBack is called with an action other than STOP
  178.  * before a call is made to this API, consumed and source should point to the same place
  179.  * (unless target ends with an imcomplete sequence of bytes and flush is FALSE).
  180.  * @param converter the Unicode converter
  181.  * @param target : I/O parameter. Input : Points to the beginning of the buffer to copy
  182.  *  Unicode characters to. Output : points to after the last UChar copied to target.
  183.  * @param targetLimit the pointer to the end of the target array
  184.  * @param source the source codepage character array
  185.  * @param sourceLimit the pointer to the end of the source array
  186.  * @param offsets if NULL is passed, nothing will happen to it, otherwise it needs to have the same number
  187.  * of allocated cells as <TT>target</TT>. Will fill in offsets from target to source pointer
  188.  * 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>
  189.  * For output data carried across calls -1 will be placed for offsets.
  190.  * @param flush TRUE if the buffer is the last buffer and the conversion will finish
  191.  * in this call, FALSE otherwise.
  192.  * @param err the error code status  <TT>ILLEGAL_ARGUMENT_ERROR</TT> will be returned if the
  193.  * converter is <TT>NULL</TT>, or if <TT>targetLimit</TT> and <TT>sourceLimit</TT> are misaligned.
  194.  * @see ucnv_toUChars
  195.  * @see ucnv_getNextUChar
  196.  * @see ucnv_convert
  197.  * @see ucnv_setFromUCallBack
  198.  */
  199. U_CAPI
  200.   void U_EXPORT2 ucnv_toUnicode (UConverter * converter,
  201.        UChar ** target,
  202.        const UChar * targetLimit,
  203.        const char **source,
  204.        const char *sourceLimit,
  205.        int32_t* offsets,
  206.        int flush,
  207.        UErrorCode * err);
  208. /**
  209.  * Transcodes the source Unicode string to the target string in a codepage encoding
  210.  * with the specified Unicode converter.  For example, if a Unicode to/from JIS
  211.  * converter is specified, the source string in Unicode will be transcoded to JIS
  212.  * encoding.  The result will be stored in JIS encoding.
  213.  * if any problems during conversion are encountered it will SUBSTITUTE with the default (initial)
  214.  * substitute characters.
  215.  * This function is a more convenient but less efficient version of Ref{ucnv_fromUnicode}.
  216.  * @param converter the Unicode converter
  217.  * @param source the <TT>source</TT> Unicode string (zero Terminated)
  218.  * @param target the <TT>target</TT> string in codepage encoding (<STRONG>not zero-terminated</STRONG> because some
  219.  * codepage do not use '' as a string terminator
  220.  * @param targetCapacity Input the number of bytes available in the <TT>target</TT> buffer
  221.  * @param err the error status code.
  222.  * <TT>INDEX_OUTOFBOUNDS_ERROR</TT> will be returned if the
  223.  * the # of bytes provided are not enough for transcoding.
  224.  * <TT>ILLEGAL_ARGUMENT_ERROR</TT> is returned if the converter is <TT>NULL</TT> or the source or target string is empty.
  225.  * <TT>BUFFER_OVERFLOW_ERROR</TT> when <TT>targetSize</TT> turns out to be bigger than <TT>targetCapacity</TT>
  226.  * @return number of bytes needed in target, regardless of <TT>targetCapacity</TT>
  227.  * @see ucnv_fromUnicode
  228.  * @see ucnv_convert
  229.  */
  230. U_CAPI
  231.   int32_t U_EXPORT2 ucnv_fromUChars (const UConverter * converter,
  232.    char *target,
  233.    int32_t targetCapacity,
  234.    const UChar * source,
  235.    UErrorCode * err);
  236. /**
  237.  * Transcode the source string in codepage encoding to the target string in
  238.  * Unicode encoding.  For example, if a Unicode to/from JIS
  239.  * converter is specified, the source string in JIS encoding will be transcoded
  240.  * to Unicode and placed into a provided target buffer.
  241.  * if any problems during conversion are encountered it will SUBSTITUTE with the Unicode REPLACEMENT char
  242.  * We recomment, the size of the target buffer needs to be at least as long as the maximum # of bytes per char
  243.  * in this character set.
  244.  * A zero-terminator will be placed at the end of the target buffer
  245.  * This function is a more convenient but less efficient version of Ref{ucnv_toUnicode}.
  246.  * @param converter the Unicode converter
  247.  * @param source the source string in codepage encoding
  248.  * @param target the target string in Unicode encoding
  249.  * @param targetCapacity capacity of the target buffer
  250.  * @param sourceSize : Number of bytes in <TT>source</TT> to be transcoded
  251.  * @param err the error status code
  252.  * <TT>MEMORY_ALLOCATION_ERROR</TT> will be returned if the
  253.  * the internal process buffer cannot be allocated for transcoding.
  254.  * <TT>ILLEGAL_ARGUMENT_ERROR</TT> is returned if the converter is <TT>NULL</TT> or
  255.  * if the source or target string is empty.
  256.  * <TT>BUFFER_OVERFLOW_ERROR</TT> when the input buffer is prematurely exhausted and targetSize non-<TT>NULL</TT>.
  257.  * @return the number of UChar needed in target (including the zero terminator)
  258.  * @see ucnv_getNextUChar
  259.  * @see ucnv_toUnicode
  260.  * @see ucnv_convert
  261.  */
  262. U_CAPI
  263.   int32_t U_EXPORT2 ucnv_toUChars (const UConverter * converter,
  264.  UChar * target,
  265.  int32_t targetCapacity,
  266.  const char *source,
  267.  int32_t sourceSize,
  268.  UErrorCode * err);
  269. /********************************
  270.  * Will convert a codepage buffer one character at a time.
  271.  * This function was written to be efficient when transcoding small amounts of data at a time.
  272.  * In that case it will be more efficient than Ref{ucnv_toUnicode}.
  273.  * When converting large buffers use Ref{ucnv_toUnicode}.
  274.  *@param converter an open UConverter
  275.  *@param source the address of a pointer to the codepage buffer, will be updated to point after
  276.  *the bytes consumed in the conversion call.
  277.  *@param points to the end of the input buffer
  278.  *@param err fills in error status (see ucnv_toUnicode)
  279.  *@return a UChar resulting from the partial conversion of source
  280.  *@see ucnv_toUnicode
  281.  *@see ucnv_toUChars
  282.  *@see ucnv_convert
  283.  */
  284. U_CAPI
  285.   UChar U_EXPORT2 ucnv_getNextUChar (UConverter * converter,
  286.    const char **source,
  287.    const char *sourceLimit,
  288.    UErrorCode * err);
  289. /**************************
  290. * Will convert a sequence of bytes from one codepage to another.
  291. * This is <STRONG>NOT AN EFFICIENT</STRONG> way to transcode.
  292. * use Ref{ucnv_toUnicode} and Ref{ucnv_fromUnicode} for efficiency
  293. * @param toConverterName: The name of the converter that will be used to encode the output buffer
  294. * @param fromConverterName: The name of the converter that will be used to decode the input buffer
  295. * @param target: Pointer to the output buffer to write to
  296. * @param targetCapacity: on input contains the capacity of target
  297. * @param source: Pointer to the input buffer
  298. * @param sourceLength: on input contains the capacity of source
  299. * @param err: fills in an error status
  300. * @return  will be filled in with the number of bytes needed in target
  301. * @see ucnv_fromUnicode
  302. * @see ucnv_toUnicode
  303. * @see ucnv_fromUChars
  304. * @see ucnv_toUChars
  305. * @see ucnv_getNextUChar
  306. */
  307. U_CAPI
  308.   int32_t U_EXPORT2 ucnv_convert (const char *toConverterName,
  309. const char *fromConverterName,
  310. char *target,
  311. int32_t targetCapacity,
  312. const char *source,
  313. int32_t sourceLength,
  314. UErrorCode * err);
  315. XERCES_CPP_NAMESPACE_END
  316. #endif