SetFallbackUnicodeToText

Associates an application-defined fallback handler with a specific UnicodeToTextInfo Unicode converter object for a single text run to be used with either the function ConvertFromUnicodeToText or ConvertFromUnicodeToPString.

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

iUnicodeToTextInfo

The Unicode converter object with 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, see UnicodeToTextFallbackProcPtr . For a description of how to create your own fallback handler, see MyUnicodeToTextFallbackProc. You should use the NewUnicodeToTextFallbackProc macro to convert a pointer to your fallback handler into a UnicodeToTextFallbackUPP. See the example in this function's discussion.

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. Control flags can also specify whether the application-defined fallback handler can move memory. See Fallback-Handler Control Flags .

iInfoPtr

The address of 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.

function result

A result code. See Text Encoding Conversion Manager Result Codes in Basic Text Types Reference

DISCUSSION

You use this function to specify 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 passed to the functions ConvertFromUnicodeToText, ConvertFromUnicodeToTextRun, ConvertFromUnicodeToPString, and ConvertFromUnicodeToScriptCodeRun. You can define multiple fallback handlers and associate them with different Unicode converter objects, depending on your requirements.

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. See Application-Defined Function for a description of the parameters of an application-defined fallback handler.

Listing 4-1 Installing an Application-Defined Fallback Handler

#include <Types.h> #include <Errors.h> #include <MixedMode.h> #include <TextCommon.h> #include <UnicodeConverter.h> pascal OSStatus MyUnicodeToTextFallbackProc( UniChar *iSrcUniStr, ByteCount iSrcUniStrLen, ByteCount *oSrcConvLen, TextPtr oDestStr, ByteCount iDestStrLen, ByteCount *oDestConvLen, LogicalAddress iInfoPtr, ConstUnicodeMappingPtr iUnicodeMappingPtr) { . . . /* include your actual fallback handler implementation here */ } . . . main () { . . . UnicodeMapping mapping; UnicodeToTextInfo unicodeToTextInfo; UnicodeToTextFallbackUPP fallbackProc; OSStatus status; . . . mapping.unicodeEncoding = CreateTextEncoding(kTextEncodingUnicodeDefault, kTextEncodingDefaultVariant, kUnicode16BitFormat); mapping.otherEncoding = CreateTextEncoding(kTextEncodingMacRoman, kTextEncodingDefaultVariant, kTextEncodingDefaultFormat); mapping.mappingVersion = kUnicodeUseLatestMapping; status = CreateUnicodeToTextInfo(&mapping, &unicodeToTextInfo); . . . fallbackProc = NewUnicodeToTextFallbackProc(MyUnicodeToTextFallbackProc); status = SetFallbackUnicodeToText(unicodeToTextInfo, fallbackProc, kUnicodeFallbackCustomFirst, NULL); . . . status = ConvertFromUnicodeToText(unicodeToTextInfo, . . . }

Legacy Document

SetFallbackUnicodeToText

DISCUSSION