Changes in Other C APIs

This chapter discusses 64-bit changes in other C APIs commonly used by Carbon applications. The APIs are listed in alphabetical order.

Alias Manager

CoreServices: Aliases.h

Alias Manager functions that use the FSSpec type or other deprecated types such as CInfoPBPtr are not available to 64-bit applications. Refer to Alias Manager Reference for detailed information about function availability.

Apple Event Manager

ApplicationServices: AppleEvents.h and related headers

Carbon: AEInteraction.h

If your 64-bit application uses the Apple Event Manager:

Apple Graphics Library (AGL)

AGL: agl.h and related headers

Apple Graphics Library is a windowing system interface for OpenGL, specifically designed for the Carbon environment. AGL is not supported for use in 64-bit applications. For information about setting up an OpenGL drawing environment in Cocoa, see Cocoa Drawing Guide. For comprehensive information about OpenGL support in OS X, and for detailed examples of how to integrate OpenGL into a Cocoa application, see OpenGL Programming Guide for Mac.

Apple Type Services for Fonts

ApplicationServices: ATSFont.h, ATSTypes.h

Apple Type Services for Fonts functions that use the FSSpec type are deprecated and are not available to 64-bit applications. The ATSPoint data type is defined as CGPoint in 64-bit applications.

Apple Type Services for Unicode Imaging (ATSUI)

ApplicationServices: ATSUnicode.h and related headers

Most functions in ATSUI are not available to 64-bit applications. Refer to ATSUI Reference for detailed information about function availability. You should use Core Text or, if possible, the Cocoa text system. To learn about these technologies, see Core Text Programming Guide and Text Layout Programming Guide.

CFNetwork

CoreServices: CFNetwork.h and related headers

Several CFNetwork functions now return the standard CFIndex type. The CFNetDiagnosticStatus type has changed to use the CFIndex type.

Code Fragment Manager

CoreServices: CodeFragments.h

The Code Fragment Manager is not available to 64-bit applications. You should use the Mach-O executable format instead. For more information, see Mach-O Programming Topics.

Collection Manager

CoreServices: Collections.h

Unlike most other managers, the Collection Manager is not being expanded to 64-bit byte counts; it continues to take and return 32-bit byte counts. Function parameters that are pointers are, of course, expanded to 64 bits.

If you’re currently using the Collection Manager, consider updating your software to use Core Foundation collection types such as CFMutableArray. For more information, see Collections Programming Topics for Core Foundation.

Color Picker Manager

Carbon: ColorPicker.h

Carbon applications use the Color Picker Manager to display a color selection window. The Color Picker Manager is not supported for use in 64-bit applications. You should use Cocoa to display the standard color selection window. For more information, see Color Programming Topics.

ColorSync Manager

ApplicationServices: ColorSync.h and related headers

Carbon: CMCalibrator.h

Many ColorSync Manager functions, data types, and constants that are rarely used, no longer recommended, or dependent on deprecated data types such as FSSpec are not available to 64-bit applications. For example, the following are no longer available:

Component Manager

CoreServices: Components.h

Component Manager functions that use the FSSpec type, as well as four other obsolete functions, are not available to 64-bit applications. The following table lists these functions and their replacements:

Removed Function

Replacement Function

RegisterComponentFile

RegisterComponentFileRef

RegisterComponentFileEntries

RegisterComponentFileRefEntries

ComponentFunctionImplemented

CallComponentCanDo

GetComponentVersion

CallComponentVersion

ComponentSetTarget

CallComponentTarget

GetComponentIconSuite

GetIconRefFromComponent

On 64-bit architectures, the packing mechanism for the parameters described by the ComponentParameters structure has changed. The params array is a true array with 64-bit arguments. The number of arguments is computed by dividing the value in the paramSize field by sizeof(long), which is 8 bytes in a 64-bit component. If you’re writing a 64-bit component and you supply a glue function that’s used to build the ComponentParameters structure, you need to update your glue code.

Core Audio

CoreAudio: CoreAudio.h and related headers

AudioToolbox: AudioToolbox.h and related headers

AudioUnit: AudioUnit.h and related headers

In the Core Audio framework, the Apple-supplied Carbon views (the generic Carbon view, and the EQ and DLS Synth custom views) are not available to 64-bit applications. In general, functions that use the FSSpec type are not available.

In the Audio Toolbox framework, the following are not available:

In the Audio Unit framework, the following are not available:

Core Foundation

CoreFoundation: CoreFoundation.h and related headers

Four Core Foundation scalar types are changing from 32 bits to 64 bits on 64-bit architectures: CFTypeID, CFOptionFlags, CFHashCode, and CFIndex. Although the CFOptionFlags type is growing, the high 32 bits may not be used for several years, because flag parameters defined in the upper range will not be usable by 32-bit programs.

