Carbon Compatibility Report

Report for: NuEdit2.0.7b2

Report date: 3/11/99

File Creator: NED2

Data gathered by analyzer version: 1.2

File Type: APPL

Data gathered on: 3/11/99


Summary

Test

Number

Analysis of Imports

Supported API

520

Supported with Modifications

12

Supported But Not Recommended

9

Unsupported API

25

Under Evaluation

8

Not in Universal Headers 3.1

3

Analysis of Access to Low Memory Addresses

Analysis of Resources Loaded into System Heap


Analysis of Imports

Supported with Modifications

Hardware Interfaces
Device Manager
Carbon will not support the Device Manager as an interface for installing or interacting with device drivers. However, you can continue to use the PBRead and PBWrite functions (and their variants) for reading and writing to open files.

In Mac OS X, code that communicates directly with hardware devices must use the IOKit API. Other types of code that have relied on the Device Manager interface in the past (such as desk accessories) should be converted into applications.

Note: The Serial Driver will be supported through a new set of functions similar to PBOpen, PBControl, PBStatus, etc., but specific to serial communication.

PBReadAsync

This function is only supported for reading from open files.

PBReadSync

This function is only supported for reading from open files.

PBWriteAsync

This function is only supported for writing to open files.

PBWriteSync

This function is only supported for writing to open files.
Human Interface Toolbox
Window Manager
Carbon will support the Window Manager. Be aware, however, that if you use custom window definition procedures (also known as WDEFs), you must compile them as PowerPC-native code. In addition:

* Your application must use the functions defined by the Window Manager whenever it creates and disposes of Window Manager data structures. For example, instead of directly creating and disposing of window records, applications must call such Window Manager functions as GetNewCWindow and DisposeWindow.

* You must revise your application so that it accesses Window Manager data structures only through accessor functions.

* You are encouraged to adopt the standard Mac OS 8 window definition procedures in your application. Applications that use the standard Mac OS 8 window definition procedures inherit the Mac OS 8 human interface appearance. Applications that use custom window definition procedures work correctly, but because custom definition procedures invoke their own drawing routines, Mac OS 8 can't draw these applications with the current appearance.

InvalRect

Calls InvalWindowRect, which takes a window pointer as an additional parameter.

InvalRgn

Calls InvalWindowRgn, which takes a window pointer as an additional parameter.

ValidRect

Calls ValidWindowRect, which takes a window pointer as an additional parameter.

ValidRgn

Calls ValidWindowRgn, which takes a window pointer as an additional parameter.
Low-Level Operating System Services
Memory Manager
Carbon will support the majority of the Memory Manager programming interface. Changes will primarily affect applications that use zones, system memory, or temporary memory. For example, temporary memory allocations in Mac OS X will be allocated in the application's address space. As a result, calling TempNewHandle will effectively be the same as calling NewHandle.

Carbon will not support current functions for accessing the system heap, but Apple will provide new routines to allocate shared and persistent memory. In addition, the virtual memory system in Mac OS X will introduce a number of changes in the addressing model.

The following Memory Manager functions are likely to change in Carbon: GZSaveHnd, MoreMasters, and TempNewHandle.

The following Memory Manager functions are still under evaluation: GetZone, HandleZone, InitZone, PtrZone, SetGrowZone, and SetZone. Please give us feedback on the importance of using subzones in your applications.

The following Memory Manager functions will not be supported in Carbon: MaxBlockSys, MaxMemSys, NewEmptyHandleSys, NewHandleSys, NewHandleSysClear, NewPtrSys, NewPtrSysClear, PurgeMemSys, PurgeSpaceSysContiguous, PurgeSpaceSysTotal, ReallocateHandleSys, RecoverHandleSys, RecoverMemSys, and SystemZone.

The following Virtual Memory functions are likely to change in Carbon: FlushMemory, MakeMemoryNonResident, MakeMemoryResident, and ReleaseMemoryData.

By adhering to the following guidelines, you can increase your application's compliance with Mac OS X memory management:

* Try to use memory only within your own application heap. Review the places where you allocate memory in the system heap.

