Legacy Document

Inside Macintosh: Processes

Chapter 5 - Notification Manager / Using the Notification Manager

Defining a Response Procedure

The nmResp field of the notification record contains the address of a response procedure executed as the final stage of a notification. If no processing is necessary in response to the notification, then you can supply the value NIL in that field. If you supply the address of your own response procedure in the nmResp field, the Notification Manager passes it one parameter, a pointer to your notification record. For example, this is how you would declare a response procedure having the name MyResponse:

PROCEDURE MyResponse (nmReqPtr: NMRecPtr);

When the Notification Manager calls this response procedure, it does not set up the A5 register or application-specific system global variables for you. If you need to access your application's global variables, you should save its A5 value in the nmRefCon field. See the chapter "Memory Management Utilities" in the book Inside Macintosh: Memory for more information on saving and restoring the A5 world.

Response procedures should never cause anything to be drawn on the screen or otherwise affect the human interface. Rather, you should use them simply to remove notification requests from the notification queue and free any memory. If you specify the special nmResp value of -1, the Notification Manager removes the queue element from the queue automatically, and you don't have to do it yourself. You have to pass your own response routine, however, if you need to do anything else in the response procedure, such as free the memory block containing the queue element or set an application global variable indicating that the notification was received.

If you use audible or alert notifications, you should probably set nmResp to -1 to remove the notification record from the queue as soon as the sound ends or the user dismisses the alert box. However, if either nmMark or nmIcon has a nonzero value, you should not set nmResp to -1 (because the Notification Manager would remove the diamond mark or the small icon before the user could see it). Note that when the value of nmResp is -1, the Notification Manager does not free the memory block containing the queue element; it merely removes that element from the notification queue.

Because the execution of the response procedure is the last step in the notification process, your application can determine whether the notification was posted by examining a global variable that you set in the response procedure. In addition, to determine that the user has actually received the notification, you need to request an alert notification. This is necessary because the response procedure is executed only after the user clicks the OK button in the alert box.