-- file OperationsDefs.mesa
-- edited by Schroeder, January 19, 1981 9:25 AM
-- edited by Levin, October 3, 1980 11:15 AM
-- edited by Brotz, March 6, 1981 3:08 PM

DIRECTORY
crD: FROM "CoreDefs",
FTPDefs,
ovD: FROM "OverviewDefs",
TimeDefs,
vmD: FROM "VirtualMgrDefs";

opD: DEFINITIONS =

BEGIN


GetMailFileOperation: PROCEDURE [mailFile: crD.UFilename]
RETURNS [ovD.ErrorCode, 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 code
-- ovD.badMailFile is returned. Error codes from crD.OpenFile are returned if the mailfile
-- cannot be opened, and from crD.ReadFile if it cannot be read. The returned TOC index
-- is that of the first unseen message in the mailfile (= 0 if all messages are unseen).


AccessNewMailOperation: PROCEDURE RETURNS [messagesRead: BOOLEAN];
-- Gets new messages from the user’s mailbox(es), appends them to the message file whose
-- handle is provided, and updates the TOC.


ReturnMailFileOperation: PROCEDURE [buffer: POINTER TO BufferRecord]
RETURNS [ovD.ErrorCode];
-- 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 CloseFile for file and tocFile.


AppendMailToFileOperation: PROCEDURE [appendFileName: crD.UFilename]
RETURNS [ovD.ErrorCode];
-- 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.


Expand: PROCEDURE [sourceName: STRING,
AcceptBlock: PROC [POINTER, CARDINAL] RETURNS [ovD.ErrorCode],
GetReady: PROC [LONG CARDINAL, TimeDefs.PackedTime] ← NIL]
RETURNS [ovD.ErrorCode, STRING];
-- 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 TimeDefs.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 other than ovD.ok then the transfer is stopped. Errors
-- encountered by Expand, including those generated by AcceptBlock, are reported as
-- errorCodes, and if the errorCode # ovD.ok then the second return value may be an error
-- string or NIL. If a string then the string body has been allocated in the heap, and the
-- client should free it using FreeErrorString.


Stuff: PROCEDURE [
targetName: STRING,
GetBlock: PROC RETURNS [POINTER, CARDINAL, ovD.ErrorCode],
OverwriteOK: PROC RETURNS [BOOLEAN],
createTime: TimeDefs.PackedTime ← TimeDefs.DefaultTime,
callerFileType: FTPDefs.FileType ← binary]
RETURNS [ovD.ErrorCode, STRING];
-- 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 other than ovD.ok
-- then the Stuff is stopped. Errors are encountered by Stuff, including the errors
-- generated by GetBlock, are returned as errorCodes, and if the errorCode # ovD.ok then
-- the second return value may be an error string or NIL. If a string then the string body
-- has been allocated in the heap, and the client should free it using FreeErrorString.


GetOrPutType: TYPE = {get, put};


Copy: PROCEDURE [source, target: STRING, OverwriteOK: PROC RETURNS [BOOLEAN] ]
RETURNS [error: ovD.ErrorCode, getOrPut: GetOrPutType, errorString: STRING,
bytesCopied: LONG CARDINAL];
-- Copies source to target using Expand and Stuff. If everything goes ok, then returns
-- error = ovD.ok, otherwise returns error with getOrPut having value of which of
-- Expand or Stuff failed plus a human readable errorString. If an errorString is returned,
-- then the client should free it using FreeErrorString.


FreeErrorString: PROCEDURE [string: STRING];
-- to be called by clients of the above operations that return error strings. This is really
-- only needed by BCDs loaded through the Run command (ugh) to keep the storage
-- bookkeeping tidy, but it doesn’t hurt for "regular" clients to call it as well.


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


--intermodule communication variables and procedures

BufferRecord: TYPE = RECORD
[b1: POINTER TO UNSPECIFIED,-- address of first word of first buffer
s1: CARDINAL,-- size of first buffer in words
b2: POINTER TO UNSPECIFIED,-- address of first word of second buffer
s2: CARDINAL];-- size of second buffer in words


END. -- of OperationsDefs --