Legacy Document

Inside Macintosh: Processes

Chapter 8 - Shutdown Manager / Using the Shutdown Manager

Installing a Custom Shutdown Procedure

If you write a shutdown procedure, you can install a pointer to it in the Shutdown Manager's queue by calling the ShutDwnInstall procedure. You're most likely to need to use a custom shutdown procedure if you are writing a device driver or a system extension. For example, drivers for early hard disk drives that use stepper motors usually need to park the drive heads in a safe zone before the power is turned off. Similarly, drivers for floppy disks and CD-ROM discs use a shutdown procedure that ejects the disks so that they don't remain in the drives when the computer shuts down.

If you are developing an application, you can also make use of shutdown procedures. For example, a remote backup application might install a shutdown procedure that reminds a user about scheduled backups. If the user attempts to shut down the computer before the application has backed up the disk, the shutdown procedure could display an alert box asking whether the user wants to back up the disk before the computer shuts down.

Remember that the Process Manager frees all application heaps before the Finder calls ShutDwnPower. For this reason, you can't rely on your heap being intact. You should load your shutdown procedure into the system heap and specify the constants sdOnDrivers or sdOnUnmount to ensure that the procedure is executed while the system heap and any necessary system software components are still available.

The ShutDwnInstall procedure accepts a number of constants that specify when during the shutdown process ShutDwnPower or ShutDwnStart should execute your custom procedure. You can specify more than one constant to have your procedure executed at different phases of the process. The points indicated by these constants are: before the drivers receive good-bye messages, before volumes are unmounted, or before the computer is restarted or the power supply is switched off. However, Apple Computer, Inc., cannot guarantee the state of the computer after volumes are unmounted. Accordingly, if you plan to use the system heap or call Toolbox or Operating System routines to open a file, display a dialog box, play a sound, and so forth, be sure to specify the sdOnDrivers or sdOnUnmount constants. For more information about these constants, see the description of the ShutDwnInstall routine on page 8-13.

Listing 8-2 illustrates a sample custom shutdown procedure that ejects a CD-ROM disc just before the Macintosh computer shuts down or restarts.

Listing 8-2 A sample custom shutdown procedure

PROCEDURE MyShutDownProc;
CONST
   kMaxScsiID = 7;
VAR
   MyDCEHandle:      DCtlHandle;
   CDRefNum:         Integer;       {driver reference number}
   myID:             Integer;       {SCSI ID}
   MyDevStatHandle:  DevStatHandle; {handle to driver's array}
BEGIN
   {Read driver reference number from the unit table.}
   CDRefNum := GetMyRefNum;
   IF CDRefNum = 0 THEN 
      Exit(MyShutDownProc);

   {Get handle to driver's device control entry.}
   MyDCEHandle := GetDCtlEntry(CDRefNum);

   {If handle is NIL, couldn't get device control entry.}
   IF MyDCEHandle = NIL THEN 
      Exit(MyShutDownProc);

   {Eject all mounted CD-ROM discs.}
   MyDevStatHandle := DevStatHandle(MyDCEHandle^^.dCtlStorage);
   FOR myID := 0 to kMaxScsiID DO
   IF (MyDevStatHandle^^[myID].isMyCDDrive = TRUE) AND
      (MyDevStatHandle^^[myID].mounted = TRUE) THEN
      MyEjectCDProc(myID);          {your routine to eject CDs}
END;

In Listing 8-2, GetMyRefNum returns the reference number for a CD device driver from the Device Manager's unit table. A value of 0 indicates that GetMyRefNum did not find a CD device driver. Next, MyShutDownProc calls GetDCtlEntry to retrieve the handle to the CD driver's device control entry record. Both the handle (of type DCtlHandle) and the device control entry record (of type DCE) are described in the chapter "Device Manager" in Inside Macintosh: Devices. If the value returned is NIL, then GetDCtlEntry did not find the device control entry, and MyShutDownProc returns. The MyShutDownProc procedure next loops through the driver's device status array looking for and ejecting mounted compact discs. The MyDevStatHandle handle points to the driver's array. After checking all elements in the array, MyShutDownProc returns control to the Shutdown Manager.

Note

Listing 8-2 does not define the device driver's array or the GetMyRefNum and MyEjectCDProc routines. These items are internal to the CD-ROM driver. ·

Once you have finished writing your shutdown procedure, you can install it by calling ShutDwnInstall. Your call to ShutDwnInstall should specify a pointer to MyShutDownProc, as follows.

ShutDwnInstall(@MyShutDwnProc, sdOnDrivers);

Assembly-Language Note

When the Shutdown Manager calls a shutdown procedure, it sets a bit in the D0 register indicating the current phase of the shutdown process. The values 0, 1, 2, and 3 represent the constants sdOnPowerOff, sdOnRestart, sdOnUnmount, and sdOnDrivers, respectively. You can have your shutdown procedure read D0 if it needs to keep track of the shutdown process. ·

The Shutdown Manager follows the standard conventions for saving registers.

You can remove your shutdown procedure at any time by calling ShutDwnRemove.