include/rtl/tencinfo.h

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