sal/inc/rtl/tencinfo.h

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: tencinfo.h,v $
  10  * $Revision: 1.11 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef _RTL_TENCINFO_H
  32 #define _RTL_TENCINFO_H
  33
  34 #ifndef _SAL_TYPES_H
  35 #include <sal/types.h>
  36 #endif
  37 #include <rtl/textenc.h>
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 // See rtl_TextEncodingInfo.Flags below for documentation on these values:
  44 #define RTL_TEXTENCODING_INFO_CONTEXT   ((sal_uInt32)0x00000001)
  45 #define RTL_TEXTENCODING_INFO_ASCII     ((sal_uInt32)0x00000002)
  46 #define RTL_TEXTENCODING_INFO_UNICODE   ((sal_uInt32)0x00000004)
  47 #define RTL_TEXTENCODING_INFO_MULTIBYTE ((sal_uInt32)0x00000008)
  48 #define RTL_TEXTENCODING_INFO_R2L       ((sal_uInt32)0x00000010)
  49 #define RTL_TEXTENCODING_INFO_7BIT      ((sal_uInt32)0x00000020)
  50 #define RTL_TEXTENCODING_INFO_SYMBOL    ((sal_uInt32)0x00000040)
  51 #define RTL_TEXTENCODING_INFO_MIME      ((sal_uInt32)0x00000080)
  52
  53 /** Information about a text encoding.
  54  */
  55 typedef struct _rtl_TextEncodingInfo
  56 {
  57     /** The size (in bytes) of this structure.  Should be 12.
  58      */
  59     sal_uInt32          StructSize;
  60
  61     /** The minimum number of bytes needed to encode any character in the
  62         given encoding.
  63
  64         Can be rather meaningless for encodings that encode global state along
  65         with the characters (e.g., ISO-2022 encodings).
  66      */
  67     sal_uInt8           MinimumCharSize;
  68
  69     /** The maximum number of bytes needed to encode any character in the
  70         given encoding.
  71
  72         Can be rather meaningless for encodings that encode global state along
  73         with the characters (e.g., ISO-2022 encodings).
  74      */
  75     sal_uInt8           MaximumCharSize;
  76
  77     /** The average number of bytes needed to encode a character in the given
  78         encoding.
  79      */
  80     sal_uInt8           AverageCharSize;
  81
  82     /** An unused byte, for padding.
  83      */
  84     sal_uInt8           Reserved;
  85
  86     /** Any combination of the RTL_TEXTENCODING_INFO flags.
  87
  88         RTL_TEXTENCODING_INFO_CONTEXT:  The encoding uses some mechanism (like
  89         state-changing byte sequences) to switch between different modes (e.g.,
  90         to encode multiple character repertoires within the same byte ranges).
  91
  92         Even if an encoding does not have the CONTEXT property, interpretation
  93         of certain byte values within that encoding can depend on context (e.g.,
  94         a certain byte value could be either a single-byte character or a
  95         subsequent byte of a multi-byte character).  Likewise, the single shift
  96         characters (SS2 and SS3) used by some of the EUC encodings (to denote
  97         that the following bytes constitute a character from another character
  98         repertoire) do not imply that encodings making use of these characters
  99         have the CONTEXT property.  Examples of encodings that do have the
 100         CONTEXT property are the ISO-2022 encodings and UTF-7.
 101
 102         RTL_TEXTENCODING_INFO_ASCII:  The encoding is a superset of ASCII.  More
 103         specifically, any appearance of a byte in the range 0x20--7F denotes the
 104         corresponding ASCII character (from SPACE to DELETE); in particular,
 105         such a byte cannot be part of a multi-byte character.  Note that the
 106         ASCII control codes 0x00--1F are not included here, as they are used for
 107         special purposes in some encodings.
 108
 109         If an encoding has this property, it is easy to search for occurences of
 110         ASCII characters within strings of this encoding---you do not need to
 111         keep track whether a byte in the range 0x20--7F really represents an
 112         ASCII character or rather is part of some multi-byte character.
 113
 114         The guarantees when mapping between Unicode and a given encoding with
 115         the ASCII property are as follows:  When mapping from Unicode to the
 116         given encoding, U+0020--007F map to 0x20--7F (but there can also be
 117         other Unicode characters mapping into the range 0x20--7F), and when
 118         mapping from the given encoding to Unicode, 0x20--7F map to U+0020--007F
 119         (again, there can also be other characters mapping into the range
 120         U+0020--007F).  In particular, this ensures round-trip conversion for
 121         the ASCII range.
 122
 123         In principle, the ASCII property is orthogonal to the CONTEXT property.
 124         In practice, however, an encoding that has the ASCII property will most
 125         likely not also have the CONTEXT property.
 126
 127         RTL_TEXTENCODING_INFO_UNICODE:  The encoding is based on the Unicode
 128         character repertoire.
 129
 130         RTL_TEXTENCODING_INFO_MULTIBYTE:  A multi-byte encoding.
 131
 132         RTL_TEXTENCODING_INFO_R2L:  An encoding used mainly or exclusively for
 133         languages written from right to left.
 134
 135         RTL_TEXTENCODING_INFO_7BIT:  A 7-bit instead of an 8-bit encoding.
 136
 137         RTL_TEXTENCODING_INFO_SYMBOL:  A (generic) encoding for symbol character
 138         sets.
 139
 140         RTL_TEXTENCODING_INFO_MIME:  The encoding is registered as a MIME
 141         charset.
 142      */
 143     sal_uInt32          Flags;
 144 } rtl_TextEncodingInfo;
 145
 146 /** Determine whether a text encoding uses single octets as basic units of
 147     information (and can thus be used with the conversion routines in
 148     rtl/textcvt.h).
 149
 150     @param nEncoding
 151     Any rtl_TextEncoding value.
 152
 153     @return
 154     True if the given encoding uses single octets as basic units of
 155     information, false otherwise.
 156  */
 157 sal_Bool SAL_CALL rtl_isOctetTextEncoding(rtl_TextEncoding nEncoding);
 158
 159 /** Return information about a text encoding.
 160
 161     @param eTextEncoding
 162     Any rtl_TextEncoding value.
 163
 164     @param pEncInfo
 165     Returns information about the given encoding.  Must not be null, and the
 166     StructSize member must be set correctly.
 167
 168     @return
 169     True if information about the given encoding is available, false
 170     otherwise.
 171  */
 172 sal_Bool SAL_CALL rtl_getTextEncodingInfo( rtl_TextEncoding eTextEncoding, rtl_TextEncodingInfo* pEncInfo );
 173
 174 /** Map from a numeric Windows charset to a text encoding.
 175
 176     @param nWinCharset
 177     Any numeric Windows charset.
 178
 179     @return
 180     The corresponding rtl_TextEncoding value, or RTL_TEXTENCODING_DONTKNOW if
 181     no mapping is applicable.
 182  */
 183 rtl_TextEncoding SAL_CALL rtl_getTextEncodingFromWindowsCharset( sal_uInt8 nWinCharset );
 184
 185 /** Map from a MIME charset to a text encoding.
 186
 187     @param pMimeCharset
 188     Any MIME charset string.  Must not be null.
 189
 190     @return
 191     The corresponding rtl_TextEncoding value, or RTL_TEXTENCODING_DONTKNOW if
 192     no mapping is applicable.
 193  */
 194 rtl_TextEncoding SAL_CALL rtl_getTextEncodingFromMimeCharset( const sal_Char* pMimeCharset );
 195
 196 /** Map from a Unix charset to a text encoding.
 197
 198     @param pMimeCharset
 199     Any Unix charset string.  Must not be null.
 200
 201     @return
 202     The corresponding rtl_TextEncoding value, or RTL_TEXTENCODING_DONTKNOW if
 203     no mapping is applicable.
 204  */
 205 rtl_TextEncoding SAL_CALL rtl_getTextEncodingFromUnixCharset( const sal_Char* pUnixCharset );
 206
 207 /** Map from a text encoding to the best matching numeric Windows charset.
 208
 209     @param eTextEncoding
 210     Any rtl_TextEncoding value.
 211
 212     @return
 213     The best matching numeric Windows charset, or 1 if none matches.
 214  */
 215 sal_uInt8       SAL_CALL rtl_getBestWindowsCharsetFromTextEncoding( rtl_TextEncoding eTextEncoding );
 216
 217 /** Map from a text encoding to a corresponding MIME charset name, if
 218     available (see <http://www.iana.org/assignments/character-sets>).
 219
 220     @param nEncoding
 221     Any rtl_TextEncoding value.
 222
 223     @return
 224     The (preferred) MIME charset name corresponding to the given encoding, or
 225     NULL if none is available.
 226  */
 227 char const * SAL_CALL rtl_getMimeCharsetFromTextEncoding(rtl_TextEncoding
 228                                                              nEncoding);
 229
 230 /** Map from a text encoding to the best matching MIME charset.
 231
 232     @param eTextEncoding
 233     Any rtl_TextEncoding value.
 234
 235     @return
 236     The best matching MIME charset string, or null if none matches.
 237  */
 238 const sal_Char* SAL_CALL rtl_getBestMimeCharsetFromTextEncoding( rtl_TextEncoding eTextEncoding );
 239
 240 /** Map from a text encoding to the best matching Unix charset.
 241
 242     @param eTextEncoding
 243     Any rtl_TextEncoding value.
 244
 245     @return
 246     The best matching Unix charset string, or null if none matches.
 247  */
 248 const sal_Char* SAL_CALL rtl_getBestUnixCharsetFromTextEncoding( rtl_TextEncoding eTextEncoding  );
 249
 250 /** Map from a Windows code page to a text encoding.
 251
 252     @param nCodePage
 253     Any Windows code page number.
 254
 255     @return
 256     The corresponding rtl_TextEncoding value (which will be an octet text
 257     encoding, see rtl_isOctetTextEncoding), or RTL_TEXTENCODING_DONTKNOW if no
 258     mapping is applicable.
 259  */
 260 rtl_TextEncoding SAL_CALL
 261 rtl_getTextEncodingFromWindowsCodePage(sal_uInt32 nCodePage);
 262
 263 /** Map from a text encoding to a Windows code page.
 264
 265     @param nEncoding
 266     Any rtl_TextEncoding value.
 267
 268     @return
 269     The corresponding Windows code page number, or 0 if no mapping is
 270     applicable.
 271  */
 272 sal_uInt32 SAL_CALL
 273 rtl_getWindowsCodePageFromTextEncoding(rtl_TextEncoding nEncoding);
 274
 275 #ifdef __cplusplus
 276 }
 277 #endif
 278
 279 #endif /* _RTL_TENCINFO_H */