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

How to get a high score in every level o...
Sky Charms is an adorable match three puzzler that provides a decent challenge thanks to its creative level design. It regularly presents something new, forcing you to think on your feet. [Read more] | Read more »
Apestorm: Full Bananas (Games)
Apestorm: Full Bananas 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: ***Launch sale – limited time only!*** Fugitive Apes have taken to the skies in search of revenge after humans have... | Read more »
How to create bigger words in Spellspire
Words have power. At least they do in Spellspire,a game about blasting out magical attacks by making words out of a jumble of letters. And it's a lot of fun. But if you want to be the best, you're going to have to think tactically when you start... | Read more »
Steel Media and DeePoon have partnered f...
Virtual reality is the next big thing, and 148Apps's publisher,Steel Media, wants to know what the hottest upcoming games are. [Read more] | Read more »
Airline Director 2 - Tycoon Game (Games...
Airline Director 2 - Tycoon Game 1.2.1 Device: iOS Universal Category: Games Price: $2.99, Version: 1.2.1 (iTunes) Description: Airline Director 2 is a management game set in the challenging field of commercial aviation. As the... | Read more »
Dog Mendonca (Games)
Dog Mendonca 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: [ Solve a criminal case beyond believe in this supernatural adventure game based on the popular graphic novel trilogy published... | Read more »
Amidakuji Knight (Games)
Amidakuji Knight 1.0 Device: iOS Universal Category: Games Price: $.99, Version: 1.0 (iTunes) Description: Ghost leg rules meets RPG!Select the best path and save a princess! A long long time ago, there was a beautiful and peaceful... | Read more »
The 5 best mobile games like Game of Thr...
Everyone's favourite weekly dosage of medieval depression, Game of Thrones, is back for its sixth season. An excellent time for the bloodthirsty! [Read more] | Read more »
How to approach quests in Fallen London
Sitting at over 1.5 million words, Fallen London is filled to the brim with intriguing tales and mysterious characters. From the start, you’ll find a slew of quests ripe for the taking. [Read more] | Read more »
How to survive in LOUD on Planet X
LOUD on Planet X is a hybrid of a tower defense and rhythm game that pits famous indie acts against invading aliens. You need timing and strategy in this game in order to succeed, things can get pretty overwhelming pretty quickly. Here are some... | Read more »

Price Scanner via MacPrices.net

Aleratec Releases Mac Software Upgrade for 1...
California based Aleratec Inc., designer, developer and manufacturer of Portable Device Management (PDM) charge/sync products for mobile devices and professional-grade duplicators for hard disk... Read more
Sale! Amazon offers 27-inch iMac, 13-inch 2.9...
Amazon has the 27″ 3.2GHz 5K iMac and the 13″ 3.9GHz Retina MacBook Pro on sale for $300 off MSRP, each including free shipping, for a limited time: - 27″ 3.2GHz/1TB HD 5K iMac (model MK462LL/A): $... Read more
Apple refurbished 13-inch Retina MacBook Pros...
Apple has Certified Refurbished 13″ Retina MacBook Pros available for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.7GHz... Read more
13-inch 2.7GHz/128GB Retina MacBook Pro on sa...
Take $200 off MSRP on the price of a new 13″ 2.7GHz/128GB Retina MacBook Pro (model MF839LL/A) at Amazon. Shipping is free: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1099.99 $200 off MSRP Act now if... Read more
Apple refurbished clearance 15-inch Retina Ma...
Apple has Certified Refurbished 2014 15″ 2.2GHz Retina MacBook Pros available for $1609, $390 off original MSRP. Apple’s one-year warranty is included, and shipping is free. They have refurbished 15... Read more
27-inch 5K iMacs on sale for up to $150 off M...
B&H Photo has 27″ 5K iMacs on sale for up to $150 off MSRP including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2199 $100 off MSRP - 27″ 3.2GHz/1TB Fusion iMac 5K: $1849.99 $150... Read more
What Does The Refreshed 12-Inch MacBook Tell...
A lot of commentators are complaining that Apple’s update of the 12-Inch MacBook last week is a bit of a damp squib. I don’t know what they were expecting, since it would be very unlike Apple to do a... Read more
Free Wittify Keyboard Now Available On The Ap...
A team of Harvard Business School students have announced that the Wittify Keyboard, a new app utility for iOS devices, is now available on the Apple App Store. The Wittify keyboard and application... Read more
Apple Reports First Year-Over-Year Quarterly...
Apple on TUesday announced financial results for its fiscal 2016 second quarter ending March 26, 2016. The Company posted quarterly revenue of $50.6 billion and quarterly net income of $10.5 billion... Read more
13-inch 2.7GHz Retina MacBook Pros on sale fo...
Take $130-$150 off MSRP on the price of a new 13″ 2.7GHz Retina MacBook Pro at Amazon. Shipping is free: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1169 $130 off MSRP - 13″ 2.7GHz/256GB Retina MacBook... Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
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* Solutions Consultant - … (United Sta...
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
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
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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.