TweetFollow Us on Twitter

A Simple Plug-In Example

Volume Number: 14 (1998)
Issue Number: 6
Column Tag: Plugging In

A Simple Plug-In Example

by Joe Zobkiw

How to add plug-in support to your application

If you've ever used Adobe Photoshop, HyperCard, or even the latest version of Metrowerks' CodeWarrior you've made use of plug-in technology. Plug-ins are simply executable code (and resources) that reside in a file other than that of the application itself. Applications can load plug-ins dynamically at run-time and benefit from the functionality they provide.

For example, Photoshop is a high-end graphics application that allows you to load an image and manipulate it in any of a number of interesting ways. You can add a drop-shadow, change the color balance, produce lighting effects, and more by using special. Much of this functionality is provided by plug-ins, known in this case as Photoshop Filters. When you launch the Photoshop application, it scans a folder in the same folder as itself named "Plug-ins" for files of a specific type. As it finds these files it makes their functionality available from within the program by displaying them in the Filters menu. Selecting items from this menu invoke the appropriate plug-in and extend the capabilities of Photoshop.

You might ask yourself, why would anyone want to write dozens of separate plug-ins if they are just going to be used from within an application anyway? The reasons are simple. By extracting certain functionality into plug-ins, you can easily update or add new features to an application without changing the application itself. For instance, to add a new filter to Photoshop, you simply drag it into the Plug-ins folder and relaunch the application. This not only allows Adobe to easily manage their software, but it also allows hundreds of third-party developers to enhance and customize the Photoshop application by writing Photoshop Filters to the Adobe-published specification, all without having access to the source code of Photoshop itself.

Given these examples, you can see that using plug-ins can not only help ease the burden of development, but it can also help your salespeople by making your application more accessible, more customizable, and more appealing to your customers. Let's look at an example of how you might implement plug-in support in your application.

Basic Plug-in Support

The following example shows you the most basic steps required to implement plug-in support in an application. We have implemented a simple PowerPC application that loads a special plug-in, in our case compiled as a PowerPC shared library, and executes code within it. Once you understand how this application and plug-in work together, you can easily extend the sample and devise your own plug-in architecture for your application.

Figure 1.

For this project we are using CodeWarrior Professional Release 2. Our shared library is written in C and our application is C++. We started out by creating a single project file that contains both targets for this project, the application and the shared library. The project is set up so whenever we build the application, the shared library will be brought up to date if need be. You do not need to have both of your targets in the same project file. However, CodeWarrior Professional Release 2 allows us to do this and it makes it easier for this particular project.

Figure 2.

Before you design an application to call a plug-in you must decide on the calling conventions. In this simple case we have decided to implement a single function in our shared library that will be called from the application. We are calling our function DisplayDialogAndBeep. It is called with one parameter, inBeepTimes, which represents the number of times to make the computer beep while displaying a dialog. It is defined as follows:

Listing 1.

OSErr DisplayDialogAndBeep(long inBeepTimes);

When the project builds both the application and the shared library, it produces two files. One is an application program named "Application" and the other is a shared library named "Shared Library." When the application is launched, it prompts the user to enter a value for inBeepTimes. Upon entering this value, the application attempts to open the shared library by name, find the exported DisplayDialogAndBeep function by name, and call the function. If these steps are completed successfully, the computer will beep and you will see a dialog box as follows:

Figure 3.

Let's look at the shared library to see how it is created, then we can see how the application is used to call this code. First, it is important to understand that a shared library is simply a file that contains a code fragment (PowerPC code) in the data fork. If you are not familiar with code fragments and the Code Fragment Manager, you will want to read about them in Inside Macintosh. You can do so at http://devworld.apple.com/.

The compiler handles most of the details for you but you want to make sure that your project is set up to export (at a minimum) the functions that you expect to be able to call from your application. If the functions are not exported, your application will not be able to access them. Other than that, a shared library is not much more than a bunch of functions without a required main() entry point as you are used to seeing in applications.

Another interested and useful feature of shared libraries (and any code fragment for that matter) is the ability to include a start function, similar to main(), the main entry point of the code fragment. You can also include initialization and termination functions. These are called when the code fragment is first connected to and when the connection is closed, respectively. Our plug-in makes use of the initialization and termination functions to insure that our shared library resource file is available so we can access our dialog box.

You do not need to use the initialization and termination routines in this way. In fact, you can use them in any way you choose, or not at all. I simply found it convenient to locate the plug-in file given the CFragInitBlockPtr that is passed into the initialization routine in this case.

The required code of the shared library, sans comments, is as follows:

Listing 2

#include <CodeFragments.h>
#include <MixedMode.h>
#include <ConditionalMacros.h>
#include <Sound.h>
#include "Shared Library.h"

