Mac Developer Library

Developer

CoreServices Framework Reference Text Encoding Conversion Manager Reference

Options
Deployment Target:

On This Page
Language:

Text Encoding Conversion Manager Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreServices

Objective-C

@import CoreServices;

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.

Functions

  • Creates and returns a text encoding specification.

    Declaration

    Objective-C

    TextEncoding CreateTextEncoding ( TextEncodingBase encodingBase, TextEncodingVariant encodingVariant, TextEncodingFormat encodingFormat );

    Parameters

    encodingBase

    A base text encoding.

    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.

    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 .

    Return Value

    The text encoding specification that the function creates from the values you pass it.

    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.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the base encoding of the specified text encoding.

    Declaration

    Objective-C

    TextEncodingBase GetTextEncodingBase ( TextEncoding encoding );

    Parameters

    encoding

    A text encoding specification whose base encoding you want to obtain.

    Return Value

    The base encoding portion of the specified text encoding.

    Discussion

    See the data type TextEncodingRun

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the format value of the specified text encoding.

    Declaration

    Objective-C

    TextEncodingFormat GetTextEncodingFormat ( TextEncoding encoding );

    Parameters

    encoding

    A text encoding specification.

    Return Value

    The text encoding format value contained in the text encoding you specified.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the localized name for a specified text encoding.

    Declaration

    Objective-C

    OSStatus GetTextEncodingName ( TextEncoding iEncoding, TextEncodingNameSelector iNamePartSelector, RegionCode iPreferredRegion, TextEncoding iPreferredEncoding, ByteCount iOutputBufLen, ByteCount *oNameLength, RegionCode *oActualRegion, TextEncoding *oActualEncoding, TextPtr oEncodingName );

    Parameters

    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 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 for the name. For example, ASCII, Mac OS Roman, or Shift-JIS. If the function cannot return the name using the preferred encoding, it returns the name using another encoding, such as Unicode or ASCII.

    iOutputBufLen

    The length in bytes of the output buffer that your application provides for the returned encoding name.

    oNameLength

    A pointer to a value of type ByteCount. On return, this parameter holds the actual length, in bytes, of the text encoding name. The value represents the full length of the name, which might be greater than the size of the output buffer, specified by the iOutputBufLen parameter. The length of the portion of the name actually contained in the output buffer is the smaller of oNameLength and iOutputBufLen.

    oActualRegion

    A pointer to a value of type RegionCode. On return, this parameter holds the actual region associated with the returned encoding name.

    oActualEncoding

    A pointer to a value of type TextEncoding. On return, this parameter holds the actual encoding associated with the returned encoding name.

    oEncodingName

    A pointer to a buffer you provide. On return, this parameter holds the text encoding name.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    Names returned by GetTextEncodingName (in the buffer referred to by oEncodingName) can contain parentheses and other menu item meta characters, and so cannot be used with AppendMenu or InsertMenuItem. You can use them with SetMenuItemText.

    This function can return resources and memory errors, and the following result codes:

    • kTextUnsupportedEncodingErr, which indicates that the encoding whose name you want to obtain is not supported.

    • kTECMissingTableErr, which indicates the name resource associated with the encoding is missing.

    • kTECTableFormatErr or kTECTableCheckSumErr, which indicates that the name resource associated with that encoding is invalid.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the variant from the specified text encoding.

    Declaration

    Objective-C

    TextEncodingVariant GetTextEncodingVariant ( TextEncoding encoding );

    Parameters

    encoding

    A text encoding specification.

    Return Value

    The text encoding variant portion of the specified text encoding.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns a text encoding specification in which any meta-values have been resolved to real values. Currently, this affects only the base encoding values packed into the text encoding specification.

    Declaration

    Objective-C

    TextEncoding ResolveDefaultTextEncoding ( TextEncoding encoding );

    Parameters

    encoding

    A text encoding specification possibly containing meta-values that you want to resolve to a text encoding specification containing only real values.

    Return Value

    A text encoding specification containing only real base encoding values.

    Discussion

    This function is useful for application developers who are providing APIs that take text encoding specifications as parameters. All APIs in the Unicode Converter and Text Encoding Converter perform this translation automatically.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts the given Mac OS text encoding specification to the corresponding script code and, if possible, language code and font name.

    Declaration

    Objective-C

    OSStatus RevertTextEncodingToScriptInfo ( TextEncoding iEncoding, ScriptCode *oTextScriptID, LangCode *oTextLanguageID, Str255 oTextFontname );

    Parameters

    iEncoding

    The text encoding specification to be converted.

    oTextScriptID

    A pointer to a value of type ScriptCode. On return, a Mac OS script code that corresponds to the text encoding specification you identified in the iEncoding parameter. If you do not pass a pointer for this parameter, the function returns a paramErr result code.

    oTextLanguageID

    A pointer to a value of type LangCode. On input, if you do not want the function to return the language code, specify NULL as the value of this parameter. On return, the appropriate language code, if the language can be unambiguously derived from the text encoding specification, for example, Japanese, and you did not set the parameter to NULL.

    If you do not specify NULL on input and the language is ambiguous—that is, the function cannot accurately derive it from the text encoding specification—the function returns a value of kTextLanguageDontCare.

    oTextFontname

    A Pascal string. On input, if you do not want the function to return the font name, specify NULL as the value of this parameter. On return, the name of the appropriate font if the font can be unambiguously derived from the text encoding specification, for example, Symbol, and you did not set the parameter to NULL.

    If you do not specify NULL on input and the font is ambiguous—that is, the function cannot accurately derive it from the text encoding specification—the function returns a zero-length string.

    Return Value

    A result code. See TEC Manager Result Codes. The function returns paramErr if the text encoding specification input parameter value is invalid. The function returns a kTECTableFormatErr result code if the internal mapping tables used for translation are invalid. For a list of other possible result codes, see “Data Types”.

    Discussion

    If you have applications that use Mac OS Script Manager and Font Manager functions, you can use the RevertTextEncodingToScriptInfo function to convert information in a text encoding specification into the appropriate Mac OS script code, language code, and font name, if they can be unambiguously derived. Your application can then use this information to display text to a user on the screen.

    For more information see the UpgradeScriptInfoToTextEncoding function and Base Text Encodings.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts any combination of a Mac OS script code, a language code, a region code, and a font name to a text encoding.

    Declaration

    Objective-C

    OSStatus UpgradeScriptInfoToTextEncoding ( ScriptCode iTextScriptID, LangCode iTextLanguageID, RegionCode iRegionID, ConstStr255Param iTextFontname, TextEncoding *oEncoding );

    Parameters

    iTextScriptID

    A valid Script Manager script code. The Mac OS Script Manager defines constants for script codes using this format: smXxx. To designate the system script, specify the meta-value of smSystemScript. To designate the current script based on the font specified in the graphics port (grafPort), specify the metavalue of smCurrentScript. To indicate that you do not want to provide a script code for this parameter, specify the constant kTextScriptDontCare.

    iTextLanguageID

    A valid Script Manager language code. The Mac OS Script Manager defines constants for language codes using this format: langXxx. To indicate that you do not want to provide a language code for this parameter, specify the constant kTextLanguageDontCare.

    iRegionID

    A valid Script Manager region code. The Mac OS Script Manager defines constants for region codes using this format: verXxx. To indicate that you do not want to provide a region code for this parameter, specify the constant kTextRegionDontCare.

    iTextFontname

    The name of a font associated with a particular text encoding specification, such as Symbol or Zapf Dingbats, or the name of any font that is currently installed on the system. To indicate that you do not want to provide a font name, specify a value of NULL.

    oEncoding

    A pointer to a value of type TextEncoding. On return, this value holds the text encoding specification that the function created from the other values you provided.

    Return Value

    A result code. See TEC Manager Result Codes. This function returns paramErr if two or more of the input parameter values conflict in some way—for example, the Mac OS language code does not belong to the script whose script code you specified, or if the input parameter values are invalid. The function returns a kTECTableFormatErr result code if the internal mapping tables used for translation are invalid.

    Discussion

    The UpgradeScriptInfoToTextEncoding function allows you to derive a text encoding specification from script codes, language codes, region codes, and font names. A one-to-one correspondence exists between many of the Script Manager’s script codes and a particular Mac OS text encoding base value. However, because text encodings are a superset of script codes, some combinations of script code, language code, region code, and font name might result in a different text encoding base value than would be the case if the translation were based on the script code alone.

    When you call the UpgradeScriptInfoToTextEncoding function, you can specify any combination of its parameters, but you must specify at least one.

    If you don’t specify an explicit value for a script, language, or region code parameter, you must pass the do-not-care constant appropriate to that parameter. If you do not specify an explicit value for iTextFontName, you must pass NULL. UpgradeScriptInfoToTextEncoding uses as much information as you supply to determine the equivalent text encoding or the closest approximation. If you provide more than one parameter, all parameters are checked against one another to ensure that they are valid in combination.

    A font name, such as 'Symbol' or 'Zapf Dingbats,' can indicate a particular text encoding base. Other font names can indicate particular variants associated with a particular text encoding base. Otherwise, the font name is used to obtain a script code, and this script code will be checked against any script code you supply (in this case, the font must be installed; if it is not, the function returns a paramErr result code). If you do not supply either a language code or a region code and the script code you supply or the one that is derived matches the system script, then the system’s localization is used to determine the appropriate region and language code. This is used for deriving text encoding base values that depend on region and language, such as kTextEncodingMacTurkish.

    For more information see the RevertTextEncodingToScriptInfo function and Base Text Encodings.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Counts and returns the number of text encodings currently configured in the Text Encoding Converter.

    Declaration

    Objective-C

    OSStatus TECCountAvailableTextEncodings ( ItemCount *numberEncodings );

    Parameters

    numberEncodings

    On return, a pointer to the number of currently supported text encodings. You use this value to determine the array size for a parameter of the TECGetAvailableTextEncodings function.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    The number of text encodings includes every instance of a text encoding. If different conversion plug-ins support the same text encoding, the text encoding will be counted more than once. For example, the Japanese Encodings plug-in supports Mac OS Japanese, and so does the Unicode Encodings plug-in. Since the TECGetAvailableTextEncodings function ignores duplicate text encoding specifications, TECCountAvailableTextEncodings may return a number greater than the number of array elements needed for the availableEncodings [] parameter.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Counts and returns the number of subencodings a text encoding supports.

    Declaration

    Objective-C

    OSStatus TECCountSubTextEncodings ( TextEncoding inputEncoding, ItemCount *numberOfEncodings );

    Parameters

    inputEncoding

    The text encoding specification that contains the subencodings.

    numberOfEncodings

    On return, a pointer to the number of currently supported subencodings. You use this value to determine the array size for a parameter of the TECGetSubTextEncodings function.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    Subencodings are text encodings that are embedded as part of a larger text encoding specification. For example, EUC-JP contains JIS Roman or ASCII, JIS X0208, JIS X0212, and half-width Katakana from JIS X0201. Not every encoding that can be broken into multiple encodings necessarily supports this routine. It’s up to the plug-in developer to decide which encodings might be useful to break up. Subencodings are not the same as text encoding variants.

    If an encoding can be converted to multiple runs of encodings (as indicated by a destination base encoding of kTextEncodingMultiRun), you can call the TECGetSubTextEncodings function to get the list of output encodings. See the TECCreateOneToManyConverter and TECGetDestinationTextEncodings functions for information.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the text encoding specifications currently configured in the Text Encoding Converter.

    Declaration

    Objective-C

    OSStatus TECGetAvailableTextEncodings ( TextEncoding availableEncodings[], ItemCount maxAvailableEncodings, ItemCount *actualAvailableEncodings );

    Parameters

    availableEncodings

    On return, an array of text encoding specifications. You should use the TECCountAvailableTextEncodings function to determine what size array to allocate.

    maxAvailableEncodings

    The number of text encoding specifications the availableEncodings array can contain.

    actualAvailableEncodings

    On return, a pointer to the number of text encodings returned in the availableEncodings array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function ignores duplicate text encoding specifications. If you used the TECCountAvailableTextEncodings function to determine the size of the availableEncodings [] array, the number of encodings may be fewer than the number of array elements, because TECCountAvailableTextEncodings includes duplicate text encodings in its count.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the text encoding specifications for the subencodings the encoding scheme supports.

    Declaration

    Objective-C

    OSStatus TECGetSubTextEncodings ( TextEncoding inputEncoding, TextEncoding subEncodings[], ItemCount maxSubEncodings, ItemCount *actualSubEncodings );

    Parameters

    inputEncoding

    A text encoding specification.

    subEncodings

    On return, the array contains the specifications for the subencodings of the inputEncoding parameter. You should use the function TECCountSubTextEncodings function to determine what size an array to allocate.

    maxSubEncodings

    The number of text encoding specifications the subEncodings array can contain.

    actualSubEncodings

    On return, a pointer to number of subencodings in the subEncodings array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    Subencodings are text encodings that are embedded as part of a larger text encoding specification. For example, EUC-JP contains JIS Roman or ASCII, JIS X0208, JIS X0212, and half-width Katakana from JIS X0201. Not every encoding that can be broken into multiple encodings necessarily supports this routine. It’s up to the plug-in developer to decide which encodings might be useful to break up. Subencodings are not the same as text encoding variants

    If an encoding can be converted to multiple runs of encodings (as indicated by a destination base encoding of kTextEncodingMultiRun), you can call the TECGetSubTextEncodings function to get the list of output encodings. See the TECCreateOneToManyConverter and TECGetDestinationTextEncodings functions for information about multiple output encoding run conversions.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Obtains the best and alternate Mac text encoding.

    Declaration

    Objective-C

    OSStatus NearestMacTextEncodings ( TextEncoding generalEncoding, TextEncoding *bestMacEncoding, TextEncoding *alternateMacEncoding );

    Parameters

    generalEncoding

    The text encoding for which you want to obtain a Mac text encoding.

    bestMacEncoding

    On return, the Mac text encoding that best matches the encoding specified by the generalEncoding parameter.

    alternateMacEncoding

    On return, the Mac text encoding that is the second best match for the encoding specified by the generalEncoding parameter.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Counts and returns the number of direct conversions currently configured in the Text Encoding Converter.

    Declaration

    Objective-C

    OSStatus TECCountDirectTextEncodingConversions ( ItemCount *numberOfEncodings );

    Parameters

    numberOfEncodings

    On return, a pointer to the number of direct conversions. You should use this value to determine the array size for a parameter of the TECGetDirectTextEncodingConversions function.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    The number of direct conversions includes every instance of a conversion. If different conversion plug-ins support the same direct conversion, the direct conversion is counted more than once.

    Since the TECGetDirectTextEncodingConversions function ignores duplicate direct conversions, TECCountDirectTextEncodingConversions may return a number greater than the number of array elements needed for the directConversions parameter.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the types of direct conversions currently configured in the Text Encoding Converter.

    Declaration

    Objective-C

    OSStatus TECGetDirectTextEncodingConversions ( TECConversionInfo availableConversions[], ItemCount maxAvailableConversions, ItemCount *actualAvailableConversions );

    Parameters

    availableConversions

    An array composed of text encoding conversion information structures, each of which specifies a set of source and destination encodings for a type of conversion. See TECConversionInfo for more information. You should use the TECGetDirectTextEncodingConversions function to determine how large to make the array.

    maxAvailableConversions

    The maximum number of text encoding conversion information structures that the directConversions array can contain.

    actualAvailableConversions

    On return, a pointer to the number of text encoding conversion information structures returned in the directConversions array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function ignores duplicate text encoding conversion information structures. If you used the TECCountDirectTextEncodingConversions function to determine the size of the directConversions[] array, the number of text encoding conversion information structures may be fewer than the number of array elements, because TECCountDirectTextEncodingConversions counts duplicate text encoding conversion information structures.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Counts and returns the number of destination encodings to which a specified source encoding can be converted in one step.

    Declaration

    Objective-C

    OSStatus TECCountDestinationTextEncodings ( TextEncoding inputEncoding, ItemCount *numberOfEncodings );

    Parameters

    inputEncoding

    The text encoding specification describing the source text.

    numberOfEncodings

    On return, a pointer to the number of text encodings to which the source encoding can be converted in one step. You should use this to determine how large to make the array you pass to the TECGetDestinationTextEncodings function.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function counts every instance of an encoding. If different conversion plug-ins support the same direct text encoding, the direct text encoding is counted more than once.

    Since the TECGetDestinationTextEncodings function ignores duplicate text encoding specifications, TECCountDestinationTextEncodings may return a number greater than the number of array elements needed for the destinationEncodings[] parameter.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the encoding specifications for all the destination text encodings to which the Text Encoding Converter can directly convert the specified source encoding.

    Declaration

    Objective-C

    OSStatus TECGetDestinationTextEncodings ( TextEncoding inputEncoding, TextEncoding destinationEncodings[], ItemCount maxDestinationEncodings, ItemCount *actualDestinationEncodings );

    Parameters

    inputEncoding

    The text encoding specification describing the source text.

    destinationEncodings

    On return, an array of specifications for the destination encodings to which the converter can directly convert the source encoding. You should use the TECCountDestinationTextEncodings function to determine how large an array to allocate.

    maxDestinationEncodings

    The maximum number of destination text encodings that the array can contain.

    actualDestinationEncodings

    On return, a pointer to the number of text encoding specifications in the destination encodings array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function ignores duplicate direct text encoding specifications. If you used the TECCountDestinationTextEncodings function to determine the size of the destinationEncodings[] array, the number of available encodings may be fewer than the number of array elements, because TECCountDestinationTextEncodings includes duplicates in its count.

    You can display the names of these destination encodings to the user.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Allocates a converter information structure of type TECInfo in the application heap using NewHandle, fills it out, and returns a handle.

    Declaration

    Objective-C

    OSStatus TECGetInfo ( TECInfoHandle *tecInfo );

    Parameters

    tecInfo

    A handle to a structure of type TECInfo containing information about the converter.

    Return Value

    A result code. See TEC Manager Result Codes. This function can return memory errors.

    Discussion

    When you are finished with the handle, your application must dispose of it using DisposeHandle. You must also perform any required preflighting or memory rearrangement before calling TECGetInfo.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Determines a conversion path for a source and destination encoding, then creates a text encoding converter object and returns a pointer to it.

    Declaration

    Objective-C

    OSStatus TECCreateConverter ( TECObjectRef *newEncodingConverter, TextEncoding inputEncoding, TextEncoding outputEncoding );

    Parameters

    newEncodingConverter

    A pointer to a converter object. On return, this reference points to a newly created text converter object.

    inputEncoding

    The text encoding specification for the source text encoding.

    outputEncoding

    The text encoding specification for the destination text encoding.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You use this converter object reference with conversion functions such as TECConvertText to convert text. This converter object describes the source, destination, and intermediate encodings; state information; and references to required plug-ins.

    If the function does not find a direct conversion path, it creates an indirect conversion path. You can use the function TECCreateConverterFromPath to specify an explicit conversion path.

    You must use the TECDisposeConverter function to remove a converter object.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Creates a converter object for a specific conversion path—from a source encoding through intermediate encodings to a destination encoding—and returns a pointer to it.

    Declaration

    Objective-C

    OSStatus TECCreateConverterFromPath ( TECObjectRef *newEncodingConverter, const TextEncoding inPath[], ItemCount inEncodings );

    Parameters

    newEncodingConverter

    A pointer to a converter object reference. On return, the reference points to a newly created text converter object.

    inPath

    An ordered array of text encoding specifications, beginning with the source encoding specification and ending with the destination encoding specification. Each adjacent pair of text encodings must represent a conversion that is supported by the Text Encoding Converter.

    inEncodings

    The number of text encoding specifications in the inPath array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function is faster than the function TECCreateConverter since it does not need to search for a conversion path. You can use the TECGetDestinationTextEncodings function to determine each step in the sequence from the source to the destination encoding.

    To remove a converter object, you must call the function TECDisposeConverter.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Resets a converter object to its initial state so you can reuse it.

    Declaration

    Objective-C

    OSStatus TECClearConverterContextInfo ( TECObjectRef encodingConverter );

    Parameters

    encodingConverter

    A reference to the text encoding converter object you want to reset. It can be a reference returned by the TECCreateConverter, TECCreateOneToManyConverter, or TECCreateConverterFromPath functions.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    It is more efficient to reuse an existing converter object than to create a new one that contains the same conversion information. This function clears the text string, but does not alter the source and destination encodings.

    If you are converting multiple segments of a text string, you should not clear the converter object until you have converted all the text segments.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Disposes of a converter object.

    Declaration

    Objective-C

    OSStatus TECDisposeConverter ( TECObjectRef newEncodingConverter );

    Parameters

    newEncodingConverter

    A reference to the text encoding converter object you want to remove. This can be the reference returned by the TECCreateConverter, TECCreateConverterFromPath, or TECCreateOneToManyConverter functions.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    If you want to reuse the converter object for a different text stream with the same source and destination encoding, you should clear the converter object using the TECClearConverterContextInfo function rather than disposing of it and then creating a new converter object.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts a stream of text from a source encoding to a destination encoding. It uses the conversion path specified by the converter object you supply.

    Declaration

    Objective-C

    OSStatus TECConvertText ( TECObjectRef encodingConverter, ConstTextPtr inputBuffer, ByteCount inputBufferLength, ByteCount *actualInputLength, TextPtr outputBuffer, ByteCount outputBufferLength, ByteCount *actualOutputLength );

    Parameters

    encodingConverter

    A reference to the text encoding converter object you want to use for the conversion. It can be a reference returned by the TECCreateConverter or TECCreateConverterFromPath functions.

    inputBuffer

    The stream of text you want to convert.

    inputBufferLength

    The length in bytes (UInt8 or unsigned char) of the stream of text.

    actualInputLength

    On return, a pointer to the number of source text bytes that were converted from the input buffer.

    outputBuffer

    A pointer to a buffer for a byte stream. On output, the buffer holds the converted text.

    outputBufferLength

    The length in bytes of the outputBuffer parameter.

    actualOutputLength

    On return, a pointer to the number of bytes of converted text returned in the outputBuffer parameter.

    Return Value

    A result code. See TEC Manager Result Codes. If there is not enough memory available for TECConvertText to convert the text when allocating internal buffers, the function returns the appropriate Memory Manager result code.

    In most cases, TECConvertText does not return “kTECUsedFallbacksStatus” even if it has substituted a fallback character in the process of converting its input text to output in another encoding (unlike, for example, ConvertFromUnicodeToText which always returns “kTECUsedFallbacksStatus” if it substitutes a fallback character). That is because TECConvertText is intended to be used primarily by clients who just want it to do the best job it can in converting from a given input encoding to a given output encoding and don't want to worry too much about the details.

    Discussion

    If the output buffer you allocate is too small to accommodate any of the converted text, the function fails. For best results, you should follow these guidelines when you allocate an output buffer:

    • Base the buffer length on an estimate of the byte requirements of the destination encoding. Make sure you account for additional bytes needed by the destination encoding (for example, an escape sequence) in addition to the actual text.

    • Always allocate a buffer at least 32 bytes long.

    • If size is a concern, make sure the output buffer is at least large enough to hold a portion of the converted text. You can convert part of the text, then use the value of the actualInputLength parameter to identify the next byte to be taken and to determine how many bytes remain. To convert the remaining text, you simply call the function again with the remaining text and a new output buffer.

    • If the destination encoding is a character encoding scheme—such as ISO-2022-JP, which begins in ASCII and switches to other coded character sets through limited combinations of escape sequences—then you need to allocate enough space to accommodate escape sequences that signal switches. ISO-2022-JP requires 3 to 5 bytes for an escape sequence preceding the 1-byte or 2-byte character it introduces. If you allocate a buffer that is less than 5 bytes, the TECConvertText function could fail, depending on the text being converted.

    To make sure that you receive all of the converted text, you should call the function TECFlushText when you are finished converting all the text in a text stream.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Flushes out any data in a converter object’s temporary buffers and resets the converter object.

    Declaration

    Objective-C

    OSStatus TECFlushText ( TECObjectRef encodingConverter, TextPtr outputBuffer, ByteCount outputBufferLength, ByteCount *actualOutputLength );

    Parameters

    encodingConverter

    A reference to the text converter object whose contents are to be flushed. This can be a reference returned by the TECCreateConverter or TECCreateConverterFromPath functions.

    outputBuffer

    On return, a pointer to a buffer that holds the converted text.

    outputBufferLength

    The length in bytes of the buffer provided by the outputBuffer parameter.

    actualOutputLength

    On return, a pointer to the number of bytes of converted text returned in the buffer specified by the outputBuffer parameter.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You should always call TECFlushText when you finish converting a text stream. If you are converting a single stream in multiple chunks using multiple calls to TECConvertText, you only need to call TECFlushText after the last call to TECConvertText for that stream. The function uses the conversion path specified in the converter object you supply.

    For the function to return successfully, the output buffer you allocate must be large enough to accommodate the flushed text. If the output buffer is too small to accommodate any flushed text, the function will fail. For best results, you should follow these guidelines when you allocate an output buffer:

    • Base the buffer length on an estimate of the byte requirements of the destination encoding. Make sure you account for additional bytes needed by the destination encoding (for example, an escape sequence) in addition to the actual text.

    • Always allocate a buffer at least 32 bytes long.

    Encodings such as ISO-2022 that need to shift back to a certain default state at the end of a conversion can do so when this function is called.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts text in the source encoding to runs of text in multiple destination encodings. It uses the conversion path specified in the converter object you supply.

    Declaration

    Objective-C

    OSStatus TECConvertTextToMultipleEncodings ( TECObjectRef encodingConverter, ConstTextPtr inputBuffer, ByteCount inputBufferLength, ByteCount *actualInputLength, TextPtr outputBuffer, ByteCount outputBufferLength, ByteCount *actualOutputLength, TextEncodingRun outEncodingsBuffer[], ItemCount maxOutEncodingRuns, ItemCount *actualOutEncodingRuns );

    Parameters

    encodingConverter

    The reference to the text encoding converter object to be used for the conversion. This is the reference returned by the function TECCreateOneToManyConverter.

    inputBuffer

    The stream of text to be converted.

    inputBufferLength

    The length in bytes of the stream of text specified in the inputBuffer parameter.

    actualInputLength

    On return, a pointer to a the number of source text bytes that were converted.

    outputBuffer

    On return, a pointer to a buffer that holds the converted text.

    outputBufferLength

    The length in bytes of the outputBuffer parameter.

    actualOutputLength

    On return, a pointer to the number of bytes of the converted text returned in the outputBuffer parameter.

    outEncodingsBuffer

    An array of text encoding runs for output. Note that the actual byte size of this buffer should be actualOutEncodingRuns * sizeof(TextEncodingRun).

    maxOutEncodingRuns

    The maximum number of runs that can fit in the outEncodingsBuffer array.

    actualOutEncodingRuns

    On return, a pointer to the number of runs in outEncodingsBuffer array.

    Return Value

    A result code. See TEC Manager Result Codes. If there is not enough memory available to convert the text when allocating internal buffers, the function returns the appropriate Memory Manager result code.

    Discussion

    For the function to return successfully, the output buffer you allocate must be large enough to accommodate the converted text. If the output buffer is too small to accommodate any converted text, the function will fail. For best results, you should follow these guidelines when you allocate an output buffer:

    • Base the buffer length on an estimate of the byte requirements of the destination encoding. Make sure you account for additional bytes needed by the destination encoding (for example, an escape sequence) in addition to the actual text.

    • Always allocate a buffer at least 32 bytes long.

    • If size is a concern, make sure the output buffer is at least large enough to hold a portion of the converted text. You can convert part of the text, then use the value of the actualInputLength parameter to identify the next byte to be taken and to determine how many bytes remain. To convert the remaining text, you simply call the function again with the remaining text and a new output buffer.

    • If the destination encoding is a character encoding scheme—such as ISO-2022-JP, which begins in ASCII and switches to other coded character sets through limited combinations of escape sequences—then you need to allocate enough space to accommodate escape sequences that signal switches. ISO-2022-JP requires 3 to 5 bytes for an escape sequence preceding the 1-byte or 2-byte character it introduces. If you allocate a buffer that is less than 5 bytes, the TECConvertText function could fail, depending on the text being converted.

    The Text Encoding Converter creates internal buffers that hold intermediate results for indirect conversions

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Determines a conversion path for the source encoding and destinations encodings you specify, creates a text encoding converter object, and returns a reference to it.

    Declaration

    Objective-C

    OSStatus TECCreateOneToManyConverter ( TECObjectRef *newEncodingConverter, TextEncoding inputEncoding, ItemCount numOutputEncodings, const TextEncoding outputEncodings[] );

    Parameters

    newEncodingConverter

    A pointer to a converter object. On return, this points to a newly created one-to-many converter object.

    inputEncoding

    The text encoding specification for the source text encoding.

    numOutputEncodings

    The number of text encoding specifications in the outputEncoding array.

    outputEncodings

    An ordered array of text encoding specifications for the destination text encodings.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You use this converter object reference with conversion functions such as TECConvertTextToMultipleEncodings. The converter object describes the source, destination, and intermediate encodings; state information; and references to required plug-ins.

    To remove a converter object, you must call the function TECDisposeConverter.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Flushes out any encodings that may be stored in a converter object’s temporary buffers and shifts encodings back to their default state, if any.

    Declaration

    Objective-C

    OSStatus TECFlushMultipleEncodings ( TECObjectRef encodingConverter, TextPtr outputBuffer, ByteCount outputBufferLength, ByteCount *actualOutputLength, TextEncodingRun outEncodingsBuffer[], ItemCount maxOutEncodingRuns, ItemCount *actualOutEncodingRuns );

    Parameters

    encodingConverter

    The reference to the text encoding converter object whose contents are to be flushed. This is the reference returned by the function TECCreateOneToManyConverter.

    outputBuffer

    On return, a pointer to a buffer that holds the converted text. An error is returned is the buffer is not large enough to hold the entire converted text stream.

    outputBufferLength

    The length in bytes of the outputBuffer parameter.

    actualOutputLength

    On return, a pointer to a the actual number of bytes of the converted text returned in the outputBuffer parameter.

    outEncodingsBuffer

    An ordered array of text encoding runs for the destination text encoding. Note that the actual byte size of this buffer should be actualOutEncodingRuns * sizeof(TextEncodingRun).

    maxOutEncodingRuns

    The maximum number of encoding runs that can fit in outEncodingsBuffer[].

    actualOutEncodingRuns

    On return, a pointer to a the number of runs in the buffer during conversion.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You should always call TECFlushMultipleEncodings at the end of the conversion process to flush out any data that may be stored in the temporary buffers of the text encoding converter object or to perform other end-of-encoding conversion tasks. Encodings such as ISO-2022-JP are reset to a default state when you use this function.

    For the function to return successfully, the output buffer you allocate must be large enough to accommodate the converted text. If the output buffer is too small to accommodate any converted text, the function will fail. For best results, you should follow these guidelines when you allocate an output buffer:

    • Base the buffer length on an estimate of the byte requirements of the destination encoding. Make sure you account for additional bytes needed by the destination encoding (for example, an escape sequence) in addition to the actual text.

    • Always allocate a buffer at least 32 bytes long.

    • If size is a concern, make sure the output buffer is at least large enough to hold a portion of the converted text. You can convert part of the text, then use the value of the actualInputLength parameter to identify the next byte to be taken and to determine how many bytes remain. To convert the remaining text, you simply call the function again with the remaining text and a new output buffer.

    • If the destination encoding is a character encoding scheme—such as ISO-2022-JP, which begins in ASCII and switches to other coded character sets through limited combinations of escape sequences—then you need to allocate enough space to accommodate escape sequences that signal switches. ISO-2022-JP requires 3 to 5 bytes for an escape sequence preceding the 1-byte or 2-byte character it introduces. If you allocate a buffer that is less than 5 bytes, the TECConvertText function could fail, depending on the text being converted.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Gets the list of destination encodings from a converter object.

    Declaration

    Objective-C

    OSStatus TECGetEncodingList ( TECObjectRef encodingConverter, ItemCount *numEncodings, Handle *encodingList );

    Parameters

    encodingConverter

    A reference to the text encoding conversion object returned by the TECCreateOneToManyConverter function.

    numEncodings

    On return, a pointer to the number of encodings specified by the encodingList handle.

    encodingList

    A handle to an array of text encoding specifications. On return, it contains an array of text encoding specifications to which the converter object can convert. The memory for the array is allocated automatically by the Text Encoding Converter.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    The TECDisposeConverter function automatically disposes of the pointer for you. This means you should not reference the pointer after you have disposed of the converter object.

    Plug-ins that perform one-to-many conversions use the TECGetEncodingList function to get the output encoding list from the converter object reference.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Creates a sniffer object and returns a reference to it.

    Declaration

    Objective-C

    OSStatus TECCreateSniffer ( TECSnifferObjectRef *encodingSniffer, const TextEncoding testEncodings[], ItemCount numTextEncodings );

    Parameters

    encodingSniffer

    A pointer to a sniffer object reference, which is of type TECSnifferObjectRef. On return, the reference pertains to the newly created sniffer object.

    testEncodings

    An array of text encoding specifications supplied by the caller; TECCreateSniffer creates a sniffer that can detect each of these encodings.

    numTextEncodings

    The number of text encoding specifications in the testEncodings[] array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    The TECCreateSniffer function polls plug-ins for available sniffers, creates a sniffer object capable of sniffing each of the specified encodings that it can find a sniffer function for, and returns a reference to it. You use this sniffer object reference with sniffer functions such as TECSniffTextEncoding. If no sniffer function is available for an encoding, no error is returned and TECSniffTextEncoding indicates later that the encoding was not examined.

    To remove a sniffer object, you must call the function TECDisposeSniffer.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Resets a sniffer object to its initial settings so you can reuse it.

    Declaration

    Objective-C

    OSStatus TECClearSnifferContextInfo ( TECSnifferObjectRef encodingSniffer );

    Parameters

    encodingSniffer

    A pointer to the sniffer object you want to reset.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    Sniffers maintain state information about the input encoding buffer and the number of errors and features found for each encoding; this information allows a caller to progressively sniff an input buffer in sequential chunks. Before sniffing a buffer that contains completely new information you must clear any state information by calling TECClearSnifferContextInfo.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Disposes of a sniffer object.

    Declaration

    Objective-C

    OSStatus TECDisposeSniffer ( TECSnifferObjectRef encodingSniffer );

    Parameters

    encodingSniffer

    The sniffer object reference you want to remove.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function releases all memory allocated to the sniffer object created by the TECCreateSniffer function.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Counts and returns the number of sniffers available in all installed plug-ins.

    Declaration

    Objective-C

    OSStatus TECCountAvailableSniffers ( ItemCount *numberOfEncodings );

    Parameters

    numberOfEncodings

    On return, a pointer to the number of sniffers in all installed plug-ins. You can use this number to determine what size array to allocate for a parameter of the TECGetAvailableSniffers function.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function counts every instance of a sniffer. If different conversion plug-ins support a sniffer for the same encoding, the sniffer is counted more than once. Since the TECGetAvailableSniffers function ignores duplicate sniffers, TECCountAvailableSniffers may return a number greater than the number of array elements needed for the availableSniffers[] parameter of the TECGetAvailableSniffers function.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the list of sniffers available in all installed plug-ins.

    Declaration

    Objective-C

    OSStatus TECGetAvailableSniffers ( TextEncoding availableSniffers[], ItemCount maxAvailableSniffers, ItemCount *actualAvailableSniffers );

    Parameters

    availableSniffers

    On return, an array of text encoding specifications that the available sniffers currently support. You should use the TECCountAvailableSniffers function to determine what size array to allocate.

    maxAvailableSniffers

    The number of text encoding specifications the availableSniffers array can contain.

    actualAvailableSniffers

    On return, a pointer to the number of text encodings in the availableSniffers array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function ignores duplicate text encoding specifications. If you used the TECCountAvailableSniffers function to determine the size of the TECGetAvailableSniffers array, the number of available encodings may be fewer than the number of array elements, because TECCountAvailableSniffers includes duplicate text encoding specifications in its count.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Analyzes a text stream and returns the probable encodings in a ranked list, based on an array of possible encodings you supply. It also returns the number of errors and features for each encoding.

    Declaration

    Objective-C

    OSStatus TECSniffTextEncoding ( TECSnifferObjectRef encodingSniffer, ConstTextPtr inputBuffer, ByteCount inputBufferLength, TextEncoding testEncodings[], ItemCount numTextEncodings, ItemCount numErrsArray[], ItemCount maxErrs, ItemCount numFeaturesArray[], ItemCount maxFeatures );

    Parameters

    encodingSniffer

    A reference to a sniffer object.

    inputBuffer

    The text to be sniffed.

    inputBufferLength

    The length of the input buffer.

    testEncodings

    An array of text encoding specifications. You must fill the array with the text encodings for which you want to sniff. On output, the array elements are reordered from the most likely to the least likely text encodings.

    numTextEncodings

    The number of entries in the testEncodings[] parameter.

    numErrsArray

    An array that must contain at least numTextEncodings elements. On return, an array of the number of errors found for each possible text encoding. The array elements are in the same order as the testEncodings[] array elements at output.

    maxErrs

    The maximum number of errors a sniffer can encounter. The sniffer stops looking for an encoding after this number is reached.

    numFeaturesArray

    An array of that must contain at least numTextEncodings elements. On return, an array of the number of features found for each possible text encoding. The array elements are in the same order as the testEncodings[] array elements at output.

    maxFeatures

    The maximum number of features a sniffer can encounter. The sniffer stops looking for a features after this number is reached.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    An error indicates a code point or sequence that is illegal in the specified encoding. A feature indicates the presence of a sequence that is characteristic of that encoding.

    For example, the byte sequence which is interpreted in Mac OS Roman as “é” could legally be interpreted either as Mac OS Roman text or as Mac OS Japanese text. Both sniffers would return zero errors, but the Mac OS Japanese sniffer would also return two features of Mac OS Japanese (representing two legal 2-byte characters.)

    The arrays are returned in a ranked list with the most likely text encodings first. The results are sorted first by number of errors (fewest to most), then by number of features (most to fewest), and then by the original order in the list. On return, the most likely encoding is in testEncodings[0] or testEncodings[1].

    If an encoding is not examined, its number of errors and features are set to 0xFFFFFFFF, and the encoding is sorted to the end of the list.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Counts and returns the number of currently supported e-mail encodings for a specified region.

    Declaration

    Objective-C

    OSStatus TECCountMailTextEncodings ( RegionCode locale, ItemCount *numberEncodings );

    Parameters

    locale

    A Mac OS region code. A region code designates a combination of language, writing system, and geographic region; the region may not correspond to a particular country (for example, Swiss French or Arabic).

    numberEncodings

    On return, a pointer to the number of currently supported e-mail encodings for the region code. You use this number to determine what size array to allocate for a parameter of the TECGetMailTextEncodings function.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function counts every instance of an encoding. If different conversion plug-ins support the same direct text encoding, the direct text encoding is counted more than once. Since the TECGetMailTextEncodings function ignores duplicate text encoding specifications, TECCountMailTextEncodings may return a number greater than the number of array elements needed.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Counts and returns the number of currently supported text encodings for a region code.

    Declaration

    Objective-C

    OSStatus TECCountWebTextEncodings ( RegionCode locale, ItemCount *numberEncodings );

    Parameters

    locale

    A Mac OS region code indicating the locale for which you want to count encodings. A region code designates a combination of language, writing system, and geographic region; the region may not correspond to a particular country (for example, Swiss French or Arabic).

    numberEncodings

    On return, a pointer to the number of currently supported text encodings for a region code. You should use this number to determine how large to make the array you pass to the TECGetWebTextEncodings function.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function counts every instance of the same encoding. That is, if different conversion plug-ins support the same text encoding for a conversion process, the text encoding is counted more than once. Since the TECGetWebTextEncodings function ignores duplicate text encoding specifications, TECCountWebTextEncodings may return a number greater than the number of array elements needed for the availableEncodings[] parameter.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the currently supported mail encoding specifications for a region code.

    Declaration

    Objective-C

    OSStatus TECGetMailTextEncodings ( RegionCode locale, TextEncoding availableEncodings[], ItemCount maxAvailableEncodings, ItemCount *actualAvailableEncodings );

    Parameters

    locale

    A Mac OS region code. A region code designates a combination of language, writing system, and geographic region; the region may not correspond to a particular country (for example, Swiss French or Arabic).

    availableEncodings

    An array of text encoding specifications. On return, the array contains specifications for the e-mail text encodings for a region code. You should use the function TECCountMailTextEncodings function to determine what size array to allocate.

    maxAvailableEncodings

    The number of text encoding specifications the availableEncodings array can contain.

    actualAvailableEncodings

    On return, a pointer to the number of text encodings in the availableEncodings array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function ignores duplicate text encoding specifications. If you used the TECCountMailTextEncodings function to determine the size of the availableEncodings[] array the number of available encodings may be fewer than the number of array elements, because TECCountMailTextEncodings includes duplicate text encoding specifications in its count.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the Mac OS text encoding specification that corresponds to an Internet encoding name.

    Declaration

    Objective-C

    OSStatus TECGetTextEncodingFromInternetName ( TextEncoding *textEncoding, ConstStr255Param encodingName );

    Parameters

    textEncoding

    On return, a pointer to a structure that contains a Mac OS text encoding specification.

    encodingName

    An Internet encoding name, in 7-bit US ASCII.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    Internet encoding names are stored as strings, while the Text Encoding Converter uses numeric values.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the Internet encoding name that corresponds to a Mac OS text encoding.

    Declaration

    Objective-C

    OSStatus TECGetTextEncodingInternetName ( TextEncoding textEncoding, Str255 encodingName );

    Parameters

    textEncoding

    A Mac OS text encoding specification.

    encodingName

    On return, the Internet encoding name, in 7-bit US ASCII. If there are several Internet encoding names for the same text encoding, the encodingName parameter contains the preferred name.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns the currently supported text encoding specifications for a region code.

    Declaration

    Objective-C

    OSStatus TECGetWebTextEncodings ( RegionCode locale, TextEncoding availableEncodings[], ItemCount maxAvailableEncodings, ItemCount *actualAvailableEncodings );

    Parameters

    locale

    A Mac OS region code. A region code designates a combination of language, writing system, and geographic region and may not correspond to a particular country (for example, Swiss French or Arabic).

    availableEncodings

    On return, an array that contains specifications for the currently supported text encodings in the specified region. You should use the TECCountWebTextEncodings function to determine how large an array to allocate.

    maxAvailableEncodings

    The number of text encodings specifications the availableEncodings array can contain.

    actualAvailableEncodings

    On return, a pointer to the number of text encodings specifications in the availableEncodings array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function ignores duplicate text encoding specifications. If you used the TECCountWebTextEncodings function to determine the size of the availableEncodings[] array the number of available encodings may be fewer than the number of array elements, because TECCountWebTextEncodings includes duplicate text encoding specifications in its count.

    You can use the list of available encodings to create an encoding selection menu for a Web browser.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Changes the mapping information for the specified Unicode converter object used to convert text to Unicode to the new mapping you provide.

    Declaration

    Objective-C

    OSStatus ChangeTextToUnicodeInfo ( TextToUnicodeInfo ioTextToUnicodeInfo, ConstUnicodeMappingPtr iUnicodeMapping );

    Parameters

    ioTextToUnicodeInfo

    The Unicode converter object of type TextToUnicodeInfo containing the mapping to be modified. You use the function CreateTextToUnicodeInfo to obtain one.

    iUnicodeMapping

    A structure of type UnicodeMapping identifying the new mapping to be used. This is the mapping that replaces the existing mapping in the Unicode converter object.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    The function replaces the mapping table information that currently exists in the Unicode converter object pointed to by the ioTextToUnicodeInfo parameter with the information contained in the UnicodeMapping structure you supply as the iUnicodeMapping parameter.

    ChangeTextToUnicodeInfo resets the Unicode converter object’s fields as necessary.

    If an error is returned, the Unicode converter object is invalid.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts a string from any encoding to Unicode.

    Declaration

    Objective-C

    OSStatus ConvertFromTextToUnicode ( TextToUnicodeInfo iTextToUnicodeInfo, ByteCount iSourceLen, ConstLogicalAddress iSourceStr, OptionBits iControlFlags, ItemCount iOffsetCount, const ByteOffset iOffsetArray[], ItemCount *oOffsetCount, ByteOffset oOffsetArray[], ByteCount iOutputBufLen, ByteCount *oSourceRead, ByteCount *oUnicodeLen, UniChar oUnicodeStr[] );

    Parameters

    iTextToUnicodeInfo

    A Unicode converter object of type TextToUnicodeInfo containing mapping and state information used for the conversion. The contents of this Unicode converter object are modified by the function. Your application obtains a Unicode converter object using the function CreateTextToUnicodeInfo.

    iSourceLen

    The length in bytes of the source string to be converted.

    iSourceStr

    The address of the source string to be converted.

    iControlFlags

    Conversion control flags. You can use Conversion Masks to set the iControlFlags parameter.

    iOffsetCount

    The number of offsets in the iOffsetArray parameter. Your application supplies this value. The number of entries in iOffsetArray must be fewer than the number of bytes specified in iSourceLen. If you don’t want offsets returned to you, specify 0 (zero) for this parameter.

    iOffsetArray

    An array of type ByteOffset. On input, you specify the array that contains an ordered list of significant byte offsets pertaining to the source string. These offsets may identify font or style changes, for example, in the source string. All array entries must be less than the length in bytes specified by the iSourceLen parameter. If you don’t want offsets returned to your application, specify NULL for this parameter and 0 (zero) for iOffsetCount.

    oOffsetCount

    On return, a pointer to the number of offsets that were mapped in the output stream.

    oOffsetArray

    An array of type ByteOffset. On return, this array contains the corresponding new offsets for the Unicode string produced by the converter.

    iOutputBufLen

    The length in bytes of the output buffer pointed to by the oUnicodeStr parameter. Your application supplies this buffer to hold the returned converted string. The oUnicodeLen parameter may return a byte count that is less than this value if the converted byte string is smaller than the buffer size you allocated. The relationship between the size of the source string and the Unicode string is complex and depends on the source encoding and the contents of the string.

    oSourceRead

    On return, a pointer to the number of bytes of the source string that were converted. If the function returns a kTECUnmappableElementErr result code, this parameter returns the number of bytes that were converted before the error occurred.

    oUnicodeLen

    On return, a pointer to the length in bytes of the converted stream.

    oUnicodeStr

    A pointer to an array used to hold a Unicode string. On input, this value points to the beginning of the array for the converted string. On return, this buffer holds the converted Unicode string. (For guidelines on estimating the size of the buffer needed, see the discussion.

    Return Value

    A result code. See TEC Manager Result Codes. The function returns a noErr result code if it has completely converted the input string to Unicode without using fallback characters.

    Discussion

    You specify the source string’s encoding in the Unicode mapping structure that you pass to the function CreateTextToUnicodeInfo to obtain a Unicode converter object for the conversion. You pass the Unicode converter object returned by CreateTextToUnicodeInfo to ConvertFromTextToUnicode as the iTextToUnicodeInfo parameter.

    In addition to converting a text string in any encoding to Unicode, the ConvertFromTextToUnicode function can map offsets for style or font information from the source text string to the returned converted string. The converter reads the application-supplied offsets, which apply to the source string, and returns the corresponding new offsets in the converted string. If you do not want the offsets at which font or style information occurs mapped to the resulting string, you should pass NULL for iOffsetArray and 0 (zero) for iOffsetCount.

    Your application must allocate a buffer to hold the resulting converted string and pass a pointer to the buffer in the oUnicodeStr parameter. To determine the size of the output buffer to allocate, you should consider the size of the source string, its encoding type, and its content in relation to the resulting Unicode string.

    For example, for 1-byte encodings, such as MacRoman, the Unicode string will be at least double the size (more if it uses noncomposed Unicode) for MacArabic and MacHebrew, the corresponding Unicode string could be up to six times as big. For most 2-byte encodings, for example Shift-JIS, the Unicode string will be less than double the size. For international robustness, your application should allocate a buffer three to four times larger than the source string. If the output Unicode text is actually UTF-8—which could occur beginning with the current release of the Text Encoding Conversion Manager, version 1.2.1—the UTF-8 buffer pointer must be cast to UniCharArrayPtr before it can be passed as the oUnicodeStr parameter. Also, the output buffer length will have a wider range of variation than for UTF-16; for ASCII input, the output will be the same size; for Han input, the output will be twice as big, and so on.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns a Unicode converter object containing information required for converting strings from a non-Unicode encoding to Unicode.

    Declaration

    Objective-C

    OSStatus CreateTextToUnicodeInfo ( ConstUnicodeMappingPtr iUnicodeMapping, TextToUnicodeInfo *oTextToUnicodeInfo );

    Parameters

    iUnicodeMapping

    A pointer to a structure of type UnicodeMapping. Your application provides this structure to identify the mapping to use for the conversion. You must supply a value of type TextEncoding in the unicodeEncoding field of this structure. A TextEncoding is a triple composed of an encoding base, an encoding variant, and a format. You can obtain a UnicodeMapping value by calling the function CreateTextEncoding.

    oTextToUnicodeInfo

    On return, the Unicode converter object holds mapping table information you supplied as the UnicodeMapping parameter and state information related to the conversion. This information is required for conversion of a text stream in a non-Unicode encoding to Unicode.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You pass a Unicode converter object returned from the function CreateTextToUnicodeInfo to the function ConvertFromTextToUnicode or ConvertFromPStringToUnicode to identify the information to be used for the conversion. These two functions modify the contents of the object.

    You pass a Unicode converter object returned from CreateTextToUnicodeInfo to the function TruncateForTextToUnicode to identify the information to be used to truncate the string. This function does not modify the contents of the Unicode converter object.

    If an error is returned, the Unicode converter object is invalid.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Based on the given text encoding specification, creates and returns a Unicode converter object containing information required for converting strings from the specified non-Unicode encoding to Unicode.

    Declaration

    Objective-C

    OSStatus CreateTextToUnicodeInfoByEncoding ( TextEncoding iEncoding, TextToUnicodeInfo *oTextToUnicodeInfo );

    Parameters

    iEncoding

    The text encoding specification for the source text.

    oTextToUnicodeInfo

    The Unicode converter object of type TextToUnicodeInfo returned by the function.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You can use this function instead of the CreateTextToUnicodeInfo function when you do not need to create a Unicode mapping structure. You simply specify the text encoding of the source text. However, this method is less efficient because the text encoding parameter must be resolved internally into a Unicode mapping.

    You cannot specify a version of Unicode. The function uses a 16-bit form of Unicode as the default.

    You pass a Unicode converter object returned from CreateTextToUnicodeInfoByEncoding to the function ConvertFromTextToUnicode or ConvertFromPStringToUnicode to identify the information to be used for the conversion. These two functions modify the contents of the Unicode converter object.

    You pass a Unicode converter object returned from CreateTextToUnicodeInfoByEncoding to the function TruncateForTextToUnicode to identify the information to be used to truncate the string. This function does not modify the contents of the Unicode converter object.

    If you are converting the text stream to Unicode as an intermediary encoding, and then from Unicode to the final destination encoding, you use the function CreateUnicodeToTextInfo to create a Unicode converter object for the second part of the process.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Releases the memory allocated for the specified Unicode converter object.

    Declaration

    Objective-C

    OSStatus DisposeTextToUnicodeInfo ( TextToUnicodeInfo *ioTextToUnicodeInfo );

    Parameters

    ioTextToUnicodeInfo

    A pointer to a Unicode converter object of type TextToUnicodeInfo, used for converting text to Unicode. On input, you specify the object to dispose. It must be an object which your application created using the function CreateTextToUnicodeInfo or CreateTextToUnicodeInfoByEncoding. You must not point to any other type of Unicode converter object. Your application should not use this function with the same structure more than once.

    Return Value

    A result code. See TEC Manager Result Codes. If your application specifies an invalid Unicode converter object, such as NULL, the function returns a paramErr result code.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Reinitializes all state information kept by the context objects.

    Declaration

    Objective-C

    OSStatus ResetTextToUnicodeInfo ( TextToUnicodeInfo ioTextToUnicodeInfo );

    Parameters

    ioTextToUnicodeInfo

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Changes the mapping information contained in the specified Unicode converter object used to convert Unicode text to a non-Unicode encoding.

    Declaration

    Objective-C

    OSStatus ChangeUnicodeToTextInfo ( UnicodeToTextInfo ioUnicodeToTextInfo, ConstUnicodeMappingPtr iUnicodeMapping );

    Parameters

    ioUnicodeToTextInfo

    The Unicode converter object of type UnicodeToTextInfo to be modified. You use the function CreateUnicodeToTextInfo or CreateUnicodeToTextInfoByEncoding to obtain a Unicode converter object of this type.

    iUnicodeMapping

    The structure of type UnicodeMapping to be used. This is the new mapping that replaces the existing mapping in the Unicode converter object.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    The function replaces the mapping table information that currently exists in the specified Unicode converter object with the information contained in the new Unicode mapping structure you provide.

    ChangeUnicodeToTextInfo resets the Unicode converter object’s fields as necessary. However, it does not initialize or reset the conversion state maintained by the Unicode converter object.

    This function is especially useful for converting a string from Unicode if the Unicode string contains characters that require multiple destination encodings and you know the next destination encoding.

    For example, you can change the other (destination) encoding of the Unicode mapping structure pointed to by the iUnicodeMapping parameter before you call the function ConvertFromUnicodeToText to convert the next character or sequence of characters that require a different destination encoding.

    If an error is returned, the Unicode converter object is invalid.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts a Unicode text string to the destination encoding you specify.

    Declaration

    Objective-C

    OSStatus ConvertFromUnicodeToText ( UnicodeToTextInfo iUnicodeToTextInfo, ByteCount iUnicodeLen, const UniChar iUnicodeStr[], OptionBits iControlFlags, ItemCount iOffsetCount, const ByteOffset iOffsetArray[], ItemCount *oOffsetCount, ByteOffset oOffsetArray[], ByteCount iOutputBufLen, ByteCount *oInputRead, ByteCount *oOutputLen, LogicalAddress oOutputStr );

    Parameters

    iUnicodeToTextInfo

    A Unicode converter object of type UnicodeToTextInfo for converting text from Unicode. You use the function CreateUnicodeToTextInfo or CreateUnicodeToTextInfoByEncoding to obtain a Unicode converter object to specify for this parameter. This function modifies the contents of the iUnicodeToTextInfo parameter.

    iUnicodeLen

    The length in bytes of the Unicode string to be converted.

    iUnicodeStr

    A pointer to the Unicode string to be converted. If the input text is UTF-8, which is supported for versions 1.2.1 or later of the converter, you must cast the UTF-8 buffer pointer to ConstUniCharArrayPtr before you can pass it as this parameter.

    iControlFlags

    Conversion control flags. You can use Conversion Masks and Directionality Masks to set the iControlFlags parameter.

    iOffsetCount

    The number of offsets contained in the array provided by the iOffsetArray parameter. Your application supplies this value. If you don’t want offsets returned to you, specify 0 (zero) for this parameter.

    iOffsetArray

    An array of type ByteOffset. On input, you specify the array that gives an ordered list of significant byte offsets pertaining to the Unicode source string to be converted. These offsets may identify font or style changes, for example, in the source string. If you don’t want offsets returned to your application, specify NULL for this parameter and 0 (zero) for iOffsetCount. All offsets must be less than iUnicodeLen.

    oOffsetCount

    On return, a pointer to the number of offsets that were mapped in the output stream.

    oOffsetArray

    An array of type ByteOffset. On return, this array contains the corresponding new offsets for the converted string in the new encoding.

    iOutputBufLen

    The length in bytes of the output buffer pointed to by the oOutputStr parameter. Your application supplies this buffer to hold the returned converted string. The oOutputLen parameter may return a byte count that is less than this value if the converted byte string is smaller than the buffer size you allocated.

    oInputRead

    On return, a pointer to a the number of bytes of the Unicode string that were converted. If the function returns a kTECUnmappableElementErr result code, this parameter returns the number of bytes that were converted before the error occurred.

    oOutputLen

    On return, a pointer to the length in bytes of the converted text stream.

    oOutputStr

    A value of type LogicalAddress. On input, this value points to a buffer for the converted string. On return, the buffer holds the converted text string. (For guidelines on estimating the size of the buffer needed, see the following discussion.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    This function can also map offsets for style or font information from the source text string to the returned converted string. The converter reads the application-supplied offsets and returns the corresponding new offsets in the converted string. If you do not want font or style information offsets mapped to the resulting string, you should pass NULL for iOffsetArray and 0 (zero) for iOffsetCount.

    Your application must allocate a buffer to hold the resulting converted string and pass a pointer to the buffer in the oOutputStr parameter. To determine the size of the output buffer to allocate, you should consider the size and content of the Unicode source string in relation to the type of encoding to which it will be converted. For example, for many encodings, such as MacRoman and Shift-JIS, the size of the returned string will be between half the size and the same size as the source Unicode string. However, for some encodings that are not Mac OS ones, such as EUC-JP, which has some 3-byte characters for Kanji, the returned string could be larger than the source Unicode string. For MacArabic and MacHebrew, the result will usually be less than half the size of the Unicode string.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns a Unicode converter object containing information required for converting strings from Unicode to a non-Unicode encoding.

    Declaration

    Objective-C

    OSStatus CreateUnicodeToTextInfo ( ConstUnicodeMappingPtr iUnicodeMapping, UnicodeToTextInfo *oUnicodeToTextInfo );

    Parameters

    iUnicodeMapping

    A pointer to a structure of type UnicodeMapping. Your application provides this structure to identify the mapping to be used for the conversion. The unicodeEncoding field of this structure can specify a Unicode format of kUnicode16BitFormat or kUnicodeUTF8Format. Note that the versions of the Unicode Converter prior to 1.2.1 do not support kUnicodeUTF8Format.

    oUnicodeToTextInfo

    On return, a pointer to a Unicode converter object that holds the mapping table information you supply as the iUnicodeMapping parameter and the state information related to the conversion. The information contained in the Unicode converter object is required for the conversion of a Unicode string to a non-Unicode encoding.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You pass the Unicode converter object returned from CreateUnicodeToTextInfo to the function ConvertFromUnicodeToText or ConvertFromUnicodeToPString to identify the information to be used for the conversion. These two functions modify the contents of the Unicode converter object.

    If an error is returned, the Unicode converter object is invalid.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Based on the given text encoding specification for the converted text, creates and returns a Unicode converter object containing information required for converting strings from Unicode to the specified non-Unicode encoding.

    Declaration

    Objective-C

    OSStatus CreateUnicodeToTextInfoByEncoding ( TextEncoding iEncoding, UnicodeToTextInfo *oUnicodeToTextInfo );

    Parameters

    iEncoding

    The text encoding specification for the destination, or converted, text.

    oUnicodeToTextInfo

    A pointer to a Unicode converter object of type UnicodeToTextInfo.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You can use this function instead of the CreateUnicodeToTextInfo function to create a Unicode converter. However, this method is less efficient internally because the destination text encoding you specify must be resolved into a Unicode mapping. Using this function, you cannot specify a version of Unicode, so a default version of Unicode is used; 16-bit format is assumed.

    You pass a Unicode converter object returned from the function CreateUnicodeToTextInfoByEncoding to the function ConvertFromUnicodeToText or ConvertFromUnicodeToPString to identify the information to be used for the conversion. These two functions modify the contents of the Unicode converter object.

    You pass a Unicode converter object returned from CreateUnicodeToTextInfoByEncoding to the function TruncateForUnicodeToText to identify the information to be used to truncate the string. This function does not modify the contents of the Unicode converter object.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Releases the memory allocated for the specified Unicode converter object.

    Declaration

    Objective-C

    OSStatus DisposeUnicodeToTextInfo ( UnicodeToTextInfo *ioUnicodeToTextInfo );

    Parameters

    ioUnicodeToTextInfo

    A pointer to a Unicode converter object for converting from Unicode to a non-Unicode encoding. You specify a Unicode converter object that your application created using the function CreateUnicodeToTextInfo or CreateUnicodeToTextInfoByEncoding. You must not point to any other type of Unicode converter object. Your application should not attempt to dispose of the same Unicode converter object more than once.

    Return Value

    A result code. See TEC Manager Result Codes. The function returns noErr if it disposes of the Unicode converter object successfully. If your application specifies an invalid Unicode converter object, such as NULL, the function returns a paramErr result code.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Reinitializes all state information kept by a Unicode converter object.

    Declaration

    Objective-C

    OSStatus ResetUnicodeToTextInfo ( UnicodeToTextInfo ioUnicodeToTextInfo );

    Parameters

    ioUnicodeToTextInfo

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts a string from Unicode to one or more encodings.

    Declaration

    Objective-C

    OSStatus ConvertFromUnicodeToTextRun ( UnicodeToTextRunInfo iUnicodeToTextInfo, ByteCount iUnicodeLen, const UniChar iUnicodeStr[], OptionBits iControlFlags, ItemCount iOffsetCount, const ByteOffset iOffsetArray[], ItemCount *oOffsetCount, ByteOffset oOffsetArray[], ByteCount iOutputBufLen, ByteCount *oInputRead, ByteCount *oOutputLen, LogicalAddress oOutputStr, ItemCount iEncodingRunBufLen, ItemCount *oEncodingRunOutLen, TextEncodingRun oEncodingRuns[] );

    Parameters

    iUnicodeToTextInfo

    You use the function CreateUnicodeToTextRunInfo, CreateUnicodeToTextRunInfoByEncoding, or CreateUnicodeToTextRunInfoByScriptCode to obtain a Unicode converter object to specify for this parameter.

    iUnicodeLen

    The length in bytes of the Unicode string to be converted.

    iUnicodeStr

    A pointer to the Unicode string to be converted.

    iControlFlags

    Conversion control flags. The following constants define the masks for control flags valid for this parameter. You can use Conversion Masks and Directionality Masks to set the iControlFlags parameter.

    If the text-run control flag is clear, ConvertFromUnicodeToTextRun attempts to convert the Unicode text to the single encoding it chooses from the list of encodings in the Unicode mapping structures array that you provide when you create the Unicode converter object. This is the encoding that produces the best result, that is, that provides for the greatest amount of source text conversion. If the complete source text can be converted into more than one of the encodings specified in the Unicode mapping structures array, then the converter chooses among them based on their order in the array. If this flag is clear, the oEncodingRuns parameter always points to a value equal to 1.

    If you set the use-fallbacks control flag, the converter uses the default fallback characters for the current encoding. If the converter cannot handle a character using the current encoding, even using fallbacks, the converter attempts to convert the character using the other encodings, beginning with the first encoding specified in the list and skipping the encoding where it failed.

    If you set the kUnicodeTextRunBit control flag, the converter attempts to convert the complete Unicode text string into the first encoding specified in the Unicode mapping structures array you passed to CreateUnicodeToTextRunInfo, CreateUnicodeToTextRunInfoByEncoding, or CreateUnicodeToTextRunInfoByScriptCode when you created the Unicode converter object for this conversion. If it cannot do this, the converter then attempts to convert the first text element that failed to the remaining encodings, in their specified order in the array. What the converter does with the next text element depends on the setting of the keep-same-encoding control flag.

    If the keep-same-encoding control flag is clear, the converter returns to the original encoding and attempts to continue conversion with that encoding; this is equivalent to converting each text element to the first encoding that works, in the order specified.

    If the keep-same-encoding control flag is set, the converter continues with the new destination encoding until it encounters a text element that cannot be converted using the new encoding. This attempts to minimize the number of encoding changes in the output text. When the converter cannot convert a text element using any of the encodings in the list and the Unicode-keep-same-encoding control flag is set, the converter uses the fallbacks default characters for the current encoding.

    iOffsetCount

    The number of offsets in the array pointed to by the iOffsetArray parameter. Your application supplies this value. If you don’t want offsets returned to you, specify 0 (zero) for this parameter.

    iOffsetArray

    An array of type ByteOffset. On input, you specify the array that contains an ordered list of significant byte offsets pertaining to the source Unicode string. These offsets may identify font or style changes, for example, in the Unicode string. If you don’t want offsets returned to your application, specify NULL for this parameter and 0 (zero) for iOffsetCount. All offsets must be less than iUnicodeLen.

    oOffsetCount

    On return, a pointer to the number of offsets that were mapped in the output stream.

    oOffsetArray

    An array of type ByteOffset. On return, this array contains the corresponding new offsets for the resulting converted string.

    iOutputBufLen

    The length in bytes of the output buffer pointed to by the oOutputStr parameter. Your application supplies this buffer to hold the returned converted string. The oOutputLen parameter may return a byte count that is less than this value if the converted byte string is smaller than the buffer size you allocated.

    oInputRead

    On return, a pointer to the number of bytes of the Unicode source string that were converted. If the function returns a result code other than noErr, then this parameter returns the number of bytes that were converted before the error occurred.

    oOutputLen

    On return, a pointer to the length in bytes of the converted string.

    oOutputStr

    A value of type LogicalAddress. On input, this value points to the start of the buffer for the converted string. On output, this buffer contains the converted string in one or more encodings. When an error occurs, the ConvertFromUnicodeToTextRun function returns the converted string up to the character that caused the error. (For guidelines on estimating the size of the buffer needed, see the discussion following the parameter descriptions.

    iEncodingRunBufLen

    The number of text encoding run elements you allocated for the encoding run array pointed to by the oEncodingRuns parameter. The converter returns the number of valid encoding runs in the location pointed to by oEncodingRunOutLen. Each entry in the encoding runs array specifies the beginning offset in the converted text and its associated text encoding.

    oEncodingRunOutLen

    On return, a pointer to a the number of valid encoding runs returned in the oEncodingRuns parameter.

    oEncodingRuns

    On input, an array of structures of type TextEncodingRun. Your application should allocate an array with the number of elements you specify in the iEncodingRunBufLen parameter. On return, this array contains the encoding runs for the converted text string. Each entry in the encoding run array specifies the beginning offset in the converted text string and the associated encoding specification.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    To use the ConvertFromUnicodeToTextRun function, you must first set up an array of structures of type UnicodeMapping containing, in order of precedence, the mapping information for the conversion. To create a Unicode converter object, you call the CreateUnicodeToTextRunInfo function passing it the Unicode mapping array, or you can the CreateUnicodeToTextRunInfoByEncoding or CreateUnicodeToTextRunInfoByScriptCode functions, which take arrays of text encodings or script codes instead of an array of Unicode mappings. You pass the returned Unicode converter object as the iUnicodeToTextInfo parameter when you call the ConvertFromUnicodeToTextRun function.

    Two of the control flags that you can set for the iControlFlags parameter allow you to control how the Unicode Converter uses the multiple encodings in converting the text string. These flags are explained in the description of the iControlFlags parameter. Here is a summary of how to use these two control flags:

    • To keep the converted text in a single encoding, clear the text-run control flag.

    • To keep as much contiguous converted text as possible in one encoding, set the text-run control flag and clear the keep-same-encoding control flag.

    • To minimize the number of resulting encoding runs and the changes of destination encoding, set both the text-run and keep-same-encoding control flags.

    The ConvertFromUnicodeToTextRun function returns the converted string in the array pointed to by the oOutputStr parameter. Beginning with the first text element in the oOutputStr array, the elements of the array pointed to by the oEncodingRuns parameter identify the encodings of the converted string. The number of elements in the oEncodingRuns array may not correspond to the number of elements in the oOutputStr array. This is because the oEncodingRuns array includes only elements for the beginning of each new encoding run in the converted string.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts a string from Unicode to one or more scripts.

    Declaration

    Objective-C

    OSStatus ConvertFromUnicodeToScriptCodeRun ( UnicodeToTextRunInfo iUnicodeToTextInfo, ByteCount iUnicodeLen, const UniChar iUnicodeStr[], OptionBits iControlFlags, ItemCount iOffsetCount, const ByteOffset iOffsetArray[], ItemCount *oOffsetCount, ByteOffset oOffsetArray[], ByteCount iOutputBufLen, ByteCount *oInputRead, ByteCount *oOutputLen, LogicalAddress oOutputStr, ItemCount iScriptRunBufLen, ItemCount *oScriptRunOutLen, ScriptCodeRun oScriptCodeRuns[] );

    Parameters

    iUnicodeToTextInfo

    You use the function CreateUnicodeToTextRunInfoByScriptCode to obtain a Unicode converter object to specify for this parameter.

    iUnicodeLen

    The length in bytes of the Unicode string to be converted.

    iUnicodeStr

    A pointer to the Unicode string to be converted.

    iControlFlags

    Conversion control flags. The following constants define the masks for control flags valid for this parameter. You can use Conversion Masks and Directionality Masks to set the iControlFlags parameter.

    If the text-run control flag is clear, ConvertFromUnicodeToScriptCodeRun attempts to convert the Unicode text to the single script from the list of scripts in the Unicode converter object that produces the best result, that is, that provides for the greatest amount of source text conversion. If the complete source text can be converted into more than one of the scripts specified in the array, then the converter chooses among them based on their order in the array. If this flag is clear, the oScriptCodeRuns parameter always points to a value equal to 1.

    If you set the use-fallbacks control flag, the converter uses the default fallback characters for the current script. If the converter cannot handle a character using the current encoding, even using fallbacks, the converter attempts to convert the character using the other scripts, beginning with the first one specified in the list and skipping the one where it failed.

    If you set the kUnicodeTextRunBit control flag, the converter attempts to convert the complete Unicode text string into the first script specified in the Unicode mapping structures array you passed to CreateUnicodeToTextRunInfo, CreateUnicodeToTextRunInfoByEncoding, or CreateUnicodeToTextRunInfoByScriptCode to create the Unicode converter object used for this conversion. If it cannot do this, the converter then attempts to convert the first text element that failed to the remaining scripts, in their specified order in the array. What the converter does with the next text element depends on the setting of the keep-same-encoding control flag:

    If the keep-same-encoding control flag is clear, the converter returns to the original script and attempts to continue conversion with that script; this is equivalent to converting each text element to the first one that works, in the order specified.

    If the Unicode-keep-same-encoding control flag is set, the converter continues with the new destination script until it encounters a text element that cannot be converted using the new script. This attempts to minimize the number of script code changes in the output text. When the converter cannot convert a text element using any of the scripts in the list and the Unicode-keep-same-encoding control flag is set, the converter uses the fallbacks default characters for the current script.

    iOffsetCount

    The number of offsets in the array pointed to by the iOffsetArray parameter. Your application supplies this value. The number of entries in iOffsetArray must be fewer than half the number of bytes specified in iUnicodeLen. If you don’t want offsets returned to you, specify 0 (zero) for this parameter.

    iOffsetArray

    An array of type ByteOffset. On input, you specify the array that contains an ordered list of significant byte offsets pertaining to the source Unicode string. These offsets may identify font or style changes, for example, in the Unicode string. If you don’t want offsets returned to your application, specify NULL for this parameter and 0 (zero) for iOffsetCount.

    oOffsetCount

    On return, a pointer to the number of offsets that were mapped in the output stream.

    oOffsetArray

    An array of type ByteOffset. On return, this array contains the corresponding new offsets for the resulting converted string.

    iOutputBufLen

    The length in bytes of the output buffer pointed to by the oOutputStr parameter. Your application supplies this buffer to hold the returned converted string. The oOutputLen parameter may return a byte count that is less than this value if the converted byte string is smaller than the buffer size you allocated.

    oInputRead

    On return, a pointer to the number of bytes of the Unicode source string that were converted. If the function returns a result code other than noErr, then this parameter returns the number of bytes that were converted before the error occurred.

    oOutputLen

    On return, a pointer to the length in bytes of the converted string.

    oOutputStr

    A buffer address. On input, this value points to the beginning of the buffer for the converted string. On return, this buffer contains the converted string in one or more encodings. When an error occurs, the ConvertFromUnicodeToScriptCodeRun function returns the converted string up to the character that caused the error.

    iScriptRunBufLen

    The number of script code run elements you allocated for the script code run array pointed to by the oScriptCodeRuns parameter. The converter returns the number of valid script code runs in the location pointed to by oScriptRunOutLen. Each entry in the script code run array specifies the beginning offset in the converted text and its associated script code.

    oScriptRunOutLen

    A pointer to a value of type ItemCount. On output, this value contains the number of valid script code runs returned in the oScriptCodeRuns parameter.

    oScriptCodeRuns

    An array of elements of type ScriptCodeRun. Your application should allocate an array with the number of elements you specify in the iScriptRunBufLen parameter. On return, this array contains the script code runs for the converted text string. Each entry in the array specifies the beginning offset in the converted text string and the associated script code specification.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    To use the ConvertFromUnicodeToScriptCodeRun function, you must first set up an array of script codes containing in order of precedence the scripts to be used for the conversion. To create a Unicode converter object, you call the function CreateUnicodeToTextRunInfoByScriptCode. You pass the returned Unicode converter object as the iUnicodeToTextInfo parameter when you call the ConvertFromUnicodeToScriptCodeRun function.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Creates and returns a Unicode converter object containing the information required for converting a Unicode text string to strings in one or more non-Unicode encodings.

    Declaration

    Objective-C

    OSStatus CreateUnicodeToTextRunInfo ( ItemCount iNumberOfMappings, const UnicodeMapping iUnicodeMappings[], UnicodeToTextRunInfo *oUnicodeToTextInfo );

    Parameters

    iNumberOfMappings

    The number of mappings specified by your application for converting from Unicode to any other encoding types, including other forms of Unicode. If you pass 0 for this parameter, the converter will use all of the scripts installed in the system. The primary script is the one with highest priority; ScriptOrder ('itlm' resource) determines the priority of the rest. If you set the high-order bit for this parameter, the Unicode converter assumes that the iEncodings parameter contains a single element specifying the preferred encoding. This feature is supported for versions 1.2 or later of the converter.

    iUnicodeMappings

    A pointer to an array of structures of type UnicodeMapping. Your application provides this structure to identify the mappings to be used for the conversion. The order in which you specify the mappings determines the priority of the destination encodings. For this function, the Unicode mapping structure can specify a Unicode format of kUnicode16BitFormat or kUnicodeUTF8Format. Note that the versions of the Unicode Converter prior to the Text Encoding Conversion Manager 1.2.1 do not support kUnicodeUTF8Format. Also, note that the unicodeEncoding field should be the same for all of the entries in iUnicodeMappings. If you pass NULL for the iUnicodeMappings parameter, the converter uses all of the scripts installed in the system, assuming the default version of Unicode with 16-bit format. The primary script is the one with the highest priority and ScriptOrder('itlm' resource) determines the priority of the rest. This is supported beginning with version 1.2 of the Text Encoding Conversion Manager.

    oUnicodeToTextInfo

    A pointer to a Unicode converter object for converting Unicode text strings to strings in one or more non-Unicode encodings. On return, a pointer to a Unicode converter object that holds the mapping table information you supply as the iUnicodeMappings parameter and the state information related to the conversion.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You pass a Unicode converter object returned from the function CreateUnicodeToTextRunInfo to the function ConvertFromUnicodeToTextRun or ConvertFromUnicodeToScriptCodeRun to identify the information to be used for the conversion. These two functions modify the contents of the Unicode converter object.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Based on the given text encoding specifications for the converted text runs, creates and returns a Unicode converter object containing information required for converting strings from Unicode to one or more specified non-Unicode encodings.

    Declaration

    Objective-C

    OSStatus CreateUnicodeToTextRunInfoByEncoding ( ItemCount iNumberOfEncodings, const TextEncoding iEncodings[], UnicodeToTextRunInfo *oUnicodeToTextInfo );

    Parameters

    iNumberOfEncodings

    The number of desired encodings. If you pass 0 for this parameter, the converter will use all of the scripts installed in the system. The primary script is the one with highest priority; ScriptOrder('itlm' resource) determines the priority of the rest. If you set the high-order bit for this parameter, the Unicode converter assumes that the iEncodings parameter contains a single element specifying the preferred encoding. This feature is supported for versions 1.2 or later of the converter.

    iEncodings

    An array of text encoding specifications for the desired encodings. Your application provides this structure to identify the encodings to be used for the conversion. The order in which you specify the encodings determines the priority of the destination encodings. If you pass NULL for this parameter, the converter will use all of the scripts installed in the system. The primary script is the one with highest priority and ScriptOrder('itlm' resource) determines the priority of the rest.This feature is supported for versions 1.2 or later of the converter.

    oUnicodeToTextInfo

    A pointer to a Unicode converter object for converting Unicode text strings to strings in one or more non-Unicode encodings. On return, a pointer to a Unicode converter object that holds the encodings you supply as the iEncodings parameter and the state information related to the conversion.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You pass a Unicode converter object returned from CreateUnicodeToTextRunInfoByEncoding to the function ConvertFromUnicodeToTextRun or ConvertFromUnicodeToScriptCodeRun to identify the information to be used for the conversion. These two functions modify the contents of the Unicode converter object.

    If an error is returned, the converter object is invalid.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Based on the given script codes for the converted text runs, creates and returns a Unicode converter object containing information required for converting strings from Unicode to one or more specified non-Unicode encodings.

    Declaration

    Objective-C

    OSStatus CreateUnicodeToTextRunInfoByScriptCode ( ItemCount iNumberOfScriptCodes, const ScriptCode iScripts[], UnicodeToTextRunInfo *oUnicodeToTextInfo );

    Parameters

    iNumberOfScriptCodes

    The number of desired scripts. If you pass 0 for this parameter, the converter uses all the scripts installed in the system. In this case, the primary script is the one with highest priority; ScriptOrder (’itlm’ resource) determines the priority of the rest. If you set the high-order bit for this parameter, the Unicode converter assumes that the iScripts parameter contains a single element specifying the preferred script. This feature is supported beginning with the Text Encoding Conversion Manager 1.2.

    iScripts

    An array of script codes for the desired scripts. Your application provides this structure to identify the scripts to be used for the conversion. The order in which you specify the scripts determines their priority. If you pass NULL for this parameter, the converter uses all of the scripts installed in the system. In this case, the primary script is the one with the highest priority and the priority order of the remaining scripts is defined by the ScriptOrder(itlm resource) resource. This feature is supported for versions 1.2 or later of the converter.

    oUnicodeToTextInfo

    A pointer to a Unicode converter object for converting Unicode text strings to strings in one or more non-Unicode encodings. On return, a pointer to Unicode converter object that holds the scripts you supply as the iScripts parameter and the state information related to the conversion.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You pass a Unicode converter object returned from CreateUnicodeToTextRunInfoByScriptCode to the function ConvertFromUnicodeToTextRun or ConvertFromUnicodeToScriptCodeRun to identify the information to be used for the conversion. These two functions modify the contents of the Unicode converter object.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Releases the memory allocated for the specified Unicode converter object.

    Declaration

    Objective-C

    OSStatus DisposeUnicodeToTextRunInfo ( UnicodeToTextRunInfo *ioUnicodeToTextRunInfo );

    Parameters

    ioUnicodeToTextRunInfo

    A pointer to a Unicode converter object. On input, you specify a Unicode converter object that points to the conversion information to dispose. It must be an object which your application created using the function CreateUnicodeToTextRunInfo, CreateUnicodeToTextRunInfoByEncoding, or CreateUnicodeToTextRunInfoByScriptCode. You must point to any other type of Unicode converter object. Your application should not use this function with the same structure more than once.

    Return Value

    A result code. See TEC Manager Result Codes. If your application specifies an invalid Unicode converter object, such as NULL, the function returns paramErr.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Reinitializes all state information kept by the context objects in TextRun conversions.

    Declaration

    Objective-C

    OSStatus ResetUnicodeToTextRunInfo ( UnicodeToTextRunInfo ioUnicodeToTextRunInfo );

    Parameters

    ioUnicodeToTextRunInfo

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts a Pascal string in a Mac OS text encoding to a Unicode string.

    Declaration

    Objective-C

    OSStatus ConvertFromPStringToUnicode ( TextToUnicodeInfo iTextToUnicodeInfo, ConstStr255Param iPascalStr, ByteCount iOutputBufLen, ByteCount *oUnicodeLen, UniChar oUnicodeStr[] );

    Parameters

    iTextToUnicodeInfo

    A Unicode converter object of type TextToUnicodeInfo for the Pascal string to be converted. You can use the function CreateTextToUnicodeInfo or CreateTextToUnicodeInfoByEncoding to create the Unicode converter object.

    iPascalStr

    The Pascal string to be converted to Unicode.

    iOutputBufLen

    The length in bytes of the output buffer pointed to by the oUnicodeStr parameter. Your application supplies this buffer to hold the returned converted string. The oUnicodeLen parameter may return a byte count that is less than this value if the converted string is smaller than the buffer size you allocated.

    oUnicodeLen

    On return, a pointer to the length in bytes of the converted Unicode string returned in the oUnicodeStr parameter.

    oUnicodeStr

    A pointer to a Unicode character array. On return, this array holds the converted Unicode string.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    The ConvertFromPStringToUnicode function provides an easy and efficient way to convert a short Pascal string to a Unicode string without incurring the overhead associated with the function ConvertFromTextToUnicode.

    If necessary, this function automatically uses fallback characters to map the text elements of the string.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Converts a Unicode string to Pascal in a Mac OS text encoding.

    Declaration

    Objective-C

    OSStatus ConvertFromUnicodeToPString ( UnicodeToTextInfo iUnicodeToTextInfo, ByteCount iUnicodeLen, const UniChar iUnicodeStr[], Str255 oPascalStr );

    Parameters

    iUnicodeToTextInfo

    A Unicode converter object. You use the CreateUnicodeToTextInfo or CreateUnicodeToTextInfoByEncoding function to obtain the Unicode converter object for the conversion.

    iUnicodeLen

    The length in bytes of the Unicode string to be converted. This is the string your application provides in the iUnicodeStr parameter.

    iUnicodeStr

    A pointer to an array containing the Unicode string to be converted.

    oPascalStr

    A buffer. On return, the converted Pascal string returned by the function.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    The ConvertFromUnicodeToPString function provides an easy and efficient way to convert a Unicode string to a Pascal string in a Mac OS text encoding without incurring the overhead associated with use of the function ConvertFromUnicodeToText or ConvertFromUnicodeToScriptCodeRun.

    If necessary, this function uses the loose mapping and fallback characters to map the text elements of the string. For fallback mappings, it uses the handler associated with the Unicode converter object.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Counts available mappings that meet the specified matching criteria.

    Declaration

    Objective-C

    OSStatus CountUnicodeMappings ( OptionBits iFilter, ConstUnicodeMappingPtr iFindMapping, ItemCount *oActualCount );

    Parameters

    iFilter

    Filter control flags representing the six subfields of the Unicode mapping structure that this function uses to match against in determining which mappings on the system to return to your application. The filter control enumeration, described in Unicode Matching Masks, define the constants for the subfield’s flags and their masks. You can include in the search criteria any of the three text encoding subfields for both the Unicode encoding and the other specified encoding. For any flag not turned on, the subfield value is ignored and the function does not check the corresponding subfield of the mappings on the system.

    iFindMapping

    A structure of type UnicodeMapping containing the text encodings whose field values are to be matched.

    oActualCount

    On return, a pointer to the number of matching mappings found.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You can filter on any of the three text encoding subfields of the Unicode mapping structure’s unicodeEncoding specification and on any of the three text encoding subfields of the structure’s otherEncoding specification. The iFilter parameter consists of a set of six control flags that you set to identify which of the corresponding six subfields to include in the match count. No filtering is performed on fields for which you do not set the corresponding filter control flag.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Returns a list of the conversion mappings available on the system that meet specified matching criteria and returns the number of mappings found.

    Declaration

    Objective-C

    OSStatus QueryUnicodeMappings ( OptionBits iFilter, ConstUnicodeMappingPtr iFindMapping, ItemCount iMaxCount, ItemCount *oActualCount, UnicodeMapping oReturnedMappings[] );

    Parameters

    iFilter

    Filter control flags representing the six values given in the Unicode mapping structure that this function uses to match against in determining which mappings on the system to return to your application. The filter control flag enumerations, described in Unicode Matching Masks, define the constants for the flags and their masks. You can include in the search criteria any of the three text encoding values—base, variant, and format—for both the Unicode encoding and the other specified encoding. For any flag not turned on, the value is ignored the function does not check the corresponding value of the mapping tables on the system.

    iFindMapping

    A structure of type UnicodeMapping containing the text encodings whose values are to be matched.

    iMaxCount

    The maximum number of mappings that can be returned. You provide this value to identify the number of elements in the array pointed to by the oReturnedMappings parameter that your application allocated. If the function identifies more matching mappings than the array can hold, it returns as many of them as fit. The function also returns a kTECArrayFullErr in this case.

    oActualCount

    On return, a pointer to the number of matching mappings found. This number may be greater than the number of mappings specified by iMaxCount if more matching mappings are found than can fit in the oReturnedMappings array.

    oReturnedMappings

    A pointer to an array of structures of type UnicodeMapping. On input, this pointer refers to an array for the matching mappings returned by the function. To allocate sufficient elements for the array, you can use the function CountUnicodeMappings to determine the number of mappings returned for given values of the iFilter and iFindMapping parameters. On return, a pointer to an array that holds the matching mappings. If there are more matches than the array can hold, the function returns as many of them as will fit and a kTECBufferBelowMinimumSizeErr error result. The oActualCount parameter identifies the number of matching mappings actually found, which may be greater than the number returned.

    Return Value

    A result code. See TEC Manager Result Codes. If the function returns a noErr result code, the value retuned in the oActualCount parameter is less than or equal to the value returned in the iMaxCount parameter and the oReturnedMappings parameter contains all of the matching mappings found. If the function returns a kTECArrayFullErr, the function found more mappings than your oReturnedMappings array could accommodate.

    Discussion

    You can use the QueryUnicodeMappings function to obtain all mappings on the system up to the number allowed by your oReturnedMappings array by specifying a value of zero for the iFilter field.

    You can use the function to obtain very specific mappings by setting individual filter control flags. You can filter on any of the three text encoding subfields of the Unicode mapping structure’s unicodeEncoding specification and on any of the three text encoding subfields of the mapping’s otherEncoding specification. The iFilter parameter consists of a set of six control flags that you set to identify which of the corresponding six subfields to include in the match. The list provided in the oReturnedMappings parameter will contain only mappings that match the fields of the Unicode mapping structure whose text encodings subfields you identify in the filter control flags. No filtering is performed on subfields for which you do not set the corresponding filter control flag.

    For example, to obtain a list of all mappings in which one of the encodings is the default variant and default format of the Unicode 1.1 base encoding and the other encoding is the default variant and default format of a base encoding other than Unicode, you would set up the iFilter and iFindMappings parameter as follows. To set up these parameters, you use the constants defined for the text encoding bases, the text encoding default variants, the text encoding default formats, and the filter control flag bitmasks. In this example, the text encoding base field of the Unicode mapping structure’s otherEncoding field is ignored, so you can specify any value for it. When you call QueryUnicodeMappings, passing it these parameters, the function will return a list of mappings between the Unicode encoding you specified and every other available encoding in which each non-Unicode base encoding shows up once because you specified its default variant and default format.

    • iFindMapping.unicodeMapping = CreateTextEncoding(
    • kTextEncodingUnicodeV1_1,
    • kTextEncodingDefaultVariant,
    • kTextEncodingDefaultFormat);
    • iFindMapping.otherEncoding = CreateTextEncoding(
    • kTextEncodingMacRoman,
    • kTextEncodingDefaultVariant,
    • kTextEncodingDefaultFormat);
    • iFilter = kUnicodeMatchUnicodeBaseMask |
    • kUnicodeMatchUnicodeVariantMask |
    • kUnicodeMatchUnicodeFormatMask |
    • kUnicodeMatchOtherVariantMask |
    • kUnicodeMatchOtherFormatMask;

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Identifies where your application can safely break a multibyte string to be converted to Unicode so that the string is not broken in the middle of a multibyte character.

    Declaration

    Objective-C

    OSStatus TruncateForTextToUnicode ( ConstTextToUnicodeInfo iTextToUnicodeInfo, ByteCount iSourceLen, ConstLogicalAddress iSourceStr, ByteCount iMaxLen, ByteCount *oTruncatedLen );

    Parameters

    iTextToUnicodeInfo

    The Unicode converter object of type TextToUnicodeInfo for the text string to be divided up with each segment properly truncated. The TruncateForTextToUnicode function does not modify the object’s contents.

    iSourceLen

    The length in bytes of the multibyte string to be divided up.

    iSourceStr

    The address of the multibyte string to be divided up.

    iMaxLen

    The maximum allowable length of the string to be truncated. This must be less than or equal to iSourceLen.

    oTruncatedLen

    A pointer to a value of type ByteCount. On return, this value contains the length of the longest portion of the multibyte string, pointed to by iSourceStr, that is less than or equal to the length specified by iMaxLen. This identifies the byte after which you can break the string.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    Your application can use this function to break a string properly before you call the function ConvertFromTextToUnicode so that the string you pass it is terminated with complete characters. You can call this function repeatedly to properly divide up a text segment, each time identifying the new beginning of the string, until the last portion of the text is less than or equal to the maximum allowable length. Each time you use the function, you get a properly terminated string within the allowable length range.

    Because the TruncateForTextToUnicode function does not modify the contents of the Unicode converter object, you can call this function safely between calls to the function ConvertFromTextToUnicode.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Identifies where your application can safely break a Unicode string to be converted to any encoding so that the string is broken in a way that preserves the text element integrity.

    Declaration

    Objective-C

    OSStatus TruncateForUnicodeToText ( ConstUnicodeToTextInfo iUnicodeToTextInfo, ByteCount iSourceLen, const UniChar iSourceStr[], OptionBits iControlFlags, ByteCount iMaxLen, ByteCount *oTruncatedLen );

    Parameters

    iUnicodeToTextInfo

    A Unicode converter object UnicodeToTextInfo for the Unicode string to be divided up. The TruncateForUnicodeToText function does not modify the contents of this private structure.

    iSourceLen

    The length in bytes of the Unicode string to be divided up.

    iSourceStr

    A pointer to the Unicode string to be divided up.

    iControlFlags

    Truncation control flags. Specify the flag kUnicodeStringUnterminatedMask if truncating a buffer of text that belongs to a longer stream containing a subsequent buffer of text that could have characters belonging to a text element that begins at the end of the current buffer. If you set this flag, typically you would set the iMaxLen parameter equal to iSourceLen.

    iMaxLen

    The maximum allowable length of the string to be truncated. This must be less than or equal to iSourceLen.

    oTruncatedLen

    A pointer to a value of type ByteCount. On return, this value contains the length of the longest portion of the Unicode source string, pointed to by the iSourceStr parameter, that is less than or equal to the value of the iMaxLen parameter. This returned parameter identifies the byte after which you can truncate the string.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    Your application can use this function to divide up a Unicode string properly truncating each portion before you call ConvertFromUnicodeToText or ConvertFromUnicodeToScriptCodeRun to convert the string. You can call this function repeatedly to properly truncate a text segment, each time identifying the new beginning of the string, until the last portion of the text is less than or equal to the maximum allowable length. Each time you use the function, you get a properly terminated string within the allowable length range.

    Because this function does not modify the contents of the Unicode converter object, you can call this function between conversion calls.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Specifies a fallback handler to be used for converting a Unicode text segment to another encoding when the Unicode Converter cannot convert the text using the mapping table specified by the Unicode converter object.

    Declaration

    Objective-C

    OSStatus SetFallbackUnicodeToText ( UnicodeToTextInfo iUnicodeToTextInfo, UnicodeToTextFallbackUPP iFallback, OptionBits iControlFlags, LogicalAddress iInfoPtr );

    Parameters

    iUnicodeToTextInfo

    \The Unicode converter object to which the fallback handler is to be associated. You use the function CreateUnicodeToTextInfo or CreateUnicodeToTextInfoByEncoding to obtain a Unicode converter object of this type.

    iFallback

    A universal procedure pointer to the application-defined fallback routine. For a description of the function prototype that your fallback handler must adhere to and how to create your own fallback handler, see UnicodeToTextFallbackProcPtr. You should use the NewUnicodeToTextFallbackProc macro to convert a pointer to your fallback handler into a UnicodeToTextFallbackUPP.

    iControlFlags

    Control flags that stipulate which fallback handler the Unicode Converter should call—the application-defined fallback handler or the default handler—if a fallback handler is required, and the sequence in which the Unicode Converter should call the fallback handlers if either can be used when the other fails or is unavailable. See Fallback Handler Selectors.

    iInfoPtr

    A point to a block of memory to be passed to the application-defined fallback handler. The Unicode Converter passes this pointer to the application-defined fallback handler as the last parameter when it calls the fallback handler. Your application can use this memory block to store data required by your fallback handler whenever it is called. This is similar in use to a reference constant (refcon). If you don’t need to use a memory block, specify NULL for this parameter.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You can define multiple fallback handlers and associate them with different Unicode converter objects, depending on your requirements. See UnicodeToTextFallbackProcPtr for a description of how to create and install an application-defined fallback handler.

    You can use a fallback handler when one of the Unicode conversion functions, ConvertFromUnicodeToText , ConvertFromUnicodeToTextRun , ConvertFromUnicodeToPString , and ConvertFromUnicodeToScriptCodeRun , cannot convert the text using the mapping table specified by the Unicode converter object passed to the function.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Specifies a fallback handler to be used for converting a Unicode text segment to another encoding when the Unicode Converter cannot convert the text using the mapping table specified by a Unicode converter object.

    Declaration

    Objective-C

    OSStatus SetFallbackUnicodeToTextRun ( UnicodeToTextRunInfo iUnicodeToTextRunInfo, UnicodeToTextFallbackUPP iFallback, OptionBits iControlFlags, LogicalAddress iInfoPtr );

    Parameters

    iUnicodeToTextRunInfo

    The Unicode converter object to which the fallback handler is to be associated. You use the function CreateUnicodeToTextRunInfo, CreateUnicodeToTextRunInfoByEncoding, or CreateUnicodeToTextRunInfoByScriptCode to obtain a Unicode converter object to specify for this parameter.

    iFallback

    A universal procedure pointer to the application-defined fallback routine. For a description of the function prototype to which your fallback handler must adhere and how to create your own fallback handler, see UnicodeToTextFallbackProcPtr. You should use the NewUnicodeToTextFallbackProc macro described in the discussion of the function SetFallbackUnicodeToText.

    iControlFlags

    Control flags that stipulate which fallback handler the Unicode Converter should call—the application-defined fallback handler or the default handler—if a fallback handler is required, and the sequence in which the Unicode Converter should call the fallback handlers if either can be used when the other fails or is unavailable. See Fallback Handler Selectors.

    iInfoPtr

    A pointer to a block of memory to be passed to the application-defined fallback handler. The Unicode Converter passes this pointer to the application-defined fallback handler as the last parameter when it calls the fallback handler. Your application can use this block to store data required by your fallback handler whenever it is called. This is similar in use to a reference constant (refcon). If you don’t need to use a memory block, specify NULL for this parameter.

    Return Value

    A result code. See TEC Manager Result Codes.

    Discussion

    You can define multiple fallback handlers and associate them with different Unicode converter objects, depending on your requirements. See UnicodeToTextFallbackProcPtr for a description of how to create and install an application-defined fallback handler.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Obtains the value associated with a property type for the specified UniChar characters.

    Declaration

    Objective-C

    OSStatus UCGetCharProperty ( const UniChar *charPtr, UniCharCount textLength, UCCharPropertyType propType, UCCharPropertyValue *propValue );

    Parameters

    charPtr

    A pointer to the Unicode text whose property value you want to obtain.

    textLength

    The length of the text pointed to by charPtr.

    propType

    The property type for the UniChar character whose value you want to obtain. See Unicode Character Property Types for a list of the constants you can supply.

    propValue

    On return, the value associated with the property type specified by the propType parameter. See Unicode Character Property Values for a list of the constants that can be returned.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

Callbacks

  • Defines a pointer to a function that converts a Unicode text element for which there is no destination encoding equivalent in the appropriate mapping table to the fallback character sequence defined by your fallback handler, and returns the converted character sequence to the Unicode Converter.

    Declaration

    Objective-C

    typedef OSStatus (*UnicodeToTextFallbackProcPtr) ( UniChar * iSrcUniStr, ByteCount iSrcUniStrLen, ByteCount * oSrcConvLen, TextPtr oDestStr, ByteCount iDestStrLen, ByteCount * oDestConvLen, LogicalAddress iInfoPtr, ConstUnicodeMappingPtr iUnicodeMappingPtr );

    Parameters

    iSrcUniStr

    A pointer to a single UTF-16 character to be mapped by the fallback handler.

    iSrcUniStrLen

    The length in bytes of the UTF-16 character indicated by the iSrcUniStr parameter. Usually this is 2 bytes, but it could be 4 bytes for a non-BMP character.

    oSrcConvLen

    On return, a pointer to the length in bytes of the portion of the Unicode character that was actually processed by your fallback handler. Your fallback handler returns this value. It should set this to 0 if none of the text was handled, or 2 or 4 if the Unicode character was handled. This value is initialized to 0 before the fallback handler is called.

    oDestStr

    A pointer to the output buffer where your handler should place any converted text.

    iDestStrLen

    The maximum size in bytes of the buffer provided by the oDestStr parameter.

    oDestConvLen

    On return, a pointer to the length in bytes of the fallback character sequence generated by your fallback handler. Your handler should return this length. It is initialized to 0 (zero) before the fallback handler is called.

    iInfoPtr

    A pointer to a block of memory allocated by your application, which can be used by your fallback handler in any way that you like. This is the same pointer passed as the last parameter of SetFallbackUnicodeToText or SetFallbackUnicodeToTextRun. How you use the data passed to you in this memory block is particular to your handler. This is similar in use to a reference constant (refcon).

    iUnicodeMappingPtr

    A constant pointer to a structure of type UnicodeMapping. This structure identifies a Unicode encoding specification and a particular base encoding specification.

    Return Value

    A result code. See TEC Manager Result Codes. Your handler should return noErr if it can handle the fallback, or kTECUnmappableElementErr if it cannot. It can return other errors for exceptional conditions, such as when the output buffer is too small. If your handler returns kTECUnmappableElementErr, then oSrcConvLen and oDestConvLen are ignored because either the default handler will be called or the default fallback sequence will be used.

    Discussion

    The Unicode Converter calls your fallback handler when it cannot convert a text string using the mapping table specified by the Unicode converter object passed to either ConvertFromUnicodeToText or ConvertFromUnicodeToPString. The control flags you set for the controlFlags parameter of the function SetFallbackUnicodeToText or the SetFallbackUnicodeToTextRun stipulate which fallback handler the Unicode Converter should call and which one to try first if both can be used.

    When the Unicode Converter calls your handler, it passes to it the Unicode character to be converted and its length, a buffer for the converted string you return and the buffer length, and a pointer to a block of memory containing the data your application supplied to be passed on to your fallback handler.

    After you convert the Unicode text segment to fallback characters, you return the fallback character sequence of the converted text in the buffer provided to you and the length in bytes of this fallback character sequence. You also return the length in bytes of the portion of the source Unicode text element that your handler actually processed.

    You provide a fallback-handler function for use with the function CreateUnicodeToTextInfoByEncoding, ConvertFromUnicodeToPString, ConvertFromUnicodeToTextRun, or ConvertFromUnicodeToScriptCodeRun. You associate an application-defined fallback handler with a particular Unicode converter object you intend to pass to the conversion function when you call it.

    Text converted from UTF-8 will already have been converted to UTF-16 before the fallback handler is called to process it. Your fallback handler should do all of its processing on text encoded in UTF-16.

    Your application-defined fallback handler should not move memory or call any toolbox function that would move memory. If it needs memory, the memory should be allocated before the call to SetFallbackUnicodeToText or SetFallbackUnicodeToTextRun, and a memory reference should be passed either directly as iInfoPtr or in the data referenced by iInfoPtr.

    To associate a fallback-handler function with a Unicode converter object you use the SetFallbackUnicodeToText and SetFallbackUnicodeToTextRun functions. For these functions, you must pass a universal procedure pointer (UniversalProcPtr). This is derived from a pointer to your function by using the predefined macro NewUnicodeToTextFallbackProc.

    For versions of the Unicode Converter prior to 1.2, the fallback handler may receive a multiple character text element, so the source string length value could be greater than 2 and the fallback handler may set srcConvLen to a value greater than 2. In versions earlier than 1.2.1, the srcConvLen and destConvLen variables are not initialized to 0; both values are ignored unless the fallback handler returns noErr.

    The following example shows how to install an application-defined fallback handler. You can name your application-defined fallback handler anything you choose. The name, MyUnicodeToTextFallbackProc, used in this example is not significant. However, you must adhere to the parameters, the return type, and the calling convention as expressed in this example, which follows the prototype, because a pointer to this function must be of type UnicodeToTextFallbackProcPtr as defined in the UnicodeConverter.h header file.

    The UnicodeConverter.h header file also defines the UnicodeToTextFallbackUPP type and the NewUnicodeToTextFallbackProc macro.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that returns a pointer to a plug-in dispatch table.

    Declaration

    Objective-C

    typedef TECPluginDispatchTable * (*TECPluginGetPluginDispatchTablePtr) ( );

    Parameters

    Return Value

    A pointer to the function dispatch table for the plug-in.

    Discussion

    You need this callback only for OS X plug-ins. When you create a TEC plug-in in OS X you must export a function named ConverterPluginGetPluginDispatchTable with the following prototype:

    extern TECPluginDispatchTable *ConverterPluginGetPluginDispatchTable (void)

    This function must return a pointer to the function dispatch table for the plug-in. It is important you name the function ConverterPluginGetPluginDispatchTable because TECPluginGetPluginDispatchTablePtr is a function pointer to a function of this exact name.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.1 and later.

  • Defines a pointer to a function that determines a conversion path for a source and destination encoding, then creates a text encoding converter object and returns a pointer to it.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginNewEncodingConverterPtr) ( TECObjectRef * newEncodingConverter, TECConverterContextRec * plugContext, TextEncoding inputEncoding, TextEncoding outputEncoding );

    Parameters

    newEncodingConverter

    A pointer to a converter object. On return, this points to a newly created text converter object.

    plugContext

    A pointer to a TEC converter context record.

    inputEncoding

    The text encoding specification for the source text.

    outputEncoding

    The text encoding specification for the destination text.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that resets a converter object to its initial state.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginClearContextInfoPtr) ( TECObjectRef encodingConverter, TECConverterContextRec * plugContext );

    Parameters

    encodingConverter

    A reference to the text encoding converter object that needs to be reset.

    plugContext

    A pointer to a TEC converter context record.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that converts stream of text from a source encoding to a destination encoding, using the conversion path specified by the converter object you supply.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginConvertTextEncodingPtr) ( TECObjectRef encodingConverter, TECConverterContextRec * plugContext );

    Parameters

    encodingConverter

    A reference to the text encoding converter object to use for the conversion.

    plugContext

    A pointer to a TEC converter context record that contains the text and other information needed for the conversion.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that flushes out any data in a converter object’s temporary buffers and resets the converter object.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginFlushConversionPtr) ( TECObjectRef encodingConverter, TECConverterContextRec * plugContext );

    Parameters

    encodingConverter

    A reference to the text converter object whose contents are to be flushed.

    plugContext

    A pointer to a TEC converter context record.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that disposes of a converter object.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginDisposeEncodingConverterPtr) ( TECObjectRef newEncodingConverter, TECConverterContextRec * plugContext );

    Parameters

    newEncodingConverter

    A reference to the converter object to dispose of.

    plugContext

    A pointer to a TEC converter context record.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that creates a sniffer object and returns a reference to it.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginNewEncodingSnifferPtr) ( TECSnifferObjectRef * encodingSniffer, TECSnifferContextRec * snifContext, TextEncoding inputEncoding );

    Parameters

    encodingSniffer

    A pointer to a sniffer object reference, which is of type TECSnifferObjectRef. On return, the reference pertains to the newly created sniffer object.

    snifContext

    A pointer to a TEC sniffer context record.

    inputEncoding

    The text encoding specification to be detected by the sniffer object.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that resets a sniffer object to its initial settings.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginClearSnifferContextInfoPtr) ( TECSnifferObjectRef encodingSniffer, TECSnifferContextRec * snifContext );

    Parameters

    encodingSniffer

    A reference to the sniffer object that needs to be reset.

    snifContext

    A pointer to a TEC sniffer context record.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that analyzes a text stream and returns the probable encodings in a ranked list, based on an array of possible encodings you supply; it also returns the number of errors and features for each encoding.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginSniffTextEncodingPtr) ( TECSnifferObjectRef encodingSniffer, TECSnifferContextRec * snifContext );

    Parameters

    encodingSniffer

    A reference to a sniffer object.

    snifContext

    A pointer to a TEC sniffer context record.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that disposes of a sniffer object.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginDisposeEncodingSnifferPtr) ( TECSnifferObjectRef encodingSniffer, TECSnifferContextRec * snifContext );

    Parameters

    encodingSniffer

    A reference to the sniffer object you want to dispose.

    snifContext

    A pointer to a TEC sniffer context record.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that obtains the available text encodings.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginGetCountAvailableTextEncodingsPtr) ( TextEncoding * availableEncodings, ItemCount maxAvailableEncodings, ItemCount * actualAvailableEncodings );

    Parameters

    availableEncodings

    On return, a pointer to the currently available text encoding specifications.

    maxAvailableEncodings

    The number of text encoding specifications the availableEncodings array can contain.

    actualAvailableEncodings

    On the return, the number of text encoding specifications the availableEncodings array actually contains.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that obtains the available text encoding pairs.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginGetCountAvailableTextEncodingPairsPtr) ( TECConversionInfo * availableEncodings, ItemCount maxAvailableEncodings, ItemCount * actualAvailableEncodings );

    Parameters

    availableEncodings

    On return, an array of text encoding conversion information structures, each of which specifies a set of source and destination encodings for a type of conversion.

    maxAvailableEncodings

    The number of text encoding information structures the availableEncodings array can contain.

    actualAvailableEncodings

    On the return, the number of text encoding information structures the availableEncodings array actually contains.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that counts and returns the number of destination encodings to which a specified source encoding can be converted in one step.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginGetCountDestinationTextEncodingsPtr) ( TextEncoding inputEncoding, TextEncoding * destinationEncodings, ItemCount maxDestinationEncodings, ItemCount * actualDestinationEncodings );

    Parameters

    inputEncoding

    The text encoding specification describing the source text.

    destinationEncodings

    On return, a pointer to text encodings to which the source encoding can be converted in one step.

    maxDestinationEncodings

    The maximum number of text encodings that can be specified by the destinationEncodings parameter.

    actualDestinationEncodings

    On return, the actual number of text encodings specified by the destinationEncodings parameter.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that obtains the text encoding specifications for the subencodings the encoding scheme supports.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginGetCountSubTextEncodingsPtr) ( TextEncoding inputEncoding, TextEncoding subEncodings[], ItemCount maxSubEncodings, ItemCount * actualSubEncodings );

    Parameters

    inputEncoding

    A text encoding specification.

    subEncodings

    On return, the array contains the specifications for the subencodings of the inputEncoding parameter.

    maxSubEncodings

    The number of text encoding specifications the subEncodings array can contain.

    actualSubEncodings

    On return, a pointer to number of subencodings in the subEncodings array.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that counts and returns the number of sniffers available in all installed plug-ins.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginGetCountAvailableSniffersPtr) ( TextEncoding * availableEncodings, ItemCount maxAvailableEncodings, ItemCount * actualAvailableEncodings );

    Parameters

    availableEncodings

    On return, a pointer to the currently available sniffer text encoding specifications.

    maxAvailableEncodings

    The number of text encoding specifications the availableEncodings array can contain.

    actualAvailableEncodings

    On the return, the number of text encoding specifications the availableEncodings array actually contains.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that obtains the available web text encodings.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginGetCountWebEncodingsPtr) ( TextEncoding * availableEncodings, ItemCount maxAvailableEncodings, ItemCount * actualAvailableEncodings );

    Parameters

    availableEncodings

    On return, points to the currently supported text encodings available for the web.

    maxAvailableEncodings

    The number of text encodings specifications that availableEncodings can specify.

    actualAvailableEncodings

    On return, the number of text encodings specifications availableEncodings actually contains.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that obtains the text encodings available for email.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginGetCountMailEncodingsPtr) ( TextEncoding * availableEncodings, ItemCount maxAvailableEncodings, ItemCount * actualAvailableEncodings );

    Parameters

    availableEncodings

    On return, a pointer to the text encodings available for email.

    maxAvailableEncodings

    The maximum number of text encodings that can be specified by the availableEncodings parameter.

    actualAvailableEncodings

    On return, the number of text encoding specifications availableEncodings actually contains.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that obtains the Internet text encoding name for a text encoding specification.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginGetTextEncodingInternetNamePtr) ( TextEncoding textEncoding, Str255 encodingName );

    Parameters

    textEncoding

    A text encoding specification.

    encodingName

    On return, the Internet encoding name, in 7-bit US ASCII. If there are several Internet encoding names for the same text encoding, the encodingName parameter contains the preferred name.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a pointer to a function that obtains the text encoding for an Internet text encoding name.

    Declaration

    Objective-C

    typedef OSStatus (*TECPluginGetTextEncodingFromInternetNamePtr) ( TextEncoding * textEncoding, ConstStr255Param encodingName );

    Parameters

    textEncoding

    On return, a pointer to a structure that contains a text encoding specification for the text encoding name specified by the encodingName parameter.

    encodingName

    An Internet encoding name, in 7-bit US ASCII.

    Return Value

    A result code. See TEC Manager Result Codes.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

