TweetFollow Us on Twitter

Accelerating Code Resources

Volume Number: 13 (1997)
Issue Number: 6
Column Tag: Plugging In

Accelerating Code Resources and Import Libraries

by Fabrice Ferino, MDL Information Systems

How your plug-in can take advantage of the Power Macintosh run-time architecture without telling the host application

Import Libraries as Plug-ins

The traditional mechanism for the extension of a Macintosh application has been the use of code resources. The Power Macintosh line of computers, and its associated run-time environment, have enabled applications to provide a new way to implement extensions as import libraries using the "universal plug-in" architecture described in [4]. However, even if the application does not provide explicit support for the use of import libraries as their extension mechanism, it is possible and advantageous for a number of reasons to implement PowerPC native extensions as import libraries, and to still package the complete plug-in a single file without contributing to the clutter of the Extensions folder.

A Bit of History

For a long time, many of the successful Macintosh applications have provided a mechanism to extend their functionality. In the 68k run-time environment, this mechanism relied on the loading and executing of code resources. However, this type of code has been more difficult to write than application code because of the limitations imposed by the 68k run-time environment: no A5 world to reference the globals, the limitation of the size of the code resource to less than 32K, and limit to a single segment (because there is no jump table).

The majority of the modern development environments provide some ways to overcome most of these limitations. The A4 register is cleverly hijacked to reference the globals of the code resource, branch islands or the 68020 32-bit branching instructions are used to allow code resource of a size larger than 32k. Still, writing a 68k code resource requires more care and attention to detail than the common application code. Readers interested in this area are directed to the excellent information available on this subject. ([3], [5]).

The situation improved significantly with the arrival of the PowerPC run-time architecture. With the availability of the Code Fragment Manager (CFM), an integral part of the PowerPC system software, it became possible to implement extensions using import libraries (colloquially known as shared libraries). Each import library is a full-fledged MacOS citizen with its own global data space, and no size limits. Additionally, if virtual memory is enabled and the import library is located on a device that supports paging, the import library will be file-mapped and its code will not take space in the heap of the host application. With all these advantages, many PowerPC native applications (Code Warrior IDE, FreeHand, etc...) quickly adapted their plug-in mechanism to use import libraries.

However, some applications still require their extensions to be code resources (some of them have not be rewritten for the PowerPC architecture and others did not adopt the new mechanism for diverse reasons). For this case, it is still possible to take advantage of the increase of performance provided by the PowerPC family of microprocessors by adopting an accelerated code resource. An accelerated code resource runs only on Power Macintosh but can be called by both a 68k application or a PowerPC application.

The format of an accelerated code resource is simple: this is a CFM code fragment preceded by a routine descriptor. The first instruction in a routine descriptor is the Mixed Mode Magic A-trap that triggers the mode switch necessary when the PowerPC code resource is called by 68k code. But accelerated code resources, although they provide some of the advantages of import libraries, still have some of the old limitations (see [2] 1-39). Finally, accelerated code resources have a very annoying characteristic: they have been difficult to debug with a source level debugger like the Metrowerks Debugger. The Macintosh Debugger from Apple provides some support for debugging memory-based code resource but it is still awkward. Source level debuggers become confused because the CFM removes the connection information from its tables after a memory based fragment has been prepared.

All these problems can be solved if most of the code of the extension resides in an import library. The accelerated code resource then is just used as an interface between the application and the import library. Figure 1 shows the general structure of a 68k code resource plug-in, of an accelerated code resource plug-in, and of a hybrid accelerated code resource-import library.

Figure 1. Some architectures for plug-in code resources. Two other useful types not represented here are safe fat code resources and import library based safe fat code resources. The article focus on the build of the third type of code resources. RD: routine descriptor.

Another advantage is that import libraries can have multiple entry points. If you need to implement several code resources, each one providing an entry point to the application, each of these code resources can call its own entry point in the import library. This design makes the development of plug-ins that share code much easier and offers the possibility for plug-ins to easily share data at run-time. This can be done without having to allocate some data structure in the heap and devising a mechanism to inform the plug-ins how to access this import data. The idea for this plug-in architecture came when reading [2] 1-40:

"Note that a code fragment stored as an accelerated code resource can import both code and data from an import library. The code and data in an import library do not move in memory. As a result you can sidestep the restrictions on global data in an accelerated code resource by putting the global data used by the accelerated code resource into an import library."

To solve the debugging problem, this idea is extended to have most of the data and of the code in an import library.

A Model Plug-in Application Based on Sprocket

An example host application is needed to demonstrate the implementation of import library based accelerated code resources. Instead of selecting one of the real world applications that do not take advantage of import libraries for their plug-in mechanism, a modified version of the Sprocket framework that can load and execute plug-ins has been implemented. With these extensions, Sprocket becomes a good model of a 68k CFM unaware application. Note that the implementation is not claimed to be the best one, but is simple and powerful enough to explore the concepts exposed in this article. Using a 68k program makes the environment even more hostile for import libraries.

