Hey You
Volume Number: | | 5
|
Issue Number: | | 5
|
Column Tag: | | Advanced Mac'ing
|
Related Info: Notification Mgr
The Notification Manager
By Steven Sheets, Contributing Editor, Haufman Estates, IL
Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.
Hey You: The Mac Notification Manager
More and more, code is being written for the Macintosh that runs in a multitasking environment. At first, an application only had to share space with Desk Accessories. Then came MultiFinder, and multiple applications started running at the same time. Along the way, Macintosh programmers started creating various low level routines to do tricks with the machine (INITs that load routines into system memory, vertical retrace routines, time manager wakeup routines, redirection of normal traps, etc.). At any given time, half a dozen or more code segments may be running in addition to a single normal application.
These code segments have to work in a very restrictive environment. Some are not allowed access to global data. Many can not make Toolbox calls that move or purge memory. Others can not even have control of the CPU for longer than a tick (60th second). Even a normal application cannot place an alert where the user can see it if it is running in the background under MultiFinder. How can these code segments inform the user of some event or action with these limitations?
Enter one of newest Toolbox managers from Apple; the Notification Manager. The Notification Manager allows the code to post a notification request that, in some method, notifies the user of something. A Notification Request can consist of an Alert Notification (displaying a text message), an Audible Notification (playing a snd sound), an Icon Notification (displaying a small icon, or SICN, in the upper left corner on top of the Apple icon) or some combination.
Using the Notification Manager, a terminal program running in the background can inform the user when a download is complete. No matter what is running at the time, when the request is processed, the Notification Alert will appear on top of all windows. Using the Manager, an Appletalk Mail program could inform the user of new mail with a flashing mail box icon.
The Notification Manager handles the processing of all requests (playing the sound, clicking on the alert, flashing the icon, etc.) asynchronously. The code segment would use two new Toolbox traps to inform the manager of a request. Neither of these two calls process the request, they simply add or detach records from the Notification Manager list. Because of this, they neither move nor purge memory, and can be safely called at any time, even inside of a low level interrupt procedure.
The Notification Manager was implemented in the System Software 6.0. The new Toolbox traps will not function on systems prior to 6.0. Portions of the System Software 6.0 already uses the Notification Manager. By flashing a small Clock icon, The Alarm Clock use the manager to signal that the alarm has gone off. The Print Monitor also uses the Notification Manager to signal printing information.
The Notification Manager
The Notification Manager maintains a queue (list) of requests that need to be processed. Whenever SystemTask or WaitNextEvent is called, the Notification Manager checks the queue for an unprocessed request. First the Notification Request, if there is one, is processed, then the response routine, if there is one, is called. The response routine can be the default routine (simply removes the request record from the queue) or the code segment can define its own response routine to do whatever it wants.
The Notification Request is a standard Macintosh Queue record expanded for the Notification Manager. The record has the following format:
{1}
NMRec = record
qLink: QElemPtr;
qType: INTEGER;
nmFlags: INTEGER;
nmPrivate: LONGINT;
nmReserved: INTEGER;
nmMark: INTEGER;
nmSIcon: Handle;
nmSound: Handle;
nmStr: StringPtr;
nmResp: ProcPtr;
nmRefCon: LONGINT;
end;
The qLink pointer points to the next request in the linked list and should not be changed by the code segment. Neither should the nmPrivate or nmReserved elements be changed by the code; the manager handles them. The qType (type of queue) of a Notification Queue is the value 8, the integer value of ORD(nmType). The qType element needs to be set to 8 before the request is added to the queue.
The nmStr pointer points to the text message that would be displayed by the Notification Manager in an alert. If the pointer is set to nil, no alert will be displayed. The nmSound is a handle to a sound record (ie. snd resource). The Sound Manager will play it before the alert is displayed. If nmSound is set to -1, the System Error sound is used. If it is set to 0, no sounds are played. The nmSIcon is the handle to the small icon (32 bytes, 16 by 16 pixel bitmap) that the Notification Manager will flash in the upper left corner of the screen on top of the Apple icon. Usually this small icon is stored as a resource of type SICN. A nil value for nmSIcon signifies no flashing icon. The nmMark element indicates who generated the notification event. An application should set nmMark to 1. When under MultiFinder, a diamond mark will be placed in the Apple menu next to the applications name. If the request was generated by a Desk Accessory, nmMark should be set to the refNum of the DA. This will place a diamond mark next to the DAs name. All other types of code segments (Drivers, patches, etc.) should set this value to 0.
The nmResp is the pointer to the procedure called after the request is processed. If nmResp is set to 0, no procedure is called. If it is set to -1, a special response routine is called that removes that request from the queue. This response routine does not dispose of any memory (the string, the sound, the icon, or the request itself). If the code segment wants to define its own response routine, nmResp is set to the pointer of that routine. In most cases (main exception is Icon Alerts), the response procedure should remove the request from the queue immediately. The response procedure has the following format:
PROCEDURE MyResponse (nmReqPtr : QElemPtr) ;
The response routine will be called by the Notification Manager during a SystemTask or WaitNextEvent call. Thus it is safe to move or purge memory. It is also safe to do any I/O (file, resource, serial, Appletalk). If the routine is suppose to change some global variables of an application, it must first make sure that the A5 is correct. For example, when under MultiFinder, the notification may occur when some other applications A5 is set. The nmRefCon may come in handy to store the value of A5. The nmRefCon element can be used by the code segment for what ever purpose the code segment wants. A handle to a data structure, a pointer to a Boolean flag, or the correct A5 value could be stored there.
Apple states that the response routine should not do user interface type of drawing. Instead the routine should set a flag so that the application knows when it should do the drawing. To change a Boolean flag, it is simpler to stuff a pointer to the flag into nmRefCon than it is to change A5 back and forth.
Using the Notification Manager
There are only two routines that exercise the Notification Manager, NMInstall and NMRemove. NMInstall is passed the pointer to the notification request that is to be installed into the queue. It returns noErr (0) if successful. NMRemove is passed a pointer to a notification request already installed in the queue. If it is successful in removing that request, it returns noErr also. Unless a request wants an Icon to be flashed for awhile, the NMRemove routine should be called after a notification request has been processed. Both calls are register based. The following are the Inline Glue routines needed to use the call from Pascal and the Assembler information:
{2}
FUNCTION NMInstall (nmReqPtr : QElemPtr) : OSErr;
inline $205F, $A05E, $3E80;
_NMInstall ($A05E)
On entry: A0pointer to the NMRec
On exit:D0result code
FUNCTION NMRemove (nmReqPtr : QElemPtr) : OSErr;
inline $205F, $A05F, $3E80;
__ NMRemove ( $A05F )
On entry: A0pointer to the NMRec
On exit:D0result code
The Sample Program: HeyYou
HeyYou uses the Notification Manager to show 3 different effects. The NotifStr routine demonstrates the simplest effect, displaying a text message to the user. The routine uses two global variables, a string to hold the text, and a NMRec to hold the notification request. The request nmResp is set to -1 so that the Notification Manager will automatically remove this request from the queue after it has been done. Since the data is stored in global variables, no other clean up has to be done.
The NotifSnd routine demonstrates a slightly more involved request. It plays a sound (snd resource) and displays a text message. No global variables are used in this example. Instead memory is allocated to hold the request and the test string. The nmResp is set to a pointer to the MySndResponse so that when the request is done, the MySndResponse routine can be called. MySndResponse can remove the request from the queue, release the sound from memory, dispose of the memory holding the string, and finally dispose of the memory holding the request itself.
The method used in NotifSnd works well for code segments that have no access to global memory space such as Desk Accessories, INITs, etc. This method also has the additional advantage of allowing more than one request to be added at the same time. This could not be done with NotifStr since each request shared the same global variables. As long as MySndResponse is locked in memory somewhere, the method used in NotifSnd will work.
The last example, NotifIcon, demonstrates the use of icons by the Notification Manager. It displays a text message, blinks a small icon in the upper left corner of the screen and marks HeyYou as the application that caused this request. Usually the code segment wants the icon to flash in the corner until the user has done something in response. For example, the Alarm Clock does not remove its icon until the alarm is turned off. To keep the Icon in use until the appropriate time, the notification request can not be removed from the queue or the flashing effect would be lost. Thus no response routine is specified. Instead the application removes the request (and flashing icon) when the application quits, when it resumes after a switch under MultiFinder, or when the user selects the Remove Icon menu item. In HeyYou, one example sets a timer going so that NotifIcon is processed 60 seconds after the menu item is selected. Since HeyYou and the timer work in the background under MultiFinder, this will demonstrate how the Notification Manager works when some other application is running. Notice the mark that appears next to the program name HeyYou in the Apple menu.
Beyond...
Here are some last ideas for Notification Manager routines/utilities that can be written:
1) An example that places a Notification Request in low System memory, and starts a Timer routine that will install the request sometime in the future. The response routine is set so that it removes the request and releases the memory used by everything (string, request, timer routine, response routine). With this routine, a Smart Alarm Clock would be easy to create.
2) An Appletalk socket completion routine that automatically adds a request whenever someone sends a packet to that computer. If this socket is loaded into low memory, it would create a simple pager utility.
3) A routine that would install an Icon Notification request, then set up a timer so that the request (and icon) would be automatically removed a few moments later.
Listing: HeyYou.pas
{ HeyYou program for MacTutor by Steve Sheets}
{Demonstrates uses of the Notificaiton Manager. Creates some simple
String Notifications, some Sound }
{Notifications, some Small Icon Notifications (imediately and after a
delay).}
program HeyYou;
{ Resource Constants. }
const
SICNdiamond = 0;
SICNheyyou = 500;
SNDbeep = 1;
SNDclick = 2;
SNDbong = 3;
SNDmonkey = 4;
ALERTabout = 500;
{Notification Manager Queue Record.}
type
NMRec = record
qLink: QElemPtr;
qType: INTEGER;
nmFlags: INTEGER;
nmPrivate: LONGINT;
nmReserved: INTEGER;
nmMark: INTEGER;
nmSIcon: Handle;
nmSound: Handle;
nmStr: StringPtr;
nmResp: ProcPtr;
nmRefCon: LONGINT;
end;
NMPtr = ^NMRec;
{Program Global Variables. Menus, Notification Requests, Strings and
Flags. }
var
myM1, myM2, myM3: MenuHandle;
StrRec, IconRec: NMRec;
StrStr, IconStr: Str255;
doneFlag, IconFlag: BOOLEAN;
Timer: LONGINT;
{Notification Manager Glue rotines.}
{Install Notifiaction Request into Queue. }
function NMInstall (nmReqPtr: QElemPtr): OSErr;
inline
$205F, $A05E, $3E80;
{MOVE.L (SP)+,A0 }
{_NMInstall }
{MOVE.W D0,(SP) }
{Remove Notifiaction Request into Queue. }
function NMRemove (nmReqPtr: QElemPtr): OSErr;
inline
$205F, $A05F, $3E80;
{MOVE.L (SP)+,A0 }
{_NMRemove}
{MOVE.W D0,(SP) }
{Checks to see if this is System 6.0 or above}
function CheckSystem: Boolean;
var
theWorld: SysEnvRec;
begin
if SysEnvirons(1, theWorld) = noErr then
CheckSystem := (theWorld.systemVersion >= $0600)
else
CheckSystem := FALSE;
end;
{Display About Info. }
procedure DoAbout;
var
dummy: INTEGER;
begin
dummy := Alert(ALERTabout, nil);
end;
{First Test of Notification Manager. }
{Displays a simple String. The Notification Request is automatically
removed after it is completed. }
procedure NotifStr (St: Str255);
var
E: OSerr;
begin
with StrRec do
begin
qType := 8;
{No Mark, Icons or Sounds.}
nmMark := 0;
nmSIcon := nil;
nmSound := nil;
{This String. }
StrStr := St;
nmStr := @StrStr;
{Automatically Removed when Completed. }
nmResp := POINTER(-1);
nmRefCon := 0;
end;
E := NMInstall(@StrRec);
end;
{Call by Notification Manager after a Sound Notification has been completed.
Removes}
{the entry from Notification queue, releases SND resource if there is
one, disposes of }
{string handle if there is one and disposes of the request record.
}
procedure MySndResponse (nmReqPtr: QElemPtr);
var
aPtr: NMPtr;
E: OSErr;
begin
aPtr := NMPtr(nmReqPtr);
E := NMRemove(nmReqPtr);
if (aPtr^.nmSound <> nil) and (aPtr^.nmSound <> POINTER(-1)) then
ReleaseResource(aPtr^.nmSound);
if aPtr^.nmRefCon <> 0 then
begin
HUnLock(Handle(aPtr^.nmRefCon));
DisposHandle(Handle(aPtr^.nmRefCon));
end;
DisposPtr(Ptr(nmReqPtr));
end;
{Second Test of Notification Manager.}
{Displays a String and plays a sound. Allocates memmory for the request
record and the string. }
{If Sound is -1, the System Beep is used. Any other number, indicates
a SND resource, and}
{that resource is loaded in. MySndResponse is setup so that it will
be called after Notification is completed.}
procedure NotifSnd (St: Str255; Sn: INTEGER);
var
E: OSerr;
tempRec: NMPtr;
StrHdl: StringHandle;
begin
tempRec := NMPtr(NewPtr(SIZEOF(NMRec)));
with tempRec^ do
begin
qType := 8;
{No Marks or Icons.}
nmMark := 0;
nmSIcon := nil;
{System Beep or SND resource. }
if (Sn = -1) then
nmSound := POINTER(-1)
else
nmSound := GetResource(snd , Sn);
{If String, allocate memmory for it. }
if St = then
begin
nmStr := nil;
nmRefCon := 0;
end
else
begin
StrHdl := NewString(St);
HLock(Handle(StrHdl));
nmRefCon := ORD4(StrHdl);
nmStr := StrHdl^;
end;
{Call MySndResponse to remove resource when completed. }
nmResp := @MySndResponse;
end;
E := NMInstall(QElemPtr(tempRec));
end;
{Third Test of Notification Manager. }
{Displays a String, displays a Small Icon and Marks the Current Application.
}
{This Notification is not removed until the User selects Remove Icon
}
{fromt the Menu or the Application is Quit. }
procedure NotifIcon (St: Str255; IC: INTEGER);
var
E: OSerr;
begin
if not IconFlag then
begin
IconFlag := TRUE;
with IconRec do
begin
qType := 8;
{Current Application is Marked (in MultiFinder).}
nmMark := 1;
{Small Icon is used. }
nmSIcon := GetResource(SICN, IC);
{No SND.}
nmSound := nil;
{This String. }
{Use String (if any).}
if St = then
nmStr := nil
else
begin
IconStr := St;
nmStr := @IconStr;
end;
{No Completion Routine. }
nmResp := nil;
nmRefCon := 0;
end;
E := NMInstall(@IconRec);
end;
end;
{If an small Icon is still flashing, Removes it and releases SND resource.
}
procedure RemoveNotifIcon;
var
E: OSerr;
begin
if IconFlag then
begin
IconFlag := FALSE;
E := NMRemove(@IconRec);
if IconRec.nmSIcon <> nil then
ReleaseResource(IconRec.nmSIcon);
end;
end;
{Normal Mac Setup Procedure }
procedure SetUp;
var
S: Str255;
begin
doneFlag := FALSE;
IconFlag := FALSE;
Timer := 0;
S := 1;
S[1] := CHR(applemark);
myM1 := NewMenu(101, S);
AppendMenu(myM1, NotifTest Source;(-);
AddResMenu(myM1, DRVR);
InsertMenu(myM1, 0);
myM2 := NewMenu(102, File);
AppendMenu(myM2, Quit);
InsertMenu(myM2, 0);
myM3 := NewMenu(103, Simple);
AppendMenu(myM3, String Test #1;String Test #2;(-;Bong Sound Test;Click
Sound Test;Bong and Click Sound Test);
AppendMenu(myM3, Monkey Sound Alone Test - no alert;System Error Sound
Test;(-;Diamond Icon Test);
AppendMenu(myM3, HeyYou Icon Alone Test - no alert;Delayed Icon Test;Remove
Icon);
InsertMenu(myM3, 0);
DrawMenuBar;
end;
{Normal Mac Menu Command Routine. }
procedure DoCommand (mResult: LONGINT);
var
theItem: INTEGER;
theMenu: INTEGER;
tempStr: Str255;
tempInteger: INTEGER;
tempLong: LONGINT;
begin
theItem := LoWord(mResult);
theMenu := HiWord(mResult);
case theMenu of
101:
if theItem = 1 then
DoAbout
else
begin
GetItem(myM1, theItem, tempStr);
tempInteger := OpenDeskAcc(tempStr);
end;
102:
if theItem = 1 then
doneFlag := TRUE;
103:
case theItem of
1:
NotifStr(This is a String Test of the Notification Manager.);
2:
begin
GetDateTime(tempLong);
IUTimeString(tempLong, TRUE, tempStr);
tempStr := CONCAT(This is another String Test of the Notification Manager.
The Time is , tempStr);
NotifStr(tempStr);
end;
4:
NotifSnd(This is a Sound Test of the Notification Manager using the
Bong sound., SNDbong);
5:
NotifSnd(This is a Sound Test of the Notification Manager using the
Click sound., SNDclick);
6:
begin
NotifSnd(This is a Sound Test of the Notification Manager using the
Bong sound., SNDbong);
NotifSnd(This is a Sound Test of the Notification Manager using the
Click sound., SNDclick);
end;
7:
NotifSnd(, SNDmonkey);
8:
NotifSnd(This is a Sound Test of the Notification Manager using the
System Error sound., -1);
10:
begin
RemoveNotifIcon;
NotifIcon(This is a Icon Test of the Notification Manager using the
Diamond Icon., SICNdiamond);
end;
11:
begin
RemoveNotifIcon;
NotifIcon(, SICNheyyou);
end;
{Call NotifIcon after 60 seconds (3600 ticks).}
12:
Timer := TickCount + 3600;
13:
RemoveNotifIcon;
otherwise
end;
otherwise
end;
HiliteMenu(0);
end;
{Simple Mac Main Event Loop. Check to see if it is time to display HeyYou
Icon. }
{If Resuming under MultiFinder, Remove Icon (if any).}
procedure MainLoop;
const
suspendResumeMessage = 1;
var
myEvent: EventRecord;
whichWindow: WindowPtr;
tempStr: Str255;
tempLong: LONGINT;
begin
repeat
if Timer <> 0 then
if TickCount > Timer then
begin
RemoveNotifIcon;
Timer := 0;
GetDateTime(tempLong);
IUTimeString(tempLong, TRUE, tempStr);
NotifIcon(CONCAT(Hey You! The Time is , tempStr), SICNheyyou);
end;
if WaitNextEvent(everyEvent, myEvent, 0, nil) then
case myEvent.what of
mouseDown:
case FindWindow(myEvent.where, whichWindow) of
inSysWindow:
SystemClick(myEvent, whichWindow);
inMenuBar:
DoCommand(MenuSelect(myEvent.where));
otherwise
end;
App4Evt:
if BitShift(myEvent.message, -24) = SuspendResumeMessage then
if Odd(myEvent.message) then
RemoveNotifIcon;
otherwise
end;
until doneFlag;
end;
{Deletes Menus and removes Icon Notification Request (if any). }
procedure CloseDown;
begin
RemoveNotifIcon;
DeleteMenu(101);
DeleteMenu(102);
DeleteMenu(103);
DisposeMenu(myM1);
DisposeMenu(myM2);
DisposeMenu(myM3);
end;
{Main Program . }
begin
InitGraf(@thePort);
InitFonts;
FlushEvents(everyEvent, 0);
InitWindows;
InitMenus;
TEInit;
InitDialogs(nil);
InitCursor;
DoAbout;
if CheckSystem then
begin
SetUp;
MainLoop;
CloseDown;
end;
end.
Listing: HeyYou.r
/*----------------------------------------------------------
HeyYou.r- Resources for HeyYou
Notification Manager Example Program for MacTutor by Steve Sheets
----------------------------------------------------------*/
#include Types.r
type HEY! as STR ;
resource HEY! (0) {
Notification Manager Example for MacTutor by Steve Sheets
};
resource BNDL (128) {
HEY!,
0,
{ /* array TypeArray: 2 elements */
/* [1] */
ICN#,
{ /* array IDArray: 1 elements */
/* [1] */
0, 128
},
/* [2] */
FREF,
{ /* array IDArray: 1 elements */
/* [1] */
0, 128
}
}
};
resource FREF (128) {
APPL,
0,
};
resource ICN# (128) {
{ /* array: 2 elements */
/* [1] */
$FFFF FFFF 807F FFFF 807F FFFF 807F FFFF
$807F FFFF 807F C0FF 887F 003F 887E 001F
$887C 000F 8078 0007 8079 5D47 8071 5143"
$8071 D9C3 8071 5083 8071 5C83 8070 0003"
$8070 0003 8070 0003 8071 5D43 8071 5543"
$87F1 D543 81F0 9543 81F0 9DC7 81F0 0007"
$81F0 000F 81E0 001F 8F80 007F 81FF FFFF
$81FF FFFF 81FF FFFF 81FF FFFF FFFF FFFF,
/* [2] */
$FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF
$FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF
$FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF
$FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF
$FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF
$FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF
$FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF
$FFFF FFFF FFFF FFFF FFFF FFFF FFFF FFFF
}
};
resource SICN (500, purgeable) {
{ /* array: 1 elements */
/* [1] */
$7FFC 8002 ABAA AA2A BB3A AA12 AB92 8002"
$ABAA AAAA BAAA 92AA 93BA 8002 7FFC
}
};
resource ICON (500) {
$FFFF FFFF 807F FFFF 807F FFFF 807F FFFF
$807F FFFF 807F C0FF 887F 003F 887E 001F
$887C 000F 8078 0007 8079 5D47 8071 5143"
$8071 D9C3 8071 5083 8071 5C83 8070 0003"
$8070 0003 8070 0003 8071 5D43 8071 5543"
$87F1 D543 81F0 9543 81F0 9DC7 81F0 0007"
$81F0 000F 81E0 001F 8F80 007F 81FF FFFF
$81FF FFFF 81FF FFFF 81FF FFFF FFFF FFFF
};
data SIZE (-1) {
$5800 0006 4000 0006 4000"
};
resource ALRT (500) {
{40, 76, 164, 436},
500,
{ /* array: 4 elements */
/* [1] */
OK, visible, sound1,
/* [2] */
OK, visible, sound1,
/* [3] */
OK, visible, sound1,
/* [4] */
OK, visible, sound1
}
};
resource DITL (500) {
{ /* array DITLarray: 3 elements */
/* [1] */
{84, 150, 104, 210},
Button {
enabled,
Ok
},
/* [2] */
{20, 84, 74, 344},
StaticText {
disabled,
A Notification Manager example program f
or MacTutor by Steve Sheets Requires Sys
tem 6.0 or higher
},
/* [3] */
{10, 10, 74, 74},
Icon {
disabled,
500
}
}
};