Data Types

  • Defines a constant script code run pointer.

    Declaration

    Objective-C

    typedef const ScriptCodeRun * ConstScriptCodeRunPtr;

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a constant text encoding run pointer.

    Declaration

    Objective-C

    typedef const TextEncodingRun * ConstTextEncodingRunPtr;

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a constant text pointer.

    Declaration

    Objective-C

    typedef const UInt8 * ConstTextPtr;

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a constant text to Unicode converter object.

    Declaration

    Objective-C

    typedef TextToUnicodeInfo ConstTextToUnicodeInfo;

    Discussion

    The TruncateForTextToUnicode function requires a Unicode converter object as a parameter. This function does not modify the contents of the private structure to which the Unicode converter object refers, so it uses the constant Unicode converter object defined by the ConstTextToUnicodeInfo data type.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a constant Unicode character array pointer.

    Declaration

    Objective-C

    typedef const UniChar * ConstUniCharArrayPtr;

    Discussion

    You specify a constant Unicode character array pointer for Unicode strings used within the scope of a function whose contents are not modified by that function.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a constant Unicode mapping pointer.

    Declaration

    Objective-C

    typedef const UnicodeMapping * ConstUnicodeMappingPtr;

    Discussion

    Many Unicode Converter functions take a pointer to a Unicode mapping structure as a parameter. For functions that do not modify the Unicode mapping contents, the Unicode Converter provides a constant pointer to a Unicode mapping structure defined by the ConstUnicodeMappingPtr data type.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a constant Unicode to text converter object.

    Declaration

    Objective-C

    typedef UnicodeToTextInfo ConstUnicodeToTextInfo;

    Discussion

    The TruncateForUnicodeToText function requires a Unicode converter object as a parameter. This function does not modify the contents of the private structure to which the Unicode converter object refers, so it uses the constant Unicode converter object defined by the ConstUnicodeToTextInfo data type.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Contains script code information for a text run.

    Declaration

    Objective-C

    struct ScriptCodeRun { ByteOffset offset; ScriptCode script; }; typedef struct ScriptCodeRun ScriptCodeRun; typedef ScriptCodeRun * ScriptCodeRunPtr;

    Fields

    offset

    The beginning character position of a text run and its script code in the converted text.

    script

    The script code for the text that begins at the position specified.

    Discussion

    To return the result of a multiple encoding conversion, the ConvertFromUnicodeToScriptCodeRun function uses a script code run structure.

    The script code run structure uses an extended script code with values in the range 0–254, which are the text encoding base equivalents to Mac OS encodings. Values 0–32 correspond directly to traditional script codes. This allows a script code run to distinguish Icelandic, Turkish, Symbol, Zapf Dingbats, and so on.

    Availability

    Available in OS X v10.0 and later.

  • Contains buffers for text and text encoding runs.

    Declaration

    Objective-C

    struct TECBufferContextRec { TextPtr textInputBuffer; TextPtr textInputBufferEnd; TextPtr textOutputBuffer; TextPtr textOutputBufferEnd; TextEncodingRunPtr encodingInputBuffer; TextEncodingRunPtr encodingInputBufferEnd; TextEncodingRunPtr encodingOutputBuffer; TextEncodingRunPtr encodingOutputBufferEnd; }; typedef struct TECBufferContextRec TECBufferContextRec;

    Discussion

    This structure is used in the TECConverterContextRec data structure that is used for a TEC plug-in.

    Availability

    Available in OS X v10.0 and later.

  • Contains text encoding conversion information.

    Declaration

    Objective-C

    struct TECConversionInfo { TextEncoding sourceEncoding; TextEncoding destinationEncoding; UInt16 reserved1; UInt16 reserved2; }; typedef struct TECConversionInfo TECConversionInfo;

    Fields

    sourceEncoding

    The text encoding specification for the source text.

    destinationEncoding

    The text encoding specification for the destination text.

    reserved1

    Reserved.

    reserved2

    Reserved.

    Discussion

    When you call the function TECGetDirectTextEncodingConversions, you pass an array of text encoding conversion information structures. The function fills these structures with information about each type of supported conversion.

    Availability

    Available in OS X v10.0 and later.

  • Contains converter information used by a Text Encoding Converter plug-in.

    Declaration

    Objective-C

    struct TECConverterContextRec { Ptr pluginRec; TextEncoding sourceEncoding; TextEncoding destEncoding; UInt32 reserved1; UInt32 reserved2; TECBufferContextRec bufferContext; UInt32 contextRefCon; ProcPtr conversionProc; ProcPtr flushProc; ProcPtr clearContextInfoProc; UInt32 options1; UInt32 options2; TECPluginStateRec pluginState; }; typedef struct TECConverterContextRec TECConverterContextRec;

    Fields

    pluginRec
    sourceEncoding

    The text encoding specification for the source text.

    destEncoding

    The text encoding specification for the destination text.

    reserved1

    Reserved.

    reserved2

    Reserved.

    bufferContext
    contextRefCon

    A 32-bit value containing or referring to plug-in-specific data.

    conversionProc

    A pointer to a callback for your conversion procedure.

    flushProc

    A pointer to a callback for your reset procedure.

    clearContextInfoProc

    A pointer to a callback for our clear procedure.

    options1

    A 32-bit value that specfies options needed by your plug-in.

    options2

    A 32-bit value that specfies options needed by your plug-in.

    pluginState

    Availability

    Available in OS X v10.0 and later.

  • Contains information about the Unicode Converter, the Text Encoding Converter, and Basic Text Types.

    Declaration

    Objective-C

    struct TECInfo { UInt16 format; UInt16 tecVersion; UInt32 tecTextConverterFeatures; UInt32 tecUnicodeConverterFeatures; UInt32 tecTextCommonFeatures; Str31 tecTextEncodingsFolderName; Str31 tecExtensionFileName; UInt16 tecLowestTEFileVersion; UInt16 tecHighestTEFileVersion; }; typedef struct TECInfo TECInfo; typedef TECInfo * TECInfoPtr;

    Fields

    format

    The current format of the returned structure. The format of the structure is indicated by the kTECInfoCurrentFormat constant. Any future changes to the format will always be backwardly compatible; any new fields will be added to the end of the structure.

    tecVersion

    The current version of the Text Encoding Conversion Manager extension in BCD (binary coded decimal), with the first byte indicating the major version; for example, 0x0121 for 1.2.1.

    tecTextConverterFeatures

    New features or bug fixes in the Text Encoding Converter. No bits are currently defined.

    tecUnicodeConverterFeatures

    Bit flags indicating new features or bug fixes in the Unicode Converter. See Unicode Converter Flags for the currently defined bit flags.

    tecTextCommonFeatures

    Bit flags indicating new features or bug fixes in Basic Text Types (the Text Common static library). No bits are currently defined.

    tecTextEncodingsFolderName

    A Pascal string with the (possibly localized) name of the Text Encodings folder.

    tecExtensionFileName

    A Pascal string with the (possibly localized) name of the Text Encoding Conversion Manager extension file.

    tecLowestTEFileVersion
    tecHighestTEFileVersion

    Discussion

    The converter information structure is used by the function TECGetInfo to hold returned information about the Unicode Converter, the Text Encoding Converter, and Basic Text Types.

    Availability

    Available in OS X v10.0 and later.

  • Defines an opaque reference to a converter object.

    Declaration

    Objective-C

    typedef struct OpaqueTECObjectRef * TECObjectRef;

    Discussion

    When making a text conversion, the Text Encoding Converter requires a reference to a converter object that indicates how to accomplish the conversion. Functions, such as TECCreateConverter, that create a converter object return this reference, which you can then pass to other functions when converting text. A converter object reference is defined by the TECObjectRef data type.

    The structure of the OpaqueTECObjectRef data type is private, and a converter object is not accessible directly.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Contains version and signature information and pointers to the callback functions used by a text encoding converter plug-in.

    Declaration

    Objective-C

    struct TECPluginDispatchTable { TECPluginVersion version; TECPluginVersion compatibleVersion; TECPluginSignature PluginID; TECPluginNewEncodingConverterPtr PluginNewEncodingConverter; TECPluginClearContextInfoPtr PluginClearContextInfo; TECPluginConvertTextEncodingPtr PluginConvertTextEncoding; TECPluginFlushConversionPtr PluginFlushConversion; TECPluginDisposeEncodingConverterPtr PluginDisposeEncodingConverter; TECPluginNewEncodingSnifferPtr PluginNewEncodingSniffer; TECPluginClearSnifferContextInfoPtr PluginClearSnifferContextInfo; TECPluginSniffTextEncodingPtr PluginSniffTextEncoding; TECPluginDisposeEncodingSnifferPtr PluginDisposeEncodingSniffer; TECPluginGetCountAvailableTextEncodingsPtr PluginGetCountAvailableTextEncodings; TECPluginGetCountAvailableTextEncodingPairsPtr PluginGetCountAvailableTextEncodingPairs; TECPluginGetCountDestinationTextEncodingsPtr PluginGetCountDestinationTextEncodings; TECPluginGetCountSubTextEncodingsPtr PluginGetCountSubTextEncodings; TECPluginGetCountAvailableSniffersPtr PluginGetCountAvailableSniffers; TECPluginGetCountWebEncodingsPtr PluginGetCountWebTextEncodings; TECPluginGetCountMailEncodingsPtr PluginGetCountMailTextEncodings; TECPluginGetTextEncodingInternetNamePtr PluginGetTextEncodingInternetName; TECPluginGetTextEncodingFromInternetNamePtr PluginGetTextEncodingFromInternetName; }; typedef struct TECPluginDispatchTable TECPluginDispatchTable;

    Availability

    Available in OS X v10.0 and later.

  • Defines a data type for a Text Encoding Converter plug-in signature.

    Declaration

    Objective-C

    typedef OSType TECPluginSig;

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a data type for a Text Encoding Converter plug-in signature.

    Declaration

    Objective-C

    typedef OSType TECPluginSignature;

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Contains state information for a Text Encoding Converter plug-in.

    Declaration

    Objective-C

    struct TECPluginStateRec { UInt8 state1; UInt8 state2; UInt8 state3; UInt8 state4; UInt32 longState1; UInt32 longState2; UInt32 longState3; UInt32 longState4; }; typedef struct TECPluginStateRec TECPluginStateRec;

    Availability

    Available in OS X v10.0 and later.

  • Defines a data type for Text Encoding Converter plug-in version.

    Declaration

    Objective-C

    typedef UInt32 TECPluginVersion;

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Contains infomation used by a sniffer object.

    Declaration

    Objective-C

    struct TECSnifferContextRec { Ptr pluginRec; TextEncoding encoding; ItemCount maxErrors; ItemCount maxFeatures; TextPtr textInputBuffer; TextPtr textInputBufferEnd; ItemCount numFeatures; ItemCount numErrors; UInt32 contextRefCon; ProcPtr sniffProc; ProcPtr clearContextInfoProc; TECPluginStateRec pluginState; }; typedef struct TECSnifferContextRec TECSnifferContextRec;

    Availability

    Available in OS X v10.0 and later.

  • Defines a reference to an opaque sniffer object.

    Declaration

    Objective-C

    typedef struct OpaqueTECSnifferObjectRef * TECSnifferObjectRef;

    Discussion

    When analyzing text for possible encodings, the Text Encoding Converter requires a reference to a sniffer object that specifies what types of encodings can be detected. You receive this reference when calling the function TECCreateSniffer. A sniffer object reference is defined by the TECSnifferObjectRef data type. The structure of the OpaqueTECObjectRef data type is private, and a sniffer object is not accessible directly.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a data type for a text encoding value.

    Declaration

    Objective-C

    typedef UInt32 TextEncoding;

    Discussion

    A TextEncoding value is specified by a text encoding base, a text encoding variant, and a text encoding format. You can obtain a TextEncoding value by calling the function CreateTextEncoding. When you call this function, you can provide the TextEncodingBase, TextEncodingVariant, and TextEncodingFormat data types.

    A TextEncoding value is used, for example, to identify the encoding of text passed to a text converter. Two TextEncoding values are needed—for source and destination encoding—when calling the Text Encoding Converter or the Unicode Converter to convert text.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Contains text encoding information for a text run.

    Declaration

    Objective-C

    struct TextEncodingRun { ByteOffset offset; TextEncoding textEncoding; }; typedef struct TextEncodingRun TextEncodingRun; typedef TextEncodingRun * TextEncodingRunPtr;

    Fields

    offset

    The beginning character position of a run of text in the converted text string.

    textEncoding

    The encoding of the text run that begins at the position specified.

    Discussion

    It is not always possible to convert text expressed in Unicode to another single encoding because no other single encoding encompasses the Unicode character encoding range. To adjust for this, you can create a Unicode mapping structure array that specifies the target encodings the Unicode text should be converted to when multiple encodings must be used.

    If the kUnicodeTextRunMask flag is set, ConvertFromUnicodeToTextRun and ConvertFromUnicodeToScriptCodeRun may convert Unicode text to a string of text containing multiple text encoding runs. Each run contains text expressed in a different encoding from that of the preceding or following text segment. For each text encoding run in the string, a TextEncodingRun structure indicates the beginning offset and the text encoding for that run.

    Functions that convert text from Unicode to a text run return the converted text in an array of text encoding run structures. A text encoding run structure is defined by the TextEncodingRun data type.

    Availability

    Available in OS X v10.0 and later.

  • Defines a data type for a text encoding variant.

    Declaration

    Objective-C

    typedef UInt32 TextEncodingVariant;

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines reference to an opaque Unicode converter object.

    Declaration

    Objective-C

    typedef struct OpaqueTextToUnicodeInfo * TextToUnicodeInfo;

    Discussion

    A Unicode converter object is a private object containing mapping and state information. Many of the Unicode Converter functions that perform conversions require a Unicode converter object containing information used for the conversion process. There are three types of Unicode converter objects, all serving the same purpose but used for different types of conversions. You use the TextToUnicodeInfo type, described here, for converting from non-Unicode text to Unicode text.

    Because your application cannot directly create or modify the contents of the private Unicode converter object, the Unicode Converter provides functions to create and dispose of it. To create a Unicode converter object for converting from non-Unicode text to Unicode text, your application must first call either the function CreateTextToUnicodeInfo or the function CreateTextToUnicodeInfoByEncoding to provide the mapping information required for the conversion. You can then pass this object to the function ConvertFromTextToUnicode or ConvertFromPStringToUnicode to identify the information to be used in performing the actual conversion. After you have finished using the object, you should release the memory allocated for it by calling the function DisposeTextToUnicodeInfo. The TextToUnicodeInfo data type defines the Unicode converter object.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Represents the boundary between two characters.

    Declaration

    Objective-C

    typedef UInt32 UniCharArrayOffset;

    Discussion

    A UniCharArrayOffset represents the boundary between two characters. For example, the first character in a buffer lies between offsets 0 and 1. So the first character in the buffer can be referred to as either “offset 0, leading” or “offset 1, trailing.” This distinction is useful when you deal with caret positions.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Contains information for mapping to or from Unicode encoding.

    Declaration

    Objective-C

    struct UnicodeMapping { TextEncoding unicodeEncoding; TextEncoding otherEncoding; UnicodeMapVersion mappingVersion; }; typedef struct UnicodeMapping UnicodeMapping; typedef UnicodeMapping * UnicodeMappingPtr;

    Fields

    unicodeEncoding

    A Unicode text encoding specification of type TextEncoding.

    otherEncoding

    A text encoding specification for the text to be converted to or from Unicode.

    mappingVersion

    The version of the Unicode mapping table to be used.

    Discussion

    A Unicode mapping structure contains a complete text encoding specification for a Unicode encoding, a complete non-Unicode text encoding specification giving the encoding for the text to be converted to or from Unicode, and the version of the mapping table to be used for conversion. You use a structure of this type to specify the text encodings to and from which the text string is to be converted. A Unicode mapping structure is defined by the UnicodeMapping data type.

    You can specify a variety of normalization options by setting up the Unicode mapping structure as described in the following.

    To specify normal canonical decomposition according to Unicode 3.2 rules, with no exclusions ("Canonical decomposition 3.2"), set up the UnicodeMapping structure as follows:

    • mapping.unicodeEncoding (in) = Unicode 2.x-3.x, kUnicodeNoSubset, kUnicode16BitFormat
    • mapping.otherEncoding (out) = Unicode 2.x-3.x, kUnicodeCanonicalDecompVariant, kUnicode16BitFormat
    • mapping.mappingVersion = kUnicodeUseLatestMapping

    Examples:

    • u00E0 -> u0061 + u0300
    • u0061 + u0300 -> u0061 + u0300
    • u03AC -> u03B1 + u0301 (3.2 rules)
    • uF900 -> u8C48
    • u00E0 + u0323 -> u0061 + u0323 + u0300 (correct)

    To specify canonical decomposition according to Unicode 3.2 rules, with HFS+ exclusions ("HFS+ decomposition 3.2"), set up the UnicodeMapping structure in one of the following ways. The second method is for compatibility with the old method of using mappingVersion = kUnicodeUseHFSPlusMapping.

    • // Method 1
    • mapping.unicodeEncoding (in) = Unicode 2.x-3.x, kUnicodeNoSubset, kUnicode16BitFormat
    • mapping.otherEncoding (out) = Unicode 2.x-3.x, kUnicodeHFSPlusDecompVariant, kUnicode16BitFormat
    • mapping.mappingVersion = kUnicodeUseLatestMapping
    • // Method 2
    • mapping.unicodeEncoding (in) = Unicode 2.x-3.x, kUnicode16BitFormat, kUnicode16BitFormat
    • mapping.otherEncoding (out) = Unicode 2.x, kUnicodeCanonicalDecompVariant, kUnicode16BitFormat
    • mapping.mappingVersion = kUnicodeUseHFSPlusMapping

    Examples:

    • u00E0 -> u0061 + u0300
    • u0061 + u0300 -> u0061 + u0300
    • u03AC -> u03B1 + u0301 (3.2 rules)
    • uF900 -> uF900 (decomposition excluded for HFS+)
    • u00E0 + u0323 -> u0061 + u0323 + u0300 (correct)

    To specify normal canonical composition according to Unicode 3.2 rules, set up the UnicodeMapping structure as follows:

    • mapping.unicodeEncoding (in) = Unicode 2.x-3.x, kUnicodeNoSubset, kUnicode16BitFormat
    • mapping.otherEncoding (out) = Unicode 2.x-3.x, kUnicodeCanonicalCompVariant, kUnicode16BitFormat
    • mapping.mappingVersion = kUnicodeUseLatestMapping

    Examples:

    • u00E0 -> u00E0
    • u0061 + u0300 -> u00E0
    • u03AC -> u03AC
    • uF900 -> u8C48
    • u00E0 + u0323 -> u1EA1 u0300 (correct)

    To specify canonical composition according to Unicode 3.2 rules, but using the HFS+ decomposition exclusions, set up the UnicodeMapping structure as follows. This is the form to use if you want to obtain a composed form that dervide from the decomposed form used for HFS+ filenames.

    • mapping.unicodeEncoding (in) = Unicode 2.x-3.x, kUnicodeNoSubset, kUnicode16BitFormat
    • mapping.otherEncoding (out) = Unicode 2.x-3.x, kUnicodeHFSPlusCompVariant, kUnicode16BitFormat
    • mapping.mappingVersion = kUnicodeUseLatestMapping

    Examples:

    • u00E0 -> u00E0
    • u0061 + u0300 -> u00E0
    • u03AC -> u03AC
    • uF900 -> uF900
    • u00E0 + u0323 -> u1EA1 u0300 (correct)

    Availability

    Available in OS X v10.0 and later.

  • Defines a universal procedure pointer to a Unicode-to-text-fallback callback function.

    Declaration

    Objective-C

    typedef UnicodeToTextFallbackProcPtr UnicodeToTextFallbackUPP;

    Discussion

    For more information, see the description of the UnicodeToTextFallbackProcPtr callback function.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a reference to an opaque Unicode to text converter object.

    Declaration

    Objective-C

    typedef struct OpaqueUnicodeToTextInfo * UnicodeToTextInfo;

    Discussion

    Many of the Unicode Converter functions that perform conversions require a Unicode converter object containing information used for the conversion process. There are three types of Unicode converter objects used for different types of conversions. You use the UnicodeToTextInfo type, described here, for converting from Unicode to text.

    Because your application cannot directly create or modify the contents of the private Unicode converter object, the Unicode Converter provides functions to create and dispose of it. To create a Unicode converter object for converting from Unicode to text, your application must first call either the function CreateUnicodeToTextInfo or CreateUnicodeToTextInfoByEncoding.

    You can then pass this object to the function ConvertFromUnicodeToText or ConvertFromUnicodeToPString to identify the information used to perform the actual conversion. After you have finished using the object, you should release the memory allocated for it by calling the function DisposeUnicodeToTextInfo.

    A Unicode converter object for this purpose is defined by the UnicodeToTextInfo data type.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Defines a reference to an opaque Unicode to text run information converter object.

    Declaration

    Objective-C

    typedef struct OpaqueUnicodeToTextRunInfo * UnicodeToTextRunInfo;

    Discussion

    Many of the Unicode Converter functions that perform conversions require a Unicode converter object containing information used for the conversion process. There are three types of Unicode converter objects used for different types of conversions. You use the UnicodeToTextRunInfo type, described here, for converting from Unicode to multiple encodings.

    Because your application cannot directly create or modify the contents of the private Unicode converter object, the Unicode Converter provides functions to create and dispose of it. You can use any of three functions to create a Unicode converter object for converting from Unicode to multiple encodings. You can use CreateUnicodeToTextRunInfo, CreateUnicodeToTextRunInfoByEncoding, or CreateUnicodeToTextRunInfoByScriptCode.

    You can then pass this object to the function ConvertFromUnicodeToTextRun or ConvertFromUnicodeToScriptCodeRun to identify the information used to perform the actual conversion. After you have finished using the object, you should release the memory allocated for it by calling the function DisposeUnicodeToTextRunInfo.

    A Unicode converter object for this purpose is defined by the UnicodeToTextRunInfo data type.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