One main difference with real world applications is that the application does not scan a special plug-in folder but allows the user to load plug-ins by selecting the new Load Plug-in... menu item in the File menu. Consequently, the plug-ins used by the application can be located anywhere on any volume. (This feature will be used later in the article.)

Most of the code for these extensions reside in a new file PlugInSupport.cp. This file implements the loading and initialization of plug-ins and the forwarding of events to the loaded plug-ins. It also implements a simple callback mechanism. The only function provided by the callback is the creation of a new Sprocket window so that a plug-in window behaves correctly in the floating window environment of Sprocket. (A new subclass of Sprocket window designed to be used by plug-ins is also implemented.) Otherwise, the plug-in rules are typical of those found with most applications: the plug-ins must be code resources of a certain type ('PLUG' in our example), and the communication between the plug-in and the application is the exchange of pointers to data structures. The file PlugInBlock.h defines how the application and its plug-ins communicate.

Listing 1: PlugInBlock.h

#define kNumParam (8)

/* 
The align pragma will be ignored by most 68k compilers. If you are 
applying the techniques described here for an old 68k application, 
it is very likely that the include file provided does not include 
these pragma statements: add them now before you build your PowerPC 
native plug-in 
*/
#if PRAGMA_ALIGN_SUPPORTED
#pragma options align=mac68k
#endif

// message that the plug-in can receive 
enum
{
   plugInInit,
   plugInEvt,
   plugInLoadFile,
   plugInWindowClosed,
   plugInExit
};

// callback request message sent by the plug-in
enum
{
   createWindow
};

// the callback in the application will receive a pointer to this structure
// message is the code for the operation requested by the plug-in
// param is used to pass the parameters back and forth between the application
// and the plug-in
typedef struct 
{
   short            message;
   Ptr               param[kNumParam];
} CallbackParamBlock, *CallbackParamPtr; 

// definition of the callback entry point
// we use pascal callling convention because C calling conventions may 
// vary between compilers
typedef pascal Boolean (*CallBackEntryPoint)                                                    (CallbackParamPtr pb);

// the plug-in will receive a pointer to this structure
// similar to the struct received by the callback with the addition of 
// a pointer to the callback function in the application
typedef struct 
{
   short             message;
   Ptr               param[kNumParam];
   CallBackEntryPoint   callback;   
} PlugInParamBlock, *PlugInParamPtr; 

// definition of the plug-in entry point
// we use pascal callling convention because C calling conventions may 
// vary between compilers
typedef pascal Boolean (*PlugInEntryPoint) 
                         (PlugInParamPtr pb);

The Plug-in: a QuickDraw3D Viewer

The plug-in implemented is a QuickDraw3D file viewer. QuickDraw3D is available only on Power Macintosh. (A Windows95 implementation should be available by the time you read this.)

Figure 2. The QuickDraw3D viewer plug-in in action.

To build the plug-in we will use two projects: one for an accelerated code resource as the bridge between an import library and the host application, the other for the import library with all of the code of the plug-in. The accelerated code resource and import library will be packaged as a single file, instead of adding yet another file to the growing crowd in the Extensions folder. This also facilitates installation and removal of the plug-in. (The Extensions folder should really contain only the import libraries used by several applications, that is shared libraries, and not every import library used by any single application.) Each CodeWarrior project will use the product of the other project, so this requires some bootstrapping. Since we must have the PEF of the import library to successfully link the accelerated code resource, we start by building the import library.

The Import Library Project

The import library will export only one symbol: its main function called PlugInMain(). This function, like the code resource entry point, accepts a single parameter, a pointer to a PlugInParamBlock, and returns a Boolean. Displaying a QuickDraw3D file is very easy because QuickDraw3D provides a QD3DViewerObject that does most of the work [1]. The other interesting parts in the code are the definitions to build and call a universal procedure pointer (UPPs) to get to the callback procedure in the 68k application. The classic trap is to copy and paste similar definitions from the universal headers. However, the definitions in the universal headers are there to help set up UPPs for the functions in the source file not for the functions called by the source file. In this example we know that the callback procedure is in 68k code, so we use kM68kISA for the run-time architecture parameter in NewRoutineDescriptor().

Listing 2: main.c

/************************************************************
   main.c
   Entry point for the import library
************************************************************/
#include "PlugInBlock.h"

#include <QD3DViewer.h>
#include <CodeFragments.h>


typedef UniversalProcPtr CallBackUPP;

// procedure info for the callback procedure
enum {    
   callBackProcInfo = kPascalStackBased
       | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
       | STACK_ROUTINE_PARAMETER(1,
     SIZE_CODE(sizeof(CallbackParamPtr)))
};

