StringEncodings.subproj/CFStringEncodingConverter.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*      CFStringEncodingConverter.h
  26         Copyright (c) 1998-2003, Apple, Inc. All rights reserved.
  27 */
  28
  29 #ifndef __CFSTRINGENCODINGCONVERTER__
  30 #define __CFSTRINGENCODINGCONVERTER__ 1
  31
  32 #include <CoreFoundation/CFString.h>
  33
  34
  35 #if defined(__cplusplus)
  36 extern "C" {
  37 #endif
  38
  39 /* Values for flags argument for the conversion functions below.  These can be combined, but the three NonSpacing behavior flags are exclusive.
  40 */
  41 enum {
  42     kCFStringEncodingAllowLossyConversion = 1, // Uses fallback functions to substitutes non mappable chars
  43     kCFStringEncodingBasicDirectionLeftToRight = (1 << 1), // Converted with original direction left-to-right.
  44     kCFStringEncodingBasicDirectionRightToLeft = (1 << 2), // Converted with original direction right-to-left.
  45     kCFStringEncodingSubstituteCombinings = (1 << 3), // Uses fallback function to combining chars.
  46     kCFStringEncodingComposeCombinings = (1 << 4), // Checks mappable precomposed equivalents for decomposed sequences.  This is the default behavior.
  47     kCFStringEncodingIgnoreCombinings = (1 << 5), // Ignores combining chars.
  48     kCFStringEncodingUseCanonical = (1 << 6), // Always use canonical form
  49     kCFStringEncodingUseHFSPlusCanonical = (1 << 7), // Always use canonical form but leaves 0x2000 ranges
  50     kCFStringEncodingPrependBOM = (1 << 8), // Prepend BOM sequence (i.e. ISO2022KR)
  51     kCFStringEncodingDisableCorporateArea = (1 << 9), // Disable the usage of 0xF8xx area for Apple proprietary chars in converting to UniChar, resulting loosely mapping.
  52     kCFStringEncodingASCIICompatibleConversion = (1 << 10), // This flag forces strict ASCII compatible converion. i.e. MacJapanese 0x5C maps to Unicode 0x5C.
  53     kCFStringEncodingLenientUTF8Conversion = (1 << 11) // 10.1 (Puma) compatible lenient UTF-8 conversion.
  54 };
  55
  56 /* Return values for CFStringEncodingUnicodeToBytes & CFStringEncodingBytesToUnicode functions
  57 */
  58 enum {
  59     kCFStringEncodingConversionSuccess = 0,
  60     kCFStringEncodingInvalidInputStream = 1,
  61     kCFStringEncodingInsufficientOutputBufferLength = 2,
  62     kCFStringEncodingConverterUnavailable = 3
  63 };
  64
  65 /* Macro to shift lossByte argument.
  66 */
  67 #define CFStringEncodingLossyByteToMask(lossByte)       ((UInt32)(lossByte << 24)|kCFStringEncodingAllowLossyConversion)
  68 #define CFStringEncodingMaskToLossyByte(flags)          ((UInt8)(flags >> 24))
  69
  70 /* Converts characters into the specified encoding.  Returns the constants defined above.
  71 If maxByteLen is 0, bytes is ignored. You can pass lossyByte by passing the value in flags argument.
  72 i.e. CFStringEncodingUnicodeToBytes(encoding, CFStringEncodingLossyByteToMask(lossByte), ....)
  73 */
  74 extern UInt32 CFStringEncodingUnicodeToBytes(UInt32 encoding, UInt32 flags, const UniChar *characters, UInt32 numChars, UInt32 *usedCharLen, UInt8 *bytes, UInt32 maxByteLen, UInt32 *usedByteLen);
  75
  76 /* Converts bytes in the specified encoding into unicode.  Returns the constants defined above.
  77 maxCharLen & usdCharLen are in UniChar length, not byte length.
  78 If maxCharLen is 0, characters is ignored.
  79 */
  80 extern UInt32 CFStringEncodingBytesToUnicode(UInt32 encoding, UInt32 flags, const UInt8 *bytes, UInt32 numBytes, UInt32 *usedByteLen, UniChar *characters, UInt32 maxCharLen, UInt32 *usedCharLen);
  81
  82 /* Fallback functions used when allowLossy
  83 */
  84 typedef UInt32 (*CFStringEncodingToBytesFallbackProc)(const UniChar *characters, UInt32 numChars, UInt8 *bytes, UInt32 maxByteLen, UInt32 *usedByteLen);
  85 typedef UInt32 (*CFStringEncodingToUnicodeFallbackProc)(const UInt8 *bytes, UInt32 numBytes, UniChar *characters, UInt32 maxCharLen, UInt32 *usedCharLen);
  86
  87 extern Boolean CFStringEncodingIsValidEncoding(UInt32 encoding);
  88
  89 /* Returns kCFStringEncodingInvalidId terminated encoding list
  90 */
  91 extern const UInt32 *CFStringEncodingListOfAvailableEncodings(void);
  92
  93 extern const char *CFStringEncodingName(UInt32 encoding);
  94
  95 /* Returns NULL-terminated list of IANA registered canonical names
  96 */
  97 extern const char **CFStringEncodingCanonicalCharsetNames(UInt32 encoding);
  98
  99 /* Returns required length of destination buffer for conversion.  These functions are faster than specifying 0 to maxByteLen (maxCharLen), but unnecessarily optimal length
 100 */
 101 extern UInt32 CFStringEncodingCharLengthForBytes(UInt32 encoding, UInt32 flags, const UInt8 *bytes, UInt32 numBytes);
 102 extern UInt32 CFStringEncodingByteLengthForCharacters(UInt32 encoding, UInt32 flags, const UniChar *characters, UInt32 numChars);
 103
 104 /* Can register functions used for lossy conversion.  Reregisters default procs if NULL
 105 */
 106 extern void CFStringEncodingRegisterFallbackProcedures(UInt32 encoding, CFStringEncodingToBytesFallbackProc toBytes, CFStringEncodingToUnicodeFallbackProc toUnicode);
 107
 108 #if defined(__cplusplus)
 109 }
 110 #endif
 111
 112 #endif /* __CFSTRINGENCODINGCONVERTER__ */
 113