Notification - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:18:22Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:18, 26 January 2025
Line 17:		Line 17:
	Setting up file notification on a file is easy. The StartNotify() function from dos.library starts notification on a file or directory:		Setting up file notification on a file is easy. The StartNotify() function from dos.library starts notification on a file or directory:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	BOOL StartNotify( struct NotifyRequest *notify );		BOOL StartNotify( struct NotifyRequest *notify );
	</syntaxhighlight>		</syntaxhighlight>
Line 24:		Line 24:
	<dos/notify.h>):		<dos/notify.h>):

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct NotifyRequest {		struct NotifyRequest {
	UBYTE nr_Name; / File/directory name which you want notification */		UBYTE nr_Name; / File/directory name which you want notification */
Line 65:		Line 65:
	When a file handler uses message notification, it will send a NotifyMessage:		When a file handler uses message notification, it will send a NotifyMessage:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct NotifyMessage {		struct NotifyMessage {
	struct Message nm_ExecMessage;		struct Message nm_ExecMessage;
Line 80:		Line 80:
	To end notification on a file, use the dos.library function EndNotify():		To end notification on a file, use the dos.library function EndNotify():

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	void EndNotify( struct NotifyRequest *notify );		void EndNotify( struct NotifyRequest *notify );
	</syntaxhighlight>		</syntaxhighlight>
Line 116:		Line 116:
	== SignalNotification.c ==		== SignalNotification.c ==

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/*		/*
	* SignalNotification.c		* SignalNotification.c
Line 200:		Line 200:
	== MessageNotification.c ==		== MessageNotification.c ==

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/*		/*
	* MessageNotification.c		* MessageNotification.c

Steven Solie: /* MessageNotification.c */

2013-07-10T14:33:16Z

MessageNotification.c

Show changes

Steven Solie: /* SignalNotification.c */

2013-07-10T14:26:49Z

SignalNotification.c

Show changes

Steven Solie: /* Examples */

2013-03-19T21:00:48Z

Examples

Show changes

Steven Solie: /* = SignalNotification.c */

2013-03-19T20:57:31Z

= SignalNotification.c

← Older revision		Revision as of 20:57, 19 March 2013
Line 114:		Line 114:
	= Examples =		= Examples =

	== SignalNotification.c =		== SignalNotification.c ==

	<syntaxhighlight>		<syntaxhighlight>

Steven Solie: /* Examples */

2013-03-19T20:55:10Z

Examples

← Older revision		Revision as of 20:55, 19 March 2013
Line 113:		Line 113:

	= Examples =		= Examples =

			== SignalNotification.c =

			<syntaxhighlight>
			/*
			* SignalNotification.c
			*/

			#include <exec/types.h>
			#include <exec/memory.h>
			#include <dos/dos.h>
			#include <dos/dosasl.h>
			#include <dos/notify.h>
			#include <dos/rdargs.h>

			#include <proto/exec.h>
			#include <proto/dos.h>

			struct Library *DOSBase;
			struct ExecBase *SysBase;


			int main()
			{
			struct RDArgs *readargs;
			LONG rargs[2];
			struct NotifyRequest *notifyrequest;
			UBYTE *filename;
			ULONG signr, signal;

			/* To appease amiga.lib */
			SysBase = (((struct Library *) 4));

			/* Fail silently if < 37 */
			if (DOSBase = OpenLibrary("dos.library", 37))
			{
			/* See the DOS Autodocs for more information about ReadArgs() */
			if (readargs = ReadArgs("Filename/A", rargs, NULL))
			{
			filename = (UBYTE *) (rargs[0]);

			/* Allocate a NotifyRequest structure */
			if (notifyrequest = AllocMem(sizeof(struct NotifyRequest), MEMF_CLEAR))
			{
			/* And allocate a signalbit */
			if ((signr = AllocSignal(-1L)) != -1)
			{

			/* Initialize notifcation request */
			notifyrequest->nr_Name = filename;
			notifyrequest->nr_Flags = NRF_SEND_SIGNAL \| NRF_NOTIFY_INITIAL;
			/* Signal this task */
			notifyrequest->nr_stuff.nr_Signal.nr_Task =
			(struct Task *) FindTask(NULL);
			/* with this signal bit */
			notifyrequest->nr_stuff.nr_Signal.nr_SignalNum = signr;

			if ((StartNotify(notifyrequest)) == DOSTRUE)
			{
			/* Loop until Ctrl-C to exit */
			for (;;)
			{
			signal = Wait(1L << signr \| SIGBREAKF_CTRL_C);
			if (signal & (1L << signr))
			VFPrintf(Output(), "Notification signal!\n", NULL);
			if (signal & SIGBREAKF_CTRL_C)
			{
			EndNotify(notifyrequest);
			PrintFault(ERROR_BREAK, NULL);
			break;
			}
			}
			}
			else
			PrintFault(ERROR_NOT_IMPLEMENTED, NULL); /* most logical */

			FreeSignal(signr);
			}
			else
			VFPrintf(Output(), "No signal available\n", NULL);
			FreeMem(notifyrequest, sizeof(struct NotifyRequest));
			}
			else
			PrintFault(ERROR_NO_FREE_STORE, NULL);

			FreeArgs(readargs);
			}
			else
			PrintFault(IoErr(), NULL);
			CloseLibrary(DOSBase);
			}
			}
			</syntaxhighlight>

Steven Solie: /* Using Notification */

2013-03-19T20:48:52Z

Using Notification

← Older revision		Revision as of 20:48, 19 March 2013
Line 86:		Line 86:
	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		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.		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.

			= Notification Using DOS Packets =

			{{Note\|title=Don't use DOS Packets\|text=DOS Library now handles notification as of version 53.?? so that file systems are no longer burdened with implementing this functionality. The information below is being provided for reference and for users of previous versions of the DOS Library.}}

			A file handler should send notification when it receives any of the following packets (from <dos/dosextens.h>) about the notification file or directory:

			ACTION_RENAME_OBJECT
			ACTION_RENAME_DISK
			ACTION_CREATE_DIR
			ACTION_DELETE_OBJECT

			ACTION_WRITE
			ACTION_FINDUPDATE
			ACTION_FINDOUTPUT
			ACTION_SET_FILE_SIZE

			ACTION_SET_DATE

			The first four packets will cause notification immediately. The second four packets will cause notification when the notification file is closed. The last packet, ACTION_SET_DATE, should cause notification immediately, but due to a bug in the V37 ROM file system, only the RAM disk's file handler (RAM:) will send notification.

			Notice that some of the packets that trigger a notification are sent by a process when it is trying to create a new file or directory. A file system that supports notification should be able to set up notification on a file or directory that does not currently exist. A file system should send notification when it creates that file or directory.

			When implementing notification in your application, there are several things to remember. Not every file system supports notification, in
			particular, most network file systems will not support notification. For this reason, no application should require notification to function.

			= Examples =

Steven Solie: /* Using Notification */

2013-03-19T20:44:39Z

Using Notification

← Older revision		Revision as of 20:44, 19 March 2013
Line 80:		Line 80:
	To end notification on a file, use the dos.library function EndNotify():		To end notification on a file, use the dos.library function EndNotify():

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

Steven Solie: /* Using Notification */

2013-03-19T20:44:20Z

Using Notification

← Older revision		Revision as of 20:44, 19 March 2013
Line 62:		Line 62:

	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.		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:

			<syntaxhighlight>
			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 */
			};
			</syntaxhighlight>

			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.

Steven Solie: /* Using Notification */

2013-03-19T20:40:46Z

Using Notification

← Older revision		Revision as of 20:40, 19 March 2013
Line 25:		Line 25:

	<syntaxhighlight>		<syntaxhighlight>
			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) */
			};
	</syntaxhighlight>		</syntaxhighlight>

			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.