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
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/
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
15 * The Original Code is Mozilla Communicator client code.
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.
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.
36 * ***** END LICENSE BLOCK ***** */
38 #ifndef nsIUnicodeDecoder_h___
39 #define nsIUnicodeDecoder_h___
42 #include "nsISupports.h"
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);
49 #define NS_IUNICODEDECODER_IID \
50 { 0xb2f178e1, 0x832a, 0x11d2, \
51 { 0x8a, 0x8e, 0x0, 0x60, 0x8, 0x11, 0xa8, 0x36 }}
54 /*---------- BEGIN DEPRECATED */
55 #define NS_EXACT_LENGTH \
56 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 11)
58 #define NS_PARTIAL_MORE_INPUT \
59 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 12)
61 #define NS_PARTIAL_MORE_OUTPUT \
62 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 13)
64 #define NS_ERROR_ILLEGAL_INPUT \
65 NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_UCONV, 14)
66 /*---------- END DEPRECATED */
68 // XXX make us hex! (same digits though)
69 #define NS_OK_UDEC_EXACTLENGTH \
70 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 11)
72 #define NS_OK_UDEC_MOREINPUT \
73 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 12)
75 #define NS_OK_UDEC_MOREOUTPUT \
76 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 13)
78 #define NS_ERROR_UDEC_ILLEGALINPUT \
79 NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_UCONV, 14)
81 #define NS_OK_UDEC_NOBOMFOUND \
82 NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 14)
85 #define NS_UNICODEDECODER_CONTRACTID_BASE "@mozilla.org/intl/unicode/decoder;1?charset="
88 * Interface for a Converter from a Charset into Unicode.
90 * @created 23/Nov/1998
91 * @author Catalin Rotaru [CATA]
93 class nsIUnicodeDecoder
: public nsISupports
96 NS_DECLARE_STATIC_IID_ACCESSOR(NS_IUNICODEDECODER_IID
)
99 kOnError_Recover
, // on an error, recover and continue
100 kOnError_Signal
// on an error, stop and signal
104 * Converts the data from one Charset to Unicode.
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.
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
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.
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
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
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"
149 NS_IMETHOD
Convert(const char * aSrc
, PRInt32
* aSrcLength
,
150 PRUnichar
* aDest
, PRInt32
* aDestLength
) = 0;
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"
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
163 NS_IMETHOD
GetMaxLength(const char * aSrc
, PRInt32 aSrcLength
,
164 PRInt32
* aDestLength
) = 0;
167 * Resets the charset converter so it may be recycled for a completely
168 * different and urelated buffer of data.
170 NS_IMETHOD
Reset() = 0;
173 NS_DEFINE_STATIC_IID_ACCESSOR(nsIUnicodeDecoder
, NS_IUNICODEDECODER_IID
)
175 #endif /* nsIUnicodeDecoder_h___ */