-- GrapevineUser (Cedar) - public DEFS for retrieval of messages

-- GVRetrieve.mesa

-- Andrew Birrell  September 1, 1982 10:08 am

DIRECTORY
RetrieveDefs    USING[ MBXState, FailureReason, ServerState, ServerType ],
GVBasics        USING[ ItemHeader, RName, Timestamp ],
Rope            USING[ ROPE ];


GVRetrieve: CEDAR DEFINITIONS =

BEGIN

ROPE: TYPE = Rope.ROPE;

-- No procedures in this interface other than the message
-- accessing procs ever raise a SIGNAL or ERROR.


Handle:	TYPE = REF Object;
   -- This interface is intended to be able to be used by multiple clients.
   -- They are distinguished by a "handle", created by "Create" and
   -- destroyed by the garbage collector.  "Close" should be called when
   -- you're finished with the handle as a hint to release resources
   -- (particularly any BSP connection). --

Object: TYPE;


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".


Close: PROC[Handle];
   -- Releases resources used by this handle.  Further use of this handle is illegal. --




-- AUTHENTICATION AND MAILBOX POLLING --


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


MBXState: TYPE = RetrieveDefs.MBXState ;
   -->>> { 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 Access Procs to read the mail in
-- the mailbox.

-- To read the mail in the mailbox, 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

-- NOTE: If the user has a mailbox on an MTP server, calling "NextMessage"
-- for that mailbox will raise "Failed[communicationFailure]".

--  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.

-- "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.

-- "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.  The
-- first item will be the guaranteed recipient list.  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.

-- 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").

ServerType: TYPE = RetrieveDefs.ServerType;
-->>> { MTP, GV };

ServerState: TYPE = RetrieveDefs.ServerState ;
-->>> { unknown, empty, notEmpty }
   -- "unknown" means the server didn't reply to mail check packets;
   -- in this case, for efficiency, you should NOT call "NextMessage".

NextServer: PROC[ handle: Handle ]
	    RETURNS[ noMore: BOOLEAN, state: ServerState, type: ServerType ];
   -- 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] RETURNS [serverName: GVBasics.RName];
   -- Provides the name of the current server.  For MTP registries, this
   -- will be equivalent to the registry name.


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

Failed:	ERROR[why: FailureReason];
   -- May be signalled by any of the procedures that handle messages.


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

StartMessage: PROC[handle: Handle ] 
	      RETURNS[postmark: GVBasics.Timestamp,
		      sender: GVBasics.RName,
		      returnTo: GVBasics.RName];

NextItem: PROC[handle: Handle] RETURNS[GVBasics.ItemHeader];

-- "NextBlock" may be called to read the item piece by piece.
NextBlock: PROC[handle: Handle, maxlength: INT] RETURNS[block: ROPE];
		
-- "ReadItem" returns the entire (remainder of the) item. --
ReadItem: PROC[handle: Handle] RETURNS[item: ROPE] = INLINE
  { RETURN[ NextBlock[handle, LAST[INT]] ] };

-- "GetBlock", "GetChar", "CharsAvail" are intended for building an IO.STREAM for the item --
GetBlock: PROC[handle: Handle, block: REF TEXT, startIndex: NAT, stopIndexPlusOne: NAT]
        RETURNS[nBytesRead: NAT];
GetChar: PROC[handle: Handle] RETURNS[CHAR];
CharsAvail: PROC[handle: Handle] RETURNS[BOOL];
EndOf: PROC[handle: Handle] RETURNS[BOOL] = INLINE { RETURN[NOT CharsAvail[handle]] };

-- "Accept" flushes the current inbox. --
Accept:	PROC[handle: Handle];



-- "ReadTOC", "WriteTOC" and "DeleteMessage" are useful mainly for Lily. --

ReadTOC: PROC[handle: Handle] RETURNS[ ROPE ];

WriteTOC: PROC[handle: Handle, entry:ROPE ];

DeleteMessage: PROC[handle: Handle] ;




END.
�ÊÖ–
"Mesa" style˜IprocšËÏcAœ
�œ
�.œ
Ïk	œžœFžœ2žœžœžœ
žœžœžœžœžœ�kœ
žœžœ�Iœ�Aœ�Fœ�Bœ�(œ
žœÏnœžœžœž	œ
žœžœ
�Fœ�Gœ�@œ�Hœ�Dœ�+œŸœžœ
�Uœ�(œŸœžœ2žœ�Fœ�œžœ�4œ�1œ�Gœ�<œ�Hœ�Iœ�Gœ�Dœ�œ
Ÿœžœžœ�Dœ�Dœ�œŸœžœ�?œ�œ�œ�#œ
�®œ
�Ü
�ǜ
�¿œ
�ˆœ
�®œ
�Á
œ
�þœ
žœ�œžœ�#œ�‰
œ
Ÿ
œžœžœ
žœ-�Iœ�Hœ�?œ�Eœ�Hœ�Gœ�FœŸ
œžœžœ"�Fœ�,œžœ�7œ
�/œ
�9œ
�-œ
�[œ	žœ�CœŸœžœžœžœŸœžœžœcŸœžœžœ�>Ÿ	œžœžœžœžœ�<œ
Ÿœžœžœžœžœžœžœ
žœ	�]œ
Ÿœ
žœžœ
žœžœžœ
žœ
žœŸœžœžœ
žœŸ
œžœžœ
žœŸœžœžœ
žœžœžœ
žœ�)œ
Ÿœžœ�KœŸœžœžœžœŸœžœžœŸ
œžœžœ
˜ËD—…—"N%*