TweetFollow Us on Twitter

Oct 93 Think 10
Volume Number:9
Issue Number:10
Column Tag:Think Top 10

Related Info: Event Manager

Support’s Solutions

By Kevin Irlen, THINK Technical Support, Symantec Corp.

This is a monthly column written by Symantec's Technical Support Engineers intended to provide you with information on Symantec products. This month we cover a single commonly asked question of Symantec’s THINK group.

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

A jGNE Starter Kit for THINK C

[This month’s THINK Top 10 is actually not a list of the top ten questions to Symantec. Instead, it handles a single commonly asked question of the THINK group. What we’d like to know is do you like this type of article, or would you prefer us to return to the Top 10 Q&A style? Send me your thoughts - my editorial e-mail addresses are on page 2 of this issue. - Ed.]

While all the latest and greatest stuff rushes relentlessly at us - C++, AppleScripting, Bedrock, PowerPC, etc. - there remain the numerous loose ends and open questions concerning Macintosh programming that Symantec Tech Support folks get asked for help with every day. Often, dealing with such questions is a straightforward matter of steering a programmer toward the appropriate sections of Inside Macintosh, the odd Tech Note, or to one of the programming forums online. Certain problems seem to fall between the cracks, however; too general to be solved by a couple of Toolbox calls, yet too Macintosh-specific to be readily solved with no clear documentation path to follow. The more often a given problem of this kind crops up, the more it cries out for a generic solution - a tech support solution.

Writing and installing a GetNextEvent filter is one such recurring problem. Essential to the functioning of many extensions, as well as applications, this oddity is mentioned only in a tiny Tech Note, with scant information about how actually to implement it.

From Macintosh Tech Note #85:

GetNextEvent uses a filter (GNE filter) which allows for a routine to be installed which overrides (or augments) the behavior of the system. The GNE filter is installed by pointing the low-memory global jGNEFilter (a long word at $29A) to the routine. After all other GNE processing is complete, the routine will be called with A1 pointing to the event record and D0 containing the boolean result. The filter may then modify the event record or change the function result by altering the word on the stack at 4(A7). This word will match D0 initially, of course.

Sounds good. This is exactly what you’ll need to blink the Apple menu, intercept disk insert events to check disks for viruses, trap special key sequences system-wide, etc. But this is where many a THINK user throws up his or her hands and calls us, wanting to what in the world to do with this information! How do you write such a routine? Do you have to do the whole thing in assembly? How exactly do you install it?

Clearly, given the register-based calling mechanism, “some assembly is required,” and naturally, installation will need to be done by an INIT. But why isn’t there some standard way of doing this, and shouldn’t you be able to write your filter in C? Why ask why? The jGNE Starter Kit, included in full on the companion disk, asks why, and answers by providing a jGNE installer INIT that can be used and re-used simply by replacing resources with ResEdit, along with everything else needed to develop and test custom jGNE’s. In this article, I’ll explain how the INIT works, and what it expects from the ‘CODE’ resource you drop in.

In solving the jGNE problem, there are essentially two hurdles to be cleared, the first relatively low, the second a bit higher. First, we must have a scheme for dealing with the jGNE calling mechanism described in Tech Note 85; and second, we must allow for multiple jGNE’s to coexist, i.e. to be chained. Credit for the snippet of assembly language that follows belongs, as far as I know, to Steve Stockman, a frequent contributor to the Macintosh Programming and Symantec Development Tools forums on CompuServe. It leaps the first hurdle, and alludes to clearing the second. I discovered it while browsing one day, in a message to a programmer in need, and it is what Mr. Stockman left out of his message that inspired me to create this Kit.

Anyway, here’s the only assembly necessary:

/* 1 */