// macro to create and call a Universal Procedure Pointer for the callback
// We know the callback is 68K code so we make sure we are using 
// the constant kM68kISA. 
#define NewCallBackProc(userRoutine)      \
      (CallBackUPP) \ 
      NewRoutineDescriptor((ProcPtr)(userRoutine),\
               callBackProcInfo, kM68kISA)

#define CallCallBackProc(userRoutine,param)\
      CallUniversalProc((UniversalProcPtr)(userRoutine),\
                                 callBackProcInfo, param)

// typedef to satisfy the compiler when checking for unresolved symbols
typedef TQ3ViewerObject (*Q3ViewerNewProcType) 
                     (CGrafPtr, Rect*, unsigned long);
// Our globals
WindowPtr         gMyWindow;         // our window
TQ3ViewerObject    gMyViewer;         // the QD3D viewer object
Boolean            gFileOpened;      // has a file been opened ?
FSSpec            gCurrentFile;      // FSSpec of the file being displayed

// prototype for the exported function. We use pragma export
// to inform CodeWarrior that this is an exported function.
#pragma export on
Boolean PlugInMain(PlugInParamPtr pb);
#pragma export off

// prototypes for functions in this file
Boolean DoInit(PlugInParamPtr pb);
Boolean DoOpenFile(PlugInParamPtr pb);
Boolean DoWindowClosed(PlugInParamPtr pb);
Boolean DoEvent(PlugInParamPtr pb);
Boolean DoExit(PlugInParamPtr pb);
Boolean Get3DViewer( PlugInParamPtr pb);
Boolean IsColorPort(GrafPtr port);
Boolean SameFile( FSSpec *spec1, FSSpec *spec2 );

PlugInMain
/*********************************************************************
   PlugInMain
   Exported function.
   Based on the message, forwards the call to the appropriate 
   function
*********************************************************************/
Boolean PlugInMain( PlugInParamPtr pb)
{
   Boolean retVal;
   
   switch( pb->message)
      {
      case plugInInit:
         retVal = DoInit(pb);
         break;
      
      case plugInLoadFile:
         retVal = DoOpenFile(pb);
         break;
      
      case plugInWindowClosed:
         retVal = DoWindowClosed(pb);
         break;
         
      case plugInEvt:
         retVal = DoEvent(pb);
         break;
         
      case plugInExit:
         retVal = DoExit(pb);
         break;
         
      default:
         retVal = false;
         break;   
      }
      
   return retVal;
}

DoInit
/*********************************************************************
   DoInit
   Deal with the init message. 
*********************************************************************/
Boolean DoInit(PlugInParamPtr /*pb*/)
{
   // verify the presence of QuickDraw3D Viewer
   return (Q3ViewerNew != 
      (Q3ViewerNewProcType) kUnresolvedCFragSymbolAddress);
}

DoOpenFile
/*********************************************************************
   DoOpenFile
   User wanted to load a file. Snif it and open it if we can.
   Application sends us a pointer to the FSSpec in param[0].
*********************************************************************/
Boolean DoOpenFile(PlugInParamPtr pb)
{
   Boolean   retVal;
   short      refNum;
   FInfo     fileInfo;
   Boolean     dataFileOpen = false;
   
   // Is it again the same file ?
   if (gFileOpened && 
         SameFile( &gCurrentFile, (FSSpecPtr) pb->param[0]))
   {
      return true;
   }
   
   retVal = (FSpGetFInfo( (FSSpecPtr) pb->param[0],
            &fileInfo) == noErr &&
            fileInfo.fdType == '3DMF');
   // open the data fork of the file then...
   if (retVal)
   {
      dataFileOpen = 
         retVal = 
         (FSpOpenDF( (FSSpecPtr) pb->param[0], fsCurPerm,                               &refNum) == noErr);
   }
   // make sure we have a 3D viewer
   if (retVal)
   {
      retVal = Get3DViewer(pb);
   }
      
   //and tell the QD3DViewer to use it as the source of its data
   if (retVal)
   {
      retVal = (Q3ViewerUseFile( gMyViewer, refNum) == noErr);
      // force a full redraw right now.
      Q3ViewerDraw(gMyViewer);
   }
   // close the file here if it was opened
   if (dataFileOpen)
   {
      FSClose( refNum);
   }
   
   if (retVal)
   {
      // store data in our globals for next call
      gFileOpened = true;
      BlockMoveData( pb->param[0], 
                           &gCurrentFile, 
                           sizeof(FSSpec));
   }
   return retVal;
}

DoWindowClosed
/*********************************************************************
   DoWindowClosed
   User closed a window. If it is ours, release our data.
   Application sends us a pointer to the WindowRecord in param[0].
*********************************************************************/
Boolean DoWindowClosed( PlugInParamPtr pb)
{
   Boolean retVal;
   
   retVal= (gMyWindow == (WindowPtr) pb->param[0]);
   if (retVal)
   {
      Q3ViewerDispose( gMyViewer);
      gMyViewer = NULL;
   }
   return retVal;
}