Constants

Feature Selectors

  • Specify how to perform conversion of text from one encoding to another.

    Declaration

    Objective-C

    enum { kUnicodeUseFallbacksBit = 0, kUnicodeKeepInfoBit = 1, kUnicodeDirectionalityBits = 2, kUnicodeVerticalFormBit = 4, kUnicodeLooseMappingsBit = 5, kUnicodeStringUnterminatedBit = 6, kUnicodeTextRunBit = 7, kUnicodeKeepSameEncodingBit = 8, kUnicodeForceASCIIRangeBit = 9, kUnicodeNoHalfwidthCharsBit = 10, kUnicodeTextRunHeuristicsBit = 11, kUnicodeMapLineFeedToReturnBit = 12 };

    Constants

    • kUnicodeUseFallbacksBit

      kUnicodeUseFallbacksBit

      Enables use of fallback mappings.

      Available in OS X v10.0 and later.

    • kUnicodeKeepInfoBit

      kUnicodeKeepInfoBit

      Sets the keep-information control flag.

      Available in OS X v10.0 and later.

    • kUnicodeDirectionalityBits

      kUnicodeDirectionalityBits

      Sets directionality.

      Available in OS X v10.0 and later.

    • kUnicodeVerticalFormBit

      kUnicodeVerticalFormBit

      Sets the vertical form control flag.

      Available in OS X v10.0 and later.

    • kUnicodeLooseMappingsBit

      kUnicodeLooseMappingsBit

      Enables use of the loose-mapping portion of a character mapping table.

      Available in OS X v10.0 and later.

    • kUnicodeStringUnterminatedBit

      kUnicodeStringUnterminatedBit

      Sets the string-unterminated control flag.

      Available in OS X v10.0 and later.

    • kUnicodeTextRunBit

      kUnicodeTextRunBit

      Sets the text-run control flag.

      Available in OS X v10.0 and later.

    • kUnicodeKeepSameEncodingBit

      kUnicodeKeepSameEncodingBit

      Sets the keep-same-encoding control flag.

      Available in OS X v10.0 and later.

    • kUnicodeForceASCIIRangeBit

      kUnicodeForceASCIIRangeBit

      Sets the force ASCII range control flag.

      Available in OS X v10.0 and later.

    • kUnicodeNoHalfwidthCharsBit

      kUnicodeNoHalfwidthCharsBit

      Available in OS X v10.0 and later.

    • kUnicodeTextRunHeuristicsBit

      kUnicodeTextRunHeuristicsBit

      Available in OS X v10.0 and later.

    • kUnicodeMapLineFeedToReturnBit

      kUnicodeMapLineFeedToReturnBit

      Available in OS X v10.2 and later.

  • Set or text for conversion flags.

    Declaration

    Objective-C

    enum { kUnicodeUseFallbacksMask = 1L << kUnicodeUseFallbacksBit, kUnicodeKeepInfoMask = 1L << kUnicodeKeepInfoBit, kUnicodeDirectionalityMask = 3L << kUnicodeDirectionalityBits, kUnicodeVerticalFormMask = 1L << kUnicodeVerticalFormBit, kUnicodeLooseMappingsMask = 1L << kUnicodeLooseMappingsBit, kUnicodeStringUnterminatedMask = 1L << kUnicodeStringUnterminatedBit, kUnicodeTextRunMask = 1L << kUnicodeTextRunBit, kUnicodeKeepSameEncodingMask = 1L << kUnicodeKeepSameEncodingBit, kUnicodeForceASCIIRangeMask = 1L << kUnicodeForceASCIIRangeBit, kUnicodeNoHalfwidthCharsMask = 1L << kUnicodeNoHalfwidthCharsBit, kUnicodeTextRunHeuristicsMask = 1L << kUnicodeTextRunHeuristicsBit, kUnicodeMapLineFeedToReturnMask = 1L << kUnicodeMapLineFeedToReturnBit };

    Constants

    • kUnicodeUseFallbacksMask

      kUnicodeUseFallbacksMask

      A mask for setting the Unicode-use-fallbacks conversion flag. The Unicode Converter uses fallback mappings when it encounters a source text element for which there is no equivalent destination encoding. Fallback mappings are mappings that do not preserve the meaning or identity of the source character but represent a useful approximation of it. See the function SetFallbackUnicodeToText.

      Available in OS X v10.0 and later.

    • kUnicodeKeepInfoMask

      kUnicodeKeepInfoMask

      A mask for setting the keep-information control flag which governs whether the Unicode Converter keeps the current state stored in the Unicode converter object before converting the text string.

      If you clear this flag, the converter will initialize the Unicode converter object before converting the text string and assume that subsequent calls do not need any context, such as direction state for the current call.

      If you set the flag, the converter uses the current state. This is useful if your application must convert a stream of text in pieces that are not block delimited. You should set this flag for each call in a series of calls on the same text stream.

      Available in OS X v10.0 and later.

    • kUnicodeDirectionalityMask

      kUnicodeDirectionalityMask

      A mask for setting the directionality control flag

      Available in OS X v10.0 and later.

    • kUnicodeVerticalFormMask

      kUnicodeVerticalFormMask

      A mask for setting the vertical form control flag. The vertical form control flag tells the Unicode Converter how to map text elements for which there are both abstract and vertical presentation forms in the destination encoding.

      If set, the converter maps these text elements to their vertical forms, if they are available.

      Available in OS X v10.0 and later.

    • kUnicodeLooseMappingsMask

      kUnicodeLooseMappingsMask

      A mask that determines whether the Unicode Converter should use the loose-mapping portion of a mapping table for character mapping if the strict mapping portion of the table does not include a destination encoding equivalent for the source text element.

      If you clear this flag, the converter will use only the strict equivalence portion.

      If set this flag and a conversion for the source text element does not exist in the strict equivalence portion of the mapping table, then the converter uses the loose mapping section.

      Available in OS X v10.0 and later.

    • kUnicodeStringUnterminatedMask

      kUnicodeStringUnterminatedMask

      A mask for setting the string-unterminated control flag. Determines how the Unicode Converter handles text-element boundaries and direction resolution at the end of an input buffer.

      If you clear this bit, the converter treats the end of the buffer as the end of text.

      If you set this bit, the converter assumes that the next call you make using the current context will supply another buffer of text that should be treated as a continuation of the current text. For example, if the last character in the input buffer is 'A', ConvertFromUnicodeToText stops conversion at the 'A' and returns kTECIncompleteElementErr, because the next buffer could begin with a combining diacritical mark that should be treated as part of the same text element. If the last character in the input buffer is a control character, ConvertFromUnicodeToText does not return kTECIncompleteElementErr because a control character could not be part of a multiple character text element.

      In attempting to analyze the text direction, when the Unicode Converter reaches the end of the current input buffer and the direction of the current text element is still unresolved, if you clear this flag, the converter treats the end of the buffer as a block separator for direction resolution. If you set this flag, it sets the direction as undetermined

      Available in OS X v10.0 and later.

    • kUnicodeTextRunMask

      kUnicodeTextRunMask

      A mask for setting the text-run control flag which determines how the Unicode Converter converts Unicode text to a non-Unicode encoding when more than one possible destination encoding exists.

      If you clear this flag, the function ConvertFromUnicodeToTextRun or ConvertFromUnicodeToScriptCodeRun attempts to convert the Unicode text to the single encoding from the list of encodings in the Unicode converter object that produces the best result, that is, that provides for the greatest amount of source text conversion.

      If you set this flag, ConvertFromUnicodeToTextRun or ConvertFromUnicodeToScriptCodeRun, which are the only functions to which it applies, may generate a destination string that combines text in any of the encodings specified by the Unicode converter object.

      Available in OS X v10.0 and later.

    • kUnicodeKeepSameEncodingMask

      kUnicodeKeepSameEncodingMask

      A mask for setting the keep-same-encoding control flag. Determines how the Unicode Converter treats the conversion of Unicode text following a text element that could not be converted to the first destination encoding when multiple destination encodings exist. This control flag applies only if the kUnicodeTextRunMask control flag is set.

      If you set this flag, the function ConvertFromUnicodeToTextRun attempts to minimize encoding changes in the conversion of the source text string; that is, once it is forced to make an encoding change, it attempts to use that encoding as the conversion destination for as long as possible.

      If you clear this flag, ConvertFromUnicodeToTextRun attempts to keep most of the converted string in one encoding, switching to other encodings only when necessary.

      Available in OS X v10.0 and later.

    • kUnicodeForceASCIIRangeMask

      kUnicodeForceASCIIRangeMask

      A mask for setting the force ASCII range control flag. If an encoding normally treats 1-byte code points 0x000x7F as an ISO 646 national variant that is different from ASCII, setting this flag forces 0x000x7F to be treated as ASCII. For example, Japanese encodings such as Shift-JIS generally treat 0x000x7F as JIS Roman, with 0x5C as YEN SIGN instead of REVERSE SOLIDUS, but when converting a DOS file path you may want to set this flag so that 0x5C is mapped as REVERSE SOLIDUS.

      Available in OS X v10.0 and later.

    • kUnicodeNoHalfwidthCharsMask

      kUnicodeNoHalfwidthCharsMask

      Sets the no halfwidth characters control flag.

      Available in OS X v10.0 and later.

    • kUnicodeTextRunHeuristicsMask

      kUnicodeTextRunHeuristicsMask

      Available in OS X v10.0 and later.

    • kUnicodeMapLineFeedToReturnMask

      kUnicodeMapLineFeedToReturnMask

      Specifies mapping o the LF (LineFeed) character used in Unix to represent new lines to the CR (CarriageReturn) used in Mac encodings. This option has an effect only when used with the constant kUnicodeLooseMappingsMask. You can pass both constants as iControlFlags parameters to the functions ConvertFromUnicodeToText, ConvertFromUnicodeToTextRun, and ConvertFromUnicodeToScriptCodeRun.

      Available in OS X v10.2 and later.

    Discussion

    You use these constants to specify how the conversion of text from one encoding to another is performed. You use these masks as the controlFlags parameter in the ConvertFromTextToUnicode, ConvertFromUnicodeToText, ConvertFromUnicodeToScriptCodeRun, ConvertFromUnicodeToTextRun, and TruncateForUnicodeToText functions. A different subset of control masks applies to each of these functions. Using the bitmask constants, you can perform a bitwise OR operation to set the pertinent flags for a particular function’s parameters. For example, when you call a function, you might pass the following controlFlags parameter setting:

    controlflags=kUnicodeUseFallbacksMask | kUnicodeLooseMappingsMask;

  • Specify a text direction.

    Declaration

    Objective-C

    enum { kUnicodeDefaultDirection = 0, kUnicodeLeftToRight = 1, kUnicodeRightToLeft = 2 };

    Constants

    • kUnicodeDefaultDirection

      kUnicodeDefaultDirection

      Use the default direction.

      Available in OS X v10.0 and later.

    • kUnicodeLeftToRight

      kUnicodeLeftToRight

      Indicates left to right direction.

      Available in OS X v10.0 and later.

    • kUnicodeRightToLeft

      kUnicodeRightToLeft

      Indicates right to left direction.

      Available in OS X v10.0 and later.

  • Set or text for directionality bits.

    Declaration

    Objective-C

    enum { kUnicodeDefaultDirectionMask = kUnicodeDefaultDirection << kUnicodeDirectionalityBits, kUnicodeLeftToRightMask = kUnicodeLeftToRight << kUnicodeDirectionalityBits, kUnicodeRightToLeftMask = kUnicodeRightToLeft << kUnicodeDirectionalityBits };

    Constants

    • kUnicodeDefaultDirectionMask

      kUnicodeDefaultDirectionMask

      A mask for setting the global, or base, line direction for the text being converted. The value kUnicodeDefaultDirectionMask tells the converter to use the value of the first strong direction character in the string. This determines which direction the converter should use for resolution of neutral coded characters, such as spaces that occur between sets of coded characters having different directions—for example, between Latin and Arabic characters—rendering ambiguous the direction of the space character.

      Available in OS X v10.0 and later.

    • kUnicodeLeftToRightMask

      kUnicodeLeftToRightMask

      A mask for setting the global, or base, line direction for the text being converted. The value kUnicodeLeftToRightMask tells the converter that the base paragraph direction is left to right. This determines which direction the converter should use for resolution of neutral coded characters, such as spaces that occur between sets of coded characters having different directions—for example, between Latin and Arabic characters—rendering ambiguous the direction of the space character.

      Available in OS X v10.0 and later.

    • kUnicodeRightToLeftMask

      kUnicodeRightToLeftMask

      The value kUnicodeRightToLeftMask tells the converter that the base paragraph direction is right to left. This determines which direction the converter should use for resolution of neutral coded characters, such as spaces that occur between sets of coded characters having different directions—for example, between Latin and Arabic characters—rendering ambiguous the direction of the space character.

      Available in OS X v10.0 and later.

  • Specify features for bug fixes in the Unicode Converter.

    Declaration

    Objective-C

    enum { kTECKeepInfoFixBit = 0, kTECFallbackTextLengthFixBit = 1, kTECTextRunBitClearFixBit = 2, kTECTextToUnicodeScanFixBit = 3, kTECAddForceASCIIChangesBit = 4, kTECPreferredEncodingFixBit = 5, kTECAddTextRunHeuristicsBit = 6, kTECAddFallbackInterruptBit = 7 };

    Constants

    • kTECKeepInfoFixBit

      kTECKeepInfoFixBit

      This is set if the Unicode Converter has a bug fix to stop ignoring certain control flags

      Available in OS X v10.0 and later.

    • kTECFallbackTextLengthFixBit

      kTECFallbackTextLengthFixBit

      This is set if the Unicode Converter has a bug fix to use the source length (srcConvLen) and destination length (destConvLen) returned by a caller-supplied fall-back handler for any status it returns except kTECUnmappableElementErr. Previously it honored only these values if noErr was returned.

      Available in OS X v10.0 and later.

    • kTECTextRunBitClearFixBit

      kTECTextRunBitClearFixBit

      This is set if ConvertFromUnicodeToTextRun and ConvertFromUnicodeToScriptCodeRun function correctly if the kUnicodeTextRunBit is clear.

      Available in OS X v10.0 and later.

    • kTECTextToUnicodeScanFixBit

      kTECTextToUnicodeScanFixBit

      This is set if ConvertFromTextToUnicode is enhanced so mappings can depend on context and saved state. The consequences of this are (1) malformed input results in kTextMalformedInputErr; (2) ConvertFromTextToUnicode accepts the control flags kUnicodeLooseMappingsMask, kUnicodeKeepInfoMask, and kUnicodeStringUnterminatedMask; (3) elimination of redundant direction overrides when converting Mac OS Arabic and Hebrew to Unicode; and (4) improved mapping of 0x30-0x39 digits in Mac OS Arabic when loose mappings are used.

      Available in OS X v10.0 and later.

    • kTECAddForceASCIIChangesBit

      kTECAddForceASCIIChangesBit

      This is set if the new control flag bits kUnicodeForceASCIIRangeBit and kUnicodeNoHalfwidthCharsBit are supported for use with the functions ConvertFromTextToUnicode, ConvertFromUnicodeToText, and so forth.

      Available in OS X v10.0 and later.

    • kTECPreferredEncodingFixBit

      kTECPreferredEncodingFixBit

      This is set to indicate that if a preferred encoding is specified for CreateUnicodeToTextRunInfo and related functions, they handle it correctly even if it does not match the system script.

      Available in OS X v10.0 and later.

    • kTECAddTextRunHeuristicsBit

      kTECAddTextRunHeuristicsBit

      Available in OS X v10.0 and later.

    • kTECAddFallbackInterruptBit

      kTECAddFallbackInterruptBit

      Available in OS X v10.0 and later.

    Discussion

    These are bit flags to indicate new features for bug fixes in the Unicode Converter. They are used by the TECInfo data type.

  • Set or test for Unicode converter flags.

    Declaration

    Objective-C

    enum { kTECKeepInfoFixMask = 1L << kTECKeepInfoFixBit, kTECFallbackTextLengthFixMask = 1L << kTECFallbackTextLengthFixBit, kTECTextRunBitClearFixMask = 1L << kTECTextRunBitClearFixBit, kTECTextToUnicodeScanFixMask = 1L << kTECTextToUnicodeScanFixBit, kTECAddForceASCIIChangesMask = 1L << kTECAddForceASCIIChangesBit, kTECPreferredEncodingFixMask = 1L << kTECPreferredEncodingFixBit, kTECAddTextRunHeuristicsMask = 1L << kTECAddTextRunHeuristicsBit, kTECAddFallbackInterruptMask = 1L << kTECAddFallbackInterruptBit };

  • Specifies options for setting fallback sequencing.

    Declaration

    Objective-C

    enum { kUnicodeFallbackSequencingBits = 0 };

  • Set or text for Unicode sequencing flag.

    Declaration

    Objective-C

    enum { kUnicodeFallbackSequencingMask = 3L << kUnicodeFallbackSequencingBits, kUnicodeFallbackInterruptSafeMask = 1L << 2 };

    Constants

    • kUnicodeFallbackSequencingMask

      kUnicodeFallbackSequencingMask

      Available in OS X v10.0 and later.

    • kUnicodeFallbackInterruptSafeMask

      kUnicodeFallbackInterruptSafeMask

      Indicate that the caller’s fallback routine doesn’t move memory.

      Available in OS X v10.0 and later.

  • Specify matching criteria for Unicode mappings.

    Declaration

    Objective-C

    enum { kUnicodeMatchUnicodeBaseBit = 0, kUnicodeMatchUnicodeVariantBit = 1, kUnicodeMatchUnicodeFormatBit = 2, kUnicodeMatchOtherBaseBit = 3, kUnicodeMatchOtherVariantBit = 4, kUnicodeMatchOtherFormatBit = 5 };

    Constants

    • kUnicodeMatchUnicodeBaseBit

      kUnicodeMatchUnicodeBaseBit

      Excludes mappings that do not match the text encoding base of the unicodeEncoding field of the structure UnicodeMapping.

      Available in OS X v10.0 and later.

    • kUnicodeMatchUnicodeVariantBit

      kUnicodeMatchUnicodeVariantBit

      Excludes mappings that do not match the text encoding variant of the unicodeEncoding field of the specified Unicode mapping structure.

      Available in OS X v10.0 and later.

    • kUnicodeMatchUnicodeFormatBit

      kUnicodeMatchUnicodeFormatBit

      Excludes mappings that do not match the text encoding format of the unicodeEncoding field of the specified Unicode mapping structure.

      Available in OS X v10.0 and later.

    • kUnicodeMatchOtherBaseBit

      kUnicodeMatchOtherBaseBit

      Excludes mappings that do not match the text encoding base of the otherEncoding field of the structure UnicodeMapping.

      Available in OS X v10.0 and later.

    • kUnicodeMatchOtherVariantBit

      kUnicodeMatchOtherVariantBit

      Excludes mappings that do not match the text encoding variant of the otherEncoding field of the specified Unicode mapping structure.

      Available in OS X v10.0 and later.

    • kUnicodeMatchOtherFormatBit

      kUnicodeMatchOtherFormatBit

      Excludes mappings that do not match the text encoding format of the otherEncoding field of the specified Unicode mapping structure.

      Available in OS X v10.0 and later.

  • Used to set or test for Unicode matching flags.

    Declaration

    Objective-C

    enum { kUnicodeMatchUnicodeBaseMask = 1L << kUnicodeMatchUnicodeBaseBit, kUnicodeMatchUnicodeVariantMask = 1L << kUnicodeMatchUnicodeVariantBit, kUnicodeMatchUnicodeFormatMask = 1L << kUnicodeMatchUnicodeFormatBit, kUnicodeMatchOtherBaseMask = 1L << kUnicodeMatchOtherBaseBit, kUnicodeMatchOtherVariantMask = 1L << kUnicodeMatchOtherVariantBit, kUnicodeMatchOtherFormatMask = 1L << kUnicodeMatchOtherFormatBit };

    Constants

    • kUnicodeMatchUnicodeBaseMask

      kUnicodeMatchUnicodeBaseMask

      If set, excludes mappings that do not match the text encoding base of the unicodeEncoding field of the structure UnicodeMapping. If not set, the function ignores the text encoding base of that field.

      Available in OS X v10.0 and later.

    • kUnicodeMatchUnicodeVariantMask

      kUnicodeMatchUnicodeVariantMask

      If set, excludes mappings that do not match the text encoding variant of the unicodeEncoding field of the specified Unicode mapping structure. If not set, the function ignores the text encoding variant of that field.

      Available in OS X v10.0 and later.

    • kUnicodeMatchUnicodeFormatMask

      kUnicodeMatchUnicodeFormatMask

      If set, excludes mappings that do not match the text encoding format of the unicodeEncoding field of the specified Unicode mapping structure. If not set, the function ignores the text encoding format of that field.

      Available in OS X v10.0 and later.

    • kUnicodeMatchOtherBaseMask

      kUnicodeMatchOtherBaseMask

      If set, excludes mappings that do not match the text encoding base of the otherEncoding field of the structure UnicodeMapping. If not set, the function ignores the text encoding base of that field.

      Available in OS X v10.0 and later.

    • kUnicodeMatchOtherVariantMask

      kUnicodeMatchOtherVariantMask

      If set, excludes mappings that do not match the text encoding variant of the otherEncoding field of the specified Unicode mapping structure. If not set, the function ignores the text encoding variant of that field.

      Available in OS X v10.0 and later.

    • kUnicodeMatchOtherFormatMask

      kUnicodeMatchOtherFormatMask

      If set, excludes mappings that do not match the text encoding format of the otherEncoding field of the specified Unicode mapping structure. If not set, the function ignores the text encoding format of that field.

      Available in OS X v10.0 and later.

  • Specify a fallback handler for the Unicode Converter to use.

    Declaration

    Objective-C

    enum { kUnicodeFallbackDefaultOnly = 0, kUnicodeFallbackCustomOnly = 1, kUnicodeFallbackDefaultFirst = 2, kUnicodeFallbackCustomFirst = 3 };

    Constants

    • kUnicodeFallbackDefaultOnly

      kUnicodeFallbackDefaultOnly

      Use the default fallback handler only.

      Available in OS X v10.0 and later.

    • kUnicodeFallbackCustomOnly

      kUnicodeFallbackCustomOnly

      Use the custom fallback handler only.

      Available in OS X v10.0 and later.

    • kUnicodeFallbackDefaultFirst

      kUnicodeFallbackDefaultFirst

      Use the default fallback handler first, then the custom one.

      Available in OS X v10.0 and later.

    • kUnicodeFallbackCustomFirst

      kUnicodeFallbackCustomFirst

      Use the custom fallback handler first, then the default one.

      Available in OS X v10.0 and later.

    Discussion

    Used to specify which fallback handler the Unicode Converter should use. If you use both the custom and default handlers, you can set the order in which they are called. You use these constants to set the controlFlags parameter of the SetFallbackUnicodeToText and SetFallbackUnicodeToTextRun functions.

