-- 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 --z20461(529)\f1