DoEvent
/*********************************************************************
   DoEvent
   Application got an event? Is it ours?
*********************************************************************/
Boolean DoEvent(PlugInParamPtr pb)
{
   Boolean retVal;
   
   if (gMyViewer)
   {
      retVal = Q3ViewerEvent( gMyViewer, 
                        (EventRecord *) pb->param[0]);
   }
   else
   {
      retVal= false;
   }
   return retVal;
}

DoExit
/*********************************************************************
   DoExit
   We are being closed down. Release our objects.
*********************************************************************/
Boolean DoExit(PlugInParamPtr /*pb*/)
{
   if (gMyViewer)
   {
      Q3ViewerDispose( gMyViewer);
      gMyViewer = NULL;
   }
}

Get3DViewer
/*********************************************************************
   Get3DViewer
   make sure we have a 3DViewer
*********************************************************************/
Boolean Get3DViewer( PlugInParamPtr pb)
{
   CallbackParamBlock    cpb;
      CallBackUPP          callBack; // UPP for the callback
   Rect            wRect;

   // do we have a viewer already ?
   if (gMyViewer == NULL)
   {
      Boolean ok;
      
      // asks the application for a window using the callback
      // create UPP on the heap
      callBack = NewCallBackProc( pb->callback);
      // fill callback parameters
      cpb.message = createWindow;               
      ok = CallCallBackProc( callBack, &cpb);
      // dispose of UPP
      DisposeRoutineDescriptor( callBack);      
   
      // extract the WindowPtr if callback successful and verify the
      // portRect is not empty and it is a color port
      if (ok)
      {
         gMyWindow = (WindowPtr) cpb.param[0];   
         wRect = gMyWindow->portRect;          
         ok = (! (EmptyRect(&wRect))) &&
                  (IsColorPort(gMyWindow));             
      }
      
      // All the checks have been done: create a QD3D Viewer object
      if (ok)
      {
         gMyViewer = Q3ViewerNew( (CGrafPtr) gMyWindow, 
                              &wRect,
                              kQ3ViewerDefault);
      }
   }
   return (gMyViewer != NULL);   
}

IsColorPort
/*********************************************************************
   IsColorPort
   The magic routine to test if a GrafPort is just a CGrafPort
   in disguise
*********************************************************************/
Boolean IsColorPort(GrafPtr port)
{
   return port & ((((CGrafPtr)port)->portVersion &                            (short)0xC000)) == (short)0xC000 : false;
}

SameFile
/**********************************************************************
   SameFile
   Are two FSSpec refering to the same file?
***********************************************************************/
Boolean SameFile ( FSSpec *spec1, FSSpec *spec2 )
{
   return (spec1->vRefNum == spec2->vRefNum) &&
            (spec1->parID != spec2->parID) &&
            EqualString( spec1->name, spec2->name, false, true );
}

The last thing to mention about the import library is the settings for the project: make sure to specify PlugInMain as the main function of the Import library in the PPC Linker preferences panel, and in the PEF preferences, select use #pragma in the topmost popup menu for the export symbols. (CodeWarrior offers other ways to specify which symbols are exported, the point here is to make sure the PlugInMain is indeed exported.) The MPW tool DumpPEF can be invaluable to check which symbols are exported or imported by a PEF container like an import library.

The Accelerated Code Resource Project

The accelerated code resource project is even simpler, at least in its first version. It consists of only two files: stub.c to forward the parameters to the import library entry point and then return the result of the call to the application, and the import library which was just built and which will be used by the linker to set up the imports of our code resource.

In its first version, the code for the accelerated code resource has an almost embarassing simplicity: it just calls the exported function from the import library. (Remember that this simplicity is desired because of the difficulty of debugging accelerated code resources.)

Listing 3: Stub.c (version 1)

// Procedure info for the code resource entry point. This will be used by 
//Code Warrior to set up the routine descriptor in front of the code fragment.
enum {
   codeResourceProcInfo = kPascalStackBased
      | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
      | STACK_ROUTINE_PARAMETER(1,
       SIZE_CODE(sizeof(PlugInParamPtr)))
};

// prototype for the import library exported function
extern Boolean PlugInMain( PlugInParamPtr pb );

// symbol used by CodeWarrior when building the accelerated code resource
ProcInfoType __procinfo = codeResourceProcInfo; 

// prototype for the code resource entry point
pascal Boolean main( PlugInParamPtr pb);

main
/************************************************************
   main
   Code Resource entry point
   In this first version, just call the entry point
************************************************************/
pascal Boolean main( PlugInParamPtr pb)
{   
   return PlugInMain( pb);
}