main()
{  
 asm  
 {   
  move.l   A1   ,-(SP)       ; A1    holds theEvent   
  move.w   8(SP),-(SP)       ; 8(SP) holds hasEvent 
 ; (4(SP) + 4 we just pushed)   
  jsr      myjGNEFilterFunc   
  move.w   D0,10(SP)         ; put return value back 
 ; at what will be 4(SP)   
  addq.l   #2,SP             ; pop hasEvent     (10 - 2 = 8)
  move.l   (SP)+,A1          ; pop theEvent back into A1 
 ; ( 8 - 4 = 4)
  movea.l  #0xFFFFFFFF,A0    ; this gets overwritten at 
 ; INIT time with either the   
  jmp      (A0)              ; next jGNE's address, or an 
 ; RTS if there isn't one!  
 }
}

There are two essential things to note about this code. First, the GetNextEvent call mechanism has been kept completely separate from the filter function itself, which may now be a simple C function of the form:

/* 2 */
            
short myjGNEFilterFunc(short hasEvent,EventRecord *anEvent);  

This function must return zero if it eats the event, non-zero if the event still needs to be handled.

The second feature of this code is something that no doubt looks a bit strange. As the comment indicates: the movea.l line is not in its final form. It is going to be tampered with at INIT time! The reason for this is that you inevitably want to be able to install multiple jGNE’s, and have them chain from one to the next. The problem is that a jGNE has no way of knowing in advance whether or not it will be last in the chain; and therefore no way of knowing whether to RTS when finished (allowing GetNextEvent to return to the current application) or to JMP to the next jGNE in line. This order isn’t determined until INIT time. A jGNE could be “loaded” simply by floating its code in the system heap and storing a pointer to it in the low-memory global jGNEFilter (0x29A). But in order for multiple jGNE’s to coexist, they must cooperate at INIT time by checking to see whether or not someone has loaded before them - and if so, store the previous jGNE’s address to jump to instead of simply returning. In this way, jGNE’s can chain in last-to-load, first-to-execute order.

Now if you just want to use the jGNE Starter Kit, you don’t have to worry about any of this. All you have to do is use the above code in conjunction with the generic jGNE INIT. The latter part of this article contains a brief discussion on building your jGNE project, which should be more than enough to get you “started.” For those of you in the mood for a hack, read on!

There are any number of strategies for stashing a “special” value so that a piece of code can find it later, but the jGNE Starter Kit’s strategy here is to go to the extreme and actually overwrite the machine instruction that depends on the value of the previously loaded jGNE, once, at INIT time, and then not to worry about it again. No finding the stashed value, or testing it, or nuthin. Here’s the entire code for the INIT (excluding the sacred ShowInitIcon routine), and an explanation to follow:

/* 3 */

#define rMyINITIcon  -4094     // ID of icon to be shown 
 // at INIT time
#define rMyjGNE        128     // ID of jGNE 'CODE' resource

#define kBRAoffset  0x0018     // offset of bra to main in a 
 // std header CODE resource
#define kLoadOffset 0x0014     // offset in "main" of the 
 // line to be changed!

Ptr jGNEFilterPtr : 0x029A;   // low-memory global: 
 // jGNEfilter

OSErr ShowInitIcon(short icon_num,short move_x_by);

main()
{
 Handle  myjGNE;
 Ptr     branInstruction,loadInstruction;
 OSErr   iErr;

 SetZone(SysZone);

 myjGNE = Get1Resource('CODE',rMyjGNE);

 if (myjGNE)
 {
  DetachResource(myjGNE);

  branInstruction = *myjGNE         + kBRAoffset;
  loadInstruction = branInstruction + *((short *) 
 (branInstruction + 2)) +kLoadOffset;

  if (jGNEFilterPtr) *((long *) (loadInstruction + 2)) = 
 (long) jGNEFilterPtr;
  else               *loadInstruction = 0x4E75;

  jGNEFilterPtr = *myjGNE;
 }
 else SysBeep(10);

 iErr = ShowInitIcon(rMyINITIcon,-1);

 if (iErr != noErr) SysBeep(10);
}