Date, Time, and Measurement Utilities

CoreServices: DateTimeUtils.h, UTCUtils.h

Most of the functions in Date, Time, and Measurement Utilities have been superseded by Core Foundation functions and are not available to 64-bit applications. For information about replacements, see Date, Time, and Measurement Utilities Reference.

Desktop Manager

CoreServices: Files.h

The Desktop Manager is not available to 64-bit applications. You should use Icon Services and Launch Services instead. For more information, see Obtaining and Using Icons With Icon Services and Launch Services Programming Guide.

Device Manager

CoreServices: Files.h

The Device Manager is not available in OS X v10.5 and later. The functions formerly declared in Devices.h have been moved into the 32-bit File Manager and deprecated. You should use the File Manager instead.

Dictionary Manager

ApplicationServices: Dictionary.h

The Dictionary Manager is deprecated in OS X v10.5 and is not available to 64-bit applications. For related information, see Language Analysis Manager.

Dictionary Services lets you create your own custom dictionaries that users can access through the Dictionary application. You also use these services to access dictionaries programatically and to support user access to dictionary look-up through a contextual menu. To learn more about Dictionary Services, see Dictionary Services Programming Guide.

Display Manager

ApplicationServices: Displays.h

The Display Manager is deprecated and is not available to 64-bit applications. The GDHandle data type, and functions that use this type, are no longer available. You must use the CGDirectDisplayID data type and Quartz Display Services instead. For more information, see Quartz Display Services Reference.

File Manager

CoreServices: Files.h

In the File Manager, deprecated functions as well as a number of data types and constants are not available to 64-bit applications. Refer to File Manager Reference for detailed information about function availability.