The project generates a file that contains the 'PLUG' accelerated code resource, which is then added to the import library project in the final step of the bootstrapping sequence. From now on, the 'PLUG' resource will be automatically added (like any other resource) to the resource fork of the import library file by the CodeWarrior linker.

Figure 3. The final project for the plug-in. QD3DPlugInStub.rsrc is the file providing the 'PLUG' accelerated code resource.

The plug-in is now ready to use. The application calls the PLUG resource that forwards the request to the import library that can directly call back to the application. Everything works perfectly until we move the plug-in away a directory other than the application directory, such as to a Plug-ins folder. What is happening?

The Need for Manual Load

The problem is that our accelerated code resource is not a full citizen in the MacOS, and the CFM cannot resolve the import in the code resource, namely PlugInMain(). The code resource resides in its host application process and, although the import library is the same physical file as the code resource, it is no longer in the CFM search path. The CFM search path is thoroughly described in [2] (p 3-7). The CFM searches for imported libraries in the directory of the fragment being loaded only (and this is not the case here) if the fragment is being loaded by a call to GetDiskFragment() or GetSharedLibrary(). If this search is not sucessful, the CFM tries to locate the import library in the application file, the application library directory (specified by the application 'cfrg' resource), the application directory, the Extensions folder in the System Folder, the ROM registry and finally, a file and directory registry currently private to the CFM. Placing our code resource-import library hybrid in a plug-in folder effectively removes the import library from the search path. Does it mean our hybrid will have to either clutter the application directory or the Extensions folder? The solution would be to programmatically load the import library. The CFM provides the necessary function: GetDiskFragment() will load a fragment contained in the data fork of a file specified by a FSSpec:

OSErr GetDiskFragment( FSSpecPtr fileSpec, long offset,
                  long length, Str63 fragName,
                  LoadFlags findFlags, 
                  ConnectionID* connID, Ptr* mainAddr,
                  Str255 errName);

The last remaining problem is to get the FSSpec of the file containing the accelerated code resource. If the fragment had been disk based, it could get its own FSSpec courtesy of the CFM by exporting a connection initialization routine. This type of routine is called by the CFM after a fragment has been loaded and prepared and should conform to the following definition:

OSErr MyConnectionInitializationRoutine( InitBlock*
                                connectionInfo);

For disk based fragments, one of the fields in the InitBlock structure is actually the FSSpec of the file containing the code fragment. However, if the fragment is memory based (and this is the case for accelerated code resources), the InitBlock specifies the address and size of the fragment but not the FSSpec of the file. However, since the loading of the plug-in import library is only needed once, using the connection initialization routine to perform this step is convenient.

There is no universal solution to this problem, because it really depends on the run-time environment provided by the application for its plug-ins. The technique described here will be applicable in almost all the cases however, since it relies on minimal assumptions typical of most applications: the resource file of the plug-in is left opened by the application, and the plug-in has either a unique resource ID or a unique name. The loading code will work even if the plug-in is not the current resource file (some applications set the current resource file to themselves after loading plug-ins). The current resource file is not necessarily the plug-in file since the connection routine is executed just before the first call to the main() routine of an accelerated code resource and not when the resource is loaded.

To get the FSSpec of its own file, the code resource will set the current resource file to the top of the resource chain to be sure its file is in the resource chain, look for itself in the resource chain with GetResource() (or GetNamedResource()), obtain its own file reference number with HomeResFile(), and convert the file reference number to a FSSpec with PBGetFCBInfo().

Listing 4: Stub.c (version 2)

#include "PlugInBlock.h"
#include <CodeFragments.h>

// our own identity 
#define kResType 'PLUG'
#define kResId      (1000)
// this structure is the C description of a Mac Resource Map
typedef struct {
   long dataOffset;
   long mapOffset;
   long dataLength;
   long mapLength;
   Handle nextMap;
   short fileRefNum;
   short fileResAttr;
   short typeListOffset;
   short nameListOffset;
} ResourceMap, *ResourceMapPtr, **ResourceMapHandle; 
// exported from the import lib
typedef Boolean (*CFMPlugInEntryPoint) (PlugInParamPtr pb);

enum {
         codeResourceProcInfo = kPascalStackBased
                | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
                | STACK_ROUTINE_PARAMETER(1,
                    SIZE_CODE(sizeof(PlugInParamPtr)))
};

// for auto-load
extern Boolean PlugInMain( PlugInParamPtr pb );

// the import library entry point
CFMPlugInEntryPoint gPlugInMain; 

// used by CW for accelerated code resource
ProcInfoType __procinfo = codeResourceProcInfo; 

// prototype for the code resource entry point
pascal Boolean main( PlugInParamPtr pb);

// connection initialization routine and prototype of the utilities
OSErr VerifySharedLibrary( InitBlockPtr initBlock);
static OSErr RefNum2FSSpec( short theRefNum, 
                      FSSpecPtr theSpec);
