michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #ifndef nsIUnicodeDecoder_h___ michael@0: #define nsIUnicodeDecoder_h___ michael@0: michael@0: #include "nscore.h" michael@0: #include "nsISupports.h" michael@0: michael@0: // Interface ID for our Unicode Decoder interface michael@0: // {25359602-FC70-4d13-A9AB-8086D3827C0D} michael@0: //NS_DECLARE_ID(kIUnicodeDecoderIID, michael@0: // 0x25359602, 0xfc70, 0x4d13, 0xa9, 0xab, 0x80, 0x86, 0xd3, 0x82, 0x7c, 0xd); michael@0: michael@0: #define NS_IUNICODEDECODER_IID \ michael@0: { 0x25359602, 0xfc70, 0x4d13, \ michael@0: { 0xa9, 0xab, 0x80, 0x86, 0xd3, 0x82, 0x7c, 0xd }} michael@0: michael@0: michael@0: #define NS_UNICODEDECODER_CONTRACTID_BASE "@mozilla.org/intl/unicode/decoder;1?charset=" michael@0: michael@0: /** michael@0: * Interface for a Converter from a Charset into Unicode. michael@0: * michael@0: * @created 23/Nov/1998 michael@0: * @author Catalin Rotaru [CATA] michael@0: */ michael@0: class nsIUnicodeDecoder : public nsISupports michael@0: { michael@0: public: michael@0: NS_DECLARE_STATIC_IID_ACCESSOR(NS_IUNICODEDECODER_IID) michael@0: michael@0: enum { michael@0: kOnError_Recover, // on an error, recover and continue michael@0: kOnError_Signal // on an error, stop and signal michael@0: }; michael@0: michael@0: /** michael@0: * Converts the data from one Charset to Unicode. michael@0: * michael@0: * About the byte ordering: michael@0: * - For input, if the converter cares (that depends of the charset, for michael@0: * example a singlebyte will ignore the byte ordering) it should assume michael@0: * network order. If necessary and requested, we can add a method michael@0: * SetInputByteOrder() so that the reverse order can be used, too. That michael@0: * method would have as default the assumed network order. michael@0: * - The output stream is Unicode, having the byte order which is internal michael@0: * for the machine on which the converter is running on. michael@0: * michael@0: * Unless there is not enough output space, this method must consume all the michael@0: * available input data! The eventual incomplete final character data will be michael@0: * stored internally in the converter and used when the method is called michael@0: * again for continuing the conversion. This way, the caller will not have to michael@0: * worry about managing incomplete input data by mergeing it with the next michael@0: * buffer. michael@0: * michael@0: * Error conditions: michael@0: * If the read value does not belong to this character set, one should michael@0: * replace it with the Unicode special 0xFFFD. When an actual input error is michael@0: * encountered, like a format error, the converter stop and return error. michael@0: * However, we should keep in mind that we need to be lax in decoding. When michael@0: * a decoding error is returned to the caller, it is the caller's michael@0: * responsibility to advance over the bad byte (unless aSrcLength is -1 in michael@0: * which case the caller should call the decoder with 0 offset again) and michael@0: * reset the decoder before trying to call the decoder again. michael@0: * michael@0: * Converter required behavior: michael@0: * In this order: when output space is full - return right away. When input michael@0: * data is wrong, return input pointer right after the wrong byte. When michael@0: * partial input, it will be consumed and cached. All the time input pointer michael@0: * will show how much was actually consumed and how much was actually michael@0: * written. michael@0: * michael@0: * @param aSrc [IN] the source data buffer michael@0: * @param aSrcLength [IN/OUT] the length of source data buffer; after michael@0: * conversion will contain the number of bytes read or michael@0: * -1 on error to indicate that the caller should re-push michael@0: * the same buffer after resetting the decoder michael@0: * @param aDest [OUT] the destination data buffer michael@0: * @param aDestLength [IN/OUT] the length of the destination data buffer; michael@0: * after conversion will contain the number of Unicode michael@0: * characters written michael@0: * @return NS_PARTIAL_MORE_INPUT if only a partial conversion was michael@0: * done; more input is needed to continue michael@0: * NS_PARTIAL_MORE_OUTPUT if only a partial conversion michael@0: * was done; more output space is needed to continue michael@0: * NS_ERROR_ILLEGAL_INPUT if an illegal input sequence michael@0: * was encountered and the behavior was set to "signal"; michael@0: * the caller must skip over one byte, reset the decoder michael@0: * and retry. michael@0: */ michael@0: NS_IMETHOD Convert(const char * aSrc, int32_t * aSrcLength, michael@0: char16_t * aDest, int32_t * aDestLength) = 0; michael@0: michael@0: /** michael@0: * Returns a quick estimation of the size of the buffer needed to hold the michael@0: * converted data. Remember: this estimation is >= with the actual size of michael@0: * the buffer needed. It will be computed for the "worst case" michael@0: * michael@0: * @param aSrc [IN] the source data buffer michael@0: * @param aSrcLength [IN] the length of source data buffer michael@0: * @param aDestLength [OUT] the needed size of the destination buffer michael@0: * @return NS_EXACT_LENGTH if an exact length was computed michael@0: * NS_OK is all we have is an approximation michael@0: */ michael@0: NS_IMETHOD GetMaxLength(const char * aSrc, int32_t aSrcLength, michael@0: int32_t * aDestLength) = 0; michael@0: michael@0: /** michael@0: * Resets the charset converter so it may be recycled for a completely michael@0: * different and urelated buffer of data. michael@0: */ michael@0: NS_IMETHOD Reset() = 0; michael@0: michael@0: /** michael@0: * Specify what to do when a character cannot be mapped into unicode michael@0: * michael@0: * @param aBehavior [IN] the desired behavior michael@0: * @see kOnError_Recover michael@0: * @see kOnError_Signal michael@0: */ michael@0: virtual void SetInputErrorBehavior(int32_t aBehavior) = 0; michael@0: michael@0: /** michael@0: * return the UNICODE character for unmapped character michael@0: */ michael@0: virtual char16_t GetCharacterForUnMapped() = 0; michael@0: }; michael@0: michael@0: NS_DEFINE_STATIC_IID_ACCESSOR(nsIUnicodeDecoder, NS_IUNICODEDECODER_IID) michael@0: michael@0: #endif /* nsIUnicodeDecoder_h___ */