Notification

Introduction

File Notification is a form of interprocess communication. An application can ask either a file system (like the RAM disk handler RAM:, df0:, df1:...) or DOS to inform it whenever changes are made to a specific file or directory, making it easy for the application to react to such changes.

The preferences control program, IPrefs, sets up notification on most of the preferences files in ENV:Sys. If the user alters any of these files (which he/she normally does with a preferences editor), the system will notify IPrefs about the change. IPrefs will react to this notification by attempting to alter the user's environment to reflect the preference change. For example, if the user opens the ScreenMode preferences editor and alters the Workbench environment so that the Workbench screen should be a Hires NTSC screen, ScreenMode writes a file called Screenmode.prefs to the ENV:Sys directory which happens to be in RAM:. Because IPrefs has set up notification on this file, the RAM disk file system or DOS will notify IPrefs of the change, IPrefs will read in the Screenmode.prefs file and will try to reset the Workbench screen so it is in Hires NTSC mode.

Notification allows very different applications to share common data files without knowing anything about each other. This has many possible uses in the Amiga's single user, multitasking environment. One possible use for notification is in a desktop publishing (DTP) package. The user can open the DTP package to layout a group of ILBMs, some structured drawings, and word processed text. When the user loads each of these, the DTP package sets up notification on each of their corresponding files. If the user loads an appropriate editor and changes any of the files on which the DTP package has set up notification, the DTP package will receive notification of these changes and can automatically re-import these files into the current DTP document without the user having to intervene. Another possible use for notification might be in a make utility. A make program for a compiler could set up notification on a set of source code and object files. If any of those files change, the make program will recompile and link the program, without the programmer having to intervene.

File System or DOS?

Starting with version 53.x of the DOS Library (dos.library), the notification feature is handled entirely by AmigaDOS. DOS notification is independent of the file system and is always available. Prior to this version, file system notification was available only if each individual file system implemented the feature. If a file system does not support notification the notification functions described below will always fail.

Using Notification

Setting up file notification on a file is easy. The StartNotify() function from dos.library starts notification on a file or directory:

BOOL StartNotify( struct NotifyRequest *notify );

StartNotify() returns DOSTRUE if the call is successful, or it returns DOSFALSE (for example, when the file's file system does not support notification). This function takes a pointer to an initialized NotifyRequest structure as its only argument (as defined in <dos/notify.h>):

struct NotifyRequest {
   UBYTE *nr_Name;  /* File/directory name which you want notification */
   UBYTE *nr_FullName; /* Used by DOS. Do not use */
   ULONG nr_UserData;  /* For applications use */
   ULONG nr_Flags;  /* Flags indicating Signal or Message notification */
 
   union {
      /* Used for Message notification */
      struct {
         struct MsgPort *nr_Port; /* Message port to receive messages on */
     } nr_Msg;
     /* Used for Signal notification */
     struct {
        struct Task *nr_Task;       /* The task to signal */
        UBYTE nr_SignalNum;         /* The signal number to use. */
        UBYTE nr_pad[3];
     } nr_Signal;
   } nr_stuff;
 
   ULONG nr_Reserved[4];          /* leave 0 for now */
 
   /* Used internally by handlers */
   ULONG nr_MsgCount;             /* number of outstanding messages */
   struct MsgPort *nr_Handler;    /* handler to send to (for EndNotify) */
};

This structure must not be altered by the application while notification is in effect!

The nr_Name field contains a pointer to the name of the file on which to set up notification. Currently, nr_Name has to be a file name and path containing a logical device name (for example df0:, work:, fonts:). The nr_FullName field is for the private use of the file system. Any other use of it is strictly prohibited. The nr_UserData field is available for an applications private use.

The nr_Flags field tells the file system which type of notification to set up, message or signal. When the file system uses message notification, it notifies an application by sending an Exec message. An application asks a file handler to notify it via an Exec message by setting the NRF_SEND_MESSAGE flag in nr_Flags. When the file system uses signal notification, it sets an Exec signal to notify an application. An application receives notification via a signal by setting the NRF_SEND_SIGNAL flag.

The nr_Flags field has two other flags, NRF_WAIT_REPLY and NRF_NOTIFY_INITIAL. The NRF_WAIT_REPLY tells the file handler not to send notification messages about a specific file/directory to an application if the application has not replied to a previous notification message about that specific file. This flag only applies to message notification. The NRF_NOTIFY_INITIAL flag tells the file handler to notify the application if the file exists when it sets up notification on the file. The flags for the nr_Flags field are defined in <dos/notify.h>.

The layout of the rest of the NotifyRequest structure depends on the type of notification. If the application is using message notification, it must supply the handler with a message port to send the notification messages. The NotifyRequest.nr_stuff.nr_Msg.nr_Port field contain the pointer to the message port that will receive the message notifications. If the application is using a signal for notification, it must supply a pointer to the task to signal and the number (not bit!) of the signal. In this case, the NotifyRequest.nr_stuff.nr_Signal.nr_Task field should contain the appropriate task pointer and the NotifyRequest.nr_stuff.nr_Signal.nr_SignalNum field should contain the signal number.

When a file handler uses message notification, it will send a NotifyMessage:

struct NotifyMessage {
   struct Message nm_ExecMessage;
   ULONG  nm_Class;               /* Class, will be NOTIFY_CLASS */
   UWORD  nm_Code;                /* Code, will be NOTIFY_CODE */
   struct NotifyRequest *nm_NReq; /* Point to NotifyRequest you supplied */
   ULONG  nm_DoNotTouch;          /* private */
   ULONG  nm_DoNotTouch2;         /* private */
};

Message notification is especially useful if you are monitoring more than one file. It quickly enables you to find out which file/directory caused this message by either comparing the NotifyRequest structure returned in nm_NReq with the one you sent in the StartNotify() function, or by reading the NotifyRequest's nr_UserData field. Because the NotifyMessage's nm_Class and nm_Code fields contain values that distinguish it from other types of messages, you can use an already allocated message port (from a window for example) to receive notification messages.

To end notification on a file, use the dos.library function EndNotify():

</syntaxhighlight> void EndNotify( struct NotifyRequest *notify ); </syntaxhighlight>

An application must call this function for each of its successful StartNotify() calls. This function takes one parameter, a pointer to the NotifyRequest structure that the application used to initiate the notification. In the case of message notification, EndNotify() will remove all pending notify messages from your message port. After calling this function, it is safe for the application to change or free the NotifyRequest structure. The application may also remove the message port or free the signal bit.