Legacy Document

Important: FontSync is deprecated in Mac OS X v10.6 and later. There is no exact replacement technology. Please use the font facilities in the Cocoa text system and Core Text instead.

FontSync Reference (Not Recommended)

Framework	ApplicationServices/ApplicationServices.h
Declared in	FontSync.h

Overview

Important: FontSync is deprecated in Mac OS X v10.6 and later. There is no exact replacement technology. Please use the font facilities in the Cocoa text system and Core Text instead.

FontSync is an API that provides a way for your application to identify fonts based upon the content of the font, rather than just the font name. Your application can use FontSync to compare fonts that are available on different computers. This document is relevant for anyone who is writing a text-intensive application that must minimize font mismatch errors when a file is moved from one computer to another. To use this document, you should understand the basics of fonts and be familiar with FontSync references and profiles.

Carbon supports FontSync. However, in Mac OS X, Apple recommends that you use FontSync only in OS X version 10.1 and later.

Functions by Task

Determining Availability, Version, and Feature Information

Providing User Interface Support

Searching by Font Reference

Working With FontSync Profiles

Working With FontSync References

Functions

FNSProfileCompact

Compacts a font profile.

OSStatus FNSProfileCompact (
   FNSFontProfile iProfile
);

Parameters

iProfile: A font profile reference. Pass a reference to the font profile you wish to compact. The profile must be editable (that is, opened with read/write access).

Return Value

A result code. See “FontSync Result Codes.” The result code kFNSBadProfileVersionErr indicates that a font profile has an unsupported format version. 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. FNSProfileCompact may return File Manager errors.

Discussion

The FNSProfileCompact function eliminates excess space created when creating a font profile (that is, the space you designate for not-yet-existent font references). This space is necessary to minimize growing the file and shuffling data. If a profile has not been opened for read/write access, FNSProfileCompact simply returns without doing anything.

You should call FNSProfileCompact before closing a profile that has been edited.

Version Notes

Available beginning with FontSync 1.0.

Availability

Available in CarbonLib 1.0 and later when Font Sync 1.0 or later is present.
Available in Mac OS X 10.0 and later.
Not available to 64-bit applications.

Declared In

FontSync.h

Data Types

FNSFeatureFlags

Represents a mask that you can use to determine available FontSync features.

typedef UInt32 FNSFeatureFlags;

Discussion

The FNSFeatureFlags type defines a bit mask your application can use to determine available FontSync features. The function FNSSysInfoGet passes back a mask of this type in the oFeatures field of the FNSSysInfo structure in the ioInfo parameter. You can use this mask to determine available FontSync features.

Version Notes

Available beginning with FontSync 1.0. In FontSync 1.0, the value is 0, since no feature flags are defined.

Availability

Available in Mac OS X v10.0 and later.

Declared In

FontSync.h

FNSFontProfile

Represents a reference to a font profile.

typedef struct OpaqueFNSFontProfile * FNSFontProfile;

Discussion

The FNSFontProfile type is a reference to an opaque structure containing a collection of font references. It defines a set of fonts on the user’s system. Although you do not need to use font profiles to iterate, identify, and match fonts on the user’s system, they are necessary in building font menus and other font selection human interface elements.

You pass a font profile to FontSync functions that manipulate font profiles. A font reference is passed back by functions that create font profiles. For a description of these functions, see “Working With FontSync Profiles.”

Version Notes

Available beginning with FontSync 1.0.

Availability

Available in Mac OS X v10.0 and later.

Declared In

FontSync.h

FNSFontReference

Represents a reference to a font reference.

typedef struct OpaqueFNSFontReference * FNSFontReference;

Discussion

The FNSFontReference type is a reference to an opaque structure containing information about a font. Some of the data contained in a font reference includes the QuickDraw font family name, ATSUI-visible font name, type of font, font version, checksums of the data, and information from the font name table.

You pass a font reference to FontSync functions that manipulate font references. A font reference is passed back by functions that create font references. For a description of these functions, see “Working With FontSync References.”

Version Notes

Available beginning with FontSync 1.0.

Availability

Available in Mac OS X v10.0 and later.

Declared In

FontSync.h

FNSSysInfo

Contains FontSync version and feature information.

struct FNSSysInfo {
   FNSObjectVersion iSysInfoVersion;
   FNSFeatureFlags oFeatures;
   FNSObjectVersion oCurRefVersion;
   FNSObjectVersion oMinRefVersion;
   FNSObjectVersion oCurProfileVersion;
   FNSObjectVersion oMinProfileVersion;
   UInt16 oFontSyncVersion;
};
typedef struct FNSSysInfo FNSSysInfo;

Fields