enum {
   uppDisplayDialogAndBeepProcInfo = kCStackBased
       | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
       | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(long)))
};

short   gFileRefNum;

__initialize

OSErr __initialize(CFragInitBlockPtr ibp)
{
   OSErr   err = noErr;

   gFileRefNum = -1;
   
   if (ibp->fragLocator.where == kDataForkCFragLocator) {
      gFileRefNum = 
         FSpOpenResFile(ibp->fragLocator.u.onDisk.fileSpec, 
                              fsRdPerm);
      if (gFileRefNum == -1)
         err = ResError();
   }
   
   return err;
}

__terminate

void __terminate(void)
{
   if (gFileRefNum != -1)
      CloseResFile(gFileRefNum);
}

DisplayDialogAndBeep

OSErr DisplayDialogAndBeep(long inBeepTimes)
{
   DialogPtr       d;
   Str32         sBeepTimes;
   long         i;
   unsigned long   someticks;
   short         saveResFile;
   saveResFile = CurResFile();
   UseResFile(gFileRefNum);
   NumToString(inBeepTimes, sBeepTimes);
   ParamText(sBeepTimes, "\p", "\p", "\p");
   d = GetNewDialog(256, nil, (WindowPtr)-1);
   if (d) {
      ShowWindow(d);
      DrawDialog(d);
   }
   
   for (i = 0; i < inBeepTimes; ++i) {
      FlashMenuBar(0);
      SysBeep(0);
      Delay(15, &someticks);
      FlashMenuBar(0);
      Delay(15, &someticks);
   }
   
   if (d)
      DisposeDialog(d);
      UseResFile(saveResFile);
      return noErr;
}

That's all there is to it, believe it or not.

The shared library isn't too useful on its own. It needs the application to call it in order for it to do anything. Basically the application first needs to locate the shared library by name. We call GetSharedLibrary() in order to do this. By passing in the name of the shared library we are looking for, the Code Fragment Manager will automatically look in the same folder as our application first, then proceed to look in the Extensions folder and the System folder until it either finds a shared library with the correct name or it fails. If found, GetSharedLibrary() will automatically open a connection (and execute its initialization routine mentioned earlier) to the shared library.

Once we find the shared library and connect to it we can then query it for an exported symbol named DisplayDialogAndBeep. In this case the symbol is an exported function but it might also be exported data. If found, we can continue by creating a routine descriptor for the function by calling NewRoutineDescriptor(), calling it by using CallUniversalProc(), and ultimately disposing of the routine descriptor using DisposeRoutineDescriptor().

Another way to call your shared library (or any code fragment for that matter) is by means of a main entry point, sometimes simply called main(). Under the 680x0 architecture that was the only way to communicate with a code resource. The code resource had a main entry point that you would call using a selector-based mechanism. That is, the main entry point would expect a selector (a unique identifier) to distinguish the purpose of the call, and then extra data, possibly in another parameter, to act on during that call. This technique allows the caller to not need to know specific exported function names, it can simply call through the main entry point, passing the correct selector and data. A sample main entry point might look like this:

OSErr main(long inSelector, void* ioDataPtr);

Another might use a single parameter block for all of the data, including the selector itself.

OSErr main(MyParameterBlock* ioParamPtr);

During the call to CallUniversalProc() is when the DisplayDialogAndBeep() function in the shared library will be called. It will be passed the parameters we specified, perform its duty, and return a result code. If you specify the universal procedure pointer incorrectly you will undoubtedly crash your computer during this call.

You can find more information about universal procedure pointers and routine descriptors in the Inside Macintosh chapter on the Mixed Mode Manager at http://devworld.apple.com/.

Once the call returns, the connection to the shared library is closed by calling CloseConnection(). At this time is when the termination routine in the shared library is executed.

The required code of the application, sans comments, is as follows:

Listing 3

ExecuteSharedLib
OSErr ExecuteSharedLib(long inBeepTimes)
{
   OSErr                     err = noErr, err2 = noErr;
   CFragConnectionID   connID = 0;
   Ptr                        mainAddr = nil;
   Str255                   errName;
   
   err = GetSharedLibrary("\pShared Library", 
                                    kPowerPCCFragArch, 
                                    kPrivateCFragCopy, 
                                    &connID, &mainAddr, errName);
   if (err == noErr) {
      Ptr         symAddr = nil;
      CFragSymbolClass   symClass;
      
      err = FindSymbol(connID, "\pDisplayDialogAndBeep", 
                              &symAddr, &symClass);
      if (err == noErr) {
         
         UniversalProcPtr upp =          
            NewRoutineDescriptor((ProcPtr)symAddr, 
            uppDisplayDialogAndBeepProcInfo, GetCurrentISA());
         if (upp) {
            err = CallUniversalProc(upp,    
                                       uppDisplayDialogAndBeepProcInfo, 
                                       inBeepTimes);
            DisposeRoutineDescriptor(upp);
         } else err = memFullErr;
      }
      
      err2 = CloseConnection(&connID);
      if (err == noErr) err = err2;
   }
   
   return err;
}

