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