intl/uconv/public/nsIUnicodeEncoder.h

   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 {
 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 ouput 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___ */