That's all there is to that too, believe it or not.

Enhanced Plug-in Support

Plug-ins Folder

The above example assumes your application knows the name of the plug-in before it is launched. However, in order to implement a Photoshop-style approach to plug-ins you need to be able to search for the plug-ins at run-time. This can be achieved using a very useful source code library called MoreFiles by Jim Luther.

MoreFiles allows you to (amongst numerous other features) easily scan a folder for files and call a specific function as files are found. Using this technique you can quickly locate all plug-ins that your application can use and add their names to a menu for your user to invoke as needed. MoreFiles can be downloaded from the Internet at ftp://dev.apple.com/devworld/Sample_Code/Files/ or http://members.aol.com/jumplong/.

Figure 4.

Callbacks

Something else to try is exporting functions from your application and having your plug-in call them, just as the application calls the functions in the plug-in. These are called callback functions because the plug-in is "calling back" into the application. These types of functions can be very useful in providing information to the plug-in as it is needed. For example, the plug-in can query the application to see if it has enough memory available in an internal buffer to handle a specific task before setting off on the task.

Import Libraries

You can also compile your shared library in the form of an import library. By doing this you can simply include the library in your project much like you would InterfaceLib. This way, you can easily call the exported functions in the import library without having to worry about the details of locating the library file, locating the exported function itself, and creating a universal procedure pointer. This may defeat the purpose of considering plug-ins in the first place, since the library is "linked" to your project. Another option, however, is to use the "weak link" option. Weak linking meets you in the middle of creating a full-fledged plug-in and "strong" linking to a library as described earlier. See your development environment documentation for details.

Fat Plug-ins

Calling a plug-in fat simply means that it can run natively on more than one microprocessor. A fat plug-in might contain code for both 680x0 and PowerPC microprocessors within the same file. This allows users to install just one file on any Macintosh computer and obtain the benefits of optimized code for their specific computer. You can easily compile and merge both 680x0 and PowerPC code in this manner. An informative book written on the subject (if I do say so myself) covers this in great detail. You can learn more about this technique (and other techniques mentioned in this article) from A Fragment of Your Imagination at http://www.triplesoft.com/fragment/.

What About SOM?

SOM is IBM's System Object Model. It was originally introduced on the Macintosh with OpenDoc. Although OpenDoc has moved on, SOM has stuck around. The Mac OS 8 Contextual Menu Manager uses SOM, for example. SOM allows you to use object-oriented techniques in a shared library. You garner all of the advantages of being able to create and override classes (including special SOM base classes) with the advantages of coding a shared library. Depending on your needs, SOM may be something you will want to explore.

For more information on SOM, see the February 1998 issue of MacTech magazine which contains articles on SOM and the Contextual Menu Manager. You can also find information on Apple's developer web site at http://devworld.apple.com/.

What About COM?

COM is Microsoft's Component Object Model. It is a programming model that defines how objects can communicate with one another, similar but different to SOM. ActiveX controls (previously known as OLE controls) are based on COM. For more information on COM and ActiveX read the June 1997 issue of MacTech Magazine.

Conclusion

Once you understand the basic concepts described in this article, you will begin to find new uses for plug-ins in your application. Many applications have areas that can be logically broken out into a plug-in architecture. The key is to understand and then experiment. Don't use this approach if you don't need it, but if you do, you can easily add years of life to your application by opening it up to yourself and third-party developers in this way. I look forward to hearing about how you've used this introductory plug-in architecture.

Special Thanks

Special thanks goes to our technical reviewers: Tantek Celik, Nick DeMello, Eric Gundrum and Marty Wachter.


