IAC Tools 3.0.3

UserLand Software, Inc.

© copyright 1992-1994, UserLand Software, Inc.

UserLand Software is located at 555 Bryant #237, Palo Alto, CA 94301. 415-326-7791, 415-326-7793 (fax). UserLand, Frontier and Frontier Runtime are trademarks of UserLand Software, Inc. Other product names may be trademarks or registered trademarks of their owners.

Email: userland.dts@applelink.apple.com. If youÕre an AppleLink user, check out the UserLand Discussion Board under the Third Parties icon. CompuServe users enter GO USERLAND at any ! prompt. On America On-Line, enter the keyword USERLAND.

Comments, questions and suggestions are welcome!

About IAC Tools

The C source files in this folder implement a simplified API for sending and receiving Apple Event messages. A lot of the power of the Apple Event Manager is hidden by this API. But weÕve found that most applications of IAC donÕt require all the power of the Apple Event Manager.

If youÕre going to do IAC youÕll probably want to write routines that simplify it. Feel free to use our source code as a starting point, or use the IAC Tools API as provided in iac.c.

All the other libraries in Frontier SDK build on the IAC Tools API.


IAC Tools 3.0.3 -- 7/27/94 dmb

Universal Headers, PowerPC compatibility

The IAC Toolkit can now be built using AppleÕs Universal Headers under Symantec C/C++ 7.0 or Metrowerks C/C++ 1.0 68K or PPC. Native or Òfat binaryÓ applications can be generated in the Code Warrior environment. Also, modern, ANSI-conformant function prototypes are used thoughout the code, so strict error checking can be enforced for IAC Toolkit projects.

IAC Tools 3.0 Change Notes

Support for new data types

HereÕs a list of the new files in the IAC Tools folder, including information about the data type it manages:

1.  iacdate.c
A 4-byte value returned by the toolbox GetDateTime call, the number of seconds since January 1, 1904, 12:00:00 AM.
Corresponds to the Frontier ÒdateÓ type.
2.  iacfilespec.c
A FSSpec, a struct containing a fileÕs vRefNum, parent directory ID and the name of the file.
Corresponds to the Frontier ÒfilespecÓ type.
3.  iacrgb.c
A RGBColor, a struct containing values for a red, green and blue description of a color. Each element is a 16-bit unsigned number.
Corresponds to the Frontier ÒrgbÓ type.
4.  iacstring4.c
An OSType, a 4-byte character string.
Corresponds to the Frontier Ôstring4Õ type.
5.  iactable.c
A Handle containing a packed Frontier table.
Used by the Applet Toolkit for documents that contain an embedded table.
There are no routines to parse the contents of a packed table.

Support for Apple Event records and lists

Frontier 3.0 includes direct support in the language for Apple Event records and lists. iacrecord.c and iaclist.c provide routines for accessing and building records and lists.

Thanks to John Baxter for this code! He writes ÒYou can get any of the supported types from a list or record, or put them into a list or record, or obtain information regarding the type or size of any AE parameter or any item in a list or record, or the keyword of the n-th item in a record. Note that an Apple event structure itself can be passed to the record-handling routines...in fact the implementation of all the tools has been changed to do just that, rather than duplicate the code. The Apple Event structure is simply a specialized AERecord structure.Ó


IAC Tools 2.0 Change Notes

System Event Handlers

Background

In IAC Tools 2.0, we introduce a way to create system event handlers. These work exactly the same way as non-system Apple Event handlers, but they often run much faster. But there are limits to what you can do in a system event handler. Support for system event handlers is implemented in iacsysevents.c in the IAC Tools folder.
Frontier 2.0 has support for system event handlers, Frontier 1.0 does not. All future versions of Frontier will support system event handlers.

Installing a system event handler

Call IACinstallsystemhandler instead of IACinstallhandler. The parameter lists are identical, the handler works the same way, but the system handler installer does a lot more work for you both at install time and when the handler is invoked. For details, check out the source to IACinstallsystemhandler and callhandler in iacsysevents.c

Trig

Our sample application for system event handlers is Trig.
It installs a system event handler for all of its messages that can be handled without a full context switch. It installs a normal handler for messages that must be handled slowly, such as displaying a string in the message window.
You can explore the source code to see how system event handlers are implemented. Open trig.¹ in the Trig folder, then open main.c. You'll see two statements in function main ():
if (!IACinstallsystemhandler ('trig', typeWildCard, &handlefastverb))

goto error;

if (!IACinstallhandler ('TRIG', typeWildCard, &handleslowverb))

goto error;

You can view the source of IACinstallsystemhandler in iacsysevents.c and handlefastverb and handleslowverb in main.c.
BarChart uses the Applet Toolkit to implement its system event handler. See bcfastiacmessage () in barchart.c for details.
DocServer 2.0 also uses fast event handlers.

Limits of System Event Handlers

¥  You can reference your globals.
IAC Tools maintains the A5 register for you. Anything declared globally is available to your code when running from a system event handler.
¥  You cannot depend on the window list.
The sending appÕs window list is current. WeÕve tried experiments to see if we can write into our own windows if we've saved WindowPtrs in A5-based globals. So far, no success.
¥  You cannot do any drawing.
This is completely uncharted territory. For now we are not doing any drawing from system event handlers.
¥  You cannot do anything with resources.
The resource map isnÕt yours. There may be some way to save and restore it, but we feel comfortable with this restriction. Resource-based operations can safely be done in scripts without calling any system event handlers.
¥  You can allocate, deallocate and reference things in your application heap.
We also maintain information about your heap zone, and save and restore the current heap zone. Without doing this, any allocation would be stored in the other app's heap.

Why system events are faster

