1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/uconv/public/nsIUnicodeDecoder.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,134 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef nsIUnicodeDecoder_h___
1.10 +#define nsIUnicodeDecoder_h___
1.11 +
1.12 +#include "nscore.h"
1.13 +#include "nsISupports.h"
1.14 +
1.15 +// Interface ID for our Unicode Decoder interface
1.16 +// {25359602-FC70-4d13-A9AB-8086D3827C0D}
1.17 +//NS_DECLARE_ID(kIUnicodeDecoderIID,
1.18 +// 0x25359602, 0xfc70, 0x4d13, 0xa9, 0xab, 0x80, 0x86, 0xd3, 0x82, 0x7c, 0xd);
1.19 +
1.20 +#define NS_IUNICODEDECODER_IID \
1.21 + { 0x25359602, 0xfc70, 0x4d13, \
1.22 + { 0xa9, 0xab, 0x80, 0x86, 0xd3, 0x82, 0x7c, 0xd }}
1.23 +
1.24 +
1.25 +#define NS_UNICODEDECODER_CONTRACTID_BASE "@mozilla.org/intl/unicode/decoder;1?charset="
1.26 +
1.27 +/**
1.28 + * Interface for a Converter from a Charset into Unicode.
1.29 + *
1.30 + * @created 23/Nov/1998
1.31 + * @author Catalin Rotaru [CATA]
1.32 + */
1.33 +class nsIUnicodeDecoder : public nsISupports
1.34 +{
1.35 +public:
1.36 + NS_DECLARE_STATIC_IID_ACCESSOR(NS_IUNICODEDECODER_IID)
1.37 +
1.38 + enum {
1.39 + kOnError_Recover, // on an error, recover and continue
1.40 + kOnError_Signal // on an error, stop and signal
1.41 + };
1.42 +
1.43 + /**
1.44 + * Converts the data from one Charset to Unicode.
1.45 + *
1.46 + * About the byte ordering:
1.47 + * - For input, if the converter cares (that depends of the charset, for
1.48 + * example a singlebyte will ignore the byte ordering) it should assume
1.49 + * network order. If necessary and requested, we can add a method
1.50 + * SetInputByteOrder() so that the reverse order can be used, too. That
1.51 + * method would have as default the assumed network order.
1.52 + * - The output stream is Unicode, having the byte order which is internal
1.53 + * for the machine on which the converter is running on.
1.54 + *
1.55 + * Unless there is not enough output space, this method must consume all the
1.56 + * available input data! The eventual incomplete final character data will be
1.57 + * stored internally in the converter and used when the method is called
1.58 + * again for continuing the conversion. This way, the caller will not have to
1.59 + * worry about managing incomplete input data by mergeing it with the next
1.60 + * buffer.
1.61 + *
1.62 + * Error conditions:
1.63 + * If the read value does not belong to this character set, one should
1.64 + * replace it with the Unicode special 0xFFFD. When an actual input error is
1.65 + * encountered, like a format error, the converter stop and return error.
1.66 + * However, we should keep in mind that we need to be lax in decoding. When
1.67 + * a decoding error is returned to the caller, it is the caller's
1.68 + * responsibility to advance over the bad byte (unless aSrcLength is -1 in
1.69 + * which case the caller should call the decoder with 0 offset again) and
1.70 + * reset the decoder before trying to call the decoder again.
1.71 + *
1.72 + * Converter required behavior:
1.73 + * In this order: when output space is full - return right away. When input
1.74 + * data is wrong, return input pointer right after the wrong byte. When
1.75 + * partial input, it will be consumed and cached. All the time input pointer
1.76 + * will show how much was actually consumed and how much was actually
1.77 + * written.
1.78 + *
1.79 + * @param aSrc [IN] the source data buffer
1.80 + * @param aSrcLength [IN/OUT] the length of source data buffer; after
1.81 + * conversion will contain the number of bytes read or
1.82 + * -1 on error to indicate that the caller should re-push
1.83 + * the same buffer after resetting the decoder
1.84 + * @param aDest [OUT] the destination data buffer
1.85 + * @param aDestLength [IN/OUT] the length of the destination data buffer;
1.86 + * after conversion will contain the number of Unicode
1.87 + * characters written
1.88 + * @return NS_PARTIAL_MORE_INPUT if only a partial conversion was
1.89 + * done; more input is needed to continue
1.90 + * NS_PARTIAL_MORE_OUTPUT if only a partial conversion
1.91 + * was done; more output space is needed to continue
1.92 + * NS_ERROR_ILLEGAL_INPUT if an illegal input sequence
1.93 + * was encountered and the behavior was set to "signal";
1.94 + * the caller must skip over one byte, reset the decoder
1.95 + * and retry.
1.96 + */
1.97 + NS_IMETHOD Convert(const char * aSrc, int32_t * aSrcLength,
1.98 + char16_t * aDest, int32_t * aDestLength) = 0;
1.99 +
1.100 + /**
1.101 + * Returns a quick estimation of the size of the buffer needed to hold the
1.102 + * converted data. Remember: this estimation is >= with the actual size of
1.103 + * the buffer needed. It will be computed for the "worst case"
1.104 + *
1.105 + * @param aSrc [IN] the source data buffer
1.106 + * @param aSrcLength [IN] the length of source data buffer
1.107 + * @param aDestLength [OUT] the needed size of the destination buffer
1.108 + * @return NS_EXACT_LENGTH if an exact length was computed
1.109 + * NS_OK is all we have is an approximation
1.110 + */
1.111 + NS_IMETHOD GetMaxLength(const char * aSrc, int32_t aSrcLength,
1.112 + int32_t * aDestLength) = 0;
1.113 +
1.114 + /**
1.115 + * Resets the charset converter so it may be recycled for a completely
1.116 + * different and urelated buffer of data.
1.117 + */
1.118 + NS_IMETHOD Reset() = 0;
1.119 +
1.120 + /**
1.121 + * Specify what to do when a character cannot be mapped into unicode
1.122 + *
1.123 + * @param aBehavior [IN] the desired behavior
1.124 + * @see kOnError_Recover
1.125 + * @see kOnError_Signal
1.126 + */
1.127 + virtual void SetInputErrorBehavior(int32_t aBehavior) = 0;
1.128 +
1.129 + /**
1.130 + * return the UNICODE character for unmapped character
1.131 + */
1.132 + virtual char16_t GetCharacterForUnMapped() = 0;
1.133 +};
1.134 +
1.135 +NS_DEFINE_STATIC_IID_ACCESSOR(nsIUnicodeDecoder, NS_IUNICODEDECODER_IID)
1.136 +
1.137 +#endif /* nsIUnicodeDecoder_h___ */
