-- Copyright (C) 1981, 1984, 1985  by Xerox Corporation. All rights reserved. 
-- RetrieveDefs.mesa, Transport Mechanism - DEFS for retrieval of new mail from GV Servers --

-- HGM: 15-Sep-85  4:27:56
-- M. D. Schroeder  February 20, 1980  5:05 PM --
-- Andrew Birrell  21-Jan-81 17:13:34 --

DIRECTORY
  BodyDefs USING [ItemHeader, RName, Timestamp];


RetrieveDefs: DEFINITIONS =
  BEGIN


  -- No procedures in this interface other than the "AccessProcs" returned by
  -- "NextServer" ever raise a SIGNAL or ERROR.




  Handle: TYPE [SIZE[LONG POINTER]];
  -- This interface is intended to be able to be used by multiple clients.
  -- They are distinquished by a "handle", created by "Create" and
  -- destroyed by "Destroy" --


  Create: PROC [
    pollingInterval: CARDINAL, reportChanges: PROCEDURE [MBXState] ¬ NIL]
    RETURNS [Handle];
  -- Must be called before any other entries in this interface.  Can be
  -- called many times.  "pollingInterval" is the interval in seconds to
  -- wait between successive inbox checks and "reportChanges" (if
  -- provided) is called  whenever the state of the user's authentication
  -- or mailboxes changes;  "reportChanges" will not be called if the
  -- state changes to "unknown" or "userOK".


  Destroy: PROC [Handle];
  -- Terminates use of this handle, releasing all resources used by it. --




  -- AUTHENTICATION AND MAILBOX POLLING --


  NewUser: PROC [handle: Handle, user: BodyDefs.RName, password: LONG STRING];
  -- Provides new user name and password, and starts authentication and
  -- mailbox checking.


  MBXState: TYPE = {
    unknown, badName, badPwd, cantAuth, userOK, allDown, someEmpty, allEmpty,
    notEmpty};
  -- Records current state of the user's mailboxes. Initially "unknown".
  -- Set to "badName", "badPwd", "cantAuth" or "userOK" after
  -- authentication check.  Set to "allDown", "someEmpty", "allEmpty", or
  -- "notEmpty" after mail polling is complete.  "someEmpty" means not all
  -- servers replied and none had mail; "allEmpty" means all replied and
  -- none had mail; "notEmpty" means at least one has mail; "allDown"
  -- means none replied.

  MailboxState: PROC [handle: Handle] RETURNS [state: MBXState];
  -- Returns the current mailbox state.  Will not return "unknown" or
  -- "userOK" (These change to "cantAuth" or "allDown" after suitable
  -- timeouts if necessary.)


  WaitForMail: PROC [handle: Handle];
  -- returns only when there is likely to be mail for the user --
  -- Possible ERRORS: none




  -- ACCESS TO MAILBOXES --


  -- The intended use is as follows.

  -- The user has a number of mailboxes, each of which is on an MTP server or
  -- on a Grapevine server.  To access all of a client's mail, call
  -- "NextServer" repeatedly until it returns noMore=TRUE.  For each
  -- successful call of "NextServer", use the AccessProcs to read the mail in
  -- the mailbox.

  -- For either type of server, call "nextMessage" until it returns
  -- msgExists=FALSE.  The first call of "nextMessage" for each server will
  -- attempt to create a stream to the server (signalling if it fails). 
  -- While accessing a mailbox, "Failed" may be signalled at any time if the
  -- communication system fails (because of network or server error).  If
  -- "Failed" is signalled, no further operations on this mailbox are allowed

  --  If "nextMessage" returns deleted=TRUE it indicates that the message is
  -- really just a placeholder and has been removed from the mailbox; you
  -- should not attempt to access the message.  Returning archived=TRUE
  -- indicates that the message has been spilled to some file server, and
  -- accessing it is likely to be much slower.  For each message that exists
  -- and is not deleted, the message may be manipulated by the other
  -- procedures provided.

  -- If the server type is GV, "readTOC" may be used to read any TOC entry
  -- for the message (giving length=0 if there is no TOC entry), then
  -- "startMessage" may be called to read the guaranteed properties of the
  -- message; these are not available for MTP servers; these may not be
  -- called after you have called "nextItem" for this message.

  -- For either type of server, "nextItem" may be called to access in
  -- sequence the items which are the contents of the message body.  Note
  -- that the ItemHeader contains the item type and length in bytes.  For an
  -- MTP server, the only item will be of type "text".  For a GV server, the
  -- first item will be the guaranteed recipient list.  For all servers, the
  -- message body is followed by an item of type "LastItem".  Within an item,
  -- use "nextBlock" to access the data of the item.  Each call of
  -- "nextBlock" within an item will fill its buffer if the data exists;  the
  -- end of the item is indicated by "nextBlock" returning 0.

  -- If the server is GV, you may call "writeTOC" to change or create a TOC
  -- entry for the message, or you may call "deleteMessage" to remove this
  -- single message from the mailbox;  "readTOC", "startMessage", "nextItem"
  -- or "nextBlock" may not be called after calling "writeTOC" or
  -- "deleteMessage" for this message.

  -- At any time within an item, you may call "nextItem" to skip the
  -- remainder of the item;  at any time within a message, you may call
  -- "nextMessage" to skip the remainder of this message.

  -- At any time within a mailbox, you may call "accept".  This
  -- terminates reading the mailbox and deletes all messages from
  -- the mailbox.  Calling "accept" will not delete any messages which you
  -- haven't been given a chance to read.  No other operations on the mailbox
  -- are allowed after calling "accept".  If you call "NextServer" without
  -- having called "accept", the mailbox is closed (if necessary) without
  -- deleting the messages (except those which were deleted by calling
  -- "deleteMessage").


  ServerState: TYPE = {unknown, empty, notEmpty};
  -- "unknown" means the server didn't reply to mail check packets.

  AccessProcs: TYPE = RECORD [  -- procedures to access mailbox --
    nextMessage: PROC [handle: Handle]
      RETURNS [msgExists, archived, deleted: BOOLEAN],
    nextItem: PROC [handle: Handle] RETURNS [BodyDefs.ItemHeader],
    nextBlock: PROC [
      handle: Handle, buffer: LONG DESCRIPTOR FOR PACKED ARRAY OF CHARACTER]
      RETURNS [bytes: CARDINAL],
    accept: PROC [handle: Handle],
    readTOC: PROC [handle: Handle, text: LONG STRING],
    startMessage: PROC [
      handle: Handle, postmark: LONG POINTER TO BodyDefs.Timestamp ¬ NIL,
      sender: BodyDefs.RName ¬ NIL, returnTo: BodyDefs.RName ¬ NIL],
    writeTOC: PROC [handle: Handle, text: LONG STRING],
    deleteMessage: PROC [handle: Handle] ];


  NextServer: PROCEDURE [handle: Handle]
    RETURNS [noMore: BOOLEAN, state: ServerState, procs: AccessProcs];
  -- Returns information about the next server in the mailbox site list of
  -- the user, and that server becomes the "current server".  If there is
  -- no such server, noMore=TRUE, in which case the next call to
  -- "NextServer" will start a new sequence of mail retrieval.  If the
  -- state is "unknown", attempting to access the mailbox is inadvisable,
  -- as the server is probably down.  If the state is "empty", there may
  -- in fact be mail, as the state is only a hint obtained by polling. 


  ServerName: PROC [handle: Handle, serverName: BodyDefs.RName];
  -- Provides the name of the current server.  For MTP registries, this
  -- will be equivalent to the registry name.


  FailureReason: TYPE = {
    communicationFailure,  -- server or network down --
    noSuchServer,  -- server name incorrect --
    connectionRejected,  -- server full, mbx busy, etc --
    badCredentials,  -- name/pwd rejected --
    unknownFailure  -- protocol violation
    -- or unknown MTP error:
    -- likely to be permanent --
    };

  Failed: ERROR [why: FailureReason];
  -- May be signalled by any of the "AcceptProcs" returned by "NextServer"



  END.