iSysInfoVersion: On input, the version of this parameter block structure. In FontSync 1.0, the version number of this structure is 1. Pass the constant kFNSCurSysInfoVersion, described in “Version Constants.” For more information, see the discussion.
oFeatures: On output, the FontSync features that are available. In FontSync 1.0, no feature flags are defined.
oCurRefVersion: On output, the current font reference format version supported by the FontSync library.
oMinRefVersion: On output, the oldest font reference format version supported by the FontSync library.
oCurProfileVersion: On output, the current font profile format version supported by the FontSync library.
oMinProfileVersion: On output, the oldest font profile format version supported by the FontSync library.
oFontSyncVersion: On output, a binary-coded decimal value indicating the version of FontSync currently running. The high-order 8 bits give the major version, the next four give the minor version, and the last four give the revision. For example, version 1.0 would be encoded as 0x0100.

Discussion

Before calling the function FNSSysInfoGet, you should fill in the iSysInfoVersion field of this structure with the version of this structure. Pass the constant kFNSCurSysInfoVersion, described in “Version Constants,” to represent the current version. FNSSysInfoGet fills in the remaining fields and passes back the structure in the ioInfo parameter. The information it provides includes the version of FontSync running in the current context and available features, as well as the current and oldest font reference and profile format versions supported by the FontSync library.

New fields may be added to the end of the structure in future versions of FontSync. FontSync uses the iSysInfoVersion field to determine which version of the structure you are using. The value of the current version constant kFNSCurSysInfoVersion will change accordingly.

Version Notes

Available beginning with FontSync 1.0. In FontSync 1.0, the value of the iSysInfoVersion field is 1. The value of the oFeatures field is 0, since no feature flags are defined.

Availability

Available in Mac OS X v10.0 and later.

Declared In

FontSync.h

Constants

Matching Options

Represent a mask that you can use to set and determine default match options.

typedef UInt32 FNSMatchOptions;
enum {
   kFNSMatchNames = 0x00000001,
   kFNSMatchTechnology = 0x00000002,
   kFNSMatchGlyphs = 0x00000004,
   kFNSMatchEncodings = 0x00000008,
   kFNSMatchQDMetrics = 0x00000010,
   kFNSMatchATSUMetrics = 0x00000020,
   kFNSMatchKerning = 0x00000040,
   kFNSMatchWSLayout = 0x00000080,
   kFNSMatchAATLayout = 0x00000100,
   kFNSMatchPrintEncoding = 0x00000200,
   kFNSMissingDataNoMatch = 0x80000000,
   kFNSMatchAll = 0xFFFFFFFF,
   kFNSMatchDefaults = 0
};

Constants

kFNSMatchNames

If the bit specified by this mask is set, all significant font names must match. This includes the QuickDraw Text family, ATSUI, unique, full, manufacturer, and version names. Note that the PostScript names are also examined as part of the kFNSMatchPrintEncoding option.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchTechnology

If the bit specified by this mask is set, scaler technologies must match. It is possible to match other parts of the font across different technologies, but this is not supported by FontSync 1.0. As a result, even if this bit is not set, fonts of different technologies will probably not match under any other criteria.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchGlyphs

If the bit specified by this mask is set, glyph repertoires and outline/bitmap data must match.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchEncodings

If the bit specified by this mask is set, the 'cmap' tables must match. If the order of the 'cmap' tables is different, although the tables are the same, this may be considered a mismatch, since it can cause QuickDraw Text to use a different 'cmap'table.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchQDMetrics

If the bit specified by this mask is set, metrics used by QuickDraw Text must match. This includes the effect of fractEnable and any metric information in the 'FOND' resource.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchATSUMetrics

If the bit specified by this mask is set, metrics used by ATSUI must match. This includes both horizontal and vertical metrics.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchKerning

If the bit specified by this mask is set, kerning data must match.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchWSLayout

If the bit specified by this mask is set, layout information given by an 'itl5' table, whether attached directly to the font or the one provided in the script bundle, must match.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchAATLayout

If the bit specified by this mask is set, advanced layout information such as that used by ATSUI, must match. This includes such things as ligature and morphing tables. OpenType-style layout information is included in this option.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchPrintEncoding

If the bit specified by this mask is set, PostScript names and 'FOND' re-encoding vectors must match. Note that it is an error for a font’s internal PostScript name to be different from the one in the 'FOND', but FontSync will record both and consider them separately.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMissingDataNoMatch

If the bit specified by this mask is set, FontSync will report font reference mismatches when both fonts are missing data needed by a selected option. This is useful, since some older fonts may not have all the data needed for matching newer fonts. This makes the mask constant kFNSMatchAll specify the most stringent possible match criteria.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchAll

If the bit specified by this mask is set, all of the match options must match. In this case, the bit specified by the mask constant kFNSMissingDataNoMatch is also set, asserting the most stringent possible match criteria.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSMatchDefaults

If this constant is specified, the global default match criteria established by the API are used (that is, use all of the options described above in the match). If the user changes the FontSync Control Panel settings, that becomes the new default. This constant basically says to use whatever the user has set.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

Discussion

