toddpw@chairie.caltech.edu (Todd P. Whitesel) (02/22/91)
The following is quoted from IIgs tech note #87, concerning tool dispatcher patching. The full text is on tybalt.caltech.edu (I'm not sure if apple.com has this one yet, it's more recent than january '90 which is where apple.com appears to be frozen.) This note describes Apple's official word on patching the tool dispatcher, and it presents a good reason for using SetTSPtr and SetDefaultTPT. The warning in toolbox ref 3 for applications not to call SetDefaultTPT is a good one, but it doesn't consider INIT's applications and neither do I -- the reason being that SetDefaultTPT is only dangerous because it forces all currently loaded tools to stay loaded, and when INITs are running this is not nearly as dangerous as when Applications, real desktop applications, are running. Tool functions have to expect two RTL's on the stack because that is how the 'second' tool vectors ($e1/4 and $e1/c) are called -- with two RTL's on the stack. The normal vectors add an RTL before calling the actual tool functions -- the whole reason for doing it is to allow for high level languages that require tool glue (Orca/C does this with functions that return structs, I believe, but didn't do it properly and DTS put out a fixed library), or applications that call internal subroutines which call the toolbox and then handle errors automatically, and so on. Todd Whitesel toddpw @ tybalt.caltech.edu _____________________________________________________________________________ This Technical Note presents the Apple standard way to patch into the Apple IIgs Tool Dispatcher vectors. This Note presents MPW IIgs assembly-language code which provides the Apple- standard way for utilities to patch and unpatch the Tool Dispatcher vectors. If all Tool Dispatcher patches follow this protocol, patches can be installed and removed in any order, without ever accidentally unpatching somebody who patched in after the one getting removed. Using this protocol, each patch begins with a header in a standard form--a form recognizable by these routines (see PatchHeader). This way routines (like RemoveE10000) can scan through the list of patches and remove one from the middle. If your patch is going to stay in the system until shutdown, use this standard patch protocol anyway. This way other utilities can still recognize your patch and scan past it to find the next one. This Note is not just to show you a way to patch the tool dispatcher--it's to show you the way. If you patch tool dispatcher vectors in any other way, you strip other utilities of their ability to remove their patches. Of course, patching the Tool Dispatcher vectors slows down all toolbox calls, so you shouldn't patch the tool dispatcher without a pretty good reason. If you need to patch a toolbox function, it is usually better to do it by modifying a tool set's function pointer table instead of patching the dispatcher. The code in this note is specific to the System tool dispatch vectors ($E10000 and $E10004), but the same technique is recommended for the User tool dispatch vectors--just change $E10000 to $E10008, $E10004 to $E1000C, and ToolPointerTable to UserToolPointerTable.