The FSSpec data type is replaced by the opaque FSRef type. (The FSSpec type continues to exist so that functions that merely pass along an FSSpec object don't have to change.) Functions that actually use or provide FSSpec information are deprecated. Functions that operate on Pascal strings are also deprecated. The File Manager provides replacement functions that use the FSRef type and Unicode strings to facilitate the 64-bit transition.

Many functions that return reference numbers now return a standard data type called FSIORefNum, which is defined as a 16-bit value on 32-bit architectures and a 32-bit value on 64-bit architectures. Another new standard type, FSVolumeRefNum, is defined as a 16-bit value on all architectures. You should start using the FSIORefNum and FSVolumeRefNum types to store reference numbers in your applications.

Folder Manager

CoreServices: Folders.h

The deprecated functions in the Folder Manager are not available to 64-bit applications. Refer to Folder Manager Reference to learn which functions are deprecated.

A new function named GetFolderNameUnicode replaces GetFolderName.

Font Manager

ApplicationServices: Fonts.h

The Font Manager is not available to 64-bit applications. You should use Core Text instead. For more information, see Core Text Programming Guide.

Fonts Window Services

Carbon: FontPanel.h

Carbon applications use Fonts Window Services to display a font selection window. Fonts Window Services is not supported for use in 64-bit applications. You should use Cocoa to display the standard Fonts window. For more information, see Font Panel Programming Topics.

Icon Services and Utilities

ApplicationServices: Icons.h

CoreServices: IconsCore.h, IconStorage.h

Icon Utilities functions and data types, which are based on QuickDraw, are not available to 64-bit applications. These include data types that support classic icon formats such as 'ICON', 'cicn', and icon suites, and functions that use these data types. You must use the IconRef data type or a CGImage to represent an icon.

Deprecated functions in Icon Services are not available to 64-bit applications. Refer to Icon Services and Utilities Reference to learn which functions are deprecated.

Image Capture

Carbon: ImageCapture.h and related headers

In ICAApplication.h, the following opaque types are defined as UInt32 instead of as pointers:

ICAConnectionID
ICAEventDataCookie
ICAObject
ICAProperty
ICAScannerSessionID
ICASessionID

Keychain Manager

Carbon: KeychainHI.h

CoreServices: KeychainCore.h

The Keychain Manager function KCMakeKCRefFromFSSpec is not available to 64-bit applications. Note that the Keychain Manager has been superseded by Keychain Services. For more information, see Keychain Services Programming Guide.

Language Analysis Manager

ApplicationServices: LanguageAnalysis.h

The Language Analysis Manager is not available to 64-bit applications. You should use CFStringTokenizer in the Core Foundation framework instead. For more information, see CFStringTokenizer Reference.

CFStringTokenizer was introduced in OS X v10.5 to support typical tasks of internationalized applications. CFStringTokenizer let you tokenize a string of text into words, sentences or paragraphs in a language-neutral way (that is, you can tokenize a string without knowing the language.) It supports languages such as Japanese and Chinese that do not delimit words by spaces, and it can de-compound German compounds. You can obtain a Latin transcription for tokens. CFStringTokenizer also provides language identification.

Launch Services

CoreServices: LaunchServices.h and related headers

In Launch Services, two obsolete fields in the LSItemInfoRecord data structure are not available to 64-bit applications.

Mathematical and Logical Utilities

CoreServices: FixMath.h, Math64.h, fp.h, ToolUtils.h

Several existing functions in Mathematical and Logical Utilities have been changed to take arguments of type SInt32 instead of type long, or to return a value of type SInt32 instead of type long. For example, see the functions Fix2Long and Long2Fix in CoreServices/CarbonCore/FixMath.h.

Memory Management Utilities

CoreServices: OSUtils.h

The deprecated functions in Memory Management Utilities are not available to 64-bit applications. Refer to Memory Management Utilities Reference to learn which functions are deprecated.

The function MakeDataExecutable is not available. You should use the BSD function mprotect instead.

Memory Manager

CoreServices: MacMemory.h

The deprecated Memory Manager functions are not available to 64-bit applications. Refer to Memory Manager Reference to learn which functions are deprecated. Several obsolete data structures such as Zone are also not available.

The BlockMove, BlockMoveData, and BlockZero family of functions are not available; use the BSD functions memmove and bzero instead.

Pointer-based data types such as Ptr and Handle are now 64-bit types.

Multiprocessing Services

CoreServices: Multiprocessing.h, MultiprocessingInfo.h

Two Multiprocessing Services data types formerly defined as UInt32 have changed:

typedef ItemCount TaskStorageIndex;
typedef LogicalAddress TaskStorageValue;

The function MPDataToCode is not available to 64-bit applications. You should use the BSD function mprotect instead.

Printing

In OS X v10.5, the Carbon Printing Manager has been divided into two C APIs called Carbon Printing and Core Printing.

Carbon Printing is used by Carbon applications to present a user interface for printing. Carbon Printing includes functions to display the Page Setup and Print dialogs, and to execute a print loop that displays a print status dialog.

Core Printing is used for printing tasks that do not display a user interface. Any application can use this API, although Cocoa applications rarely need to use it.

Printing API changes that affect 64-bit applications are described below.

Carbon Printing

Carbon: PMApplication.h, PMApplicationDeprecated.h

Carbon Printing is not available to 64-bit applications. A 64-bit application with a Cocoa user interface should use Cocoa to display and customize printing dialogs, and to execute print jobs. For information on printing in Cocoa, see Printing Programming Guide for Mac.

Core Printing

ApplicationServices: PMCore.h, PMCoreDeprecated.h, PMDefinitions.h, PMDefinitionsDeprecated.h

Core Printing is available to 64-bit applications. However, most deprecated functions, data types, and constants are not available. Refer to Core Printing Reference for detailed information about function availability.

Deprecated functions include:

  • Functions that use or assume the availability of QuickDraw

  • Functions used to interleave PostScript and QuickDraw commands (the so-called “PICT with PostScript” document format)

  • Functions that act on a current session rather than an explicit PMPrintSession object

  • Functions that act on a current printer rather than an explicit PMPrinter object

  • Functions that use or return Mac OS 9–style print records

  • Functions that use or return handles

  • A number of functions relevant only in Mac OS 9 and earlier

Other Printing Interfaces

Some additional changes have been made in the OS X printing system that are related to 64-bit software development:

  • You cannot build a 64-bit version of a printing dialog extension based on the CFPlugIn architecture described in Extending Printing Dialogs. If you’re a printer vendor and you want to build a 64-bit version of a plug-in that adds custom panes to the Print dialog, you need to use the newer Cocoa-based printing dialog extension API. For more information, see the header file Carbon/Print/PDEPluginInterface.h and the sample project OutputBinsPDE, which is located in /Developer/Examples/Printing/Printer.

  • To get information from PostScript printer description (PPD) files in a 64-bit application, you must use CUPS instead of PPDLib. See the functions, data types, and constants declared in /usr/include/cups/ppd.h.

  • If you plan to write a 64-bit printer driver, you must write a CUPS filter instead of a traditional printer module. Note that there is no specific need to have a 64-bit driver unless you think you will get better performance or need access to larger amounts of memory.

  • You cannot build a 64-bit version of a printer browser. You can use the function PMServerLaunchPrinterBrowser to display the standard printer browser.

Process Manager

ApplicationServices: Processes.h

Several Process Manager data structures with fields that refer to the FSSpec type are not available to 64-bit applications. The Process Manager provides 64-bit versions of these data structures with fields that refer to the FSRef type.

QuickDraw

ApplicationServices: QuickDraw.h and related headers

QuickDraw graphics ports are not supported. Consequently, the entire drawing API has been removed from 64-bit QuickDraw. Functions that manipulate regions and simple data structures (Point and Rect) are still available, but you cannot use QuickDraw to draw in a 64-bit application. To learn about other drawing APIs, see Quartz Programming Guide for QuickDraw Developers and Cocoa Drawing Guide.

PICT files cannot be rendered any more, not even with the function QDPictDrawToCGContext. They need to be converted to PDF or other image formats supported by Image I/O.

The Picture Utilities API is deprecated and is not available to 64-bit applications.

QuickTime

QuickTime: QuickTime.h and related headers

The QuickTime C APIs are not available to 64-bit applications. For these applications, the QuickTime Kit Objective-C classes are the primary interface into QuickTime. For example, if you use the QuickTime C API to play movies and you want to build a 64-bit version of your application, use the QuickTime Kit and display the movie in a Cocoa window. The QuickTime Kit is described in detail in QuickTime Kit Programming Guide.

Almost all of the QuickTime Kit classes, methods, and functions are supported, with one major exception: methods that take or return native QuickTime identifiers (in particular, Movie, MovieController, Track, and Media). For example, you cannot use the quickTimeMovie method in the QTMovie class to “dip down” into the QuickTime C APIs.

The following is a complete list of the QuickTime Kit methods that are not available to 64-bit applications.

In the QTMovie class:

+ (id)movieWithQuickTimeMovie:(Movie)movie
    disposeWhenDone:(BOOL)dispose
    error:(NSError **)errorPtr;
- (id)initWithQuickTimeMovie:(Movie)movie
    disposeWhenDone:(BOOL)dispose
    error:(NSError **)errorPtr;
- (Movie)quickTimeMovie;
- (MovieController)quickTimeMovieController;

In the QTTrack class:

+ (id)trackWithQuickTimeTrack:(Track)track
    error:(NSError **)errorPtr;
- (id)initWithQuickTimeTrack:(Track)track
    error:(NSError **)errorPtr;
- (Track)quickTimeTrack;

In the QTMedia class:

+ (id)mediaWithQuickTimeMedia:(Media)media
    error:(NSError **)errorPtr;
- (id)initWithQuickTimeMedia:(Media)media
    error:(NSError **)errorPtr;
- (Media)quickTimeMedia;

The QuickTime Music Architecture (QTMA) is not available to 64-bit applications. As an alternative, you should use Core Audio for audio and MIDI application development.

Resource Manager

CoreServices: Resources.h

Resource Manager functions that use the FSSpec type for creating and opening resource files are not available to 64-bit applications.

The Resource Manager introduces several new standard types:

No code changes are necessary in order for your application to call functions that use these new types. You should adapt the ResFileRefNum type to declare local instances of resource reference numbers.

Script Manager

CoreServices: Script.h

The Script Manager is deprecated, and most Script Manager functions are not available to 64-bit applications. Refer to Script Manager Reference for detailed information about function availability.

Sound Manager

Carbon: Sound.h

The Sound Manager is deprecated in OS X v10.5 and is not available to 64-bit applications. You should use Core Audio instead. For general information about Core Audio, see Core Audio Overview. For information about writing audio units, see Audio Unit Programming Guide.

Speech Recognition Manager

Carbon: SpeechRecognition.h

Some function parameter types have changed; for example, parameters of type Size are now of type SInt32. User-supplied callback data is now of type SRefCon.

Speech Synthesis Manager

ApplicationServices: SpeechSynthesis.h

A number of parameters and fields of type long are now of type SInt32. User-supplied callback data is now of type SRefCon.

Text Utilities

Carbon: TypeSelect.h

CoreServices: TextUtils.h, StringCompare.h, NumberFormatting.h

Most of the functions in Text Utilities are deprecated and are not available to 64-bit applications. (The only exception is the Munger utility function.) Refer to Text Utilities Reference to learn about replacements for deprecated functions.

Thread Manager

CoreServices: Threads.h

The underlying data type of ThreadID has changed from UInt32 to long:

typedef unsigned long ThreadID;

As a result, the ThreadID type is still mapped directly to the pthread_t type in 64-bit applications.

Translation Manager

Carbon: Translation.h, TranslationExtensions.h

The Translation Manager and Translation Extensions are not available to 64-bit applications. You should use Translation Services instead. For more information, see the header file ApplicationServices/HIServices/TranslationServices.h.

vImage

Accelerate: vImage.h and related headers

The vImage framework declares the data type vImage_AffineTransform to serve the same purpose as the Quartz data type CGAffineTransform. The intent is that applications could use these types interchangeably. For example, you might use Quartz functions to operate on values of type vImage_AffineTransform.

In 64-bit applications, these data types are no longer interchangeable. Values of type vImage_AffineTransform contain single-precision quantities while values of type CGAffineTransform contain double-precision quantities. As a result, 64-bit applications that assume these types are interchangeable may fail.