-- file OperationsDefs.mesa
-- edited by Schroeder, November 6, 1981 4:57 PM
-- edited by Levin, October 3, 1980 11:15 AM
-- edited by Brotz, August 31, 1982 9:28 AM

DIRECTORY
FTPDefs USING [FileType],
RetrieveDefs USING [Handle],
vmD: FROM "VirtualMgrDefs" USING [TOCHandle, TOCIndex, VirtualMessagePtr],
VMDefs USING [defaultTime, FileTime];

opD: DEFINITIONS =

BEGIN


MailFileError: ERROR [reason: MailFileProblem];
-- May be raised by GetMailFileOperation if the indicated file does not confrom to mail
-- file format.

MailFileProblem: TYPE = {ok, notAMailFile, lastStampTooLong};


GetMailFileOperation:
PROCEDURE [toc: vmD.TOCHandle, key: CARDINAL, mailFile: STRING]
RETURNS [firstUnseen: vmD.TOCIndex];
-- On satisfactory return, a valid TOC exists and is virtualized. The file handle for the
-- pre-existing or newly created mail file is put in intC.mailFileHandle. If the mailfile
-- cannot be parsed (i.e. there is a bad stamp) then the file is closed and the ERROR
-- NotAMailFile is raised. ERRORs from VM may occur as a result of opening and
-- reading the mail file. The returned TOC index is that of the first unseen message in
-- the mailfile (= 0 if all messages are seen).


AccessNewMailOperation: PROCEDURE
[toc: vmD.TOCHandle, key: CARDINAL, retrieveHandle: RetrieveDefs.Handle,
registry: STRING, ignoreUserFeedback: BOOLEAN ← FALSE,
deleteEachMessage: BOOLEAN ← FALSE]
RETURNS [messagesRead: BOOLEAN];
-- Gets new messages from the user’s mailbox(es) through "retrieveHandle", appends them
-- to the mail file "toc", and updates the TOC. If "deleteEachMessage" is FALSE, then
-- each mailbox in turn is flushed only after successfully retrieveing all messages in
-- that mailbox. If "deleteEachMessage" is TRUE, then each message is deleted from its
-- mailbox after successful retrieval of that message.


ReturnMailFileOperation: PROCEDURE [toc: vmD.TOCHandle, key: CARDINAL];
-- Returns the mail file. All changes made in the TOC are reflected into the mailfile.
-- Deleted entries are compacted out. Also causes TOC file to be truncated at the first
-- changed entry. Deletes both file and TOC file if an empty file would result from this
-- cleanup operation. Calls Core.Close for file and tocFile.


NoMessagesMoved: ERROR [reason: NoMoveReason];
-- May be raised by AppendMailToFileOperation if no messages are actually moved.

NoMoveReason: TYPE = {diskFull, diskError, noUndeleted, ok};


AppendMailToFileOperation: PROCEDURE
[toc: vmD.TOCHandle, key: CARDINAL, appendFileName: STRING];
-- Opens the appendFile named, appends all undeleted selected messages to that file with
-- stamps, closes append file. Skips any messages in the range that are deleted.
-- May raise NoMessagesMoved.


ReplaceMailOperation: PROCEDURE
[delete: BOOLEAN, index: vmD.TOCIndex, msg: vmD.VirtualMessagePtr,
toc: vmD.TOCHandle, key: CARDINAL] RETURNS [worked: BOOLEAN];
-- Inserts, deletes or replaces a message in the mail file whose table of contents is toc. msg
-- is the new message (if non-NIL). index is index of the message to be deleted or
-- replaced, or if delete is TRUE, then index is the index that the new message will have.
-- delete determines whether or not an existing message is deleted. The replacement is
-- made in the mail file and toc immediately, not waiting for a Return and subsequent Get.
-- The combinations of delete and msg have results as follows:
-- delete = TRUE, msg = NIL => index’th message in toc is deleted.
-- delete = TRUE, msg # NIL => index’th message in toc is replaced by msg.
-- delete = FALSE, msg = NIL => illegal combination.
-- delete = FALSE, msg # NIL => msg is inserted to become the index’th message in toc.
-- N.B. msg may not be a DisplayMessage from toc, i.e., you may not insert a message
-- from a toc into that same toc directly.


FileError: ERROR [reason: FileErrorReason, errorString: STRING];
-- May be raised by Expand or Stuff under various awful circumstances.

FileErrorReason: TYPE = {notFound, cancel, get, put, cantConnect, illegalName, fileInUse,
diskFull, ftpError, other, ok};


Expand: PROCEDURE [sourceName: STRING,
AcceptBlock: PROCEDURE [POINTER, CARDINAL] RETURNS [BOOLEAN],
GetReady: PROCEDURE [LONG CARDINAL, VMDefs.FileTime] ← NIL];
-- sourceName is the string name of a local file, remote file, or distribution list. Retrieve
-- will attempt to provide the contents of the named object. If contents are to be
-- forthcoming, Retrieve will call the client’s procedure GetReady if not NIL,
-- passing the number of bytes to expect and the time the object was created
-- (if known, otherwise VMDefs.defaultTime).
-- The client’s GetBlock procedure will then be called over and over with
-- a buffer pointer and byte count. A final call with a zero byte count indicates the end.
-- If AcceptBlock returns FALSE then the transfer is stopped.
-- May raise FileError if any errors (including FALSE returned by AcceptBlock) are
-- encountered by Expand.


Stuff: PROCEDURE [targetName: STRING,
GetBlock: PROCEDURE RETURNS [POINTER, CARDINAL, BOOLEAN],
OverwriteOK: PROCEDURE RETURNS [BOOLEAN],
createTime: VMDefs.FileTime ← VMDefs.defaultTime,
callerFileType: FTPDefs.FileType ← binary];
-- targetName is the string name of a local or remote file. Stuff will
-- attempt to update the contents of the named object with the bytes provided by the
-- client’s GetBlock procedure. The client’s procedure OverwriteOK is first called if the
-- Stuff will overwrite a local file, and Stuff will continue only if TRUE is returned.
-- Created object will be given the provided creation time, where the default means now.
-- Providing a zero length block with GetBlock tells Stuff that the transfer has been
-- successfully completed (ftp requirement?). If GetBlock returns FALSE then the Stuff
-- is stopped.
-- May raise FileError if any errors (including FALSE returned by GetBlock) are
-- encountered by Stuff.


Copy: PROCEDURE [source, target: STRING, OverwriteOK: PROC RETURNS [BOOLEAN] ]
RETURNS [bytesCopied: LONG CARDINAL];
-- Copies source to target using Expand and Stuff. If everything goes ok, then returns
-- bytesCopied, otherwise raises FileError with reason = get or put plus a human readable
-- errorString.


-- Constants
substringSeparator: CHARACTER = 177C;
maxTOCStringLength: CARDINAL = 300;


END. -- of OperationsDefs --