AddDiskChangeHook()
Synopsis
void AddDiskChangeHook(
struct Hook * hook,
BOOL add_or_remove );
Function
Add a hook to the device-wide disk-change notification list, or remove
a hook previously added to that list. Appended hooks run in list order.
Result
No result. There is no duplicate-registration or membership check.
Notes
Keep the device open and the hook, entry code and h_Data alive until
removal returns. The device borrows the hook; it neither copies nor
frees it. Remove it before freeing storage or unloading callback code.
A Hook has one list node and cannot be registered in both hook lists.
Call registration/removal from task context; semaphore waits have no
timeout. Do not change either hook list from inside a callback.
Notifications execute in the affected unit process with the disk-
change semaphore held shared. The object is a borrowed ULONG pointer
to the unit number; the message is hook->h_Data. Copy the number during
the callback if needed. The return value is ignored. Notifications
follow message replies, and multiple image operations can be combined
into one notification. They are not a per-request completion service.
Different unit processes may invoke the same hook concurrently.
Do not perform synchronous unit control or reload from the hook:
waiting for the current unit to process another message deadlocks it.
Signal the application task and return promptly. External removal
acquires the semaphore exclusively and waits for active callbacks.
AddReloadPluginsHook()
Synopsis
void AddReloadPluginsHook(
struct Hook * hook,
BOOL add_or_remove );
Function
Add a hook to the device-wide plugin-reload notification list, or
remove a hook previously added to that list. Appended hooks run in
list order after ReloadPlugins() has rebuilt the plugin list.
Result
No result. There is no duplicate-registration or membership check.
Notes
Keep the device open and the hook, entry code and h_Data alive until
removal returns. The device borrows the hook; it neither copies nor
frees it. Remove it before freeing storage or unloading callback code.
A Hook has one list node and cannot be registered in both hook lists.
Call registration/removal from task context; semaphore waits have no
timeout. Do not change either hook list from inside a callback.
Notifications execute in the task calling ReloadPlugins(). The object
is SysBase and the message is hook->h_Data; the return value is ignored.
Both the unit and plugin semaphores are held exclusively. Do not call
synchronous unit control, recursively reload plugins, or wait for work
that requires those locks. Signal the application task and return.
External removal waits for any active reload to release its semaphore.
DoHookPlugins()
Synopsis
void DoHookPlugins(
struct Hook * hook );
Function
Call a hook once for each currently loaded plugin in list order.
Pass the DiskImagePlugin pointer as object and hook->h_Data as the
message. Ignore the hook's return value and continue enumeration.
Result
No result. An empty plugin list produces no callbacks. Returning a
nonzero value from the hook does not stop enumeration.
Notes
Keep diskimage.device open. Call from context that permits semaphore
acquisition. Callbacks execute synchronously in the caller's task
while PluginSemaphore is held shared. Do not mutate the plugin list,
reload plugins, alter reload-hook registration, or wait for work that
requires exclusive access to that semaphore.
Plugin structures and their strings are borrowed. Copy any metadata
needed after the callback; a concurrent reload may invalidate it as
soon as enumeration releases the semaphore. The hook is not retained
or added to a notification list. No timeout is provided.
MountImage()
Synopsis
LONG MountImage(
ULONG unit_num,
CONST_STRPTR filename );
Function
Remove the unit's current image and, if filename is non-NULL, open a
replacement using automatic plugin selection. Resolve relative names
using the calling process's current directory. The previous image is
removed before the replacement is opened; failure does not restore it.
Result
Zero on reported success. ERROR_BAD_NUMBER if the unit does not exist.
Otherwise, an operation error reported by the unit or image plugin.
The return value is the error code; no caller IoErr() value is set by
this wrapper.
Notes
Keep diskimage.device open while calling this interface. The unit must
already exist; these calls do not create units. Call from task/process
context where semaphore acquisition and waiting are permitted, never
from an interrupt or a disk-change callback. The call waits for the
unit process without a timeout or cancellation mechanism.
File access and plugin opening run in the unit process and may display
requesters. The filename is borrowed for the call; image resources are
retained by the device until removal. An actual image transition can
update ENV:DiskImage and ENVARC:DiskImage preferences. The disk-change
notification is processed after replying and may occur after return.
Use UnitControlA() for explicit plugin, screen and password settings.
Bugs
diskimage.conf assigns A0,D0 to unit_num,filename. This implementation
and the bundled AROS call macros use D0,A0. Generated interfaces must
resolve this disagreement before being used on a register-sensitive
target. This synopsis follows the implementation.
The unit retains the address of this wrapper's temporary error value
after return. See UnitControlA() for the stale error-pointer defect.
ReloadPlugins()
Synopsis
LONG ReloadPlugins();
Function
Eject images from every existing unit, free the current plugin list,
load built-in plugins and plugins from DEVS:DiskImage, then invoke
registered reload hooks. Images are not remounted.
Result
Zero when the routine returns. Plugin discovery and initialisation
failures are not propagated through this result. Zero is not proof
that all expected plugins were loaded.
Notes
Keep diskimage.device open. Call from DOS process context. This is a
device-wide operation: it affects other users' mounted images and
may remove saved image selections from ENV: and ENVARC:DiskImage.
It waits for each unit without a timeout or cancellation mechanism.
UnitSemaphore is held exclusively throughout. PluginSemaphore is
held exclusively while freeing/loading plugins and calling reload
hooks. Do not call from a unit process, plugin enumeration callback,
or another device callback. Hooks must not synchronously call unit
control or reload APIs, mutate hook lists, or wait for work that needs
these locks. Signal an application task and return instead.
All borrowed plugin pointers and names become invalid at reload.
Copy information that must outlive a DoHookPlugins() callback.
UnitControlA()
Synopsis
LONG UnitControlA(
ULONG unit_num,
struct TagItem * tags );
LONG UnitControl(
ULONG unit_num,
TAG tag, ... );
Function
Send a tag list to an existing unit and wait for its reply. Process
tags in order until the list ends or the unit records an error.
Earlier effects are not rolled back. Unknown tags are ignored.
Result
Zero after receiving the unit's reply, even if a requested operation
failed. ERROR_BAD_NUMBER if no such unit exists; no tags are processed
in that case. Use DITAG_Error to receive the operation's error code.
Notes
Keep diskimage.device open while calling this interface. The unit must
already exist; these calls do not create units. Call from task/process
context where semaphore acquisition and waiting are permitted, never
from an interrupt or a disk-change callback. The call waits for the
unit process without a timeout or cancellation mechanism.
Put error outputs and operation settings before DITAG_Filename.
Output tags after a failing operation are not processed. Initialise
outputs before calling. Tag data is neither copied nor validated.
A NULL output address for a getter is invalid.
Mounting removes the previous image first and can write preferences.
Plugin/file operations may block or display requesters. A successful
reply does not guarantee that subsequent disk-change hooks have run.
Do not call this interface synchronously from a unit-process hook or
while holding resources needed by the unit or its callbacks.
Bugs
ErrorPtr is not reset at request entry or completion. Omitting
DITAG_Error can make a later failure write through an earlier caller's
pointer, including a completed wrapper's stack variable. Always put
DITAG_Error first, using NULL to disable reporting, but this does not
repair unsafe requests issued by other callers. The implementation
needs to clear its borrowed error pointer at request boundaries.
DITAG_GetImageName checks the output address instead of the allocated
string. A NULL result may be returned without an allocation error.
ErrorStringLength persists between requests; supply the real buffer
length before DITAG_ErrorString whenever requesting error text.
UnitInfo()
Synopsis
LONG UnitInfo(
ULONG unit_num,
STRPTR * filename,
BOOL * writeprotect );
Function
Obtain the mounted image's basename and the unit's software write-
protection flag in one synchronous request. Allocate a separate copy
of the name when an image name is present.
Result
Zero on reported success; ERROR_BAD_NUMBER if the unit does not exist.
Outputs are untouched if the unit does not exist. A zero return does
not distinguish a missing image from a failed name allocation.
Notes
Keep diskimage.device open while calling this interface. The unit must
already exist; these calls do not create units. Call from task/process
context where semaphore acquisition and waiting are permitted, never
from an interrupt or a disk-change callback. The call waits for the
unit process without a timeout or cancellation mechanism.
Both output addresses are required. The string is a snapshot owned by
the caller and remains valid after ejecting the image. It is not the
full source path. The flag does not describe host-file permissions or
whether the selected plugin implements writing.
Bugs
The name-allocation check tests the output address rather than the
allocated result. Allocation failure can therefore return NULL with
a zero error. The wrapper also leaves a temporary error-pointer
address in the unit; see UnitControlA().
WriteProtect()
Synopsis
LONG WriteProtect(
ULONG unit_num,
BOOL writeprotect );
Function
Set the unit's software write-protection flag. Nonzero writeprotect
enables protection; zero disables it. No mounted image is required.
Result
Zero after the request is processed; ERROR_BAD_NUMBER if the unit
does not exist. The previous state is not returned.
Notes
Keep diskimage.device open while calling this interface. The unit must
already exist; these calls do not create units. Call from task/process
context where semaphore acquisition and waiting are permitted, never
from an interrupt or a disk-change callback. The call waits for the
unit process without a timeout or cancellation mechanism.
Clearing this flag cannot make a read-only plugin writable and does
not change the image file's permissions. The ordinary write path also
rejects a missing plugin write method. This call does not save the
flag in preferences or issue a disk-change notification.
Bugs
The wrapper leaves a temporary error-pointer address in the unit;
see UnitControlA().
