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