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 : // {25359602-FC70-4d13-A9AB-8086D3827C0D}
46 : //NS_DECLARE_ID(kIUnicodeDecoderIID,
47 : // 0x25359602, 0xfc70, 0x4d13, 0xa9, 0xab, 0x80, 0x86, 0xd3, 0x82, 0x7c, 0xd);
48 :
49 : #define NS_IUNICODEDECODER_IID \
50 : { 0x25359602, 0xfc70, 0x4d13, \
51 : { 0xa9, 0xab, 0x80, 0x86, 0xd3, 0x82, 0x7c, 0xd }}
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 15552 : {
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 : * However, we should keep in mind that we need to be lax in decoding. When
127 : * a decoding error is returned to the caller, it is the caller's
128 : * responsibility to advance over the bad byte (unless aSrcLength is -1 in
129 : * which case the caller should call the decoder with 0 offset again) and
130 : * reset the decoder before trying to call the decoder again.
131 : *
132 : * Converter required behavior:
133 : * In this order: when output space is full - return right away. When input
134 : * data is wrong, return input pointer right after the wrong byte. When
135 : * partial input, it will be consumed and cached. All the time input pointer
136 : * will show how much was actually consumed and how much was actually
137 : * written.
138 : *
139 : * @param aSrc [IN] the source data buffer
140 : * @param aSrcLength [IN/OUT] the length of source data buffer; after
141 : * conversion will contain the number of bytes read or
142 : * -1 on error to indicate that the caller should re-push
143 : * the same buffer after resetting the decoder
144 : * @param aDest [OUT] the destination data buffer
145 : * @param aDestLength [IN/OUT] the length of the destination data buffer;
146 : * after conversion will contain the number of Unicode
147 : * characters written
148 : * @return NS_PARTIAL_MORE_INPUT if only a partial conversion was
149 : * done; more input is needed to continue
150 : * NS_PARTIAL_MORE_OUTPUT if only a partial conversion
151 : * was done; more output space is needed to continue
152 : * NS_ERROR_ILLEGAL_INPUT if an illegal input sequence
153 : * was encountered and the behavior was set to "signal";
154 : * the caller must skip over one byte, reset the decoder
155 : * and retry.
156 : */
157 : NS_IMETHOD Convert(const char * aSrc, PRInt32 * aSrcLength,
158 : PRUnichar * aDest, PRInt32 * aDestLength) = 0;
159 :
160 : /**
161 : * Returns a quick estimation of the size of the buffer needed to hold the
162 : * converted data. Remember: this estimation is >= with the actual size of
163 : * the buffer needed. It will be computed for the "worst case"
164 : *
165 : * @param aSrc [IN] the source data buffer
166 : * @param aSrcLength [IN] the length of source data buffer
167 : * @param aDestLength [OUT] the needed size of the destination buffer
168 : * @return NS_EXACT_LENGTH if an exact length was computed
169 : * NS_OK is all we have is an approximation
170 : */
171 : NS_IMETHOD GetMaxLength(const char * aSrc, PRInt32 aSrcLength,
172 : PRInt32 * aDestLength) = 0;
173 :
174 : /**
175 : * Resets the charset converter so it may be recycled for a completely
176 : * different and urelated buffer of data.
177 : */
178 : NS_IMETHOD Reset() = 0;
179 :
180 : /**
181 : * Specify what to do when a character cannot be mapped into unicode
182 : *
183 : * @param aBehavior [IN] the desired behavior
184 : * @see kOnError_Recover
185 : * @see kOnError_Signal
186 : */
187 : virtual void SetInputErrorBehavior(PRInt32 aBehavior) = 0;
188 :
189 : /**
190 : * return the UNICODE character for unmapped character
191 : */
192 : virtual PRUnichar GetCharacterForUnMapped() = 0;
193 : };
194 :
195 : NS_DEFINE_STATIC_IID_ACCESSOR(nsIUnicodeDecoder, NS_IUNICODEDECODER_IID)
196 :
197 : #endif /* nsIUnicodeDecoder_h___ */
|