This document describes the way in which a host filing system (eg ADFS) follows the changes made to discs it's hosting (eg DOSFS discs).
The host filing system keeps two pieces of information about a disc which it uses to identify the same disc at a later time. These are the disc's name and its ID number. The name is the public bit of the identification and is what the user sees. The ID number is used to distinguish between different discs with the same name.
When a 'new' disc is seen by the host filing system it needs to be identified. See doc.Identify for a description of this process. As part of a successful disc identification the disc name and ID will have been filled in by the MultiFS in the disc record supplied by the host filing system. These values, together with other information concerning the disc's physical parameters (sector size etc) are used by the host filing system to match this 'new' disc against discs which it has seen before and still remembers. Once this match-up has happened the disc can be updated safely in the knowledge that this 'new' disc is, in fact, that disc which the host filing system had seen before.
Clearly the host filing system needs to be kept abreast of any changes made to the disc's name or ID number. These may be triggered by OS_FSControl call FSControl_NameDisc which changes the disc name, or by the MultiFS updating the disc's ID. In the first case, this being the only way the disc name can be changed, FileSwitch will inform the host filing system using fsfunc_NameDisc of the change. In the second case the onus is placed upon the MultiFS to call OS_Args OSArgs_ImageStampIs with the new ID, which will be passed to the host filing system by FileSwitch. If the MultiFS does not do this the next time the host filing system identifies that disc the ID will be different to the one the host filing system remembers, and it will assume the disc as seen later is a different one to the earlier version of that disc. This can have disasterous results.
When a disc is updated it is highly desirable that the ID is updated too. This ensures that another machine which has seen that disc does not retain any cached information about that disc which may have since changed. Clearly updating the ID on every update has to be grossly inefficient so the host filing system makes use of the disc changed information supplied by the lower level drivers to determine when would be a good time to update the ID and when not. Basically, if the disc in the drive might have been removed from the machine since the last ID update, its time to update the ID again when the disc is next updated for any other reason. To inform the MultiFS that this needs to be done the host filing system calls OS_FSControl FSControl_StampImage with the 'update ID next update' sub-reason. This call will get fed through to the MultiFS by FileSwitch. When a MultiFS receives a fsfunc_StampImage with this sub-reason it should note down that that image needs its ID updating next time the image is updated, but it need take no further action at that time.
In summary:
For a host filing system (eg ADFS):
Depending on a MultiFS's disc format there may or may not be 'room' to fit in an explicit disc ID somewhere on the disc. For disc's where there is room a StampImage NextUpdate should simply increment the ID when the next update happens. For disc's where there isn't room a disc's ID may be some derivative of the structures on the disc, such as a checksum of the free space map. Clearly there's not much that can be done in this situation to respond to fsfunc_StampImage NextUpdate, but the ID is likely to change anyway so this should not be thought of as a problem.
You may think that as an fsfunc_StampImage caused the change of image ID that an OSArgs_ImageStampIs need not be issued, the host filing system implying the new ID. This is not the case:
*****
WHENEVER A DISC'S ID IS CHANGED, FOR WHATEVER REASON,
OSArgs_ImageStampIs **MUST** BE CALLED.
Also note that the ID passed into OSArgs_ImageStampIs MUST BE THE SAME AS the one filled in by the identification of a disc.