The FNSMatchOptions enumeration defines masks your application can use to set or test match option bits. You can use this mask with the functions FNSReferenceMatch, FNSProfileMatchReference, FNSReferenceMatchFonts, and FNSReferenceMatchFamilies to set the match options used during font comparison. If you wish, your application can specify options that are different from the user’s preferences via this mask. You can use this mask to test the match option bits produced by the function FNSMatchDefaultsGet, thereby obtaining the default match options to use in a font comparison. You can also use this mask to test the match option bits produced by the function FNSReferenceMatch, thereby determining the match options under consideration that did not match.

At least one of the match options must be set. Having all of these bits clear is equivalent to saying “don’t look at anything,” which would allow any font to match. Since having all flags clear is nonsensical, the value of the mask constant kFNSMatchDefaults is 0. Setting undefined bits does not generate an error and provides backward compatibility.

Version Notes

Available beginning with FontSync 1.0.

Font Profile Constants

Represent the file type and default creator code of a font profile.

enum {
   kFNSCreatorDefault = 0,
   kFNSProfileFileType = 'fnsp'
};

Constants

kFNSCreatorDefault

Assigns a file creator code instead of using one of your own. Pass this constant in the iCreator parameter of the function FNSProfileCreate.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSProfileFileType

The file type of a profile. It is not used in the API, but is provided for convenience. For example, you can use it to put up a Navigation Services dialog box to select a profile.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

Version Notes

Available beginning with FontSync 1.0. In FontSync 1.0, if you specify the constant kFNSCreatorDefault in the iCreator parameter of the function FNSProfileCreate, FontSync assigns the creator code 'fns'.

Version Constants

Represents version information.

typedef UInt32 FNSObjectVersion;
enum {
   kFNSVersionDontCare = 0,
   kFNSCurSysInfoVersion = 1
};

Constants

kFNSVersionDontCare

Specifies the most recent font reference or font profile version supported by the FontSync library, regardless of version number. In FontSync 1.0, the most recent version for both font references and profiles is version 1. You pass this constant in the iDesiredVersion parameter of the functions FNSSysInfo, FNSSysInfoGet, and FNSProfileCreate.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

kFNSCurSysInfoVersion

Identifies the current version of the parameter block structure FNSSysInfo returned by the function FNSSysInfoGet. You pass this constant in the iSysInfoVersion field of the system information structure. The version of the structure used by FontSync 1.0 is version 1.

Available in Mac OS X v10.0 and later.

Declared in FontSync.h.

Discussion

You can pass the kFNSVersionDontCare constant in the iDesiredVersion parameter of the functions FNSReferenceCreate, FNSReferenceCreateFromFamily, and FNSProfileCreate, to specify the most recent font reference or font profile version supported by the FontSync library. You can use the kFNSCurSysInfoVersion constant in the iSysInfoVersion field of the structure FNSSysInfo to indicate the current version of the structure.

Result Codes

The most common result codes returned by FontSync are listed below.

Result Code	Value	Description
`kFNSInvalidReferenceErr`	-29580	Returned by FontSync functions that operate on font references to indicate that the specified font reference is invalid. This can also be returned by the function `FNSReferenceUnflatten` if the reconstructed reference is bad. Available in Mac OS X v10.0 and later.
`kFNSBadReferenceVersionErr`	-29581	Returned by FontSync functions that operate on font references to indicate that the 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 This is also be returned by font reference creation functions if an unsupported reference version was requested. Available in Mac OS X v10.0 and later.
`kFNSInvalidProfileErr`	-29582	Returned by FontSync functions that operate on font profiles to indicate that the profile does not have a valid structure. Available in Mac OS X v10.0 and later.
`kFNSBadProfileVersionErr`	-29583	Returned by FontSync functions that operate on font profiles to indicate that the 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. This is also be returned by font profile creation functions if an unsupported profile version was requested. Available in Mac OS X v10.0 and later.
`kFNSDuplicateReferenceErr`	-29584	Returned by the function `FNSProfileAddReference` to indicate that the font reference being added already exists in the profile. Available in Mac OS X v10.0 and later.
`kFNSMismatchErr`	-29585	Indicates that either a reference did not match, the reference you wish to remove is not in the profile, or that no font names were recorded in the reference. Available in Mac OS X v10.0 and later.
`kFNSInsufficientDataErr`	-29586	Returned by the functions `FNSReferenceMatch`, `FNSReferenceGetFamilyInfo`, `FNSReferenceFindName`, and `FNSReferenceGetIndName` to indicate that the mask constant `kFNSMissingDataNoMatch` has been set and both references being compared are missing the same data. Available in Mac OS X v10.0 and later.
`kFNSBadFlattenedSizeErr`	-29587	Returned by the function `FNSReferenceUnflatten` to indicate that the specified size doesn’t match the size recorded in the flattened reference or that the size was not large enough for a flattened reference. Available in Mac OS X v10.0 and later.
`kFNSNameNotFoundErr`	-29589	Returned by the function `FNSReferenceFindName` to indicate that there was no name in the font reference that matched the given parameters. Available in Mac OS X v10.0 and later.

Last updated: 2008-10-01

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.