OK, this is code may be short, but it does have a couple of rather obscure lines, and a couple of unfamiliar constants. We are attempting to locate in memory, within the loaded ‘CODE’ resource that is our jGNE, the exact word where the “movea.l” instruction begins, and this depends on two things. First, since our assembly snippet comprises the main() function of the jGNE resource, one key constant is the offset of the “movea.l” instruction from the beginning of main(). Disassembly (crude, but effective) reveals that this offset is 20 words (0x0014), and we’ll name the constant kLoadOffset since it’s the instruction that loads the next jGNE address to be jumped to.

This is only halfway toward locating the instruction, though, because where, after all, is main()? The answer is that in a code resource, main() can wind up anywhere. Fortunately, the entry point to a THINK C code resource is a standard header (unless you make it otherwise), and this standard header contains an BRA.S instruction whose sole purpose is to branch to main(). Examine a code resource (using MacsBug, or a code editor), and you will see that this branch instruction is 24 words (0x0018) from the beginning (segment loader info and other no-op stuff). Hence the constant kBRAOffset.

So here’s the deal: load the code resource, dereference the handle, add kBRAOffset to its value, and you’re pointing at the BRA.S instruction. The second word of that instruction is the number of bytes to branch over to get to main(). So add kLoadOffset to that and you’re pointing at your load instruction:

/* 4 */

branInstruction = *myjGNE         + kBRAoffset;
loadInstruction = branInstruction + *((short *) 
 (branInstruction + 2)) + kLoadOffset;

Now we’re home free. All we do now is decide whether to change the second word of that load instruction to the address of the next jGNE, or just replace the instruction with an RTS (0x4E75):

/* 5 */

if (jGNEFilterPtr) *((long *) (loadInstruction + 2)) = 
 (long) jGNEFilterPtr;
else               *loadInstruction = 0x4E75;

Now we can safely replace whatever was in jGNEFilterPtr with a pointer to our jGNE filter, and chaining will take care of itself (assuming the other jGNE’s you’ve installed are just as polite).

That’s all there is to it. Although this technique may be a bit unorthodox, it provides an extremely high degree of modularity to an aspect of Mac programming that is usually shrouded in mystery - one of those tasks that is more often abandoned than solved, or else solved so painfully that one shudders at the thought of having to go through it again.

An additional windfall is that this installation procedure does not in any way depend upon being executed at INIT time. It can be run from a regular THINK C project, allowing you to install a jGNE filter on the fly, as you’re developing it. If you install a faulty filter, removing it is as easy as restoring the previous value to the low-memory global jGNEFilter. Just be sure to note the value of jGNEFilter before you do your install, then, in MacsBug for example, it’s just “SM jGNEFilter oldval” to restore it. Of course the detached resource will just lay there in your system heap, but why worry?

To wrap things up, let’s look briefly at the process of writing the jGNE filter itself. The Starter Kit comes with a generic jGNE code resource project that contains a single file, “generic jGNE.c”. If you build this project, you’ll get a resource of type ‘CODE’ and id 128 that can be dropped into the generic jGNE INIT with ResEdit (in fact, it’s already been put there, but you can do it again just to see how fun and easy it is). Once installed, this filter demonstrates the awesome power of the jGNE mechanism by beeping whenever the user types cmd-shift j, g, n, or e (author is not responsible if this interferes with the proper functioning of any other applications). Your filter will hopefully do something more useful, but the basic structure will be essentially the same. Here’s the code:

/* 6 */

main()
{  
 asm  
 {   
  move.l   A1   ,-(SP)       ; A1    holds theEvent   
  move.w   8(SP),-(SP)       ; 8(SP) holds hasEvent 
 ; (4(SP) + 4 we just pushed)   
  jsr      myjGNEFilterFunc   
  move.w   D0,10(SP)         ; put return value back at 
 ; what will be 4(SP)   
  addq.l   #2,SP             ; pop hasEvent   
  move.l   (SP)+,A1          ; pop theEvent back into A1   
  movea.l  #0xFFFFFFFF,A0    ; this gets overwritten at INIT 
 ; time with either the   
  jmp      (A0)              ; next jGNE's address, or an 
 ; RTS if there isn't one!  
 }
}

