Bump version to 6.4-15
[LibreOffice.git] / include / rtl / tencinfo.h
blob74c3bb04f0717304ed90e09976a7383045ff59f8
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /*
3 * This file is part of the LibreOffice project.
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
9 * This file incorporates work covered by the following license notice:
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
20 #ifndef INCLUDED_RTL_TENCINFO_H
21 #define INCLUDED_RTL_TENCINFO_H
23 #include "sal/config.h"
25 #include "rtl/textenc.h"
26 #include "sal/saldllapi.h"
27 #include "sal/types.h"
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
33 // See rtl_TextEncodingInfo.Flags below for documentation on these values:
34 #define RTL_TEXTENCODING_INFO_CONTEXT ((sal_uInt32)0x00000001)
35 #define RTL_TEXTENCODING_INFO_ASCII ((sal_uInt32)0x00000002)
36 #define RTL_TEXTENCODING_INFO_UNICODE ((sal_uInt32)0x00000004)
37 #define RTL_TEXTENCODING_INFO_MULTIBYTE ((sal_uInt32)0x00000008)
38 #define RTL_TEXTENCODING_INFO_R2L ((sal_uInt32)0x00000010)
39 #define RTL_TEXTENCODING_INFO_7BIT ((sal_uInt32)0x00000020)
40 #define RTL_TEXTENCODING_INFO_SYMBOL ((sal_uInt32)0x00000040)
41 #define RTL_TEXTENCODING_INFO_MIME ((sal_uInt32)0x00000080)
43 /** Information about a text encoding.
45 typedef struct _rtl_TextEncodingInfo
47 /** The size (in bytes) of this structure. Should be 12.
49 sal_uInt32 StructSize;
51 /** The minimum number of bytes needed to encode any character in the
52 given encoding.
54 Can be rather meaningless for encodings that encode global state along
55 with the characters (e.g., ISO-2022 encodings).
57 sal_uInt8 MinimumCharSize;
59 /** The maximum number of bytes needed to encode any character in the
60 given encoding.
62 Can be rather meaningless for encodings that encode global state along
63 with the characters (e.g., ISO-2022 encodings).
65 sal_uInt8 MaximumCharSize;
67 /** The average number of bytes needed to encode a character in the given
68 encoding.
70 sal_uInt8 AverageCharSize;
72 /** An unused byte, for padding.
74 sal_uInt8 Reserved;
76 /** Any combination of the RTL_TEXTENCODING_INFO flags.
78 RTL_TEXTENCODING_INFO_CONTEXT: The encoding uses some mechanism (like
79 state-changing byte sequences) to switch between different modes (e.g.,
80 to encode multiple character repertoires within the same byte ranges).
82 Even if an encoding does not have the CONTEXT property, interpretation
83 of certain byte values within that encoding can depend on context (e.g.,
84 a certain byte value could be either a single-byte character or a
85 subsequent byte of a multi-byte character). Likewise, the single shift
86 characters (SS2 and SS3) used by some of the EUC encodings (to denote
87 that the following bytes constitute a character from another character
88 repertoire) do not imply that encodings making use of these characters
89 have the CONTEXT property. Examples of encodings that do have the
90 CONTEXT property are the ISO-2022 encodings and UTF-7.
92 RTL_TEXTENCODING_INFO_ASCII: The encoding is a superset of ASCII. More
93 specifically, any appearance of a byte in the range 0x20--7F denotes the
94 corresponding ASCII character (from SPACE to DELETE); in particular,
95 such a byte cannot be part of a multi-byte character. Note that the
96 ASCII control codes 0x00--1F are not included here, as they are used for
97 special purposes in some encodings.
99 If an encoding has this property, it is easy to search for occurrences of
100 ASCII characters within strings of this encoding---you do not need to
101 keep track whether a byte in the range 0x20--7F really represents an
102 ASCII character or rather is part of some multi-byte character.
104 The guarantees when mapping between Unicode and a given encoding with
105 the ASCII property are as follows: When mapping from Unicode to the
106 given encoding, U+0020--007F map to 0x20--7F (but there can also be
107 other Unicode characters mapping into the range 0x20--7F), and when
108 mapping from the given encoding to Unicode, 0x20--7F map to U+0020--007F
109 (again, there can also be other characters mapping into the range
110 U+0020--007F). In particular, this ensures round-trip conversion for
111 the ASCII range.
113 In principle, the ASCII property is orthogonal to the CONTEXT property.
114 In practice, however, an encoding that has the ASCII property will most
115 likely not also have the CONTEXT property.
117 RTL_TEXTENCODING_INFO_UNICODE: The encoding is based on the Unicode
118 character repertoire.
120 RTL_TEXTENCODING_INFO_MULTIBYTE: A multi-byte encoding.
122 RTL_TEXTENCODING_INFO_R2L: An encoding used mainly or exclusively for
123 languages written from right to left.
125 RTL_TEXTENCODING_INFO_7BIT: A 7-bit instead of an 8-bit encoding.
127 RTL_TEXTENCODING_INFO_SYMBOL: A (generic) encoding for symbol character
128 sets.
130 RTL_TEXTENCODING_INFO_MIME: The encoding is registered as a MIME
131 charset.
133 sal_uInt32 Flags;
134 } rtl_TextEncodingInfo;
136 /** Determine whether a text encoding uses single octets as basic units of
137 information (and can thus be used with the conversion routines in
138 rtl/textcvt.h).
140 @param nEncoding
141 Any rtl_TextEncoding value.
143 @return
144 True if the given encoding uses single octets as basic units of
145 information, false otherwise.
147 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_isOctetTextEncoding(rtl_TextEncoding nEncoding);
149 /** Return information about a text encoding.
151 @param eTextEncoding
152 Any rtl_TextEncoding value.
154 @param pEncInfo
155 Returns information about the given encoding. Must not be null, and the
156 StructSize member must be set correctly.
158 @return
159 True if information about the given encoding is available, false
160 otherwise.
162 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_getTextEncodingInfo(
163 rtl_TextEncoding eTextEncoding, rtl_TextEncodingInfo* pEncInfo );
165 /** Map from a numeric Windows charset to a text encoding.
167 @param nWinCharset
168 Any numeric Windows charset.
170 @return
171 The corresponding rtl_TextEncoding value, or RTL_TEXTENCODING_DONTKNOW if
172 no mapping is applicable.
173 If nWinCharset is 255 (OEM_CHARSET), then return value is RTL_TEXTENCODING_IBM_850,
174 regardless of current locale.
176 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL rtl_getTextEncodingFromWindowsCharset(
177 sal_uInt8 nWinCharset );
179 /** Map from a MIME charset to a text encoding.
181 @param pMimeCharset
182 Any MIME charset string. Must not be null.
184 @return
185 The corresponding rtl_TextEncoding value, or RTL_TEXTENCODING_DONTKNOW if
186 no mapping is applicable.
188 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL rtl_getTextEncodingFromMimeCharset(
189 const sal_Char* pMimeCharset );
191 /** Map from a Unix charset to a text encoding.
193 @param pUnixCharset
194 Any Unix charset string. Must not be null.
196 @return
197 The corresponding rtl_TextEncoding value, or RTL_TEXTENCODING_DONTKNOW if
198 no mapping is applicable.
200 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL rtl_getTextEncodingFromUnixCharset(
201 const sal_Char* pUnixCharset );
203 /** Map from a text encoding to the best matching numeric Windows charset.
205 @param eTextEncoding
206 Any rtl_TextEncoding value.
208 @return
209 The best matching numeric Windows charset, or 1 if none matches.
211 SAL_DLLPUBLIC sal_uInt8 SAL_CALL rtl_getBestWindowsCharsetFromTextEncoding(
212 rtl_TextEncoding eTextEncoding );
214 /** Map from a text encoding to a corresponding MIME charset name, if
215 available (see <http://www.iana.org/assignments/character-sets>).
217 @param nEncoding
218 Any rtl_TextEncoding value.
220 @return
221 The (preferred) MIME charset name corresponding to the given encoding, or
222 NULL if none is available.
224 SAL_DLLPUBLIC char const * SAL_CALL rtl_getMimeCharsetFromTextEncoding(
225 rtl_TextEncoding nEncoding );
227 /** Map from a text encoding to the best matching MIME charset.
229 @param eTextEncoding
230 Any rtl_TextEncoding value.
232 @return
233 The best matching MIME charset string, or null if none matches.
235 SAL_DLLPUBLIC const sal_Char* SAL_CALL rtl_getBestMimeCharsetFromTextEncoding(
236 rtl_TextEncoding eTextEncoding );
238 /** Map from a text encoding to the best matching Unix charset.
240 @param eTextEncoding
241 Any rtl_TextEncoding value.
243 @return
244 The best matching Unix charset string, or null if none matches.
246 SAL_DLLPUBLIC const sal_Char* SAL_CALL rtl_getBestUnixCharsetFromTextEncoding(
247 rtl_TextEncoding eTextEncoding );
249 /** Map from a Windows code page to a text encoding.
251 @param nCodePage
252 Any Windows code page number.
254 @return
255 The corresponding rtl_TextEncoding value (which will be an octet text
256 encoding, see rtl_isOctetTextEncoding), or RTL_TEXTENCODING_DONTKNOW if no
257 mapping is applicable.
259 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL
260 rtl_getTextEncodingFromWindowsCodePage(sal_uInt32 nCodePage);
262 /** Map from a text encoding to a Windows code page.
264 @param nEncoding
265 Any rtl_TextEncoding value.
267 @return
268 The corresponding Windows code page number, or 0 if no mapping is
269 applicable.
271 SAL_DLLPUBLIC sal_uInt32 SAL_CALL
272 rtl_getWindowsCodePageFromTextEncoding(rtl_TextEncoding nEncoding);
274 #ifdef __cplusplus
276 #endif
278 #endif // INCLUDED_RTL_TENCINFO_H
280 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */