![]() |
QueryUnicodeMappings |
||||
Header: | UnicodeConverter.h | Carbon status: | Supported | |
Returns a list of the conversion mappings available on the system that meet specified matching criteria and returns the number of mappings found.
OSStatus QueryUnicodeMappings ( OptionBits iFilter, ConstUnicodeMappingPtr iFindMapping, ItemCount iMaxCount, ItemCount *oActualCount, UnicodeMapping oReturnedMappings[] );
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
A structure of type UnicodeMapping containing the text encodings whose values are to be matched.
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.
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.
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.
A result code. 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.
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 structures unicodeEncoding specification and on any of the three text encoding subfields of the mappings 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 structures 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;
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 7/17/2000)