Instead of being attached to your application, system event handlers belong to the operating system. They're much faster because there is no context switch. When the script running in Frontier calls one of your system event handlers, none of the heavy machinery of the Macintosh Process Manager gets invoked.

IACremovesystemhandlers ()

All apps that install system event handlers must call IACremovesystemhandlers before exiting. If they don't, system event handlers will accumulate in the system event table. If somehow one of these handlers were invoked, the system would almost certainly crash.
IACremovesystemhandlers is called by Trig at the end of main () in main.c.
IACremovesystemhandlers is called by the Applet Toolkit at the end of runapplet in appletmain.c.

Calling System Event Handlers from Frontier

From Frontier 2.0, you can invoke a system event handler by calling the new systemEvent verb.
Here's an example, the script that calls the Trig verb that determines the absolute value of a number:
on abs (x)

return (systemEvent ('trig', 'abs ', 'ÐÐÐÐ', double (x)))

Trig installs two classes of handlers, one to handle its slower events and one to handle the faster events. The slower event handler's class is 'TRIG' and the faster one's class is 'trig'. WeÕre also following that convention in the Applet Toolkit, all uppercase is the slower handler, all lowercase is the faster one.

Reorganized IAC Tools

In Frontier SDK 1.0, IAC Tools was implemented in a single C source file. In 2.0, there are 20 source files.

We reorganized for two reasons:

1.  To take advantage of THINK C's "Smart Link" feature. If an application or code extension never calls routines in one of the files, the code for that file isn't linked into the resulting program or resource. This was especially important in implementing space-efficient UCMDs.
2.  By having modular support for each data type (long, string, text, boolean, etc.) it makes it easier to upgrade IAC Tools to support additional data types. If you implement support for a new type, please consider sharing it with other users of the IAC Tools library.

Here's a list of the 20 files that make up the IAC Tools library:

1.  iac.c ÐÐ main file.
2.  iac.h ÐÐ header file, include this in all files that call iac.c routines.
3.  iacapps.c -- routines that are likely to be called by a double-clickable application.
4.  iacasynch.c ÐÐ support for asynchronous Apple Events.
5.  iacbinary.c ÐÐ support for binary parameters and returned values.
6.  iacboolean.c ÐÐ support for boolean parameters and returned values.
7.  iacdouble.c ÐÐ support for double parameters and returned values.
8.  iachandler.c -- routines that install and remove Apple Event handlers.
9.  iacinternal.h ÐÐ function prototypes for routines in iacops.c.
10.  iaclong.c ÐÐ support for long parameters and returned values.
11.  iacnewsystemverb.c -- the single system-handler call that UCMDs are likely to make. Putting this routine in a separate file helps keep code extensions smaller.
12.  iacops.c ÐÐ basic support routines for all iacxxx.c files.
13.  iacpoint.c ÐÐ support for Point parameters and returned values.
14.  iacreceive.c -- routines for code that receives Apple Events.
15.  iacrect.c ÐÐ support for Rect parameters and returned values.
16.  iacsend.c -- routines for code that sends Apple Events.
17.  iacshort.c ÐÐ support for short parameters and returned values.
18.  iacstring.c ÐÐ support for string parameters and returned values.
19.  iacsysevents.c ÐÐ support for system event handlers.
20.  iactext.c ÐÐ support for text parameters and returned values.

Changed 'doub' to 'exte'

In Trig, double parameters were coming in from Frontier with the type 'exte' not 'doub.' In the Quick Script window I typed ÒdoubleTypeÓ and got the value 'exte'. This nailed it for me. Could it be that the double routines in iac.c never worked?

Routines that work with double-precision floating point numbers now deal with parameters whose type is 'exte'. THINK C developers: be sure that Native Floating Point Format is checked in the Options dialog.

New field in IACglobals ÐÐ idprocess

It's set by IACinit by asking the Process Manager for the id of the process we're running inside of. Menu Sharing Toolkit now uses this field to set the value of MSglobals.clientid.

Asynchronous events

Added support for asynchronous events in iacasynch.c. You create the message using IACnewverb or IACnewsystemverb, add parameters, and then call IACsendasynch to send the message. You provide a callback routine that gains control when the answer is received.

All messages sent "normal" priority

In IACnewverb, we used to send them with the constant kAEHighPriority, now we use the constant kAENormalPriority.

New iac.c routine IAChandlerinstalled

Makes it possible to find out if an event handler has been installed for a given class and id. This call is used by menusharing.c to determine if fast menu sharing is available.

New field in IACglobals ÐÐ errorcode

Most iac.c routines just return true or false indicating whether they worked. In some cases you may need to know specifically why an operation failed. The error code from all iac.c routines is copied into IACglobals.errorcode for this purpose.

Changes from Leonard Rosenthol, Aladdin Systems

Leonard made several changes to IAC Tools and asked that they be integrated with the released version of iac.c/iac.h. Here's a list of the changes:

1.  Streamlined IACreturnstring.
2.  Added IACnextparamisoptional to mimic functionality that was available in UserLand IAC Toolkit.
Call this function before doing one of the IACgetxxxparam routines. If the param isn't there, the Apple Event handler will not return an error to the caller. Added a new global, IACglobals.nextparamoptional to support this.

Deleted IACpushCstringparam, IACgetCstringparam

They were there to support some early experimentation we were doing with Microsoft apps. The experiment didn't lead anywhere, so we axedÕm.

IACreturnerror

In iac.c, if errs is nil or empty, then don't push the string onto the reply. The net: Frontier will interpret the error code as a Macintosh operating system error and display a more informative error message.

BarChart

Now implements a pair of system event handlers that allow a script to get the value of a bar very quickly, and to set the value of a bar.