static short SetResToTop(void);

main
/************************************************************
   main
   Code Resource entry point
   verify our global is set up and call the import library       
   entry point as before
************************************************************/
pascal Boolean main( PlugInParamPtr pb)
{   
   Boolean retVal = false;
   
   // Verify we did resolve the import   
   if (gPlugInMain != 
         (CFMPlugInEntryPoint) kUnresolvedCFragSymbolAddress)
   {
       retVal = (*gPlugInMain) (pb);
   }
   return retVal;
}

VerifySharedLibrary
/************************************************************
   VerifySharedLibrary
   ConnectionInitialization routine that verifies that the import library is 
   loaded, and if not load it programmatically.
************************************************************/
OSErr VerifySharedLibrary( InitBlockPtr /*initBlock*/)
{
   Handle             codeResourceHandle;
   FSSpec             myFSSpec;
   ConnectionID      myConnection;
   Str255            myError;
   short            myRefNum;
   OSErr              myErr = noErr;
   unsigned char      myEmptyString = 0x00;
   if (gPlugInMain == 
         (CFMPlugInEntryPoint) kUnresolvedCFragSymbolAddress)
   {
      // the CFM has not been loaded -> do it ourselves
      // the first part is to find our resource handle
      // so that we get to our ref num. The inMem info from the InitBlock 
      // is useless
      short oldResFile = SetResToTop();
      
      // get our own handle
      codeResourceHandle = GetResource(kResType, kResId);
      if (codeResourceHandle == NULL)
      {
         myErr = ResError();
      }
      // with the handle, get our file refnum
      if (myErr == noErr)
      {
         myRefNum = HomeResFile(codeResourceHandle);
         
         // now get the FSSpec corresponding to the refnum
         // this is much easier than you think   
         myErr = RefNum2FSSpec( myRefNum, &myFSSpec);
      }
      if (myErr == noErr)
      {
         myErr = GetDiskFragment( &myFSSpec, 
                       0,      // offset 0 for fragment 
                       kWholeFork, // whole data fork
                       &myEmptyString, // used for debug
                       kLoadLib, // load it
                       &myConnection, // get the connection
                       (Ptr*)&gPlugInMain, //get address directly
                       myError);
      }      
         
      if (myErr != noErr)
      {
         // just to stay on the safe side
         gPlugInMain = kUnresolvedCFragSymbolAddress; 
      }
      
      // restore current res file to its old value not to confuse the 
      // application
      UseResFile(oldResFile); 
   }
   else
   {
      gPlugInMain = PlugInMain; //Fragment loaded automatically
   }
   return myErr;
}

RefNum2FSSpec
/************************************************************
   RefNum2FSSpec
   given a file refNum, returns the file FSSpec
************************************************************/
   OSErr RefNum2FSSpec( short theRefNum, FSSpecPtr theSpec)
{
   FCBPBRec   paramBlock;
   OSErr         theError;
   Str255      theName;

   paramBlock.ioCompletion   = nil;
   paramBlock.ioNamePtr   = theName;
   paramBlock.ioVRefNum   = 0;
   paramBlock.ioRefNum   = theRefNum;
   paramBlock.ioFCBIndx   = 0;
   theError = PBGetFCBInfo(&paramBlock, false);

   if (theError == noErr) 
   {
      theError = FSMakeFSSpec(paramBlock.ioFCBVRefNum,
                    paramBlock.ioFCBParID,
                    theName, 
                    theSpec);
   }
   return theError;
}

SetResToTop
/*******************************************************
   SetResToTop
   Sets the current resource file to the top of the resource map
   Returns the current resource file before the call.
********************************************************/
short SetResToTop(void)
{
   short topResFile;
   short oldResFile;
   
   // Save the current resource file 
   oldResFile = CurResFile();
   
   // now sets the current Resfile to the top of the resource map
   // using the low-memory global TopMapHndl
   topResFile = (**((ResourceMapHandle)                                     LMGetTopMapHndl())).fileRefNum;
   UseResFile(topResFile);
   return oldResFile;
}

To improve the robustness of the manual loading of the import library, instead of relying on GetDiskFragment() which simply returns a transition vector to the main entry point of the import library, the code could use FindSymbol() to verify that the import library loaded by GetDiskFragment() exports a routine with the expected name.

myErr = FindSymbol( 
         myConnection,         // obtained with GetDiskFragment()
         "\pPlugInMain",         // name of routine to look for
         (Ptr*)&gPlugInMain,  //get address directly
         &symbolType);      // get class of symbol (transition vector, data)

Evidently, calls to FindSymbol() are necessary if the code resource does not call the main entry point (this would happen if the import library implemented the code for several distinct code resources all calling different entry points).

