intl/uconv/public/nsIUnicodeDecoder.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Mozilla Communicator client code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef nsIUnicodeDecoder_h___
  39 #define nsIUnicodeDecoder_h___
  40
  41 #include "nscore.h"
  42 #include "nsISupports.h"
  43
  44 // Interface ID for our Unicode Decoder interface
  45 // {B2F178E1-832A-11d2-8A8E-00600811A836}
  46 //NS_DECLARE_ID(kIUnicodeDecoderIID,
  47 //  0xb2f178e1, 0x832a, 0x11d2, 0x8a, 0x8e, 0x0, 0x60, 0x8, 0x11, 0xa8, 0x36);
  48
  49 #define NS_IUNICODEDECODER_IID  \
  50         { 0xb2f178e1, 0x832a, 0x11d2,   \
  51                 { 0x8a, 0x8e, 0x0, 0x60, 0x8, 0x11, 0xa8, 0x36 }}
  52
  53 // XXX deprecated
  54 /*---------- BEGIN DEPRECATED */
  55 #define NS_EXACT_LENGTH \
  56   NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 11)
  57
  58 #define NS_PARTIAL_MORE_INPUT \
  59   NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 12)
  60
  61 #define NS_PARTIAL_MORE_OUTPUT \
  62   NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 13)
  63
  64 #define NS_ERROR_ILLEGAL_INPUT \
  65   NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_UCONV, 14)
  66 /*---------- END DEPRECATED */
  67
  68 // XXX make us hex! (same digits though)
  69 #define NS_OK_UDEC_EXACTLENGTH      \
  70   NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 11)
  71
  72 #define NS_OK_UDEC_MOREINPUT        \
  73   NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 12)
  74
  75 #define NS_OK_UDEC_MOREOUTPUT       \
  76   NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 13)
  77
  78 #define NS_ERROR_UDEC_ILLEGALINPUT  \
  79   NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_UCONV, 14)
  80
  81 #define NS_OK_UDEC_NOBOMFOUND       \
  82   NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 14)
  83
  84
  85 #define NS_UNICODEDECODER_CONTRACTID_BASE "@mozilla.org/intl/unicode/decoder;1?charset="
  86
  87 /**
  88  * Interface for a Converter from a Charset into Unicode.
  89  *
  90  * @created         23/Nov/1998
  91  * @author  Catalin Rotaru [CATA]
  92  */
  93 class nsIUnicodeDecoder : public nsISupports
  94 {
  95 public:
  96   NS_DECLARE_STATIC_IID_ACCESSOR(NS_IUNICODEDECODER_IID)
  97
  98   enum {
  99     kOnError_Recover,       // on an error, recover and continue
 100     kOnError_Signal         // on an error, stop and signal
 101   };
 102
 103   /**
 104    * Converts the data from one Charset to Unicode.
 105    *
 106    * About the byte ordering:
 107    * - For input, if the converter cares (that depends of the charset, for
 108    * example a singlebyte will ignore the byte ordering) it should assume
 109    * network order. If necessary and requested, we can add a method
 110    * SetInputByteOrder() so that the reverse order can be used, too. That
 111    * method would have as default the assumed network order.
 112    * - The output stream is Unicode, having the byte order which is internal
 113    * for the machine on which the converter is running on.
 114    *
 115    * Unless there is not enough output space, this method must consume all the
 116    * available input data! The eventual incomplete final character data will be
 117    * stored internally in the converter and used when the method is called
 118    * again for continuing the conversion. This way, the caller will not have to
 119    * worry about managing incomplete input data by mergeing it with the next
 120    * buffer.
 121    *
 122    * Error conditions:
 123    * If the read value does not belong to this character set, one should
 124    * replace it with the Unicode special 0xFFFD. When an actual input error is
 125    * encountered, like a format error, the converter stop and return error.
 126    * Hoever, we should keep in mind that we need to be lax in decoding.
 127    *
 128    * Converter required behavior:
 129    * In this order: when output space is full - return right away. When input
 130    * data is wrong, return input pointer right after the wrong byte. When
 131    * partial input, it will be consumed and cached. All the time input pointer
 132    * will show how much was actually consumed and how much was actually
 133    * written.
 134    *
 135    * @param aSrc        [IN] the source data buffer
 136    * @param aSrcLength  [IN/OUT] the length of source data buffer; after
 137    *                    conversion will contain the number of bytes read
 138    * @param aDest       [OUT] the destination data buffer
 139    * @param aDestLength [IN/OUT] the length of the destination data buffer;
 140    *                    after conversion will contain the number of Unicode
 141    *                    characters written
 142    * @return            NS_PARTIAL_MORE_INPUT if only a partial conversion was
 143    *                    done; more input is needed to continue
 144    *                    NS_PARTIAL_MORE_OUTPUT if only  a partial conversion
 145    *                    was done; more output space is needed to continue
 146    *                    NS_ERROR_ILLEGAL_INPUT if an illegal input sequence
 147    *                    was encountered and the behavior was set to "signal"
 148    */
 149   NS_IMETHOD Convert(const char * aSrc, PRInt32 * aSrcLength,
 150       PRUnichar * aDest, PRInt32 * aDestLength) = 0;
 151
 152   /**
 153    * Returns a quick estimation of the size of the buffer needed to hold the
 154    * converted data. Remember: this estimation is >= with the actual size of
 155    * the buffer needed. It will be computed for the "worst case"
 156    *
 157    * @param aSrc        [IN] the source data buffer
 158    * @param aSrcLength  [IN] the length of source data buffer
 159    * @param aDestLength [OUT] the needed size of the destination buffer
 160    * @return            NS_EXACT_LENGTH if an exact length was computed
 161    *                    NS_OK is all we have is an approximation
 162    */
 163   NS_IMETHOD GetMaxLength(const char * aSrc, PRInt32 aSrcLength,
 164       PRInt32 * aDestLength) = 0;
 165
 166   /**
 167    * Resets the charset converter so it may be recycled for a completely
 168    * different and urelated buffer of data.
 169    */
 170   NS_IMETHOD Reset() = 0;
 171 };
 172
 173 NS_DEFINE_STATIC_IID_ACCESSOR(nsIUnicodeDecoder, NS_IUNICODEDECODER_IID)
 174
 175 #endif /* nsIUnicodeDecoder_h___ */