Carbon


FNSProfileMatchReference

Header: FontSync.h Carbon status: Supported

Obtains a list of the references in a profile that match a given reference.

OSStatus FNSProfileMatchReference (
    FNSFontProfile iProfile, 
    FNSFontReference iReference, 
    FNSMatchOptions iMatchOptions, 
    ItemCount iOutputSize, 
    UInt32 oIndices[], 
    ItemCount *oNumMatches
);
Parameter descriptions
iProfile

A reference to the font profile containing the font references you wish to compare.

iReference

A reference to a font reference against which you are performing the comparison.

iMatchOptions

A bit mask you can use to set the matching option bits to be used in the comparison. To specify the global default match criteria, pass the bit mask returned by the function FNSMatchDefaultsGet. Your application can specify options that are different from the user’s preferences via this mask.

iOutputSize

The number of font references you want passed back in the oIndices array. This may be less than the actual number of matches passed back in the oNumMatches parameter. To determine this value, see the discussion below.

oIndices

On return, a pointer to an array of indices identifying the font references that matched. The number of indices returned is limited by the value you specify in the iOutputSize parameter. The total number of matching references is passed back in the oNumMatches parameter.

oNumMatches

On return, a pointer to the total number of matching font references. This value may be greater than the number of indices passed back in the oIndices array.

function result

A result code. The result code kFNSBadProfileVersionErr indicates that a font profile has an unsupported version number. This may indicate that the profile is valid, but created by a later version of FontSync, or that the profile is truly invalid. The result code kFNSInvalidProfileErr indicates that a profile does not have a valid structure. The result code kFNSBadReferenceVersionErr indicates that a font reference has an unsupported version number. This may indicate that the reference is valid, but created by a later version of FontSync, or that the reference is truly invalid. The result code kFNSInvalidReferenceErr indicates that a font reference is invalid. The result code kFNSMismatchErr indicates that no matches were found. The File Manager error permErr indicates that the file is either locked and not editable or opened for read-only access. FNSProfileMatchReference may return other File Manager errors. Memory Manager errors indicate that you did not have enough memory available in your heap.

DISCUSSION

The FNSProfileMatchReference function obtains a list of the font references that match a specified reference. Since there may be more than one matching reference, a list is returned.

The number of font references passed back in the oIndices array is limited by the value you specify in the iOutputSize parameter. The actual number of matches is passed back in the oNumMatches parameter. You can check this value to determine whether the oIndices array was large enough to contain the matches.

If you want to determine whether the profile has a matching font, but don’t care which one, pass 0 for the iOutputSize parameter and NULL for the oNumMatches parameter. The result code noErr indicates that matches were found, while the result code kFNSMismatchErr indicates that no matches were found.

To determine the number of matches, call FNSProfileMatchReference and pass 0 for the iOutputSize parameter. The pointer passed back in the oNumMatches parameter will point to the actual number of matches. You can then call FNSProfileMatchReference again, passing the returned number of matches in the iOutputSize parameter.

VERSION NOTES

Available beginning with FontSync 1.0.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when Font Sync 1.0 or later is present.


© 2000 Apple Computer, Inc. (Last Updated 7/13/2000)