#include <SetUpA4.h>         // DO NOT move this before main! 
 // (It generates code.)

short myjGNEFilterFunc(short hasEvent,EventRecord *theEvent)
{
 char theChar;

 RememberA0(); SetUpA4();

 if (hasEvent)
 {
  switch (theEvent->what)
  {
   case keyDown:
   case autoKey:
    theChar = theEvent->message & charCodeMask;

    if  ((theEvent->modifiers & cmdKey) && 
 (theEvent->modifiers & shiftKey))
     if ((theChar == 'j') || (theChar == 'g') ||
         (theChar == 'n') || (theChar == 'e'))
     {
      SysBeep(10);

      hasEvent = 0;
     }

   default:
    break;
  }
 }
 RestoreA4();

 return hasEvent;
}

Just your basic event-handling switch block, plus RememberA0, SetupA4, and RestoreA4 to allow for global and static variables. Of course, you can handle any events you like and in as sophisticated a manner as you’d like, with additional function calls, multiple source files and segments if necessary, MacTraps, ANSI-A4, etc.

With the jGNE Starter Kit, you’ll have that Apple menu blinking in no time!

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

BusyContacts 1.0.2 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more
Capture One Pro 8.2.0.82 - RAW workflow...
Capture One Pro 8 is a professional RAW converter offering you ultimate image quality with accurate colors and incredible detail from more than 300 high-end cameras -- straight out of the box. It... Read more
Backblaze 4.0.0.872 - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac.With unlimited storage available for $5 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more
Little Snitch 3.5.2 - Alerts you about o...
Little Snitch gives you control over your private outgoing data. Track background activity As soon as your computer connects to the Internet, applications often have permission to send any... Read more
Monolingual 1.6.4 - Remove unwanted OS X...
Monolingual is a program for removing unnecesary language resources from OS X, in order to reclaim several hundred megabytes of disk space. If you use your computer in only one (human) language, you... Read more
CleanApp 5.0 - Application deinstaller a...
CleanApp is an application deinstaller and archiver.... Your hard drive gets fuller day by day, but do you know why? CleanApp 5 provides you with insights how to reclaim disk space. There are... Read more
Fantastical 2.0 - Create calendar events...
Fantastical is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event details... Read more
Cocktail 8.2 - General maintenance and o...
Cocktail is a general purpose utility for OS X 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
Direct Mail 4.0.4 - Create and send grea...
Direct Mail is an easy-to-use, fully-featured email marketing app purpose-built for OS X. It lets you create and send great looking email campaigns. Start your newsletter by selecting from a gallery... Read more
jAlbum Pro 12.6 - Organize your digital...
jAlbum Pro has all the features you love in jAlbum, but comes with a commercial license. With jAlbum, you can create gorgeous custom photo galleries for the Web without writing a line of code!... Read more