Joe Zobkiw, zobkiw@triplesoft.com, is a programmer, author, musician and practicing carver of stone. He is the author of A Fragment of Your Imagination, a book about code fragments and code resources for the Mac OS. You can learn more about (and order a copy of) the book at http://www.triplesoft.com/fragment/.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Can PokeMatch help you find love with Po...
The unofficial Pokemon GO companion app space has exploded almost as fast as the game itself over the last few weeks. Aspiring app developers, many of them working solo, have given us apps that locate Pokemon, keep track of the server status, and... | Read more »
How to get started with Prisma
If there's one thing people like to do more than taking pictures with their smartphones, it's tinkering with those photos in some way. Numerous apps have sprung up over the last several years that allow you to use filters and special effects to... | Read more »
6 Pokemon GO updates you can expect, acc...
Pokemon GO had a scheduled appearance at this year's San Diego Comic-Con for a while, but it was only relatively close to the show that it was upgraded to a spot in Hall H. That's the biggest venue at SDCC, one usually reserved for the largest... | Read more »
How to evolve Eevee in Pokemon GO
By now, almost everyone should be hip to how to evolve Pokemon in Pokemon GO (and if not, there's a guide for that). Just gather enough candy of the appropriate type, feed them all to the Pokemon, and evolution happens. It's a miracle that would... | Read more »
CSR Racing 2: Guide to all game modes
It might not seem like there are all that many ways to go fast in a straight line, but CSR Racing 2 begs to differ. [Read more] | Read more »
Bulb Boy (Games)
Bulb Boy 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Multi-award winning 2D point & click horror adventure about a boy with a glowing head. | Read more »
5 top free emoji keyboard apps
If we're not at peak emoji yet as a society, it feels like we definitely should be. The emoji concept has gone far beyond what anyone in Japan could have envisioned when the people there unleashed it on an unsuspecting world, but the West has... | Read more »
How to unlock more characters in Disney...
One of the big charms of Disney Emoji Blitz is seeing a wide variety of beloved Disney and Pixar characters transformed into smiling emojis. Even someone like the sneaky Randall from Monsters Inc., who probably never cracked a smile on film, is... | Read more »
Cubway (Games)
Cubway 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Cubway is a journey with an abstract story of lifecycle of rebirth, called Samsara. Guide the cube through the long way full of dangers... | Read more »
Colorcube (Games)
Colorcube 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Turn pieces and blend colours in this minimal yet visually stunning puzzler.Over 200 handcrafted and challenging levels. Features... | Read more »

Price Scanner via MacPrices.net

GSK Rheumatoid Arthritis Study Leverages iPho...
Global healthcare products company GlaxoSmithKline (GSK) says that since 2014 they have begun transforming the way they conduct research, by leveraging state-of-the-art digital technologies — a... Read more
Clearance 12-inch Retina MacBooks, Apple refu...
Apple has Certified Refurbished 2015 12″ Retina MacBooks available starting at $929. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The following... Read more
13-inch Retina MacBook Pros on sale for up to...
B&H Photo has 13″ Retina MacBook Pros on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1199 $100 off MSRP - 13″ 2.7GHz/... Read more
13-inch 1.6GHz/128GB MacBook Air on sale for...
Amazon has the 13″ 1.6GHz/128GB MacBook Air on sale for $200 off MSRP for a limited time. Shipping is free: - 13″ 1.6GHz/128GB MacBook Air (sku MMGF2LL/A): $799.99 $200 off MSRP Their price is the... Read more
13-inch 1.6GHz/256GB MacBook Air on sale for...
Amazon has the 13″ 1.6GHz/256GB MacBook Air on sale for $200 off MSRP for a limited time. Shipping is free: - 13″ 1.6GHz/256GB MacBook Air (sku MMGG2LL/A): $999.99 $200 off MSRP Their price is the... Read more
Free iOS Business App notably* Helps Service...
PayStudio Inc. has introduced their new business app notably* 1.0, developed for iPhone and iPod touch. notably* was specifically developed to help service and trade professionals go digital and... Read more
27-inch iMacs on sale for $200 off MSRP
Amazon has 27″ iMacs on sale for $200 off MSRP including free shipping: - 27″ 3.3GHz iMac 5K: $2099 $200 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $1799.99 $200 off MSRP - 27″ 3.2GHz/1TB HD iMac 5K... Read more
Mac Pros on sale for $200 off MSRP
B&H Photo has Mac Pros on sale for $200 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2799, $200 off MSRP - 3.5GHz 6-core Mac Pro: $3799, $200... Read more
Save up to $600 with Apple refurbished Mac Pr...
Apple has Certified Refurbished Mac Pros available for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The following... Read more
Apple price trackers, updated continuously
Scan our Apple Price Trackers for the latest information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the trackers continuously: - 15″... Read more

Jobs Board

*Apple* Retail - Multiple Positions, Willow...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Evangelist - JAMF Software (United S...
The Apple Evangelist is responsible for building and cultivating strategic relationships with Apple 's small and mid-market business development field teams. This Read more
*Apple* Solutions Consultant - APPLE (United...
Job Summary As an Apple Solutions Consultant, you'll be the link between our future customers and our products. You'll showcase your entrepreneurial spirit as you Read more
*Apple* Professional Learning Specialist - A...
Job Summary The Apple Professional Learning Specialist is a full-time position for one year with Apple in the Phoenix, AZ area. This position requires a high Read more
*Apple* Picker - Apple Hill Orchard (United...
Apple Hill Orchard, Co. Rte. 21,Whitehall, NY 9/7/16-10/228/16. Pick fresh market or processing apples Productivity of 60 boxes and 80 boxes processing fruit per Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.