-- GrapevineUser (Cedar) - public DEFS for client sending mail --

-- GVSend.mesa

-- Andrew Birrell  August 27, 1982 3:41 pm

DIRECTORY
Rope            USING[ ROPE ],
SendDefs        USING[ StartSendInfo, ExpandInfo ],
GVBasics        USING[ ItemType, Password, RName ];

GVSend:    CEDAR DEFINITIONS =

BEGIN

ROPE: TYPE = Rope.ROPE;

-- These defs allow clients to inject messages into the mail system.  They
-- are designed so that they can be used by multiple processes creating
-- different messages;  the state of creation of a single message is
-- represented by a "Handle".  The interface is also designed so that it
-- may be implemented either by transmission over the network to a remote
-- mail server, or by calls on a local mail server. --

Handle:        TYPE = REF Object;

Object:        TYPE;

Create:        PROCEDURE RETURNS[handle: Handle];

Close:      PROCEDURE[ handle: Handle ];
  -- Release resources associated with the Handle, particularly a
  -- BSP connection.  The Handle may not be used subsequently.


-- For any one Handle, the following calls must be made in the order:
--    StartSend,
--    AddRecipient, AddRecipient, AddRecipient, . . .
--    CheckValidity {iff "validate=TRUE" when "StartSend" was called},
--    StartItem, (AddToItem, AddToItem, . . .), StartItem, (...), . . .
--    Send
-- Abort may be called at any point to abandon the sequence.
-- A Handle may be re-used, until calling "Close".  "Close" happens
-- implicitly sometime after the last reference to the Handle goes
-- away.

SendFailed: ERROR [ notDelivered: BOOLEAN ] ;
  -- "StartSend" raises no signals that may be caught by the client.
  -- The ERROR "SendFailed" may be raised by any of AddRecipient,
  -- CheckValidity, StartItem, AddToItem, or Send if some communication
  -- failure occurs.  If it is raised, the client should generally catch
  -- it, go back to the start of the message, and re-call "StartSend". 
  -- "StartSend" will then attempt to find a better mail server to talk
  -- to.  Only when "StartSend" returns "allDown" is it not possible to
  -- send the message.  The client may want to inform the user if this
  -- re-try mechanism has been invoked.

StartSendInfo:    TYPE = SendDefs.StartSendInfo;
-- { ok, badPwd, badSender, badReturnTo, allDown };

StartSend: PROC[ handle:    Handle,
         senderPwd: ROPE,
         sender:    GVBasics.RName,
         returnTo:  GVBasics.RName _ NIL,
         validate:  BOOLEAN ]
       RETURNS[ StartSendInfo ];
  -- Starts a message.  If "returnTo" is NIL, the sender name is used as
  -- return-to name.  "validate" says whether recipient names should be
  -- validated during the communication with the mail server. --


SendFromClient:    PROC[ handle:    Handle,
              fromNet:   [0..256) _ 0,
              fromHost:  [0..256) _ 0,
              senderKey: GVBasics.Password,
              sender:    GVBasics.RName,
              returnTo:  GVBasics.RName,
              validate:  BOOLEAN ]
        RETURNS[ StartSendInfo ];
  -- Note: this procedure is intended for use only by the remote server.
  -- Starts a message.  "fromNet" and "fromHost" are ignored if the mail
  -- server is remote.  "validate" says whether recipient names should be
  -- validated during the communication with the mail server. --


AddRecipient: PROC[ handle: Handle, recipient: GVBasics.RName ];
  -- Adds to the recipient list. --


CheckValidity: PROC[ handle: Handle,
              notify: PROCEDURE[INT,GVBasics.RName] ]
        RETURNS[ ok: LONG INTEGER ];
  -- Must be called after all the recipients have been given, iff the
  -- "validate" argument to "StartSend" was TRUE.  Calls "notify" for each
  -- bad recipient.  The arguments to "notify" are the recipient number
  -- (counting from 1) and name of an illegal recipient.  Returns the
  -- number of valid recipients.  If any recipients were invalid, delivery
  -- of the message is still allowed.


StartItem: PROC[ handle: Handle, type: GVBasics.ItemType ];
  -- Start a message body item.  The type must not be "Postmark",
  -- "Sender", "ReturnTo", or "Recipients". --


StartText: PROC[ handle: Handle ] = INLINE{ StartItem[handle,Text] };


AddToItem: PROC[ handle: Handle, buffer: ROPE ];
  -- Add the data to the current message body item. --


Send: PROC[ handle: Handle ];
  -- Commit to sending the message; returns only when the mail server has
  -- commited to delivering the message. --


Abort: PROC[ handle: Handle ];
  -- Abandon the message.  May be called at any time. --

ExpandInfo: TYPE = SendDefs.ExpandInfo ;

ExpandFailed: ERROR;

Expand:    UNSAFE PROC[name: GVBasics.RName, work: PROC[GVBasics.RName]] RETURNS[ ExpandInfo ];
  -- If the name will be interpreted by the mail server as a distribution
  -- list, enumerates the names which are direct members of that list.
  -- This is intended for use only if the user wants to inspect the
  -- contents.  Note that the contents may change, or the name may become
  -- invalid, before delivery of any message.  "Expand" works even if the
  -- list has to be read from an MTP server.  May raise "ExpandFailed". 
  -- If ExpandFailed is raised, some communication error has occurred; 
  -- you should re-call Expand, which will try another server.  Note that
  -- failure of Expand may be caused by failure of some remote server; 
  -- you may still be able to send a message successfully.
  -- "notFound" means the name is invalid; "individual" means the name
  -- specifies an individual; "allDown" means either all mail servers
  -- are inaccessible, or some other server (possibly MTP) needed for the
  -- expansion is inaccessible.

END.