Home / Autodocs / dos.library
NAME
- StartNotify
-
Starts notification on a file or directory (V36)
SYNOPSIS
success = StartNotify(notifystructure)
D0 D1
BOOL StartNotify(struct NotifyRequest *)
D0 D1
BOOL StartNotify(struct NotifyRequest *)
FUNCTION
Posts a notification request. Do not modify the notify structure while it is active. You will be notified when the file or directory changes. For files, you will be notified after the file is closed.
Not all file systems will support this: applications SHOULD NOT require it. In particular, most network file systems will not support it.
Not all file systems will support this: applications SHOULD NOT require it. In particular, most network file systems will not support it.
INPUTS
- notifystructure
-
A filled-in NotifyRequest structure
RESULT
- success
-
Success/failure of request
NOTES
Always set the NotifyRequest structure contents to zero before you initialize its nr_Flags, nr_Port, nr_Task/nr_SignalNum and nr_Name fields, such as by using memset(nreq, 0, sizeof(struct NotifyRequest)). Some file systems may otherwise fail to work correctly, corrupting memory or showing undefined behaviour. Do not take this lightly: StartNotify() is easy to break.
Bits 31..16 of the nr_Flags field are reserved for system and internal handler use. Make sure that these bits are 0 before you call StartNotify().
Make sure that you set only the NRF_SEND_MESSAGE or the NRF_SEND_SIGNAL flag, but not both. File systems may react in an unpredictable manner if both flags are set. They might even try to perform both notification methods, even though these are mutually exclusive by design.
File systems may not react in a predictable manner if the notification method is unset, e.g. if neither the NRF_SEND_MESSAGE nor the NRF_SEND_SIGNAL flag is set.
Part of the task performed by StartNotify() involves building the full path name of the directory entry referenced by the nr_Name member. The maximum path name length is 255 characters, which matches the limits of a BCPL string. Should 255 characters be insufficient to represent the full path name, StartNotify() may show undefined behaviour.
Requesting notification for changes made to a directory will not provide information on what, specifically, has changed in that directory. Whether the metadata of a file in that directory was changed, a new directory was added or removed, or even if just the modification time of the directory was changed is not part of the protocol. If you want to learn what exactly was changed, you will have to rescan the entire directory and compare your findings against the results of a prior scan.
Bits 31..16 of the nr_Flags field are reserved for system and internal handler use. Make sure that these bits are 0 before you call StartNotify().
Make sure that you set only the NRF_SEND_MESSAGE or the NRF_SEND_SIGNAL flag, but not both. File systems may react in an unpredictable manner if both flags are set. They might even try to perform both notification methods, even though these are mutually exclusive by design.
File systems may not react in a predictable manner if the notification method is unset, e.g. if neither the NRF_SEND_MESSAGE nor the NRF_SEND_SIGNAL flag is set.
Part of the task performed by StartNotify() involves building the full path name of the directory entry referenced by the nr_Name member. The maximum path name length is 255 characters, which matches the limits of a BCPL string. Should 255 characters be insufficient to represent the full path name, StartNotify() may show undefined behaviour.
Requesting notification for changes made to a directory will not provide information on what, specifically, has changed in that directory. Whether the metadata of a file in that directory was changed, a new directory was added or removed, or even if just the modification time of the directory was changed is not part of the protocol. If you want to learn what exactly was changed, you will have to rescan the entire directory and compare your findings against the results of a prior scan.
BUGS
The V36 floppy/hard disk file system does not actually send notifications. The V36 ram handler (RAM:) does. This has been fixed for V37.
Some file systems will show undefined behaviour unless all the structure members of the NotifyRequest are set to well-known values. Reusing a NotifyRequest which you just passed to EndNotify() is unsafe. Always reinitialize it before you reuse it with StartNotify().
StartNotify() will build a full path name, including volume name, subdirectory path and name of the directory entry for which change notifications should be sent. The full path name may exceed 255 characters. This can lead to undefined behaviour for file systems which need to convert this path into a BCPL string. The path name will get truncated, preventing the respective file system to correctly identify the directory entry for which change notifications should be sent. This bug has existed in the FFS since at least version 37 and is still present in version 47.4. This bug may not be fixable because it is a by-product of the maximum path/file name size limitation inherent in the packet types which underly the dos.library API functions (Open(), Lock(), Rename(), etc.).
Some file systems will show undefined behaviour unless all the structure members of the NotifyRequest are set to well-known values. Reusing a NotifyRequest which you just passed to EndNotify() is unsafe. Always reinitialize it before you reuse it with StartNotify().
StartNotify() will build a full path name, including volume name, subdirectory path and name of the directory entry for which change notifications should be sent. The full path name may exceed 255 characters. This can lead to undefined behaviour for file systems which need to convert this path into a BCPL string. The path name will get truncated, preventing the respective file system to correctly identify the directory entry for which change notifications should be sent. This bug has existed in the FFS since at least version 37 and is still present in version 47.4. This bug may not be fixable because it is a by-product of the maximum path/file name size limitation inherent in the packet types which underly the dos.library API functions (Open(), Lock(), Rename(), etc.).