Important: The information in this document is obsolete and should not be used for new development.
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 theShutDwnInstall
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 constantssdOnDrivers
orsdOnUnmount
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 processShutDwnPower
orShutDwnStart
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 thesdOnDrivers
orsdOnUnmount
constants. For more information about these constants, see the description of theShutDwnInstall
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 thatGetMyRefNum
did not find a CD device driver. Next,MyShutDownProc
callsGetDCtlEntry
to retrieve the handle to the CD driver's device control entry record. Both the handle (of typeDCtlHandle
) and the device control entry record (of typeDCE
) are described in the chapter "Device Manager" in Inside Macintosh: Devices. If the value returned isNIL
, thenGetDCtlEntry
did not find the device control entry, andMyShutDownProc
returns. TheMyShutDownProc
procedure next loops through the driver's device status array looking for and ejecting mounted compact discs. TheMyDevStatHandle
handle points to the driver's array. After checking all elements in the array,MyShutDownProc
returns control to the Shutdown Manager.
Once you have finished writing your shutdown procedure, you can install it by calling
- Note
- Listing 8-2 does not define the device driver's array or the
GetMyRefNum
andMyEjectCDProc
routines. These items are internal to the CD-ROM driver. ·ShutDwnInstall
. Your call toShutDwnInstall
should specify a pointer toMyShutDownProc
, as follows.
ShutDwnInstall(@MyShutDwnProc, sdOnDrivers);The Shutdown Manager follows the standard conventions for saving registers.
- 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
, andsdOnDrivers
, respectively. You can have your shutdown procedure read D0 if it needs to keep track of the shutdown process. ·You can remove your shutdown procedure at any time by calling
ShutDwnRemove
.