-- Copyright (C) 1984  by Xerox Corporation. All rights reserved. 
-- RetrieveXDefs.mesa, Transport Mechanism: User: Private DEFS for mail retrieval

-- HGM: 10-Dec-84 23:44:37
-- 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],
  Stream USING [Handle];

RetrieveXDefs: DEFINITIONS =
  BEGIN


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

  MBXData: TYPE = RECORD [
    next: MBXPtr,
    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,

    -- Current state of mail reading: --
    state: {beforeMBX, beforeTOCr, beforeBody, inBody, beforeTOCw, afterMessage, afterMBX},
    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.


  END.