* Do not pass pointers to data among applications through Apple events, Gestalt routines, or other means. For example, don't share Toolbox data structures between applications, because in Mac OS X, each application will run in its own protected address space.

* Do not use inline, hard-coded addresses.

* Do not use the following Memory Manager functions: EnterSupervisorMode, StripAddress, Translate24To32.

* Do not modify a field in a zone header to specify how many master pointer blocks are allocated by each call to the function MoreMasters. The Memory Manager will supply a new version of the MoreMasters function that allows you to specify the number of master pointer blocks to allocate. Note, however, that master pointer blocks do not need to be preallocated or optimized in the Mac OS X memory model, so the new function will provide the most benefit for applications running on previous versions of the Mac OS.

* Don't make assumptions about the layout of memory, such as the relative position of data stored in heaps, stacks, and other memory areas.

* Don't use the DisposePtr or DisposeHandle functions on pointers or handles allocated by Toolbox managers. For example, don't call the function DisposeHandle on a control allocated with the function NewControl--use DisposeControl instead.

* Because Mac OS X applications will run in a large, protected memory space, memory sizing routines such as MaxMem and FreeMem will work differently than they do now.

GZSaveHnd

MoreMasters

MoreMasters will have a longint parameter for specifying the number of master pointers to allocate in the block. Specifying a number less than 32 will result in 32 master pointers in the allocated block, the current standard allocation.

TempNewHandle

Temporary memory allocations will actually come from the applications's address space in Mac OS X. However, Carbon applications running under Mac OS 8.x will be able to get true temporary memory.
Process Manager
Carbon will support most of the Process Manager. The exception is the LaunchDeskAccessory function, which may not be supported (or it may simply do nothing).

Note that some Process Manager functions access a ProcessInfoRec data structure, which contains fields that are no longer applicable in a preemptively scheduled environment (for example, the processLocation, processFreeMem, and processActiveTime fields). Your application should avoid accessing such fields. Changes to the memory model may also affect certain fields.

GetProcessInformation

Some fields in the ProcessInfoRec structure may no longer be applicable.

Supported But Not Recommended

Human Interface Toolbox
Dialog Manager
Carbon will support the Dialog Manager. However, Apple encourages you to ensure that your application accesses Dialog Manager data structures only through the supplied accessor functions. The use of these accessor functions, to be provided soon, will give your application greater threading flexibility in Mac OS X. Furthermore, you are encouraged to use the functions provided for creating and disposing of Dialog Manager data structures. In Mac OS X, applications might not be allowed to create and dispose of Dialog Manager data structures except by calling Dialog Manager functions.

InitDialogs

InitDialogs does nothing. There is no need to initialize the Window Manager, because the shared library gets loaded as needed.
Menu Manager
Carbon will support the Menu Manager, with the following changes:

* Your application must use the functions defined by the Menu Manager whenever it creates and disposes of Menu Manager data structures. Some applications, for example, create menus by using the Resource Manager function GetResource (instead of the Menu Manager function GetMenu) and dispose of them by calling ReleaseResource instead of DisposeMenu. This practice is not supported in Carbon.

* The MenuInfo structure is opaque in Carbon. You must revise your application so that it accesses Menu Manager data structures only through accessor functions.

* There are several Menu Manager functions that deal with manipulating menu color information tables. Apple recommends that you stop using them. The Appearance Manager generally disregards these color tables and instead uses the colors defined for the current appearance.

* You are strongly encouraged to adopt the standard Mac OS 8 menu definition procedures (also known as MDEFs) in your application. Your menus will then inherit the systemwide appearance and, furthermore, take advantage of other Menu Manager enhancements planned for the future. Note, however, that if you must use custom menu definition procedures, you must compile them as PowerPC-native code.

InitMenus

InitMenus does nothing. There is no need to initialize the Menu Manager, because the shared library gets loaded as needed.
Window Manager
Carbon will support the Window Manager. Be aware, however, that if you use custom window definition procedures (also known as WDEFs), you must compile them as PowerPC-native code. In addition:

* Your application must use the functions defined by the Window Manager whenever it creates and disposes of Window Manager data structures. For example, instead of directly creating and disposing of window records, applications must call such Window Manager functions as GetNewCWindow and DisposeWindow.

