![]() |
UnicodeToTextFallbackProcPtr |
||||
Header: | UnicodeConverter.h | Carbon status: | Supported | |
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.
typedef OSStatus(* UnicodeToTextFallbackProcPtr) ( UniChar *iSrcUniStr, ByteCount iSrcUniStrLen, ByteCount *oSrcConvLen, TextPtr oDestStr, ByteCount iDestStrLen, ByteCount *oDestConvLen, LogicalAddress iInfoPtr, ConstUnicodeMappingPtr iUnicodeMappingPtr );
You would declare your function like this if you were to name it MyUnicodeToTextFallbackCallback:
OSStatus MyUnicodeToTextFallbackCallback ( UniChar *iSrcUniStr, ByteCount iSrcUniStrLen, ByteCount *oSrcConvLen, TextPtr oDestStr, ByteCount iDestStrLen, ByteCount *oDestConvLen, LogicalAddress iInfoPtr, ConstUnicodeMappingPtr iUnicodeMappingPtr );
A pointer to a single UTF-16 character to be mapped by the fallback handler.
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.
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.
A pointer to the output buffer where your handler should place any converted text.
The maximum size in bytes of the buffer provided by the oDestStr parameter.
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.
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).
A constant pointer to a structure of type UnicodeMapping. This structure identifies a Unicode encoding specification and a particular base encoding specification.
A result code. 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.
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.
© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)