-- Transport Mechanism: User: Private DEFS for mail retrieval

-- [Juniper]<Grapevine>User>RetrieveXDefs.mesa

-- Andrew Birrell  September 1, 1982 3:16 pm

DIRECTORY
BodyDefs	USING[ ItemHeader, Password, RName, Timestamp ],
PupDefs		USING[ PupAddress ],
PupTypes	USING[ Pair ],
RetrieveDefs	USING[ MBXState, ServerState, ServerType ],
Stream		USING[ Handle ];

RetrieveXDefs: DEFINITIONS = BEGIN


-- The client's mailboxes are represented by a chain: --

MBXData:	TYPE = RECORD[ next:    MBXPtr,
                           type:        RetrieveDefs.ServerType,
                           state:       RetrieveDefs.ServerState,
                           addrState:   { unknown, known, bad },
                           replyWanted: BOOLEAN,
                           addr:        PupDefs.PupAddress,
                           name:        BodyDefs.RName ];
MBXPtr:		TYPE = POINTER TO MBXData;
noMBX:		MBXPtr = NIL;


-- The overall state of mail is represented by a HandleObject --

Handle:		TYPE = POINTER TO HandleObject;

HandleObject:	TYPE = MONITORED RECORD[

   -- list of the user's mailboxes --
   MBXChain:   MBXPtr,
   mbxKnown:   BOOLEAN, -- whether user's mailbox sites are known --
   notEmptyMBXCount: CARDINAL,
   unknownMBXCount:  CARDINAL,

   -- user's registry type --
   registry:     RetrieveDefs.ServerType,

   -- Current state of mail reading: --
   state: -- position in legal call sequences --
                 { -- GV states --
                   beforeMBX, beforeTOCr, beforeBody, inBody,
                   beforeTOCw, afterMessage, afterMBX,
                   -- MTP states --
                   end, beginning, message, lastItem, block,
                   lastBlock, lastMessage },
   spareByte:    BOOLEAN, -- GV padding, or MTP odd-byte mess --
   spareByteValue: CHARACTER, -- for MTP odd-byte mess --
   header:       BodyDefs.ItemHeader, -- header of current item --
   currentMBX:   MBXPtr, -- mailbox being read --
   messages:     CARDINAL, -- number of messages in the mailbox --
   currentStr:   Stream.Handle, -- stream to mailbox being read --
   ftpUser:      UNSPECIFIED, -- actually, FTPDefs.FTPUser except in Cedar --

   -- State of mailbox polling: --
   mbxState:     RetrieveDefs.MBXState,
   polling:      BOOLEAN,
   pollWanted:   BOOLEAN,
   newPollWanted:BOOLEAN,
   pollReplying: BOOLEAN,
   mbxStateChange: CONDITION,
   pollCond:     CONDITION,
   pollID:       PupTypes.Pair,
   sendPoll:     PROCESS,
   pollStarted:  LONG CARDINAL, -- real time when poll last started --

   -- Global information supplied by the client: --
   interval:   CARDINAL, -- polling interval, in seconds --
   changes:    PROCEDURE[RetrieveDefs.MBXState],
   userName:   BodyDefs.RName,
   userPwd:    STRING,
   userKey:    BodyDefs.Password ];




-- Interface to mailbox polling: exported by RetrievePoll --

SendPollProcess: PROC[handle: Handle];
   -- for forking to --

NoteChangedMBX:	PROC[handle: Handle, mbx: MBXPtr,
		     new: RetrieveDefs.ServerState];
   -- changes handle.mbxState appropriately to reflect change in the
   -- known state of this mailbox --

SetMBXState:	PROC[handle: Handle, state: RetrieveDefs.MBXState];
   -- changes handle.mbxState to given value. --


-- Interface to obtain new info about user: exported by RetrieveInit --

FindRegistryAndMailboxes: PROC[handle: Handle];
   -- determines registry type and mailbox locations --

FindAddress:	PROC[handle: Handle, mbx: MBXPtr];
   -- attempts to find mailboxes address (which must have been unknown) --

ServerAddress:	PROC[handle: Handle] RETURNS[ PupDefs.PupAddress];
   -- may signal Failed[communicationError] or Failed[noSuchServer] --




-- Procedures for access to mail on GV servers --

-- See "RetrieveDefs" for specifications of these procedures --

GVNextMessage:	PROC[ handle: Handle ]
		RETURNS[ msgExists: BOOLEAN,
			 archived:  BOOLEAN,
			 deleted:   BOOLEAN ];

GVReadTOC:	PROC[ handle: Handle, text: STRING];

GVStartMessage:	PROC[ handle: Handle,
		      postmark: POINTER TO BodyDefs.Timestamp ← NIL,
		      sender:   BodyDefs.RName ← NIL,
		      returnTo: BodyDefs.RName ← NIL ];

GVNextItem:	PROC[ handle: Handle ]
		RETURNS[ itemHeader: BodyDefs.ItemHeader ];

GVNextBlock:	PROC[ handle: Handle,
		      buffer: DESCRIPTOR FOR PACKED ARRAY OF CHARACTER ]
		RETURNS[ bytes: CARDINAL ];

GVWriteTOC:	PROC[ handle: Handle, text: STRING];

GVDeleteMessage: PROC[ handle: Handle ];

GVAccept:	PROC[ handle: Handle ];

GVClose:	PROC[ handle: Handle ];
   -- Close any stream created for this mailbox without deleting messages
   -- Does not complain if there is no stream.




-- Procedures for access to mail on MTP servers --

-- See "RetrieveDefs" for specifications of these procedures --

MTPNextMessage:	PROC[ handle: Handle ]
		RETURNS[ msgExists: BOOLEAN,
			 archived:  BOOLEAN,
			 deleted:   BOOLEAN ];

MTPNextItem:	PROC[ handle: Handle ]
		RETURNS[ itemHeader: BodyDefs.ItemHeader ];

MTPNextBlock:	PROC[ handle: Handle,
		      buffer: DESCRIPTOR FOR PACKED ARRAY OF CHARACTER ]
		RETURNS[ bytes: CARDINAL ];

MTPAccept:	PROC[ handle: Handle ];

MTPClose:	PROC[ handle: Handle ];
   -- Close any stream created for this mailbox without deleting messages
   -- Does not complain if there is no stream.

END.