* You must revise your application so that it accesses Window Manager data structures only through accessor functions.

* You are encouraged to adopt the standard Mac OS 8 window definition procedures in your application. Applications that use the standard Mac OS 8 window definition procedures inherit the Mac OS 8 human interface appearance. Applications that use custom window definition procedures work correctly, but because custom definition procedures invoke their own drawing routines, Mac OS 8 can't draw these applications with the current appearance.

InitWindows

InitWindows does nothing. There is no need to initialize the Window Manager, because the shared library gets loaded as needed.
Text and Other International Services
Date, Time, and Measurement Utilities
Carbon will fully support the Date, Time, and Measurement Utilities. However, some obsolete functions that are prefixed with IU (such as IUDateString and IUTimeString) may not be supported in the future.

IUDateString

Use DateString instead.

IUTimeString

Use TimeString instead.
Text Utilities
Carbon will fully support Text Utilities. However, some obsolete functions that are prefixed with IU (such as IUStringOrder and IUTextOrder) may not be supported in the future.

IUEqualPString

Use IdenticalString instead.

IUEqualString

Use IdenticalString instead.

IUMagIDPString

Use IdenticalText instead.

IUMagPString

Use CompareText instead.

Unsupported API

Graphics Services
Printing Manager
Carbon introduces substantial changes to the Printing Manager, which are summarized here. For more information, read the "Carbon Printing API" specification, available at <http://developer.apple.com/macosx/carbon/>

* The Print Record has been split into two separate entities: a PrintSettings object and a PageFormat object. Applications will be given references to these two privately defined data structures. These references are then used to query the Printing Manager for information contained within the objects.

* A consequence of splitting the Print Record and making it private is there are no fixed sizes. Applications will be able to "extend" both the PrintSettings and PageFormat objects. But applications must not assume a specific size when storing and retrieving a PageFormat with documents.

* The Printing Manager will supply functions for flattening and restoring both the PrintSettings and PageFormat object. When storing printing information with documents it will suffice to store just the PageFormat object. If older versions of your application store a print record with a saved document, you may continue to do so to provide backward compatibility.

* Application developers should reduce the use of calls that append items to print dialogs. We expect to provide a new panel-based interface in the near future.

* There are many improvements to the QuickDraw interfaces for Carbon, including new accessor functions and data structures that should be used. Please see the Carbon QuickDraw specification for more details.

* All print records use the "draft" style, not the "deferred" style, which implies that a print driver must handle the spooling if it wants to provide spooling for the user. Many, if not all, print drivers perform their own spooling and don't require applications to call PrPicFile() to implement spooling. Because it is rarely used, we are eliminating system level spooling code from the Printing Manager.

* The Printing Manager will now enforce an order in which some routines are called. Any routine used out of scope will return an error.

* All Printing Manager routines are only valid within a PMBegin/PMEnd block.

* PrintSettings and PageFormats are automatically disposed of during a PMEnd call.

PrClose

PrClose does nothing; you don't need to call it.

PrCloseDoc

In place of a print record, the Printing Manager uses a reference to an opaque, variable-length data structure.

PrClosePage

In place of a print record, the Printing Manager uses a reference to an opaque, variable-length data structure.

PrError

PrJobDialog

In place of a print record, the Printing Manager uses a reference to an opaque, variable-length data structure.

PrOpen

PrOpen performs nothing; you don't need to call it.

PrOpenDoc

In place of a print record, the Printing Manager uses a reference to an opaque, variable-length data structure.

PrOpenPage

In place of a print record, the Printing Manager uses a reference to an opaque, variable-length data structure.

PrPicFile

This function has become obsolete. Printer drivers perform their own spooling; therefore, applications end up not calling PrPicFile.

PrStlDialog

In place of a print record, the Printing Manager uses a reference to an opaque, variable-length data structure.

PrValidate

In place of a print record, the Printing Manager uses a reference to an opaque, variable-length data structure.

PrintDefault

In place of a print record, the Printing Manager uses a reference to an opaque, variable-length data structure.
QuickDraw Manager
Carbon will fully support QuickDraw.