Appy to Have Known You - Lee Hamlet Look...
Being at 148Apps these past 2 years has been an awesome experience that has taught me a great deal, and working with such a great team has been a privilege. Thank you to Rob Rich, and to both Rob LeFebvre and Jeff Scott before him, for helping me... | Read more »
MLB Manager 2015 (Games)
MLB Manager 2015 5.0.14 Device: iOS Universal Category: Games Price: $4.99, Version: 5.0.14 (iTunes) Description: Guide your favorite MLB franchise to glory! MLB Manager 2015, officially licensed by MLB.com and based on the award-... | Read more »
Breath of Light (Games)
Breath of Light 1.0.1421 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.1421 (iTunes) Description: Hold a quiet moment. Breath of Light is a meditative and beautiful puzzle game with a hypnotic soundtrack by... | Read more »
WWE WrestleMania Tags into the App Store
Are You ready to rumble? The official WWE WrestleMania app, by World Wrestling Entertainment, is now available. Now you can get all your WrestleMania info in one place before anyone else. The app offers details on superstar signings, interactive... | Read more »
Bio Inc's New Expansion is Infectin...
Bio Inc., by DryGin Studios, is the real time strategy game where you infect a human body with the worst virus your evil brain can design. Recently, the game was updated to add a whole lot of new features. Now you can play the new “Lethal”... | Read more »
The Monocular Minion is Here! Despicable...
Despicable Me: Minion Rush, by Gameloft, is introducing a new runner to the mix in their latest update. Now you can play as Carl, the prankster minion. Carl has a few new abilities to play with, including running at a higher speed from the start.... | Read more »
Dungeon of Madness (Games)
Dungeon of Madness 1.0.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.0 (iTunes) Description: Dungeon of Madness is an action game where you rotate tiles to create our own route. Help the hero by connecting the... | Read more »
Filters for iPhone (Photography)
Filters for iPhone 1.0 Device: iOS iPhone Category: Photography Price: $.99, Version: 1.0 (iTunes) Description: | Read more »
Jump'N'Shoot Attack (Games)
Jump'N'Shoot Attack 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: A mobile game for gamers! Join Louise Lightfoot, the legendary "Master of Jumping and Shooting", on her mission to save... | Read more »
Space Bounties Inc. (Games)
Space Bounties Inc. 1.4 Device: iOS Universal Category: Games Price: $1.99, Version: 1.4 (iTunes) Description: SuperGameDroid: 4/5 "Satisfying futuristic RPG combat, high replay value, and a heavy dose of nostalgia make Space... | Read more »

Price Scanner via MacPrices.net

iMacs on sale for up to $205 off MSRP
B&H Photo has 21″ and 27″ iMacs on sale for up to $205 off MSRP including free shipping plus NY sales tax only: - 21″ 1.4GHz iMac: $1019 $80 off - 21″ 2.7GHz iMac: $1189 $110 off - 21″ 2.9GHz... Read more
Färbe Technik Offers iPhone Battery Charge LI...
Färbe Technik, which manufactures and markets of mobile accessories for Apple, Blackberry and Samsung mobile devices, is offering tips on how to keep your iPhone charged while in the field: •... Read more
Electronic Recyclers International CEO Urges...
Citing a recent story on CNBC about concerns some security professionals have about the forthcoming Apple Watch, John Shegerian, Chairman and CEO of Electronic Recyclers International (ERI), the... Read more
Save up to $380 with Apple refurbished iMacs
The Apple Store has Apple Certified Refurbished iMacs available for up to $380 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $2119 $... Read more
Logitech Says MX Master Is Its Most Advanced...
Logitech’s new MX Master Wireless Mouse incorporates the best of Logitech’s many computer mouse innovations into a striking hand-sculpted design. The company claims that the MX Master creates a new... Read more
Save up to $300 on a new Mac, $30 on an iPad,...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
Apple refurbished 2014 MacBook Airs available...
The Apple Store lowered prices on Apple Certified Refurbished 2014 MacBook Airs recently, with models now available starting at $679. An Apple one-year warranty is included with each MacBook, and... Read more
Mac Notebook Evolution; A Desktop Replacement...
More often than not right from the beginning, Apple’s Macs have tended to skew toward small. The original Macs were called “compacts,”, and notwithstanding a few exceptions like the honking Big Mac... Read more
13-inch 1.4GHz/128GB MacBook Air (Apple refur...
The Apple Store has Apple Certified Refurbished 2014 13″ 1.4GHz/128GB MacBook Airs available for $759 including free shipping plus Apple’s standard one-year warranty. Their price is $240 off original... Read more
YEP! Alternative Browser for iOS Now Supports...
Pfaeffikon, Switzerland based Power App AG has announced the release of an update to their Yep! Web Browser (v1.3.0) for iOS8 iPhone and iPad. Yep! hit the App Store shortly after the release of iOS... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Sr. Technical Services Consultant, *Apple*...
**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional Read more
Lead *Apple* Solutions Consultant - Retail...
**Job Summary** Job Summary The Lead ASC is an Apple employee who serves as the Apple business manager and influencer in a hyper-business critical Reseller's store Read more
*Apple* Pay - Site Reliability Engineer - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.