Encodings and Variants

  • Specify base text encodings.

    Declaration

    Objective-C

    typedef UInt32 TextEncodingBase; enum { kTextEncodingMacRoman = 0, kTextEncodingMacJapanese = 1, kTextEncodingMacChineseTrad = 2, kTextEncodingMacKorean = 3, kTextEncodingMacArabic = 4, kTextEncodingMacHebrew = 5, kTextEncodingMacGreek = 6, kTextEncodingMacCyrillic = 7, kTextEncodingMacDevanagari = 9, kTextEncodingMacGurmukhi = 10, kTextEncodingMacGujarati = 11, kTextEncodingMacOriya = 12, kTextEncodingMacBengali = 13, kTextEncodingMacTamil = 14, kTextEncodingMacTelugu = 15, kTextEncodingMacKannada = 16, kTextEncodingMacMalayalam = 17, kTextEncodingMacSinhalese = 18, kTextEncodingMacBurmese = 19, kTextEncodingMacKhmer = 20, kTextEncodingMacThai = 21, kTextEncodingMacLaotian = 22, kTextEncodingMacGeorgian = 23, kTextEncodingMacArmenian = 24, kTextEncodingMacChineseSimp = 25, kTextEncodingMacTibetan = 26, kTextEncodingMacMongolian = 27, kTextEncodingMacEthiopic = 28, kTextEncodingMacCentralEurRoman = 29, kTextEncodingMacVietnamese = 30, kTextEncodingMacExtArabic = 31, kTextEncodingMacSymbol = 33, kTextEncodingMacDingbats = 34, kTextEncodingMacTurkish = 35, kTextEncodingMacCroatian = 36, kTextEncodingMacIcelandic = 37, kTextEncodingMacRomanian = 38, kTextEncodingMacCeltic = 39, kTextEncodingMacGaelic = 40, kTextEncodingMacKeyboardGlyphs = 41 };

    Constants

    • kTextEncodingMacRoman

      kTextEncodingMacRoman

      The encoding for Mac OS Roman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacJapanese

      kTextEncodingMacJapanese

      The encoding for Mac OS Japanese.

      Available in OS X v10.0 and later.

    • kTextEncodingMacChineseTrad

      kTextEncodingMacChineseTrad

      The encoding for Mac OS traditional Chinese.

      Available in OS X v10.0 and later.

    • kTextEncodingMacKorean

      kTextEncodingMacKorean

      The encoding for Mac OS Korean.

      Available in OS X v10.0 and later.

    • kTextEncodingMacArabic

      kTextEncodingMacArabic

      The encoding for Mac OS Arabic.

      Available in OS X v10.0 and later.

    • kTextEncodingMacHebrew

      kTextEncodingMacHebrew

      The encoding for Mac OS Hebrew.

      Available in OS X v10.0 and later.

    • kTextEncodingMacGreek

      kTextEncodingMacGreek

      The encoding for Mac OS Greek.

      Available in OS X v10.0 and later.

    • kTextEncodingMacCyrillic

      kTextEncodingMacCyrillic

      The encoding for Mac OS Cyrillic.

      Available in OS X v10.0 and later.

    • kTextEncodingMacDevanagari

      kTextEncodingMacDevanagari

      The encoding for Mac OS Devanagari.

      Available in OS X v10.0 and later.

    • kTextEncodingMacGurmukhi

      kTextEncodingMacGurmukhi

      The encoding for Mac OS Gurmukhi.

      Available in OS X v10.0 and later.

    • kTextEncodingMacGujarati

      kTextEncodingMacGujarati

      The encoding for Mac OS Gujurati.

      Available in OS X v10.0 and later.

    • kTextEncodingMacOriya

      kTextEncodingMacOriya

      The encoding for Mac OS Oriya.

      Available in OS X v10.0 and later.

    • kTextEncodingMacBengali

      kTextEncodingMacBengali

      The encoding for Mac OS Bengali.

      Available in OS X v10.0 and later.

    • kTextEncodingMacTamil

      kTextEncodingMacTamil

      The encoding for Mac OS Tamil.

      Available in OS X v10.0 and later.

    • kTextEncodingMacTelugu

      kTextEncodingMacTelugu

      The encoding for Mac OS Telugu.

      Available in OS X v10.0 and later.

    • kTextEncodingMacKannada

      kTextEncodingMacKannada

      The encoding for Mac OS Kannada.

      Available in OS X v10.0 and later.

    • kTextEncodingMacMalayalam

      kTextEncodingMacMalayalam

      The encoding for Mac OS Malayalam.

      Available in OS X v10.0 and later.

    • kTextEncodingMacSinhalese

      kTextEncodingMacSinhalese

      The encoding for Mac OS Sinhalese.

      Available in OS X v10.0 and later.

    • kTextEncodingMacBurmese

      kTextEncodingMacBurmese

      The encoding for Mac OS Burmese.

      Available in OS X v10.0 and later.

    • kTextEncodingMacKhmer

      kTextEncodingMacKhmer

      The encoding for Mac OS Khmer.

      Available in OS X v10.0 and later.

    • kTextEncodingMacThai

      kTextEncodingMacThai

      The encoding for Mac OS Thai.

      Available in OS X v10.0 and later.

    • kTextEncodingMacLaotian

      kTextEncodingMacLaotian

      The encoding for Mac OS Laotian.

      Available in OS X v10.0 and later.

    • kTextEncodingMacGeorgian

      kTextEncodingMacGeorgian

      The encoding for Mac OS Georgian.

      Available in OS X v10.0 and later.

    • kTextEncodingMacArmenian

      kTextEncodingMacArmenian

      The encoding for Mac OS Armenian.

      Available in OS X v10.0 and later.

    • kTextEncodingMacChineseSimp

      kTextEncodingMacChineseSimp

      The encoding for Mac OS simple Chinese.

      Available in OS X v10.0 and later.

    • kTextEncodingMacTibetan

      kTextEncodingMacTibetan

      The encoding for Mac OS Tibetan.

      Available in OS X v10.0 and later.

    • kTextEncodingMacMongolian

      kTextEncodingMacMongolian

      The encoding for Mac OS Mongolian.

      Available in OS X v10.0 and later.

    • kTextEncodingMacEthiopic

      kTextEncodingMacEthiopic

      The encoding for Mac OS Ethiopic.

      Available in OS X v10.0 and later.

    • kTextEncodingMacCentralEurRoman

      kTextEncodingMacCentralEurRoman

      The encoding for Mac OS Central European Roman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacVietnamese

      kTextEncodingMacVietnamese

      The encoding for Mac OS Vietnamese.

      Available in OS X v10.0 and later.

    • kTextEncodingMacExtArabic

      kTextEncodingMacExtArabic

      The encoding for Mac OS ExtArabic.

      Available in OS X v10.0 and later.

    • kTextEncodingMacSymbol

      kTextEncodingMacSymbol

      This Mac OS encoding uses script code 0, smRoman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacDingbats

      kTextEncodingMacDingbats

      This Mac OS encoding uses script code 0, smRoman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacTurkish

      kTextEncodingMacTurkish

      This Mac OS encoding uses script code 0, smRoman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacCroatian

      kTextEncodingMacCroatian

      This Mac OS encoding uses script code 0, smRoman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacIcelandic

      kTextEncodingMacIcelandic

      This Mac OS encoding uses script code 0, smRoman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacRomanian

      kTextEncodingMacRomanian

      This Mac OS encoding uses script code 0, smRoman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacCeltic

      kTextEncodingMacCeltic

      This Mac OS encoding uses script code 0, smRoman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacGaelic

      kTextEncodingMacGaelic

      This Mac OS encoding uses script code 0, smRoman.

      Available in OS X v10.0 and later.

    • kTextEncodingMacKeyboardGlyphs

      kTextEncodingMacKeyboardGlyphs

      Available in OS X v10.0 and later.

    Discussion

    You use a base text encoding data type to specify which text encoding or text encoding scheme you have used to express a given text. The text encoding base value is the primary specification of the source or target encoding. Values 0 through 32 correspond directly to Mac OS script codes. Values 33 through 254 are for other Mac OS encodings that do not have their own script codes, such as the Symbol encoding implemented by the Symbol font. You can also specify a meta-value as a base text encoding, such as kTextEncodingMacHFS and kTextEncodingUnicodeDefault. A meta-value is mapped to a real value.

    The function GetTextEncodingBase returns the text encoding base of a text encoding specification.

    A base text encoding is defined by the TextEncodingBase data type.

    Import Statement

    Objective-C

    @import CoreServices;

    Availability

    Available in OS X v10.0 and later.

  • Specify text encodings that are provided for backward compatibility.

    Declaration

    Objective-C

    enum { kTextEncodingMacTradChinese = kTextEncodingMacChineseTrad, kTextEncodingMacRSymbol = 8, kTextEncodingMacSimpChinese = kTextEncodingMacChineseSimp, kTextEncodingMacGeez = kTextEncodingMacEthiopic, kTextEncodingMacEastEurRoman = kTextEncodingMacCentralEurRoman, kTextEncodingMacUninterp = 32 };

  • Specify text encodings used by IBM computers.

    Declaration

    Objective-C

    enum { kTextEncodingEBCDIC_US = 0x0C01, kTextEncodingEBCDIC_CP037 = 0x0C02 };

    Constants

    • kTextEncodingEBCDIC_US

      kTextEncodingEBCDIC_US

      Basic EBCDIC-US encoding.

      Available in OS X v10.0 and later.

    • kTextEncodingEBCDIC_CP037

      kTextEncodingEBCDIC_CP037

      Code page 037, extended EBCDIC-US Latin1.

      Available in OS X v10.0 and later.

    Discussion

    EBCDIC (Extended Binary- Coded Decimal Interchange Code) is used by IBM computers to represent characters as numbers.

  • Specify variants of Big-5 encoding.

    Declaration

    Objective-C

    enum { kBig5_BasicVariant = 0, kBig5_StandardVariant = 1, kBig5_ETenVariant = 2 };

    Constants

    • kBig5_BasicVariant

      kBig5_BasicVariant

      The basic encoding variant.

      Available in OS X v10.0 and later.

    • kBig5_StandardVariant

      kBig5_StandardVariant

      The standard variant; 0xC6A1-0xC7FC: kana, Cyrillic, enclosed numerics.

      Available in OS X v10.0 and later.

    • kBig5_ETenVariant

      kBig5_ETenVariant

      Adds kana, Cyrillic, radicals, and so forth with high-bytes C6-C8, F9.

      Available in OS X v10.0 and later.

    Discussion

    Big-5 encoding was developed by five companies as a character set standard in Tawain.

  • Specify variant Mac OS encodings that use script codes other than 0

    Declaration

    Objective-C

    enum { kTextEncodingMacFarsi = 0x8C, kTextEncodingMacUkrainian = 0x98, kTextEncodingMacInuit = 0xEC, kTextEncodingMacVT100 = 0xFC };

    Constants

    • kTextEncodingMacFarsi

      kTextEncodingMacFarsi

      Uses script code 4, smArabic. It is similar to Mac Arabic but uses Farsi digits.]

      Available in OS X v10.0 and later.

    • kTextEncodingMacUkrainian

      kTextEncodingMacUkrainian

      Uses script code 7, smCyrillic.]

      Available in OS X v10.0 and later.

    • kTextEncodingMacInuit

      kTextEncodingMacInuit

      Uses script code 28, smEthiopic.]

      Available in OS X v10.0 and later.

    • kTextEncodingMacVT100

      kTextEncodingMacVT100

      Uses script code 32, smUninterp; VT100/102 font from the common toolbox; Latin-1 characters plus box drawing.]

      Available in OS X v10.0 and later.

  • Specify variants of MacArabic.

    Declaration

    Objective-C

    enum { kMacArabicStandardVariant = 0, kMacArabicTrueTypeVariant = 1, kMacArabicThuluthVariant = 2, kMacArabicAlBayanVariant = 3 };

    Constants

    • kMacArabicStandardVariant

      kMacArabicStandardVariant

      A Mac OS Arabic variant is supported by the Cairo font (the system font for Arabic) and is the encoding supported by the text processing utilities.

      Available in OS X v10.0 and later.

    • kMacArabicTrueTypeVariant

      kMacArabicTrueTypeVariant

      A Mac OS Arabic variant used for most of the Arabic TrueType fonts: Baghdad, Geeza, Kufi, Nadeem.

      Available in OS X v10.0 and later.

    • kMacArabicThuluthVariant

      kMacArabicThuluthVariant

      A Mac OS Arabic variant used for the Arabic PostScript-only fonts: Thuluth and Thuluth bold.

      Available in OS X v10.0 and later.

    • kMacArabicAlBayanVariant

      kMacArabicAlBayanVariant

      A Mac OS Arabic variant used for the Arabic TrueType font Al Bayan.

      Available in OS X v10.0 and later.

  • Specify variants of MacCroation.

    Declaration

    Objective-C

    enum { kMacCroatianDefaultVariant = 0, kMacCroatianCurrencySignVariant = 1, kMacCroatianEuroSignVariant = 2 };

    Constants

    • kMacCroatianDefaultVariant

      kMacCroatianDefaultVariant

      This is a meta value that maps to one of the following constants, depending on version of the Mac OS.

      Available in OS X v10.0 and later.

    • kMacCroatianCurrencySignVariant

      kMacCroatianCurrencySignVariant

      In versions of Mac OS earlier than 8.5, 0xDB is the currency sign.

      Available in OS X v10.0 and later.

    • kMacCroatianEuroSignVariant

      kMacCroatianEuroSignVariant

      In Mac OS version 8.5 and later, 0xDB is the Euro sign.

      Available in OS X v10.0 and later.

  • Specify variants of MacCyrillic.

    Declaration

    Objective-C

    enum { kMacCyrillicDefaultVariant = 0, kMacCyrillicCurrSignStdVariant = 1, kMacCyrillicCurrSignUkrVariant = 2, kMacCyrillicEuroSignVariant = 3 };

    Constants

    • kMacCyrillicDefaultVariant

      kMacCyrillicDefaultVariant

      This is a meta value that maps to one of the following constants, depending on version of the Mac OS.

      Available in OS X v10.0 and later.

    • kMacCyrillicCurrSignStdVariant

      kMacCyrillicCurrSignStdVariant

      In Mac OS versions prior to 9.0 (RU, BG), 0xFF = currency sign, 0xA2/0xB6 = CENT / PARTIAL DIFF.

      Available in OS X v10.0 and later.

    • kMacCyrillicCurrSignUkrVariant

      kMacCyrillicCurrSignUkrVariant

      In Mac OS version 9.0 and later (UA, LangKit), 0xFF = currency sign, 0xA2/0xB6 = GHE with upturn.

      Available in OS X v10.0 and later.

    • kMacCyrillicEuroSignVariant

      kMacCyrillicEuroSignVariant

      In Mac OS 9.0 and later, 0xFF is Euro sign, 0xA2/0xB6 = GHE with upturn.

      Available in OS X v10.0 and later.

  • Specify variants of MacFarsi.

    Declaration

    Objective-C

    enum { kMacFarsiStandardVariant = 0, kMacFarsiTrueTypeVariant = 1 };

    Constants

    • kMacFarsiStandardVariant

      kMacFarsiStandardVariant

      This Mac OS Farsi variant is supported by the Tehran font (the system font for Farsi) and is the encoding supported by the text processing utilities.

      Available in OS X v10.0 and later.

    • kMacFarsiTrueTypeVariant

      kMacFarsiTrueTypeVariant

      This Mac OS Farsi variant is used for most of the Farsi TrueType fonts: Ashfahan, Amir, Kamran, Mashad, NadeemFarsi.

      Available in OS X v10.0 and later.

  • Specify variants of MacHebrew.

    Declaration

    Objective-C

    enum { kMacHebrewStandardVariant = 0, kMacHebrewFigureSpaceVariant = 1 };

    Constants

    • kMacHebrewStandardVariant

      kMacHebrewStandardVariant

      The standard Mac OS Hebrew variant.

      Available in OS X v10.0 and later.

    • kMacHebrewFigureSpaceVariant

      kMacHebrewFigureSpaceVariant

      The Mac OS Hebrew variant in which 0xD4 represents figure space, not left single quotation mark as in the standard variant.

      Available in OS X v10.0 and later.

  • Specify variants of MacIcelandic.

    Declaration

    Objective-C

    enum { kMacIcelandicStdDefaultVariant = 0, kMacIcelandicTTDefaultVariant = 1, kMacIcelandicStdCurrSignVariant = 2, kMacIcelandicTTCurrSignVariant = 3, kMacIcelandicStdEuroSignVariant = 4, kMacIcelandicTTEuroSignVariant = 5 };

    Constants

    • kMacIcelandicStdDefaultVariant

      kMacIcelandicStdDefaultVariant

      This is a meta value that maps to kMacIcelandicStdCurrSignVariant or kMacIcelandicStdEuroSignVariant, depending on version of the Mac OS.

      Available in OS X v10.0 and later.

    • kMacIcelandicTTDefaultVariant

      kMacIcelandicTTDefaultVariant

      This is a meta value that maps to kMacIcelandicTTCurrSignVariant or kMacIcelandicTTEuroSignVariant, depending on version of the Mac OS.

      Available in OS X v10.0 and later.

    • kMacIcelandicStdCurrSignVariant

      kMacIcelandicStdCurrSignVariant

      In Mac OS versions prior to 8.5, 0xDB is the currency sign; 0xBB/0xBC are fem./masc. ordinal indicators.

      Available in OS X v10.0 and later.

    • kMacIcelandicTTCurrSignVariant

      kMacIcelandicTTCurrSignVariant

      In Mac OS versions prior to 8.5, 0xDB is the currency sign; 0xBB/0xBC are fi/fl ligatures

      Available in OS X v10.0 and later.

    • kMacIcelandicStdEuroSignVariant

      kMacIcelandicStdEuroSignVariant

      In Mac OS version 8.5 and later , 0xDB is the Euro sign ; 0xBB/0xBC are fem./masc. ordinal indicators.

      Available in OS X v10.0 and later.

    • kMacIcelandicTTEuroSignVariant

      kMacIcelandicTTEuroSignVariant

      In Mac OS versions earlier than 8.5, 0xDB is the Euro sign; 0xBB/0xBC are fi/fl ligatures.

      Available in OS X v10.0 and later.

  • Specify variants of MacJapanese.

    Declaration

    Objective-C

    enum { kMacJapaneseStandardVariant = 0, kMacJapaneseStdNoVerticalsVariant = 1, kMacJapaneseBasicVariant = 2, kMacJapanesePostScriptScrnVariant = 3, kMacJapanesePostScriptPrintVariant = 4, kMacJapaneseVertAtKuPlusTenVariant = 5 };

    Constants

    • kMacJapaneseStandardVariant

      kMacJapaneseStandardVariant

      The standard Mac OS Japanese variant. Shift-JIS with JIS Roman modifications, extra 1-byte characters, 2-byte Apple extensions, and some vertical presentation forms in the range 0xEB40—0xEDFE (“ku plus 84").

      Available in OS X v10.0 and later.

    • kMacJapaneseStdNoVerticalsVariant

      kMacJapaneseStdNoVerticalsVariant

      An artificial Mac OS Japanese variant for callers who don’t want to use separately encoded vertical forms (for example, developers using QuickDraw GX).

      Available in OS X v10.0 and later.

    • kMacJapaneseBasicVariant

      kMacJapaneseBasicVariant

      An artificial Mac OS Japanese variant without Apple double-byte extensions.

      Available in OS X v10.0 and later.

    • kMacJapanesePostScriptScrnVariant

      kMacJapanesePostScriptScrnVariant

      The Mac OS Japanese variant for the screen bitmap version of the Sai Mincho and Chu Gothic fonts.

      Available in OS X v10.0 and later.

    • kMacJapanesePostScriptPrintVariant

      kMacJapanesePostScriptPrintVariant

      The Mac OS Japanese variant for PostScript printing versions of the Sai Mincho and Chu Gothic PostScript fonts. This version includes double-byte half-width characters in addition to single-byte half-width characters.

      Available in OS X v10.0 and later.

    • kMacJapaneseVertAtKuPlusTenVariant

      kMacJapaneseVertAtKuPlusTenVariant

      The Mac OS Japanese variant for the Hon Mincho and Maru Gothic fonts used in the Japanese localized version of System 7.1. It does not include the standard Apple extensions, and encodes vertical forms at a different location.

      Available in OS X v10.0 and later.

  • Specify variants of MacRoman.

    Declaration

    Objective-C

    enum { kMacRomanStandardVariant = 0, kMacIcelandicStandardVariant = 0, kMacIcelandicTrueTypeVariant = 1, kJapaneseStandardVariant = 0, kJapaneseStdNoVerticalsVariant = 1, kJapaneseBasicVariant = 2, kJapanesePostScriptScrnVariant = 3, kJapanesePostScriptPrintVariant = 4, kJapaneseVertAtKuPlusTenVariant = 5, kHebrewStandardVariant = 0, kHebrewFigureSpaceVariant = 1, kUnicodeMaxDecomposedVariant = 2, kUnicodeNoComposedVariant = 3, kJapaneseNoOneByteKanaOption = 0x20, kJapaneseUseAsciiBackslashOption = 0x40 };

    Constants

    • kMacRomanStandardVariant

      kMacRomanStandardVariant

      The standard variant of Mac OS Roman for Mac OS 8.5 and later; 0xDB is the Euro sign.

      Available in OS X v10.0 and later.

    • kMacIcelandicStandardVariant

      kMacIcelandicStandardVariant

      The standard Mac OS Icelandic encoding supported by the bitmap versions of Chicago, Geneva, Monaco, and New York in the Icelandic system. This is also the variant supported by the text processing utilities.

      Available in OS X v10.0 and later.

    • kMacIcelandicTrueTypeVariant

      kMacIcelandicTrueTypeVariant

      The Mac OS Icelandic variant used for the bitmap versions of Courier, Helvetica, Palatino, and Times in the Icelandic system, and for the TrueType versions of Chicago, Geneva, Monaco, New York, Courier, Helvetica, Palatino, and Times.

      Available in OS X v10.0 and later.

    • kJapaneseStandardVariant

      kJapaneseStandardVariant

      Available in OS X v10.0 and later.

    • kJapaneseStdNoVerticalsVariant

      kJapaneseStdNoVerticalsVariant

      Available in OS X v10.0 and later.

    • kJapaneseBasicVariant

      kJapaneseBasicVariant

      Available in OS X v10.0 and later.

    • kJapanesePostScriptScrnVariant

      kJapanesePostScriptScrnVariant

      Available in OS X v10.0 and later.

    • kJapanesePostScriptPrintVariant

      kJapanesePostScriptPrintVariant

      Available in OS X v10.0 and later.

    • kJapaneseVertAtKuPlusTenVariant

      kJapaneseVertAtKuPlusTenVariant

      Available in OS X v10.0 and later.

    • kHebrewStandardVariant

      kHebrewStandardVariant

      Available in OS X v10.0 and later.

    • kHebrewFigureSpaceVariant

      kHebrewFigureSpaceVariant

      Available in OS X v10.0 and later.

    • kUnicodeMaxDecomposedVariant

      kUnicodeMaxDecomposedVariant

      Replaced by kUnicodeCanonicalDecompVariant.

      Available in OS X v10.0 and later.

    • kUnicodeNoComposedVariant

      kUnicodeNoComposedVariant

      Replaced by kUnicodeCanonicalCompVariant.

      Available in OS X v10.0 and later.

    • kJapaneseNoOneByteKanaOption

      kJapaneseNoOneByteKanaOption

      Replaced by Unicode Converter option kUnicodeNoHalfwidthCharsBit.

      Available in OS X v10.0 through OS X v10.4.

      Not available to 64-bit applications.

    • kJapaneseUseAsciiBackslashOption

      kJapaneseUseAsciiBackslashOption

      Replaced by Unicode Converter option kUnicodeForceASCIIRangeBit.

      Available in OS X v10.0 through OS X v10.4.

      Not available to 64-bit applications.

  • Specify variants of MacRoman that are related to currency.

    Declaration

    Objective-C

    enum { kMacRomanDefaultVariant = 0, kMacRomanCurrencySignVariant = 1, kMacRomanEuroSignVariant = 2 };

    Constants

    • kMacRomanDefaultVariant

      kMacRomanDefaultVariant

      This is a meta value that maps to one of the following constants, depending on version of the Mac OS.

      Available in OS X v10.0 and later.

    • kMacRomanCurrencySignVariant

      kMacRomanCurrencySignVariant

      In Mac OS versions earlier than 8.5 0xDB is the currency sign; still used for some older fonts even in Mac OS 8.5.

      Available in OS X v10.0 and later.

    • kMacRomanEuroSignVariant

      kMacRomanEuroSignVariant

      In Mac OS version 8.5 and later, 0xDB is the Euro sign.

      Available in OS X v10.0 and later.

  • Specify variants of MacRomanian.

    Declaration

    Objective-C

    enum { kMacRomanianDefaultVariant = 0, kMacRomanianCurrencySignVariant = 1, kMacRomanianEuroSignVariant = 2 };

    Constants

    • kMacRomanianDefaultVariant

      kMacRomanianDefaultVariant

      This is a meta value that maps to one of the following constants, depending on version of the Mac OS.

      Available in OS X v10.0 and later.

    • kMacRomanianCurrencySignVariant

      kMacRomanianCurrencySignVariant

      In Mac OS versions earlier than 8.5, 0xDB is the currency sign.

      Available in OS X v10.0 and later.

    • kMacRomanianEuroSignVariant

      kMacRomanianEuroSignVariant

      In Mac OS version 8.5 and later, 0xDB is the Euro sign.

      Available in OS X v10.0 and later.

  • Specify variants of MacRomanLatin1.

    Declaration

    Objective-C

    enum { kMacRomanLatin1DefaultVariant = 0, kMacRomanLatin1StandardVariant = 2, kMacRomanLatin1TurkishVariant = 6, kMacRomanLatin1CroatianVariant = 8, kMacRomanLatin1IcelandicVariant = 11, kMacRomanLatin1RomanianVariant = 14 };

    Constants

    • kMacRomanLatin1DefaultVariant

      kMacRomanLatin1DefaultVariant

      This is a meta value that maps to one of the following constants, depending on version of the Mac OS.

      Available in OS X v10.0 and later.

    • kMacRomanLatin1StandardVariant

      kMacRomanLatin1StandardVariant

      Permuted MacRoman, Euro sign variant.

      Available in OS X v10.0 and later.

    • kMacRomanLatin1TurkishVariant

      kMacRomanLatin1TurkishVariant

      Permuted MacTurkish.

      Available in OS X v10.0 and later.

    • kMacRomanLatin1CroatianVariant

      kMacRomanLatin1CroatianVariant

      Permuted MacCroatian, Euro sign variant.

      Available in OS X v10.0 and later.

    • kMacRomanLatin1IcelandicVariant

      kMacRomanLatin1IcelandicVariant

      Permuted MacIcelandic, standard Euro sign variant.

      Available in OS X v10.0 and later.

    • kMacRomanLatin1RomanianVariant

      kMacRomanLatin1RomanianVariant

      Permuted MacRomanian, Euro sign variant.

      Available in OS X v10.0 and later.

  • Specify variants of MacVT100.

    Declaration

    Objective-C

    enum { kMacVT100DefaultVariant = 0, kMacVT100CurrencySignVariant = 1, kMacVT100EuroSignVariant = 2 };

    Constants

    • kMacVT100DefaultVariant

      kMacVT100DefaultVariant

      This is a meta value that maps to one of the following constants, depending on version of the Mac OS.

      Available in OS X v10.0 and later.

    • kMacVT100CurrencySignVariant

      kMacVT100CurrencySignVariant

      In Mac OS versions earlier than 8.5, 0xDB is the currency sign.

      Available in OS X v10.0 and later.

    • kMacVT100EuroSignVariant

      kMacVT100EuroSignVariant

      In Mac OS version 8.5 and later, 0xDB is the Euro sign.

      Available in OS X v10.0 and later.

  • Specify variants of Unicode.

    Declaration

    Objective-C

    enum { kUnicodeNoSubset = 0, kUnicodeCanonicalDecompVariant = 2, kUnicodeCanonicalCompVariant = 3, kUnicodeHFSPlusDecompVariant = 8, kUnicodeHFSPlusCompVariant = 9 };

    Constants

    • kUnicodeNoSubset

      kUnicodeNoSubset

      The standard Unicode encoded character set in which the full set of Unicode characters are supported.

      Available in OS X v10.0 and later.

    • kUnicodeCanonicalDecompVariant

      kUnicodeCanonicalDecompVariant

      A variant of Unicode using maximal decomposition with characters in canonical order. This variant does not include most characters which have a canonical decomposition, such as single characters for accented Latin letters or single characters for Korean Hangul syllables (however, this restriction is relaxed for symbol characters in the range U+2000 to U+2FFF). In TEC Manager 1.3, the Unicode Converter supports this variant for converting to and from Mac OS encodings.

      Available in OS X v10.0 and later.

    • kUnicodeCanonicalCompVariant

      kUnicodeCanonicalCompVariant

      This is the normal canonical composition according to Unicode 3.2 rules.

      Available in OS X v10.2 and later.

    • kUnicodeHFSPlusDecompVariant

      kUnicodeHFSPlusDecompVariant

      Specifies canonical decomposition according to Unicode 3.2 rules, with HFS+ exclusions ("HFS+ decomposition 3.2"). That is, it doesn't decompose in 2000-2FFF, F900-FAFF, 2F800-2FAFF. You can use ths option when converting HFS file names.

      Available in OS X v10.2 and later.

    • kUnicodeHFSPlusCompVariant

      kUnicodeHFSPlusCompVariant

      Specifies canonical composition according to Unicode 3.2 rules, but using the HFS+ decomposition exclusions. You can use ths option when converting HFS file names. You should use this form when you want to obtain a composed form that can be converted to and from the decomposed form specified by kUnicodeHFSPlusDecompVariant. This is the recommended way to request decompositions with HFS+ exclusions, instead of using mappingVersion = kUnicodeUseHFSPlusMapping.

      Available in OS X v10.2 and later.

  • Specify Extendec Unix Code text encodings.

    Declaration

    Objective-C

    enum { kTextEncodingEUC_JP = 0x0920, kTextEncodingEUC_CN = 0x0930, kTextEncodingEUC_TW = 0x0931, kTextEncodingEUC_KR = 0x0940 };

    Constants

    • kTextEncodingEUC_JP

      kTextEncodingEUC_JP

      ISO 646,1-byte katakana,JIS 208 ,JIS 212.

      Available in OS X v10.0 and later.

    • kTextEncodingEUC_CN

      kTextEncodingEUC_CN

      ISO 646, GB 2312-80.

      Available in OS X v10.0 and later.

    • kTextEncodingEUC_TW

      kTextEncodingEUC_TW

      ISO 646, CNS 11643-1992 Planes 1-16.

      Available in OS X v10.0 and later.

    • kTextEncodingEUC_KR

      kTextEncodingEUC_KR

      ISO 646, KS C 5601-1987.

      Available in OS X v10.0 and later.

  • Specifies a Mac OS HFS text encoding.

    Declaration

    Objective-C

    enum { kTextEncodingMacHFS = 0xFF };

    Constants

    • kTextEncodingMacHFS

      kTextEncodingMacHFS

      This is a metavalue for a special Mac OS encoding.

      Available in OS X v10.0 and later.

  • Specify text encodings for ISO 2002.

    Declaration

    Objective-C

    enum { kTextEncodingISO_2022_JP = 0x0820, kTextEncodingISO_2022_JP_2 = 0x0821, kTextEncodingISO_2022_JP_1 = 0x0822, kTextEncodingISO_2022_JP_3 = 0x0823, kTextEncodingISO_2022_CN = 0x0830, kTextEncodingISO_2022_CN_EXT = 0x0831, kTextEncodingISO_2022_KR = 0x0840 };

    Constants

    • kTextEncodingISO_2022_JP

      kTextEncodingISO_2022_JP

      See RFC 1468.

      Available in OS X v10.0 and later.

    • kTextEncodingISO_2022_JP_2

      kTextEncodingISO_2022_JP_2

      See RFC 1554.

      Available in OS X v10.0 and later.

    • kTextEncodingISO_2022_JP_1

      kTextEncodingISO_2022_JP_1

      See RFC 2237.

      Available in OS X v10.0 and later.

    • kTextEncodingISO_2022_JP_3

      kTextEncodingISO_2022_JP_3

      JIS X0213

      Available in OS X v10.1 and later.

    • kTextEncodingISO_2022_CN

      kTextEncodingISO_2022_CN

      Available in OS X v10.0 and later.

    • kTextEncodingISO_2022_CN_EXT

      kTextEncodingISO_2022_CN_EXT

      Available in OS X v10.0 and later.

    • kTextEncodingISO_2022_KR

      kTextEncodingISO_2022_KR

      Available in OS X v10.0 and later.

  • Specify text encodings for ISO 8-bit and 7-bit.

    Declaration

    Objective-C

    enum { kTextEncodingISOLatin1 = 0x0201, kTextEncodingISOLatin2 = 0x0202, kTextEncodingISOLatin3 = 0x0203, kTextEncodingISOLatin4 = 0x0204, kTextEncodingISOLatinCyrillic = 0x0205, kTextEncodingISOLatinArabic = 0x0206, kTextEncodingISOLatinGreek = 0x0207, kTextEncodingISOLatinHebrew = 0x0208, kTextEncodingISOLatin5 = 0x0209, kTextEncodingISOLatin6 = 0x020A, kTextEncodingISOLatin7 = 0x020D, kTextEncodingISOLatin8 = 0x020E, kTextEncodingISOLatin9 = 0x020F };

    Constants

    • kTextEncodingISOLatin1

      kTextEncodingISOLatin1

      ISO 8859-1.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatin2

      kTextEncodingISOLatin2

      ISO 8859-2.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatin3

      kTextEncodingISOLatin3

      ISO 8859-3.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatin4

      kTextEncodingISOLatin4

      ISO 8859-4.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatinCyrillic

      kTextEncodingISOLatinCyrillic

      ISO 8859-5.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatinArabic

      kTextEncodingISOLatinArabic

      ISO 8859-6; equivalent to ASMO 708 and DOS CP 708.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatinGreek

      kTextEncodingISOLatinGreek

      ISO 8859-7.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatinHebrew

      kTextEncodingISOLatinHebrew

      ISO 8859-8.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatin5

      kTextEncodingISOLatin5

      ISO 8859-9.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatin6

      kTextEncodingISOLatin6

      ISO 8859-10.

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatin7

      kTextEncodingISOLatin7

      ISO 8859-13; Baltic Rim

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatin8

      kTextEncodingISOLatin8

      ISO 8859-14; Celtic

      Available in OS X v10.0 and later.

    • kTextEncodingISOLatin9

      kTextEncodingISOLatin9

      ISO 8859-15, 8859-1; changed for Euro & CP1252 letters

      Available in OS X v10.0 and later.

  • Specifies a script code that should be handled as a special Mac OS script code.

    Declaration

    Objective-C

    enum { kTextEncodingMacUnicode = 0x7E };

    Constants

    • kTextEncodingMacUnicode

      kTextEncodingMacUnicode

      Beginning with Mac OS 8.5, the set of Mac OS script codes has been extended for some Mac OS components to include Unicode. Some of these components have only 7 bits available for script code, so kTextEncodingUnicodeDefault cannot be used to indicate Unicode. Instead, kTextEncodingMacUnicode is used as a meta-value to indicate that Unicode handles the script code a special Mac OS script code. The Text Encoding Converter handles this value similar to the way it handles the constant kTextEncodingUnicodeDefault.

      Available in OS X v10.0 and later.

  • Specify miscellaneous text encodings.

    Declaration

    Objective-C

    enum { kTextEncodingShiftJIS = 0x0A01, kTextEncodingKOI8_R = 0x0A02, kTextEncodingBig5 = 0x0A03, kTextEncodingMacRomanLatin1 = 0x0A04, kTextEncodingHZ_GB_2312 = 0x0A05, kTextEncodingBig5_HKSCS_1999 = 0x0A06 };

    Constants

    • kTextEncodingShiftJIS

      kTextEncodingShiftJIS

      Plain Shift-JIS.

      Available in OS X v10.0 and later.

    • kTextEncodingKOI8_R

      kTextEncodingKOI8_R

      Russian Internet standard.

      Available in OS X v10.0 and later.

    • kTextEncodingBig5

      kTextEncodingBig5

      Big-5 encoding.

      Available in OS X v10.0 and later.

    • kTextEncodingMacRomanLatin1

      kTextEncodingMacRomanLatin1

      Mac OS Roman permuted to align with 8859-1.

      Available in OS X v10.0 and later.

    • kTextEncodingHZ_GB_2312

      kTextEncodingHZ_GB_2312

      See RFC 1842; for Chinese mail and news.

      Available in OS X v10.0 and later.

    • kTextEncodingBig5_HKSCS_1999

      kTextEncodingBig5_HKSCS_1999

      Available in OS X v10.1 and later.

  • Specify text encodings for MS-DOS and Windows.

    Declaration

    Objective-C

    enum { kTextEncodingDOSLatinUS = 0x0400, kTextEncodingDOSGreek = 0x0405, kTextEncodingDOSBalticRim = 0x0406, kTextEncodingDOSLatin1 = 0x0410, kTextEncodingDOSGreek1 = 0x0411, kTextEncodingDOSLatin2 = 0x0412, kTextEncodingDOSCyrillic = 0x0413, kTextEncodingDOSTurkish = 0x0414, kTextEncodingDOSPortuguese = 0x0415, kTextEncodingDOSIcelandic = 0x0416, kTextEncodingDOSHebrew = 0x0417, kTextEncodingDOSCanadianFrench = 0x0418, kTextEncodingDOSArabic = 0x0419, kTextEncodingDOSNordic = 0x041A, kTextEncodingDOSRussian = 0x041B, kTextEncodingDOSGreek2 = 0x041C, kTextEncodingDOSThai = 0x041D, kTextEncodingDOSJapanese = 0x0420, kTextEncodingDOSChineseSimplif = 0x0421, kTextEncodingDOSKorean = 0x0422, kTextEncodingDOSChineseTrad = 0x0423, kTextEncodingWindowsLatin1 = 0x0500, kTextEncodingWindowsANSI = 0x0500, kTextEncodingWindowsLatin2 = 0x0501, kTextEncodingWindowsCyrillic = 0x0502, kTextEncodingWindowsGreek = 0x0503, kTextEncodingWindowsLatin5 = 0x0504, kTextEncodingWindowsHebrew = 0x0505, kTextEncodingWindowsArabic = 0x0506, kTextEncodingWindowsBalticRim = 0x0507, kTextEncodingWindowsVietnamese = 0x0508, kTextEncodingWindowsKoreanJohab = 0x0510 };

    Constants

    • kTextEncodingDOSLatinUS

      kTextEncodingDOSLatinUS

      Code page 437.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSGreek

      kTextEncodingDOSGreek

      Code page 737, formerly 437G.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSBalticRim

      kTextEncodingDOSBalticRim

      Code page 775.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSLatin1

      kTextEncodingDOSLatin1

      Code page 860. “multilingual.”

      Available in OS X v10.0 and later.

    • kTextEncodingDOSGreek1

      kTextEncodingDOSGreek1

      Code page 851.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSLatin2

      kTextEncodingDOSLatin2

      Code page 852, Slavic.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSCyrillic

      kTextEncodingDOSCyrillic

      Code page 855, IBM Cyrillic.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSTurkish

      kTextEncodingDOSTurkish

      Code page 857, IBM Turkish.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSPortuguese

      kTextEncodingDOSPortuguese

      Code page 860.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSIcelandic

      kTextEncodingDOSIcelandic

      Code page 861.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSHebrew

      kTextEncodingDOSHebrew

      Code page 862.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSCanadianFrench

      kTextEncodingDOSCanadianFrench

      Code page 863.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSArabic

      kTextEncodingDOSArabic

      Code page 864.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSNordic

      kTextEncodingDOSNordic

      Cde page 865.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSRussian

      kTextEncodingDOSRussian

      Code page 866.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSGreek2

      kTextEncodingDOSGreek2

      Code page 869, IBM Modern Green.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSThai

      kTextEncodingDOSThai

      Code page 874, also for Windows.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSJapanese

      kTextEncodingDOSJapanese

      Code page 932, also for Windows

      Available in OS X v10.0 and later.

    • kTextEncodingDOSChineseSimplif

      kTextEncodingDOSChineseSimplif

      Code page 936, also for Windows.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSKorean

      kTextEncodingDOSKorean

      Code page 949, also for Windows; unified Hangul.

      Available in OS X v10.0 and later.

    • kTextEncodingDOSChineseTrad

      kTextEncodingDOSChineseTrad

      Code page 950, also for Windows.

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsLatin1

      kTextEncodingWindowsLatin1

      Code page 1252.

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsANSI

      kTextEncodingWindowsANSI

      Code page 1252 (alternate name).

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsLatin2

      kTextEncodingWindowsLatin2

      Code page 1250, Central Europe.

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsCyrillic

      kTextEncodingWindowsCyrillic

      Code page 1251, Slavic Cyrillic.

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsGreek

      kTextEncodingWindowsGreek

      Code page 1253.

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsLatin5

      kTextEncodingWindowsLatin5

      Code page 1254, Turkish.

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsHebrew

      kTextEncodingWindowsHebrew

      Code page 1255.

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsArabic

      kTextEncodingWindowsArabic

      Code page 1256.

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsBalticRim

      kTextEncodingWindowsBalticRim

      Code page 1257.

      Available in OS X v10.0 and later.

    • kTextEncodingWindowsVietnamese

      kTextEncodingWindowsVietnamese

      Code page 1258.

      Available in OS X v10.0 and later.