In the past, parts of QuickDraw have been documented in Inside Macintosh as the Color Manager and Cursor Utilities. Note, however, that Inside Macintosh: Imaging with QuickDraw describes animated cursor functions, such as SpinCursor, that are available in the MPW programming environment and possibly in other environments, but not in system software. These animated cursor functions, which are defined in the MPW interface file CursorCtl.h, will continue to be supported in Carbon by MPW.

OpenCPort

Carbon applications should use CreateNewPort and DisposePort to open and close graphics ports.
Hardware Interfaces
Device Manager
Carbon will not support the Device Manager as an interface for installing or interacting with device drivers. However, you can continue to use the PBRead and PBWrite functions (and their variants) for reading and writing to open files.

In Mac OS X, code that communicates directly with hardware devices must use the IOKit API. Other types of code that have relied on the Device Manager interface in the past (such as desk accessories) should be converted into applications.

Note: The Serial Driver will be supported through a new set of functions similar to PBOpen, PBControl, PBStatus, etc., but specific to serial communication.

GetDCtlEntry

OpenDeskAcc

Desk accessories will not be supported in Carbon. A new mechanism will be provided for handling selections from the Apple menu.

PBCloseSync

Human Interface Toolbox
Menu Manager
Carbon will support the Menu Manager, with the following changes:

* Your application must use the functions defined by the Menu Manager whenever it creates and disposes of Menu Manager data structures. Some applications, for example, create menus by using the Resource Manager function GetResource (instead of the Menu Manager function GetMenu) and dispose of them by calling ReleaseResource instead of DisposeMenu. This practice is not supported in Carbon.

* The MenuInfo structure is opaque in Carbon. You must revise your application so that it accesses Menu Manager data structures only through accessor functions.

* There are several Menu Manager functions that deal with manipulating menu color information tables. Apple recommends that you stop using them. The Appearance Manager generally disregards these color tables and instead uses the colors defined for the current appearance.

* You are strongly encouraged to adopt the standard Mac OS 8 menu definition procedures (also known as MDEFs) in your application. Your menus will then inherit the systemwide appearance and, furthermore, take advantage of other Menu Manager enhancements planned for the future. Note, however, that if you must use custom menu definition procedures, you must compile them as PowerPC-native code.

DisableItem

Replaced by DisableMenuItem.

EnableItem

Replaced by EnableMenuItem.
Standard File Package
Carbon will not support the Standard File Package. You must use Navigation Services instead. Navigation Services 1.0 is compatible back to System 7.5.5.

To assist your transition efforts, Apple will provide source code that maps many common Standard File Package calls to their Navigation Services counterparts. Note, however, that this code provides an interim solution only--you will eventually need to adopt Navigation Services.

CustomGetFile

CustomPutFile

StandardPutFile

Window Manager
Carbon will support the Window Manager. Be aware, however, that if you use custom window definition procedures (also known as WDEFs), you must compile them as PowerPC-native code. In addition:

* Your application must use the functions defined by the Window Manager whenever it creates and disposes of Window Manager data structures. For example, instead of directly creating and disposing of window records, applications must call such Window Manager functions as GetNewCWindow and DisposeWindow.

* You must revise your application so that it accesses Window Manager data structures only through accessor functions.

* You are encouraged to adopt the standard Mac OS 8 window definition procedures in your application. Applications that use the standard Mac OS 8 window definition procedures inherit the Mac OS 8 human interface appearance. Applications that use custom window definition procedures work correctly, but because custom definition procedures invoke their own drawing routines, Mac OS 8 can't draw these applications with the current appearance.

GetAuxWin

Remove application reliance on AuxWinRec data structures; in the future, the information in these structures may be invalid or unavailable to applications.
Low-Level Operating System Services
File Manager
While Carbon will support most of the File Manager interface, there are a number of significant changes.

You should not access File Manager structures directly if accessor functions for the structure exist. For example, you should call PBGetFCBInfo rather than calling LMGetFCBSPtr and walking the FCB table.

Similarly, you should create file system specification (FSSpec) records using the functions PBMakeFSSpec or FSMakeFSSpec instead of filling in your own structures. File system specification records must contain a volume reference number, a parent directory, and a name. Substituting a working directory for the volume reference number or a full or partial pathname for the name is not supported.