The other modifications to the import library project are the specification of VerifySharedLibrary as the connection initialization routine (Figure 4) and the addition of two libraries: InterfaceLib to link with all the Toolbox routines used, and MWCRuntimeLib to provide the glue to call the transition vectors obtained with GetDiskFragment() or FindSymbol(). A transition vector is a function pointer associated with the value of the Table Of Contents register (RTOC) used to reference global data in the called code fragment ([2] p.1-26). Calling a function located in another code fragment is known as a cross-TOC call, and the MWCRuntimeLib automatically provides the glue to set the TOC register before and after cross-TOC calls. The C programmer just deals with classic C pointers to functions.

Finally, the link to the import library should be set as "weak" so that the CFM does not give up loading and preparing the accelerated code resource if it cannot resolve the import. A weak link gives the connection initialization routine a chance to resolve the imports.

Figure 4. Setting the connection initialization routine of the accelerated code resource.

Conclusion

Adopting the mixed architecture with import libraries for accelerated code resources offers several advantages: the code of the plug-in does not impact the amount of free memory of the application, data can be easily shared between the plug-ins, the developer does not have to deal with the limitations inherent to the use of code resources, and can debug using mainstream source level debuggers. The implementation of these hybrid files is very easy once the stub resource has been built. Most, if not all of the development effort is then spent in the import library code. It is even easy to convert an existing accelerated code resource to use the hybrid architecture. All these advantages should speed up the development of new plug-ins of better quality for all the applications that still do not take explicitly advantage of the CFM. This hybrid design also can be used to develop private or fat safe code resources. (For more information on this type of code resource, see [5].) Finally, packaging the code resource in the same file helps reduce the System Folder clutter.

Even if you do not have a accelerated code resource project in the foreseeable future, the techniques presented here may give new ideas on how to take advantage of the power and versatility of the CFM, one of the most awesome parts of the Macintosh Operating System.

Bibliography and References

  1. Apple Computer Inc. "3D Graphics Programming with QuickDraw 3D", (1995) Addison-Wesley.
  2. Apple Computer Inc. "Inside Macintosh: PowerPC System Software", (1994) Addison-Wesley.
  3. Prouse, Craig. "Technical Note PT35-Stand alone code, ad nauseam", (1990) Apple Computer Inc.
  4. Nichols, Tim. "Standalone code on the PowerPC". (1994) develop 17, Apple Computer Inc.
  5. Zobkiw, Joe. "A fragment of your imagination", (1995) Addison-Wesley.
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

ClamXav 2.10 - Virus checker based on Cl...
ClamXav is a popular virus checker for OS X. I have been working on ClamXav for more than 10 years now, and over those years, I have invested a huge amount of my own time and energy into bringing... Read more
Tweetbot 2.4.4 - Popular Twitter client.
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
Sierra Cache Cleaner 11.0.1 - Clear cach...
Sierra Cache Cleaner is an award-winning general purpose tool for macOS X. SCC makes system maintenance simple with an easy point-and-click interface to many macOS X functions. Novice and expert... Read more
Things 2.8.8 - Elegant personal task man...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
Remotix 4.1 - Access all your computers...
Remotix is a fast and powerful application to easily access multiple Macs (and PCs) from your own Mac. Features Complete Apple Screen Sharing support - including Mac OS X login, clipboard... Read more
Airfoil 5.1.2 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
Firefox 49.0.1 - Fast, safe Web browser.
Firefox offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals and casual... Read more
Default Folder X 5.0.7 - Enhances Open a...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click on... Read more
Safari Technology Preview 10.1 - The new...
Safari Technology Preview contains the most recent additions and improvements to WebKit and the latest advances in Safari web technologies. And once installed, you will receive notifications of... Read more
Pinegrow Web Designer 2.94 - Mockup and...
Pinegrow Web Designer is desktop app that lets you mockup and design webpages faster with multi-page editing, CSS and LESS styling, and smart components for Bootstrap, Foundation, Angular JS, and... Read more

