Legacy Document

Inside Macintosh: Processes

Chapter 8 - Shutdown Manager / Using the Shutdown Manager

Sending a Shutdown or Restart Event

Applications that support high-level events can send a Shutdown or Restart event to the Finder to request the system to shut down or restart. Once notified, the Finder calls the Process Manager, which gives open applications the opportunity to exit gracefully before the computer shuts down or restarts. The Process Manager checks its list of open applications and sends a Quit Application event to applications that can process Apple events. For applications that can't, the Process Manager sends a mouse-down event indicating that Quit was chosen from the File menu. Applications that display the Quit item in a different menu or that use a different wording must specify a resource of type 'mstr' or 'mst#'with a resource ID of 100 or 101, respectively. Once notified, the open applications then have time to perform cleanup operations (such as displaying a Save Changes alert box) before quitting.

The Shutdown and Restart events have the event class defined by the kAEFinderEvents constant.

CONST
   kAEFinderEvents = 'FNDR';     {event class for Finder}

The Restart event has the event ID defined by the kAERestart constant, and the Shutdown event has the event ID defined by the kAEShutDown constant:

CONST
   kAERestart = 'rest';    {event ID for Restart event}
   kAEShutDown = 'shut';   {event ID for Shutdown event}

Listing 8-1 defines a function that sends a Shutdown event to the Finder.

Listing 8-1 Sending a Shutdown event

FUNCTION ShutDownSafely: OSErr;
CONST
   kFinderSig = 'FNDR';
VAR
   myErr:         OSErr;
   finderAddr:    AEDesc;
   myShutDown:    AppleEvent;
   nilReply:      AppleEvent;
BEGIN
   myErr := AECreateDesc(typeApplSignature, kFinderSig,
                        SizeOf(OSType), finderAddr);
   IF myErr = noErr THEN
      myErr := AECreateAppleEvent(kAEFinderEvents, kAEShutDown,
                              finderAddr, kAutoGenerateReturnID,
                              kAnyTransactionID, myShutDown);
   IF myErr = noErr THEN
      myErr := AESend(myShutDown, nilReply, kAENoReply +
                  kAECanSwitchLayer + kAEAlwaysInteract,
                  kAENormalPriority, kAEDefaultTimeout, NIL, NIL);
   ShutDownSafely := myErr;
END;

To send a Shutdown or Restart event, you must call three Apple Event Manager functions. First, use the AECreateDesc function to create an address descriptor record that specifies the address of the Finder. You can specify the address of the Finder by its signature, 'FNDR'. Next, call AECreateAppleEvent to create the Apple event you want to send. Finally, call the AESend function. Use the Apple event returned in the myShutDown variable of the AECreateAppleEvent function as the Apple event to send in AESend.

After sending the event, remember to dispose of the descriptor record and Apple event at some point, by calling the AEDisposeDesc function. For complete details about this function and the ones used in Listing 8-1, see the chapter "Apple Event Manager" in Inside Macintosh: Interapplication Communication.

Note

Applications running under system software version 6.0.x cannot send Apple events to MultiFinder because it cannot process them. As a result, your application cannot request that open applications be notified to quit before it calls ShutDwnPower and ShutDwnStart. Therefore, you should avoid calling these procedures unless absolutely necessary. ·