File Manager functions that support MFS (the Macintosh file system) will not be supported in Carbon. These include

* functions, such as OpenWD and GetWDInfo, that manipulate working directories

* functions that identify a file or folder using a volume reference number and pathname but not a parent directory ID. You should use the HFS version of these calls (which use a parent directory ID) instead.

Functions that cannot be called by PowerPC applications (such as PBGetAltAccessSync and PBGetAltAccessAsync) will not be supported.

In general, you should use only documented File Manager interfaces in your application. For example, you should use a documented API call to get low memory information rather than access undocumented low memory global variables or vectors directly.

The default volume format for Carbon will be the Mac OS Extended format; in most cases you will not need to modify your application to gain this volume support.

Carbon may not support the File System Manager (FSM) as defined in the header file FSM.h. FSM plug-ins today often must make assumptions about File Manager data structures that may not be valid in Carbon. In addition, some plug-ins use 68K calling conventions when calling internal File Manager functions. Since the File System Manager was designed for a single-threaded file system, it cannot use the full threading capabilities of Mac OS X.

PBGetVInfoSync

Obsolete. Use PBHGetVInfoSync instead.
Memory Manager
Carbon will support the majority of the Memory Manager programming interface. Changes will primarily affect applications that use zones, system memory, or temporary memory. For example, temporary memory allocations in Mac OS X will be allocated in the application's address space. As a result, calling TempNewHandle will effectively be the same as calling NewHandle.

Carbon will not support current functions for accessing the system heap, but Apple will provide new routines to allocate shared and persistent memory. In addition, the virtual memory system in Mac OS X will introduce a number of changes in the addressing model.

The following Memory Manager functions are likely to change in Carbon: GZSaveHnd, MoreMasters, and TempNewHandle.

The following Memory Manager functions are still under evaluation: GetZone, HandleZone, InitZone, PtrZone, SetGrowZone, and SetZone. Please give us feedback on the importance of using subzones in your applications.

The following Memory Manager functions will not be supported in Carbon: MaxBlockSys, MaxMemSys, NewEmptyHandleSys, NewHandleSys, NewHandleSysClear, NewPtrSys, NewPtrSysClear, PurgeMemSys, PurgeSpaceSysContiguous, PurgeSpaceSysTotal, ReallocateHandleSys, RecoverHandleSys, RecoverMemSys, and SystemZone.

The following Virtual Memory functions are likely to change in Carbon: FlushMemory, MakeMemoryNonResident, MakeMemoryResident, and ReleaseMemoryData.

By adhering to the following guidelines, you can increase your application's compliance with Mac OS X memory management:

* Try to use memory only within your own application heap. Review the places where you allocate memory in the system heap.

* Do not pass pointers to data among applications through Apple events, Gestalt routines, or other means. For example, don't share Toolbox data structures between applications, because in Mac OS X, each application will run in its own protected address space.

* Do not use inline, hard-coded addresses.

* Do not use the following Memory Manager functions: EnterSupervisorMode, StripAddress, Translate24To32.

* Do not modify a field in a zone header to specify how many master pointer blocks are allocated by each call to the function MoreMasters. The Memory Manager will supply a new version of the MoreMasters function that allows you to specify the number of master pointer blocks to allocate. Note, however, that master pointer blocks do not need to be preallocated or optimized in the Mac OS X memory model, so the new function will provide the most benefit for applications running on previous versions of the Mac OS.

* Don't make assumptions about the layout of memory, such as the relative position of data stored in heaps, stacks, and other memory areas.

* Don't use the DisposePtr or DisposeHandle functions on pointers or handles allocated by Toolbox managers. For example, don't call the function DisposeHandle on a control allocated with the function NewControl--use DisposeControl instead.

* Because Mac OS X applications will run in a large, protected memory space, memory sizing routines such as MaxMem and FreeMem will work differently than they do now.

MaxApplZone

Runtime Services
Mixed Mode Manager
Mac OS X will not run 68K code, so the Mixed Mode Manager will no longer serve any useful purpose. However, Carbon will support universal procedure pointers (UPPs) transparently, so you do not have to change them or remove them from your code. You may want to keep Mixed Mode Manager calls in your application to maintain compatibility with the current version of the Mac OS. Mixed Mode Manager calls from Carbon applications running on Mac OS 8 will function normally.

