TweetFollow Us on Twitter

MACINTOSH C CARBON
MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
2001 K. J. Bricknell
Go to Contents

CHAPTER 5

CARBON AND UNIVERSAL PROCEDURE POINTERS

Introduction

Previous demonstration programs have called a function (AEInstallEventHandler) which takes a universal procedure pointer as a parameter; however, an explanation of this term has been delayed until this chapter because the AEInstallEventHandler calls were only incidental to the main purpose of those demonstrations. The demonstration programs at Chapter 7 are the first in which calls to a system software function which takes a universal procedure pointer as a parameter are central to the demonstration. As a brief but necessary prelude for what is to come, therefore, this chapter addresses the role of universal procedure pointers in the general scheme of things, when and why they were introduced, and their relevance in the Carbon environment.

In a sense, universal procedure pointers are a piece of historical baggage dragged into Carbon by Mac OS 8/9. They was first introduced with the so-called Universal Headers which, in turn, were introduced with the Power Macintosh. They had to with the ability of the Power Macintosh to run applications that use the instruction set of the Motorola 680x0 microprocessor (used in 680x0-based Macintoshes) as well as applications that use the native instruction set of the Power Macintosh's PowerPC microprocessor.

In the Chapter 7 demonstration programs, the system software function which takes a universal procedure pointer is TrackControl. This function is called by your application when a mouse-down event occurs in a control, such as a scroll bar. Prior to the introduction of the Power Macintosh and the associated introduction of the Universal Headers, the TrackControl prototype looked like this:

     Sint16  TrackControl(TrackControl(ControlHandle theControl,Point localPoint,
                          ProcPtr actionProc);

The actionProc a parameter is simply the address of an application-defined function, called a callback procedure (or, in C terminology, a callback function) that is called repeatedly while the mouse button remains down. In other words, the TrackControl function used to take a procedure pointer (or, in C terminology, a function pointer) in its actionProc parameter.

The Universal Headers, which, amongst other things, allow you to write Classic API source code capable of being compiled as either 680x0 code or native PowerPC code, changed the prototype for TrackControl to:

     ControlPartCode  TrackControl(ControlHandle theControl,Point startPoint,
                                   ControlActionUPP actionProc);

Notice that the third parameter is now of type ControlActionUPP. This means that the actionProc parameter now takes a universal procedure pointer. This prototype has been carried through to the Carbon headers, hence the necessity to gain a basic understanding of universal procedure pointers.

The 68LC040 Emulator and the Mixed Mode Manager

The Emulator

This ability of the Mac OS 8/9 system software to execute applications that use the instruction set of the Motorola 680x0 microprocessor as well as applications that use the native instruction set of the PowerPC microprocessor is provided by an emulator (the 68LC040 Emulator). The emulator, which is essentially a 680x0 microprocessor implemented in software, provides an execution environment that is virtually identical to the execution environment found on 680x0-based Macintoshes.

One important aspect of the 68LC040 emulator is that it made it possible for parts of the system software to remain as 680x0 code while other parts were progressively re-written, primarily for reasons of speed, as native PowerPC code. In this regard, it is important to understand that some of Mac OS 8/9 still remains as 680x0 code. For example, in Mac OS 8.6, parts of the Control Manager (including, possibly, TrackControl) remain in 680x0 code. For the purposes of explanation, the following assumes that, in Mac OS 8/9, TrackControl still exists as 680x0 code.

The Mixed Mode Manager

In Mac OS 8/9, the emulator works together with a manager called the Mixed Mode Manager. The Mixed Mode Manager manages mode switches between code in different instruction set architectures (ISAs).

Mode Switches

In Mac OS 8/9, mode switches are required when an application calls a system software function (or, indeed, any other code) that exists in a different ISA. For example:

  • When a PowerPC application invokes a system software function that exists only as 680x0 code, a mode switch is required to move from the native environment to the emulator environment. Then, when that system software function completes, another mode switch is required to return from the emulator to the PowerPC environment to allow the PowerPC application to continue executing.

    This situation can occur in a Carbon application running on Mac OS 8/9 because, as previously stated, not all of Mac OS 8/9 has been re-written as native PowerPC code.

  • When a 680x0 application running under the emulator calls a system software function that exists as native PowerPC code, a mode switch is required to move out of the emulator and into the native PowerPC environment. Then, when that system software function completes, another mode switch is required to return to the emulator and to allow the 680x0 application to continue executing.

    This situation cannot occur in a Carbon application running on Mac OS 8/9 because all Carbon applications must be compiled as native PowerPC code.

The Mixed Mode Manager operates transparently to most applications and other types of software, meaning that most cross-mode calls (calls to code in a different ISA from the caller's ISA) are detected automatically by the Mixed Mode Manager and handled without intervention by the calling software.

Intervention in Mode Switching

Sometimes, however, executable code needs to interact directly with the Mixed Mode Manager to ensure that a mode switch occurs at the correct time. When writing native PowerPC code, you only have to intervene in the mode-switching process when you execute code whose ISA might be different from the calling code. For example, when you pass the address of your application-defined action function (native PowerPC code) to TrackControl (680x0 code), the ISA of the code whose address you are passing is different from the ISA of the function you are passing it to. In such cases, you must ensure that the Mixed Mode Manager is called to make the necessary mode switch. You do this by explicitly signalling:

  • The type of code you are passing.

  • The code's calling conventions.

Indicating the ISA of a Callback Function - Routine Descriptors

You create a routine descriptor for a particular function to indicate the ISA of that function (see Fig 1).The first field of a routine descriptor (goMixedModeTrap) is an executable 680x0 instruction which invokes the Mixed Mode Manager. The Mixed Mode Manager having been called, it inspects the remaining fields of the routine descriptor to determine whether a mode switch is required. The Mixed Mode Manager is particularly interested in the routineRecords field.

The routineRecords field is an array of routine structures, each element of which describes a single function. In the simplest case, the array of routine structures contains a single element.

The ISA and procInfo fields are the most important fields in a routine structure:

  • ISA Field. The ISA field contains the ISA code of the function being described, and always contains one of these two constants:

         kM68kISA  = (ISAType) 0  MC680x0 architecture.
         KPowerPCISA  = (ISAType) 1  PowerPC Architecture.
    

  • procInfo Field. The procInfo field contains the function's function information, including the function's calling conventions and information about the function's parameters.

Creating a Routine Descriptor For a Control Action Function

Using the function NewControlActionUPP, you can create a routine descriptor for a control action function as follows, in which myControlAction is your application-defined control action function:

     ControlActionUPP myControlActionUPP;

     myControlActionUPP = NewControlActionUPP(myControlAction);

Notice that the result returned by NewControlActionUPP is of type ControlActionUPP. The UPP stands for a universal procedure pointer, which is defined to be either a 680x0 function pointer or a pointer to a routine descriptor (hence the term "universal"). Thus, in Mac OS 8/9, the effect of the call to NewControlActionUPP depends on whether it is executed in the 680x0 environment or the PowerPC environment:

  • In the 680x0 environment, NewControlActionUPP simply returns its first parameter, that is, a pointer to your application-defined control action function.

  • In the PowerPC environment, NewControlActionUPP creates a routine descriptor in your application heap and returns the address of that routine descriptor.

Effect of the Routine Descriptor

Once you have created the routine descriptor, you can later call TrackControl like this:

     TrackControl(myControl,myPoint,myControlActionUPP);

In Mac OS 8/9, if your application is a PowerPC application (as will be the case in Carbon), the value passed in the myControlActionUPP parameter is not the address of your action function itself, but the address of the routine descriptor. If a 680x0 version of TrackControl executes your action function, it begins by executing the instruction in the first field of the routine descriptor. That instruction invokes the Mixed Mode Manager, which inspects the ISA of the action function (contained in the ISA field of the routine structure). Since that ISA differs from the ISA of the TrackControl function, the Mixed Mode Manager causes a mode switch. (Of course, if TrackControl existed as PowerPC code, the ISAs would be identical, and the Mixed Mode Manager would simply execute the action function without switching modes.)

In short, you solve the problem of indicating a routine's ISA by creating a routine descriptor and by using the address of that routine descriptor (that is, a universal procedure pointer) where you would have used the address of the function (that is, a procedure pointer) in the 680x0 programming environment.

Disposing of Routine Descriptors

Disposing of routine descriptors is only necessary or advisable if you know that you will not be using the descriptor any more during the execution of your application or if you allocate a routine descriptor for temporary use only.

Functions Requiring Universal Procedure Pointers

Some of the functions for which universal procedure pointers must be created are as follows:

Function Type

Examples are at the Demonstration Programs Associated With:

Control action functions

Chapters 7, 14, 17, and 21.

Event filter functions

Chapters 4, 8, 14, and 21.

Apple event handling functions

Chapters 10, 18, and 26.

Key filter functions

Chapter 14.

Edit text validation functions

Chapter 14.

User pane drawing functions

Chapters 14 and 21.

User pane activate functions

Chapter 14.

Carbon event handlers

Chapters 17 to 26.

Carbon event timers

Chapter 17, 18, 21, 23, and 26.

Navigation Services event handlers

Chapter 18, 21, 23, and 26.

TextEdit click loop functions

Chapter 21.

List search functions

Chapter 22.

List definition functions

Chapter 22.

Device loop drawing functions

Chapter 25.

Universal Procedure Pointers and Carbon

Carbon supports universal procedure pointers transparently. By using the system-supplied universal procedure pointer functions, your application will operate correctly in both the Mac OS 8/9 and Mac OS X environments.

On Mac OS 8/9, the universal procedure pointer creation functions allocate routine descriptors in memory just as you would expect. On Mac OS X, the implementation of universal procedure pointers depends on various factors, including the object file format you choose. Universal procedure pointers will allocate memory if your application is compiled as a CFM binary, but are likely to return a simple procedure pointer if your application is compiled as a Mach-O binary. (All demonstration programs in this book are compiled as CFM binaries so that they will run on both Mac OS 8/9 and Mac OS X. Mach-O binaries only run on Mac OS X.)

In Carbon, routine descriptors must be disposed of using the specific disposal function associated with the creation function. For example, routine descriptors created with NewControlActionUPP must be disposed of using DisposeControlActionUPP. The generic disposal function DisposeRoutineDescriptor is not supported in Carbon.

Creation/Disposal Functions Relevant to Demonstration Programs

Creating Routine Descriptors

ControlActionUPP             NewControlActionUPP(ControlActionProcPtr userRoutine);
ModalFilterUPP               NewModalFilterUPP(ModalFilterProcPtr userRoutine);
AEEventHandlerUPP            NewAEEventHandlerUPP(AEEventHandlerProcPtr userRoutine);
ControlKeyFilterUPP          NewControlKeyFilterUPP(ControlKeyFilterProcPtr userRoutine);
ControlEditTextValidationUPP NewControlEditTextValidationUPP(ControlEditTextValidationProcPtr
                             userRoutine);
ControlUserPaneDrawUPP       NewControlUserPaneDrawUPP(ControlUserPaneDrawProcPtr
                             userRoutine);
ControlUserPaneActivateUPP   NewControlUserPaneActivateUPP(ControlUserPaneActivateProcPtr
                             userRoutine);
TEClickLoopUPP               NewTEClickLoopUPP(TEClickLoopProcPtr userRoutine);
ListSearchUPP                NewListSearchUPP(ListSearchProcPtr userRoutine);
ListDefUPP                   NewListDefUPP(ListDefProcPtr  userRoutine);
DeviceLoopDrawingUPP         NewDeviceLoopDrawingUPP(DeviceLoopDrawingProcPtr userRoutine);

Disposing of Routine Descriptors

void  DisposeControlActionUPP(ControlActionUPP userUPP);
void  DisposeModalFilterUPP(ModalFilterUPP userUPP);
void  DisposeAEEventHandlerUPP(AEEventHandlerUPP userUPP);
void  DisposeControlKeyFilterUPP(ControlKeyFilterUPP userUPP);
void  DisposeControlEditTextValidationUPP(ControlEditTextValidationUPP userUPP);
void  DisposeControlUserPaneDrawUPP(ControlUserPaneDrawUPP userUPP);
void  DisposeControlUserPaneActivateUPP(ControlUserPaneActivateUPP userUPP);
void  DisposeTEClickLoopUPP(TEClickLoopUPP userUPP);
void  DisposeListSearchUPP(ListSearchUPP userUPP);
void  DisposeListDefUPP(ListDefUPP userUPP);
void  DisposeDeviceLoopDrawingUPP(DeviceLoopDrawingUPP userUPP);

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Sketch 47.1 - Design app for UX/UI for i...
Sketch is an innovative and fresh look at vector drawing. Its intentionally minimalist design is based upon a drawing space of unlimited size and layers, free of palettes, panels, menus, windows, and... Read more
Cocktail 11.0.1 - General maintenance an...
Cocktail is a general purpose utility for macOS that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
Path Finder 7.6.1 - Powerful, award-winn...
Path Finder makes you a master of file management. Take full control over your file system. Save your time: compare and synchronize folders, view hidden files, use Dual Pane and full keyboard... Read more
Slack 2.8.2 - Collaborative communicatio...
Slack is a collaborative communication app that simplifies real-time messaging, archiving, and search for modern working teams. Version 2.8.2: A small release containing nothing but another Electron... Read more
Smultron 10.0.2 - Easy-to-use, powerful...
Smultron 10 is an elegant and powerful text editor that is easy to use. You can use Smultron 10 to create or edit any text document. Everything from a web page, a note or a script to any single piece... Read more
Capto 1.2.5 - $29.99
Capto (was Voila) is an easy-to-use app that takes capturing, recording, video and image editing to the next level. With an intelligent file manager and quick sharing options, Capto is perfect for... Read more
ScreenFlow 7.1.1 - Create screen recordi...
ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your entire monitor while also capturing your video camera, microphone and your... Read more
Xcode 9.0.1 - Integrated development env...
Xcode includes everything developers need to create great applications for Mac, iPhone, iPad, and Apple Watch. Xcode provides developers a unified workflow for user interface design, coding, testing... Read more
TotalFinder 1.10.2 - Adds tabs, hotkeys,...
TotalFinder is a universally acclaimed navigational companion for your Mac. Enhance your Mac's Finder with features so smart and convenient, you won't believe you ever lived without them. Features... Read more
Adobe Flash Player 27.0.0.170 - Plug-in...
Adobe Flash Player is a cross-platform, browser-based application runtime that provides uncompromised viewing of expressive applications, content, and videos across browsers and operating systems.... Read more

Dune! guide - how to toe the line and ge...
Publisher Voodoo is at it again with an all new high score chaser -- Dune! In this fast-paced arcade game, you have to propel yourself along sand dunes, gaining enough momentum to jump above the line to score points, while making sure you have... | Read more »
The best deals on the App Store this wee...
Happy Tuesday, dear readers. Your favorite part of the week as officially arrived. It's time to take a look at the best deals in games. Things are admittedly a bit sparse, but there are a few diamonds in the rough to see you through if you're... | Read more »
Be the last person standing in Legacy of...
Yoozoo Games’ popular action MMO Legacy of Discord is getting a huge new update to celebrate its first anniversary. Perhaps the biggest change is the addition of an exciting survival mode titled Last Guardian. This new survival mode will pit you... | Read more »
Home Street guide - how to make friends...
From the creators of Food Street comes Home Street, a new simulation game that tasks you with building a social network and designing a beautiful home. It's a bit like The Sims, but you won't have to worry about the daily chores involved (feeding,... | Read more »
Color Ballz guide - how to bounce to the...
Color Ballz is an addictive new arcade title from Ketchapp Studios. It takes old school mechanics from games like Brickles and puts a fun twist on it. Your job? To catch balls with a paddle and send them back into a chute to be carried back to... | Read more »
Q&A: A-33 Studio explains why Combat...
When it comes to mobile FPS, it’s often tricky to get the fundamentals right on a platform lacking a physical controller, large display and hefty RAM. With Combat Squad: Project Wednesday, A-33 Studio bravely took on the challenge of making a... | Read more »
Taichi Panda 3: Dragon Hunter guide - ti...
Taichi Panda 3: Dragon Hunter launched this week to players all over the world. It's a beautiful mobile MMORPG that blends elements of Eastern and Western fantasy. It reminds us of a mix between World of Warcraft and Jade Empire. MMO's can have a... | Read more »
The best new games we played this week -...
Phew. It has been a week, but now it's time to relax, put your feet up, and enjoy some brand new mobile games. It was a bit of slow week, but there's still plenty of new titles to add to your collection. Here are four of our favorites. [Read... | Read more »
Yoink - Improved Drag and Drop (Product...
Yoink - Improved Drag and Drop 1.0 Device: iOS Universal Category: Productivity Price: $2.99, Version: 1.0 (iTunes) Description: Yoink for iPad and iPhone lets you easily and quickly store items you drag, copy or share, for later use... | Read more »
Cottage Garden (Games)
Cottage Garden 1.11 Device: iOS Universal Category: Games Price: $4.99, Version: 1.11 (iTunes) Description: | Read more »

Price Scanner via MacPrices.net

13″ MacBook Pros on sale for up to $120 off M...
B&H Photo has 2017 13″ MacBook Pros in stock today and on sale for up to $120 off MSRP, each including free shipping plus NY & NJ sales tax only: – 13-inch 2.3GHz/128GB Space Gray MacBook... Read more
15″ MacBook Pros on sale for up to $200 off M...
B&H Photo has 15″ MacBook Pros on sale for up to $200 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: – 15″ 2.8GHz MacBook Pro Space Gray (MPTR2LL/A): $2249, $150... Read more
Roundup of Apple Certified Refurbished iMacs,...
Apple has a full line of Certified Refurbished 2017 21″ and 27″ iMacs available starting at $1019 and ranging up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free... Read more
Sale! 27″ 3.8GHz 5K iMac for $2098, save $201...
Amazon has the 27″ 3.8GHz 5K iMac (MNED2LL/A) on sale today for $2098 including free shipping. Their price is $201 off MSRP, and it’s the lowest price available for this model (Apple’s $1949... Read more
Sale! 10″ Apple WiFi iPad Pros for up to $100...
B&H Photo has 10.5″ WiFi iPad Pros in stock today and on sale for $50-$100 off MSRP. Each iPad includes free shipping, and B&H charges sales tax in NY & NJ only: – 10.5″ 64GB iPad Pro: $... Read more
Apple iMacs on sale for up to $130 off MSRP w...
B&H Photo has 21-inch and 27-inch iMacs in stock and on sale for up to $130 off MSRP including free shipping. B&H charges sales tax in NY & NJ only: – 27″ 3.8GHz iMac (MNED2LL/A): $2179 $... Read more
2017 3.5GHz 6-Core Mac Pro on sale for $2799,...
B&H Photo has the 2017 3.5GHz 6-Core Mac Pro (MD878LL/A) on sale today for $2799 including free shipping plus NY & NJ sales tax only . Their price is $200 off MSRP. Read more
12″ 1.2GHz Space Gray MacBook on sale for $11...
Amazon has the 2017 12″ 1.2GHz Space Gray Retina MacBook on sale for $100 off MSRP. Shipping is free: 12″ 1.2GHz Space Gray MacBook: $1199.99 $100 off MSRP Read more
Bare Bones Software Releases macOS High Sierr...
Bare Bones Software has announced the release and immediate availability of BBEdit 12.0, a significant upgrade to its professional strength text and code editor. BBEdit 12 introduces a new foundation... Read more
Yale Announces Availability of Apple HomeKit-...
Yale Locks & Hardware has announced that Apple HomeKit support for its Assure Lock family is available this month. The new Yale iM1 Network Module, which provides support for the Apple Home app... Read more

Jobs Board

Fraud Analyst, *Apple* Advertising Platform...
Job Summary Apple Ad Platforms has an opportunity to redefine advertising on mobile devices. Apple reaches hundreds of millions of iPhone, iPod touch, and iPad Read more
*Apple* Information Security - Security Data...
Job Summary This role is responsible for helping to strengthen Apple 's information security posture through the identification and curation of security event data. Read more
Lead *Apple* Solution Consultant - Apple In...
…develop a team of diverse partner employees focusing on excellence to deliver the Apple story. Even when you're not present, you will maintain a consistent influence Read more
watchOS Frameworks Engineering Manager, *App...
Job Summary Join the team that is shaping the future of software development for Apple Watch! Apple is looking for an exceptional software engineering leader to Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.