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