3 reasons you need to play Kingdom: New...
Developed by a tag team of indie developers - Thomas "Noio" van den Berg and Marco "Licorice" Bancale - Kingdom is a vibrant medieval fantasy adventure that casts players as a king or queen who must expand their empire by exploring the vasts lands... | Read more »
JoyCity have launched a brand new King o...
Great news for all of you Game of Dice fans out there - JoyCity have just released a brand new limited edition pack with a really cool twist. The premise of Game of Dice is fairly straightforward, asking you to roll dice to navigate your way around... | Read more »
Burly Men at Sea (Games)
Burly Men at Sea 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Burly Men at Sea is a folktale about a trio of large, bearded fishermen who step away from the ordinary to seek adventure. | Read more »
3 tips for catching the gnarliest waves...
Like a wave breaking on the shore, Tidal Rider swept its way onto the App Store charts this week settling firmly in the top 10. It’s a one-touch high score-chaser in which you pull surfing stunts while dodging seagulls and collecting coins. The... | Read more »
The beginner's guide to destroying...
Age of Heroes: Conquest is 5th Planet Games’ all new turn-based multiplayer RPG, full of fantasy exploration, guild building, and treasure hunting. It’s pretty user-friendly as far as these games go, but when you really get down to it, you’ll find... | Read more »
Infinite Tanks (Games)
Infinite Tanks 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: | Read more »
Agatha Christie - The ABC Murders (FULL)...
Agatha Christie - The ABC Murders (FULL) 1.0 Device: iOS Universal Category: Games Price: $6.99, Version: 1.0 (iTunes) Description: Agatha Christie: The ABC Murders Your weapon is your knowledge. Your wits will be put to the ultimate... | Read more »
HeadlessD (Games)
HeadlessD 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: HeadlessD is hand-painted dungeon crawler with intuitive touch controls and NO in-app purchases. | Read more »
Leaf for Twitter (Social Networking)
Leaf for Twitter 1.0.1 Device: iOS iPhone Category: Social Networking Price: $4.99, Version: 1.0.1 (iTunes) Description: | Read more »
Banner Saga 2 (Games)
Banner Saga 2 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: The epic award winning story-based role-playing game continues its emotional journey across a breaking world. Lead your Viking... | Read more »

Price Scanner via MacPrices.net

MacBook Airs on sale for up to $100 off MSRP
B&H Photo has 13″ and 11″ MacBook Airs on sale for up to $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 11″ 1.6GHz/128GB MacBook Air: $799 $100 MSRP - 11″ 1.6GHz/256GB... Read more
Apple refurbished 12-inch 128GB iPad Pros ava...
Apple has Certified Refurbished 12″ Apple iPad Pros available for up to $160 off the cost of new iPads. An Apple one-year warranty is included with each model, and shipping is free: - 32GB 12″ iPad... Read more
Phone2Action Unveils New Voter Turnout Techno...
Phone2Action, a leading digital advocacy platform, today launched its Tech to Vote Civic Action Center digital advocacy and communications platform on National Voter Registration Day September 27.... Read more
Apple & Deloitte Team Up to Help Business...
Apple and international professional services firm Deloitte have announced a partnership to help companies quickly and easily transform their workflow dynamics by maximizing the power, ease-of-use,... Read more
Chop Commute – See Traffic and Drive Times on...
Shrewsbury, Massachusetts based Indie developer, InchWest has released Chop Commute 1.61, a Mac app that takes the guesswork out of daily commute by showing real-time traffic and drive times right on... Read more
12-inch 32GB WiFi iPad Pros on sale for $50 o...
B&H Photo has 12″ 32GB WiFi Apple iPad Pros on sale for $50 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 12″ Space Gray 32GB WiFi iPad Pro: $749 $50 off MSRP -... Read more
Recent price drops on refurbished iPad minis...
Apple recently dropped prices on several Certified Refurbished iPad mini 4s and 2s as well as iPad Air 2s. An Apple one-year warranty is included with each model, and shipping is free: - 16GB iPad... Read more
Apple refurbished Mac minis available startin...
Apple has Certified Refurbished Mac minis available starting at $419. Apple’s one-year warranty is included with each mini, and shipping is free: - 1.4GHz Mac mini: $419 $80 off MSRP - 2.6GHz Mac... Read more
13-inch 2.5GHz MacBook Pro available for $928...
Overstock has the 13″ 2.5GHz MacBook Pro available for $927.99 including free shipping. Their price is $171 off MSRP. Read more
Buying McLaren Would Give Apple Instant Car C...
Apple “iCar” rumors have waxed and waned over the years, piquing interest and speculation as to whether Apple is seriously interested in getting into the automotobile business, either in a joint... Read more

Jobs Board

Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
*Apple* Wireless Lead - T-ROC - The Retail O...
…wealth of knowledge in wireless sales and activations to the Beautiful and NEW APPLE Experience store within MACYS.. THIS role, APPLE Wireless Lead, isbrandnewas Read more
Lead *Apple* Advocate - T-ROC - The Retail...
…Company, is proud of its unprecedented relationship with our partner and client, APPLE ,in bringing amazing" APPLE ADVOCATES"to "non" Apple store locations. Read more
*Apple* Advocate - T-ROC - The Retail Outsou...
…Company, is proud of its unprecedented relationship with our partner and client, APPLE ,in bringing amazing" APPLE ADVOCATES"to "non" Apple store locations. Read more
Lead *Apple* Solutions Consultant - Apple (...
# Lead Apple Solutions Consultant Job Number: 51829230 Detroit, Michigan, United States Posted: Sep. 19, 2016 Weekly Hours: 40.00 **Job Summary** The Lead ASC is an Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.