NewRoutineDescriptor

Applications should use ProcPtrs for their own code and plug-ins, and use the system-supplied UPP creation functions (such as NewModalFilterProc) for Toolbox callback UPPs. You still need to dispose of those UPPs using DisposeRoutineDescriptor, so that any allocated memory can be cleaned up when your application is running on Mac OS 8.

Under Evaluation

Application Utilities
Speech Manager
Apple is investigating the extent to which Carbon will support the Speech Manager. Please give us feedback on the importance of this interface in your development efforts.

CountVoices

DisposeSpeechChannel

GetIndVoice

GetVoiceDescription

NewSpeechChannel

SpeakText

SpeechBusy

Low-Level Operating System Services
Memory Manager
Carbon will support the majority of the Memory Manager programming interface. Changes will primarily affect applications that use zones, system memory, or temporary memory. For example, temporary memory allocations in Mac OS X will be allocated in the application's address space. As a result, calling TempNewHandle will effectively be the same as calling NewHandle.

Carbon will not support current functions for accessing the system heap, but Apple will provide new routines to allocate shared and persistent memory. In addition, the virtual memory system in Mac OS X will introduce a number of changes in the addressing model.

The following Memory Manager functions are likely to change in Carbon: GZSaveHnd, MoreMasters, and TempNewHandle.

The following Memory Manager functions are still under evaluation: GetZone, HandleZone, InitZone, PtrZone, SetGrowZone, and SetZone. Please give us feedback on the importance of using subzones in your applications.

The following Memory Manager functions will not be supported in Carbon: MaxBlockSys, MaxMemSys, NewEmptyHandleSys, NewHandleSys, NewHandleSysClear, NewPtrSys, NewPtrSysClear, PurgeMemSys, PurgeSpaceSysContiguous, PurgeSpaceSysTotal, ReallocateHandleSys, RecoverHandleSys, RecoverMemSys, and SystemZone.

The following Virtual Memory functions are likely to change in Carbon: FlushMemory, MakeMemoryNonResident, MakeMemoryResident, and ReleaseMemoryData.

By adhering to the following guidelines, you can increase your application's compliance with Mac OS X memory management:

* Try to use memory only within your own application heap. Review the places where you allocate memory in the system heap.

* Do not pass pointers to data among applications through Apple events, Gestalt routines, or other means. For example, don't share Toolbox data structures between applications, because in Mac OS X, each application will run in its own protected address space.

* Do not use inline, hard-coded addresses.

* Do not use the following Memory Manager functions: EnterSupervisorMode, StripAddress, Translate24To32.

* Do not modify a field in a zone header to specify how many master pointer blocks are allocated by each call to the function MoreMasters. The Memory Manager will supply a new version of the MoreMasters function that allows you to specify the number of master pointer blocks to allocate. Note, however, that master pointer blocks do not need to be preallocated or optimized in the Mac OS X memory model, so the new function will provide the most benefit for applications running on previous versions of the Mac OS.

* Don't make assumptions about the layout of memory, such as the relative position of data stored in heaps, stacks, and other memory areas.

* Don't use the DisposePtr or DisposeHandle functions on pointers or handles allocated by Toolbox managers. For example, don't call the function DisposeHandle on a control allocated with the function NewControl--use DisposeControl instead.

* Because Mac OS X applications will run in a large, protected memory space, memory sizing routines such as MaxMem and FreeMem will work differently than they do now.

SetGrowZone

Not in Universal Headers 3.1

Unknown Group
Unknown Manager

ApplyThemeBackground

GetThemeBrushAsColor

GetThemeTextColor

 

Analysis of Access to Low Memory Addresses

Address
Access Type
Located in Function
Comments

No Invalid Access Detected

 

Analysis of Resources Loaded into System Heap

These resources have the system heap bit set. The resource name is included, if defined.

Resource Name
Type
ID
<none>
'patc'
0


Copyright 1998 Apple Computer, Inc. All rights reserved.