Server handles
ServerHandle: TYPE ~ REF ServerObject;
ServerObject:
TYPE ~
RECORD [
flavor: ATOM,
name: ROPE, -- e.g. "Palain-NFS"
procs: ServerProcs,
data: REF
];
ServerProcs: TYPE ~ REF ServerProcsObject;
ServerProcsObject:
TYPE ~
RECORD [
sweep: SweepProc ← NIL,
validate: ValidateProc,
delete: DeleteProc,
do: DoProc,
enumerateForInfo: EnumerateForInfoProc,
enumerateForNames: EnumerateForNamesProc,
getInfo: GetInfoProc,
rename: RenameProc,
retrieve: RetrieveProc,
store: StoreProc,
open: OpenProc,
close: CloseProc,
rw: RWProc
];
SweepProc:
TYPE ~
PROC [h: ServerHandle, seconds:
CARD];
Called a few times a minute by this package for miscellaneous housekeeping:
ValidateProc:
TYPE ~
PROC [h: ServerHandle]
RETURNS [obsolete:
BOOL, downMsg:
ROPE];
Called to validate a handle that might be stale.
If obsolete=TRUE, the handle is out of date and should be replaced (by calling appropriate getServerProc).
IF downMsg#NIL, the server is known to exist but is down.
File Operations
None of these procs know anything about pseudo-servers; that knowledge is confined to FSRemoteFileImpl itself.
The file or pattern argument should have a version part (possibly !h or !l or just !) if that's desired; otherwise the name on the server is assumed to have no version part (not all servers will support this).
The version part "!" should be interpreted as "default": it means "!h" when reading, "!l" when deleting, and "create next higher version" when writing. Note this is NOT THE SAME as leaving out the version part altogether.
If case = TRUE then upper/lower case is significant in the file names (not all servers will support this).
The file name argument to a callback (InfoProc, NameProc, ...) should not have a server part.
All these procs should raise appropriate FS.Error's to indicate failure.
DeleteProc:
TYPE ~
PROC [h: ServerHandle, file:
ROPE, wantedCreatedTime:
GMT, case:
BOOL, proc: ConfirmProc ←
NIL];
Delete the named file.
If wantedCreatedTime # nullGMT, then any version info in file name is treated as a hint only — the right file will be found by enumerating the directory if necessary.
ConfirmProc: TYPE ~ PROC [version: FSBackdoor.Version] RETURNS [ok: BOOLEAN];
DoProc:
TYPE ~
PROC [h: ServerHandle, cmd:
ATOM, arg:
REF, result:
REF];
Catch-all for flavor-specific operations.
EnumerateForInfoProc:
TYPE ~
PROC [h: ServerHandle, pattern:
ROPE, case:
BOOL, proc: InfoProc];
Enumerate all files matchine pattern.
InfoProc: TYPE ~ PROC [file: ROPE, bytes: INT, created: GMT, type: FileType] RETURNS [continue: BOOL];
EnumerateForNamesProc:
TYPE ~
PROC [h: ServerHandle, pattern:
ROPE, case:
BOOL, proc: NameProc];
Enumerate all files matchine pattern.
NameProc: TYPE ~ PROC [file: ROPE] RETURNS [continue: BOOL];
GetInfoProc:
TYPE ~
PROC [h: ServerHandle, file:
ROPE, wantedCreatedTime:
GMT, case:
BOOL]
RETURNS [version: Version, bytes: INT, created: GMT, fileType: FileType];
If wantedCreatedTime # nullGMT, then any version info in file name is treated as a hint only — the right file will be found by enumerating the directory if necessary.
RenameProc:
TYPE ~
PROC [h: ServerHandle, fromFile:
ROPE, fromCreated:
GMT, toFile:
ROPE, case:
BOOL, proc: ConfirmProc ←
NIL];
If fromCreated # nullGMT, then any version info in fromFile name is treated as a hint only — the right file will be found by enumerating the directory if necessary. proc is called with the version of fromFile.
RetrieveProc:
TYPE ~
PROC [h: ServerHandle, file:
ROPE, wantedCreatedTime:
GMT, case:
BOOL, proc: ConfirmRetrieveProc];
If fromCreated # nullGMT, then any version info in fromFile name is treated as a hint only — the right file will be found by enumerating the directory if necessary.
ConfirmRetrieveProc: TYPE ~ PROC [file: ROPE, bytes: INT, created: GMT, type: FileType] RETURNS [IO.STREAM];
StoreProc:
TYPE ~
PROC [h: ServerHandle, file:
ROPE, case:
BOOL, str:
IO.
STREAM, created:
GMT, proc: ConfirmProc ←
NIL];
Data is copied from str to the named remote file.
If created is not nullGMT then the createTime of the remote file is set to created.
Random-access file operations
Many servers don't implement these.
FileHandle: TYPE ~ REF;
OpenProc:
TYPE ~
PROC [h: ServerHandle, cmd:
ATOM, file:
ROPE, wantedCreatedTime:
GMT, case:
BOOL, proc: ConfirmRetrieveProc ←
NIL]
RETURNS [FileHandle];
Return handle for random-access I/O on named file.
Standard values for cmd are
$read : file must already exist
$write : also allows reading; file must already exist
$create : like $write, but creates file if it doesn't exist
$exclusiveCreate : like $write, but fails if file already exists
CloseProc: TYPE ~ PROC [h: ServerHandle, fileHandle: FileHandle];
RWProc:
TYPE ~
PROC [h: ServerHandle, fileHandle: FileHandle, cmd:
ATOM, bytePos:
CARD, block:
REF
TEXT]
RETURNS [bytesTransferred:
CARD];
Standard values for cmd are
$read : behaves like IO.GetBlock, may return a short block.
$write : behaves like IO.PutBlock; short transfer is an error.
Registration
Register:
PROC [flavor:
ATOM, getServer: GetServerProc];
Register an(other) remote file ops implementation. Any existing registration for "flavor" disappears. "getServer" may be NIL, to clear a registration.
GetServerProc:
TYPE ~
PROC [server:
ROPE]
RETURNS [h: ServerHandle, downMsg:
ROPE];
Tries to find a server of the given name.
If successful, creates ServerHandle h and return [h, NIL].
If no server responds and no server is known to exist, returns [NIL, NIL].
If server is known to exist but is not responding, returns [NIL, message],
Does not raise FS.Error itself!
The caller may Process.Abort a GetServerProc.
GetServer:
PROC [server:
ROPE]
RETURNS [h: ServerHandle];
Tries to find a server of the given name, using the server cache.
Raises FS.Error[unknownServer] if unsuccessful.