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 #ifndef INCLUDED_RTL_TENCINFO_H
  21 #define INCLUDED_RTL_TENCINFO_H
  22
  23 #include "sal/config.h"
  24
  25 #include "rtl/textenc.h"
  26 #include "sal/saldllapi.h"
  27 #include "sal/types.h"
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  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)
  42
  43 /** Information about a text encoding.
  44  */
  45 typedef struct _rtl_TextEncodingInfo
  46 {
  47     /** The size (in bytes) of this structure.  Should be 12.
  48      */
  49     sal_uInt32          StructSize;
  50
  51     /** The minimum number of bytes needed to encode any character in the
  52         given encoding.
  53
  54         Can be rather meaningless for encodings that encode global state along
  55         with the characters (e.g., ISO-2022 encodings).
  56      */
  57     sal_uInt8           MinimumCharSize;
  58
  59     /** The maximum number of bytes needed to encode any character in the
  60         given encoding.
  61
  62         Can be rather meaningless for encodings that encode global state along
  63         with the characters (e.g., ISO-2022 encodings).
  64      */
  65     sal_uInt8           MaximumCharSize;
  66
  67     /** The average number of bytes needed to encode a character in the given
  68         encoding.
  69      */
  70     sal_uInt8           AverageCharSize;
  71
  72     /** An unused byte, for padding.
  73      */
  74     sal_uInt8           Reserved;
  75
  76     /** Any combination of the RTL_TEXTENCODING_INFO flags.
  77
  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).
  81
  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.
  91
  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.
  98
  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.
 103
 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.
 112
 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.
 116
 117         RTL_TEXTENCODING_INFO_UNICODE:  The encoding is based on the Unicode
 118         character repertoire.
 119
 120         RTL_TEXTENCODING_INFO_MULTIBYTE:  A multi-byte encoding.
 121
 122         RTL_TEXTENCODING_INFO_R2L:  An encoding used mainly or exclusively for
 123         languages written from right to left.
 124
 125         RTL_TEXTENCODING_INFO_7BIT:  A 7-bit instead of an 8-bit encoding.
 126
 127         RTL_TEXTENCODING_INFO_SYMBOL:  A (generic) encoding for symbol character
 128         sets.
 129
 130         RTL_TEXTENCODING_INFO_MIME:  The encoding is registered as a MIME
 131         charset.
 132      */
 133     sal_uInt32          Flags;
 134 } rtl_TextEncodingInfo;
 135
 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).
 139
 140     @param nEncoding
 141     Any rtl_TextEncoding value.
 142
 143     @return
 144     True if the given encoding uses single octets as basic units of
 145     information, false otherwise.
 146  */
 147 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_isOctetTextEncoding(rtl_TextEncoding nEncoding);
 148
 149 /** Return information about a text encoding.
 150
 151     @param eTextEncoding
 152     Any rtl_TextEncoding value.
 153
 154     @param pEncInfo
 155     Returns information about the given encoding.  Must not be null, and the
 156     StructSize member must be set correctly.
 157
 158     @return
 159     True if information about the given encoding is available, false
 160     otherwise.
 161  */
 162 SAL_DLLPUBLIC sal_Bool SAL_CALL rtl_getTextEncodingInfo(
 163         rtl_TextEncoding eTextEncoding, rtl_TextEncodingInfo* pEncInfo );
 164
 165 /** Map from a numeric Windows charset to a text encoding.
 166
 167     @param nWinCharset
 168     Any numeric Windows charset.
 169
 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.
 175  */
 176 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL rtl_getTextEncodingFromWindowsCharset(
 177         sal_uInt8 nWinCharset );
 178
 179 /** Map from a MIME charset to a text encoding.
 180
 181     @param pMimeCharset
 182     Any MIME charset string.  Must not be null.
 183
 184     @return
 185     The corresponding rtl_TextEncoding value, or RTL_TEXTENCODING_DONTKNOW if
 186     no mapping is applicable.
 187  */
 188 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL rtl_getTextEncodingFromMimeCharset(
 189         const sal_Char* pMimeCharset );
 190
 191 /** Map from a Unix charset to a text encoding.
 192
 193     @param pUnixCharset
 194     Any Unix charset string.  Must not be null.
 195
 196     @return
 197     The corresponding rtl_TextEncoding value, or RTL_TEXTENCODING_DONTKNOW if
 198     no mapping is applicable.
 199  */
 200 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL rtl_getTextEncodingFromUnixCharset(
 201         const sal_Char* pUnixCharset );
 202
 203 /** Map from a text encoding to the best matching numeric Windows charset.
 204
 205     @param eTextEncoding
 206     Any rtl_TextEncoding value.
 207
 208     @return
 209     The best matching numeric Windows charset, or 1 if none matches.
 210  */
 211 SAL_DLLPUBLIC sal_uInt8 SAL_CALL rtl_getBestWindowsCharsetFromTextEncoding(
 212         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 SAL_DLLPUBLIC char const * SAL_CALL rtl_getMimeCharsetFromTextEncoding(
 225         rtl_TextEncoding 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 SAL_DLLPUBLIC const sal_Char* SAL_CALL rtl_getBestMimeCharsetFromTextEncoding(
 236         rtl_TextEncoding eTextEncoding );
 237
 238 /** Map from a text encoding to the best matching Unix charset.
 239
 240     @param eTextEncoding
 241     Any rtl_TextEncoding value.
 242
 243     @return
 244     The best matching Unix charset string, or null if none matches.
 245  */
 246 SAL_DLLPUBLIC const sal_Char* SAL_CALL rtl_getBestUnixCharsetFromTextEncoding(
 247         rtl_TextEncoding eTextEncoding  );
 248
 249 /** Map from a Windows code page to a text encoding.
 250
 251     @param nCodePage
 252     Any Windows code page number.
 253
 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.
 258  */
 259 SAL_DLLPUBLIC rtl_TextEncoding SAL_CALL
 260 rtl_getTextEncodingFromWindowsCodePage(sal_uInt32 nCodePage);
 261
 262 /** Map from a text encoding to a Windows code page.
 263
 264     @param nEncoding
 265     Any rtl_TextEncoding value.
 266
 267     @return
 268     The corresponding Windows code page number, or 0 if no mapping is
 269     applicable.
 270  */
 271 SAL_DLLPUBLIC sal_uInt32 SAL_CALL
 272 rtl_getWindowsCodePageFromTextEncoding(rtl_TextEncoding nEncoding);
 273
 274 #ifdef __cplusplus
 275 }
 276 #endif
 277
 278 #endif // INCLUDED_RTL_TENCINFO_H
 279
 280 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */