Handler

This is the handler function name. The function must be exported as an entry point into the executable.

ThreadSafe

OSA and AppleScript in Mac OS X v10.6 are thread-safe. If a script is executed on a background thread and invokes an event handler that is not thread-safe, it will be called on the main thread, which is slower than directly invoking it on the calling thread and may reduce application responsiveness to user input. Ideally, all handlers should be thread-safe. Some inherently cannot be; for example, almost anything that displays UI must be executed on the main thread. You are encouraged to either verify that your event handlers are thread-safe or update them to make them thread-safe.

If the value of this key is true, then the handler may be executed on a non-main thread and it may be executed concurrently from multiple threads. If false, it will only be executed on the main thread. This key is required for event handlers, and must not be present for coercion handlers, which are required to be thread-safe. If a coercion handler cannot be made safe to run on background threads, the handler must arrange to execute the coercion on the main thread, such as using by using libdispatch and the main dispatch queue.

Context

For security reasons, Mac OS X v10.6 will only execute scripting additions in other processes if it is necessary, and in some cases may ask for authorization before doing so. Exactly how a scripting addition is handled depends on the value of the "Context" key, which describes what execution context the handler depends on in order to function correctly. In the script, a scripting addition command may be inside a tell block for, say, Mail.app on a remote machine, but if its "context" is relaxed enough, it will actually be executed in a different process that presents less of a security risk, typically the application running the script. The Context key may have one of four values:

Any value of Context implies the dependencies of the contexts above it, so User implies Machine dependencies, and Process implies User and Machine dependencies. Try to write handlers with as few dependencies as possible, since more dependencies means greater security risk.

This key is required for event handlers, and must not be present for coercion handlers, which are always executed in the same process as the script.

Initialization

Your scripting addition's initialization routine is responsible for installing your scripting addition's handler routines. To implement it, the scripting addition must export a routine named SAInitialize, which will be called by AppleScript and must install all the event and coercion handlers. Listing 3 provides a sketch of a scripting addition's initialization routine:

Listing 3  Sample scripting addition initialization routine.

OSErr SAInitialize(CFBundleRef additionBundle)
{
    OSErr err;

    Boolean isSysHandler = true;
    err = AEInstallEventHandler(theAEEventClass, theAEEventID, eventHandlerUPP, refcon, isSysHandler);
    err = AEInstallCoercionHandler(fromType, toType, coercionHandlerUPP, refcon, fromIsDesc, isSysHandler);

    return err;
}

All scripting addition handlers must be installed in the system dispatch table, as shown above.

Your scripting addition should always install all of its handlers, even if functionality they require is not present in the system. That way, you have an opportunity to provide a meaningful error message when your addition is invoked, rather than the generic "doesn't understand" or "can't coerce" message.

Your initialization function may perform additional setup operations, such as allocating memory or finding files, but this is not recommended: it creates additional startup cost, and may not even be necessary, since your scripting addition may never be invoked. Initialization should be deferred until your addition is actually invoked.

The additionBundle parameter passed to SAInitialize is a reference to the scripting addition's bundle. This is only present for historical reasons. If a handler needs access to the scripting addition's bundle resources, it can locate the bundle using CFBundleGetBundleWithIdentifier.

Information about bundle references and the bundle format can be found in the References section at the end of this article.

Termination

Your scripting addition's termination routine is responsible for removing your scripting addition's handler routines. To implement it, a scripting addition must export a routine named SATerminate, which will be called by AppleScript and must remove all the event and coercion handlers. Listing 4 provides a sketch of a scripting addition's termination routine:

Listing 4  Sample scripting addition termination routine.

void SATerminate(void) {     AERemoveEventHandler(theAEEventClass, theAEEventID, gTheHandler, true);     DisposeAEEventHandlerUPP(gTheHandler);      ...other cleanup operations... }

The termination routine may perform other cleanup operations, such as releasing resources. However, the termination function will never be called in Leopard. If your addition needs to do work at process termination time, such as releasing resources, use atexit(3). Bear in mind that many resources, such as allocated memory, will be freed automatically when the process exits.

Reference Counting

This routine exists for historical reasons: in classic Mac OS, it was possible to crash the system by removing a scripting addition while it was still running. Therefore, scripting additions exported a function named SAIsBusy to indicate whether or not they were busy, and therefore not safe to unload. This possible crash was solved by other means in Mac OS X v10.2, rendering SAIsBusy obsolete. It still needs to exist, but can simply return false, as shown in Listing 5.

Listing 5  Sample SAIsBusy routine for a scripting addition.

Boolean SAIsBusy(void) {     return false; }

Runtime Considerations

Your scripting addition may be loaded into any application's process, and should therefore take care to not disturb the global state outside of the addition handler itself, such as the Resource Manager resource chain, effective user id, and so on.

Scripting additions are loaded separately into each application process that uses them. As a result, you should design your scripting addition keeping in mind that there may be many instances of your scripting addition open in many different applications at the same time. Some scripting additions may require additional code if they use a single shared resource such as a printer or a serial port.

Locating Your Scripting Addition's Bundle Resources

Scripting additions may need to access resources and files located inside of their bundle. To do this, get a CFBundleRef using CFBundleGetBundleWithIdentifier, passing it the bundle identifier of your scripting addition.

Information about bundle references and the bundle format can be found in the References section at the end of this article.

Local and Remote Requests

If executing your scripting addition command on a remote machine is not meaningful or would constitute a security risk, your command handler should detect and reject events from remote machines. A handler can determine the source of an event by examining the keyEventSourceAttr attribute in the incoming event. An event from a remote system will have an attribute value of kAERemoteProcess.

DescType sourceAttr;

err = AEGetAttributePtr(eventPtr, keyEventSourceAttr, typeType, NULL, &sourceAttr, sizeof(sourceAttr), NULL);
if (err != noErr || sourceAttr == kAERemoteProcess)
{
    return errAELocalOnly;
}