Text Encoding Conversion Manager Reference May 1, 2003 Simultaneously published in the United Apple Computer, Inc. States and Canada. © 2004 Apple Computer, Inc. Even though Apple has reviewed this manual, All rights reserved. APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, No part of this publication may be ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A reproduced, stored in a retrieval system, or PARTICULAR PURPOSE. AS A RESULT, THIS transmitted, in any form or by any means, MANUAL IS SOLD ªAS IS,º AND YOU, THE mechanical, electronic, photocopying, PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. recording, or otherwise, without prior IN NO EVENT WILL APPLE BE LIABLE FOR written permission of Apple Computer, Inc., DIRECT, INDIRECT, SPECIAL, INCIDENTAL, with the following exceptions: Any person OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR is hereby authorized to store documentation INACCURACY IN THIS MANUAL, even if on a single computer for personal use only advised of the possibility of such damages. and to print copies of documentation for THE WARRANTY AND REMEDIES SET personal use provided that the FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, documentation contains Apple’s copyright EXPRESS OR IMPLIED. No Apple dealer, agent, notice. or employee is authorized to make any modification, extension, or addition to this The Apple logo is a trademark of Apple warranty. Computer, Inc. Some states do not allow the exclusion or limitation of implied warranties or liability for Use of the “keyboard” Apple logo incidental or consequential damages, so the (Option-Shift-K) for commercial purposes above limitation or exclusion may not apply to you. This warranty gives you specific legal without the prior written consent of Apple rights, and you may also have other rights which may constitute trademark infringement and vary from state to state. unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Chicago, Geneva, Mac, Mac OS, Monaco, New York, QuickDraw, and TrueType are trademarks of Apple Computer, Inc., registered in the United States and other countries. eMac is a trademark of Apple Computer, Inc. Helvetica, Palatino, and Times are trademarks of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. Contents Chapter 1 Text Encoding Conversion Manager Reference 7 TEC Manager Functions 7 Creating a Text Encoding Specification 7 Obtaining Information From a Text Encoding Specification 8 Converting Between Script Manager Values and Text Encodings 11 Obtaining Information About Available Text Encodings 14 Identifying Direct Encoding Conversions 18 Identifying Possible Destination Encodings 19 Obtaining Converter Information 21 Creating and Deleting Converter Objects 22 Converting Text Between Encodings 24 Converting to Multiple Encoding Runs 27 Using Sniffers to Investigate Encodings 32 Getting Information About Internet and Regional Text Encoding Names 37 Converting to Unicode 41 Converting From Unicode 47 Converting From Unicode to Multiple Encodings 53 Converting Between Unicode and Pascal Strings 64 Obtaining Unicode Mapping Information 66 Truncating Strings Before Converting Them 69 Setting the Fallback Handler 71 Working With Universal Procedure Pointers 73 Getting UniChar Property Values 75 TEC Manager Callbacks 75 Setting Up a Fallback Handler 75 Setting Up a TEC Plug-in 79 TEC Manager Data Types 90 ConstScriptCodeRunPtr 90 ConstTextEncodingRunPtr 90 ConstTextPtr 90 ConstTextToUnicodeInfo 90 ConstUniCharArrayPtr 91 ConstUnicodeMappingPtr 91 ConstUnicodeToTextInfo 91 ScriptCodeRun 91 TECBufferContextRec 92 TECConversionInfo 92 3 © 2004 Apple Computer, Inc. All Rights Reserved. CONTENTS TECConverterContextRec 93 TECInfo 94 TECObjectRef 95 TECPluginDispatchTable 95 TECPluginSig 96 TECPluginSignature 96 TECPluginStateRec 96 TECPluginVersion 96 TECSnifferContextRec 96 TECSnifferObjectRef 97 TextEncoding 97 TextEncodingRun 97 TextEncodingVariant 98 TextToUnicodeInfo 98 UniCharArrayOffset 99 UnicodeMapping 99 UnicodeToTextFallbackUPP 101 UnicodeToTextInfo 101 UnicodeToTextRunInfo 102 TEC Manager Constants 103 Feature Selectors 103 Encodings and Variants 112 Assorted Constants 135 TEC Manager Result Codes 142 Appendix A Updated Unicode Decompositions 147 Document Revision History 149 Index 151 4 © 2004 Apple Computer, Inc. All Rights Reserved. Tables Appendix A Updated Unicode Decompositions 147 Table A-1 MacArabic/MacFarsi mapping from composed to decomposed 148 5 © 2004 Apple Computer, Inc. All Rights Reserved. TABLES 6 © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Text Encoding Conversion Manager Reference Framework: CoreServices/CoreServices.h Header: UnicodeConverter.h, TextCommon.h, Unicode.h, TextEncodingConverter.h, TextEncodingPlugin.h The Text Encoding Conversion (TEC) Manager provides two facilitiesÐthe Text Encoding Converter and the Unicode ConverterÐthat your application can use to handle text encoding conversion on the Mac OS. You will find the Text Encoding Conversion Manager helpful if you develop Internet applications, such as Web browsers or e-mail applications, applications that transfer text across different platforms, or applications based in Unicode. TEC Manager Functions Creating a Text Encoding Specification CreateTextEncoding Creates and returns a text encoding specification. TextEncoding CreateTextEncoding ( TextEncodingBase encodingBase, TextEncodingVariant encodingVariant, TextEncodingFormat encodingFormat ); Parameter Descriptions encodingBase A base text encoding of type TextEncodingRun (page 97). encodingVariant A variant of the base text encoding. To specify the default variant for the base encoding given in the encodingBase parameter, you can use the kTextEncodingDefaultVariant constant. TEC Manager Functions 7 © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Text Encoding Conversion Manager Reference encodingFormat A format for the base text encoding. To specify the default format for the base encoding, you can use the kTextEncodingDefaultFormat constant. If you want to obtain a TextEncoding value that references UTF-16 or UTF-8, pass kUnicode16BitFormat or kUnicodeUTF8Format . function result The text encoding specification that the function creates from the values you pass it. See page for a description of the TextEncoding data type. Discussion When you create a text encoding specification, the three values that you specify are packed into an unsigned integer, which you can then pass by value to the functions that use text encodings. See the data type TextEncodingRun (page 97). Availability Available in CarbonLib 1.0 and later when Text Common 1.0 or later is present. Available in Mac OS X 10.0 and later. Header: TextCommon.h Carbon Porting Notes Obtaining Information From a Text Encoding Specification GetTextEncodingBase Returns the base encoding of the specified text encoding. TextEncodingBase GetTextEncodingBase ( TextEncoding encoding ); Parameter Descriptions encoding A text encoding specification whose base encoding you want to obtain. function result The base encoding portion of the specified text encoding. Discussion See the data type TextEncodingRun (page 97) Availability Available in CarbonLib 1.0 and later when Text Common 1.0 or later is present. Available in Mac OS X 10.0 and later. Header: TextCommon.h GetTextEncodingFormat Returns the format value of the specified text encoding. 8 TEC Manager Functions © 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Text Encoding Conversion Manager Reference TextEncodingFormat GetTextEncodingFormat ( TextEncoding encoding ); Parameter Descriptions encoding A text encoding specification. function result The text encoding format value contained in the text encoding you specified. Availability Available in CarbonLib 1.0 and later when Text Common 1.0 or later is present. Available in Mac OS X 10.0 and later. Header: TextCommon.h GetTextEncodingName Returns the localized name for a specified text encoding. OSStatus GetTextEncodingName ( TextEncoding iEncoding, TextEncodingNameSelector iNamePartSelector, RegionCode iPreferredRegion, TextEncoding iPreferredEncoding, ByteCount iOutputBufLen, ByteCount * oNameLength, RegionCode * oActualRegion, TextEncoding * oActualEncoding, TextPtr oEncodingName ); Parameter Descriptions iEncoding A text encoding specification whose name you want to obtain. iNamePartSelector The portion of the encoding name you want to obtain. See ªText Encoding Name Selectorsº (page 133) for a list of possible values. iPreferredRegion The preferred region to use for the name. You can specify a Mac OS region code (which also implies a language) for this parameter. If the function cannot return the name for the preferred region, it returns the name using a region code with the same language or in a default language (for example, English). iPreferredEncoding The preferred encoding to use