PATH Mac OS 8 and 9 Developer Documentation > Text Encoding Conversion Manager
Programming With the Text Encoding Conversion Manager

---

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. For a description of the function prototype your handler should adhere to, see UnicodeToTextFallbackProcPtr.

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.

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.

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.

Ideally your application-defined fallback handler should not call any Memory Manager function or any toolbox function that would move memory. If it needs memory, you should allocate it before the call to SetFallbackUnicodeToText or SetFallbackUnicodeToTextRun, and pass a reference to the memory either directly in the iInfoPtr parameter or in the data referenced by iInfoPtr.

If your application-defined fallback handler does not move memory, then you should set the bit corresponding to kUnicodeFallbackInterruptSafeMask in the iControlFlags parameter of either SetFallbackUnicodeToText or SetFallbackUnicodeToTextRun (depending on whether you want to install the handler in a UnicodeToTextInfo object or a UnicodeToTextRunInfo object, respectively). If you do this, ConvertFromUnicodeToText (or ConvertFromUnicodeToTextRun) calls that use that UnicodeToTextInfo (or UnicodeToTextRunInfo) object will not need to lock relocatable memory items and can therefore operate more efficiently.

If your application-defined fallback handler must move memory, you should leave the bit corresponding to kUnicodeFallbackInterruptSafeMask unset when installing the callback handler. In such cases, calls to ConvertFromUnicodeToText or ConvertFromUnicodeToTextRun that use that use that UnicodeToTextInfo (or UnicodeToTextRunInfo) object will lock the necessary relocatable memory items to ensure that the fallback handlers cannot move them.

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.

For a complete description of how to use universal procedure pointers, refer to Inside Macintosh: PowerPC System Software.