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 nsIUnicodeEncoder_h___
39 : #define nsIUnicodeEncoder_h___
40 :
41 : #include "nscore.h"
42 : #include "nsError.h"
43 : #include "nsISupports.h"
44 :
45 : // Interface ID for our Unicode Encoder interface
46 : // {2B2CA3D0-A4C9-11d2-8AA1-00600811A836}
47 : #define NS_IUNICODEENCODER_IID \
48 : { 0x2b2ca3d0, 0xa4c9, 0x11d2, \
49 : { 0x8a, 0xa1, 0x0, 0x60, 0x8, 0x11, 0xa8, 0x36 }}
50 :
51 : // Interface ID for our Unicode Character Encoder interface
52 : // {299BCCD0-C6DF-11d2-8AA8-00600811A836}
53 : #define NS_IUNICHARENCODER_IID \
54 : { 0x299bccd0, 0xc6df, 0x11d2, \
55 : {0x8a, 0xa8, 0x0, 0x60, 0x8, 0x11, 0xa8, 0x36 }}
56 :
57 : #define NS_OK_UENC_EXACTLENGTH \
58 : NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 0x21)
59 :
60 : #define NS_OK_UENC_MOREOUTPUT \
61 : NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 0x22)
62 :
63 : #define NS_ERROR_UENC_NOMAPPING \
64 : NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 0x23)
65 :
66 : #define NS_OK_UENC_MOREINPUT \
67 : NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_UCONV, 0x24)
68 :
69 :
70 : #define NS_UNICODEENCODER_CONTRACTID_BASE "@mozilla.org/intl/unicode/encoder;1?charset="
71 :
72 : /**
73 : * Interface which converts a single character from Unicode into a given
74 : * charset.
75 : *
76 : * @created 17/Feb/1999
77 : * @author Catalin Rotaru [CATA]
78 : */
79 : class nsIUnicharEncoder : public nsISupports
80 : {
81 : public:
82 : NS_DECLARE_STATIC_IID_ACCESSOR(NS_IUNICHARENCODER_IID)
83 :
84 : /**
85 : * Converts a character from Unicode to a Charset.
86 : */
87 : NS_IMETHOD Convert(PRUnichar aChar, char * aDest, PRInt32 * aDestLength) = 0;
88 : };
89 :
90 : NS_DEFINE_STATIC_IID_ACCESSOR(nsIUnicharEncoder, NS_IUNICHARENCODER_IID)
91 :
92 : //
93 : // Malloc an Encoder (unicode -> charset) buffer if the
94 : // result won't fit in the static buffer
95 : //
96 : // p = the buffer pointer (char*)
97 : // e = encoder (nsIUnicodeEncoder*)
98 : // s = string (PRUnichar*)
99 : // l = string length (PRInt32)
100 : // sb = static buffer (char[])
101 : // sbl = static buffer length (PRUint32)
102 : // al = actual buffer length (PRInt32)
103 : //
104 : #define ENCODER_BUFFER_ALLOC_IF_NEEDED(p,e,s,l,sb,sbl,al) \
105 : PR_BEGIN_MACRO \
106 : if (e \
107 : && NS_SUCCEEDED((e)->GetMaxLength((s), (l), &(al)))\
108 : && ((al) > (PRInt32)(sbl)) \
109 : && (nsnull!=((p)=(char*)nsMemory::Alloc((al)+1))) \
110 : ) { \
111 : } \
112 : else { \
113 : (p) = (char*)(sb); \
114 : (al) = (sbl); \
115 : } \
116 : PR_END_MACRO
117 :
118 : //
119 : // Free the Encoder buffer if it was allocated
120 : //
121 : #define ENCODER_BUFFER_FREE_IF_NEEDED(p,sb) \
122 : PR_BEGIN_MACRO \
123 : if ((p) != (char*)(sb)) \
124 : nsMemory::Free(p); \
125 : PR_END_MACRO
126 :
127 : /**
128 : * Interface for a Converter from Unicode into a Charset.
129 : *
130 : * @created 23/Nov/1998
131 : * @author Catalin Rotaru [CATA]
132 : */
133 : class nsIUnicodeEncoder : public nsISupports
134 11500 : {
135 : public:
136 : NS_DECLARE_STATIC_IID_ACCESSOR(NS_IUNICODEENCODER_IID)
137 :
138 : enum {
139 : kOnError_Signal, // on an error, stop and signal
140 : kOnError_CallBack, // on an error, call the error handler
141 : kOnError_Replace // on an error, replace with a different character
142 : };
143 :
144 : /**
145 : * Converts the data from Unicode to a Charset.
146 : *
147 : * About the byte ordering:
148 : * - The input stream is Unicode, having the byte order which is internal
149 : * for the machine on which the converter is running on.
150 : * - For output, if the converter cares (that depends of the charset, for
151 : * example a singlebyte will ignore the byte ordering) it should assume
152 : * network order. If necessary and requested, we can add a method
153 : * SetOutputByteOrder() so that the reverse order can be used, too. That
154 : * method would have as default the assumed network order.
155 : *
156 : * For the last converted char, even if there is not enough output
157 : * space, a partial output must be done until all available space will be
158 : * used. The rest of the output should be buffered until more space becomes
159 : * available. But this is not also true about the error handling method!!!
160 : * So be very, very careful...
161 : *
162 : * @param aSrc [IN] the source data buffer
163 : * @param aSrcLength [IN/OUT] the length of source data buffer; after
164 : * conversion will contain the number of Unicode
165 : * characters read
166 : * @param aDest [OUT] the destination data buffer
167 : * @param aDestLength [IN/OUT] the length of the destination data buffer;
168 : * after conversion will contain the number of bytes
169 : * written
170 : * @return NS_OK_UENC_MOREOUTPUT if only a partial conversion
171 : * was done; more output space is needed to continue
172 : * NS_OK_UENC_MOREINPUT if only a partial conversion
173 : * was done; more input is needed to continue. This can
174 : * occur when the last UTF-16 code point in the input is
175 : * the first of a surrogate pair.
176 : * NS_ERROR_UENC_NOMAPPING if character without mapping
177 : * was encountered and the behavior was set to "signal".
178 : */
179 : NS_IMETHOD Convert(const PRUnichar * aSrc, PRInt32 * aSrcLength,
180 : char * aDest, PRInt32 * aDestLength) = 0;
181 :
182 : /**
183 : * Finishes the conversion. The converter has the possibility to write some
184 : * extra data and flush its final state.
185 : *
186 : * @param aDest [OUT] the destination data buffer
187 : * @param aDestLength [IN/OUT] the length of destination data buffer; after
188 : * conversion it will contain the number of bytes written
189 : * @return NS_OK_UENC_MOREOUTPUT if only a partial conversion
190 : * was done; more output space is needed to continue
191 : */
192 : NS_IMETHOD Finish(char * aDest, PRInt32 * aDestLength) = 0;
193 :
194 : /**
195 : * Returns a quick estimation of the size of the buffer needed to hold the
196 : * converted data. Remember: this estimation is >= with the actual size of
197 : * the buffer needed. It will be computed for the "worst case"
198 : *
199 : * @param aSrc [IN] the source data buffer
200 : * @param aSrcLength [IN] the length of source data buffer
201 : * @param aDestLength [OUT] the needed size of the destination buffer
202 : * @return NS_OK_UENC_EXACTLENGTH if an exact length was computed
203 : * NS_OK if all we have is an approximation
204 : */
205 : NS_IMETHOD GetMaxLength(const PRUnichar * aSrc, PRInt32 aSrcLength,
206 : PRInt32 * aDestLength) = 0;
207 :
208 : /**
209 : * Resets the charset converter so it may be recycled for a completely
210 : * different and urelated buffer of data.
211 : */
212 : NS_IMETHOD Reset() = 0;
213 :
214 : /**
215 : * Specify what to do when a character cannot be mapped into the dest charset
216 : *
217 : * @param aOrder [IN] the behavior; taken from the enum
218 : */
219 : NS_IMETHOD SetOutputErrorBehavior(PRInt32 aBehavior,
220 : nsIUnicharEncoder * aEncoder, PRUnichar aChar) = 0;
221 : };
222 :
223 : NS_DEFINE_STATIC_IID_ACCESSOR(nsIUnicodeEncoder, NS_IUNICODEENCODER_IID)
224 :
225 : #endif /* nsIUnicodeEncoder_h___ */
|