-- Copyright (C) 1981, 1984, 1985  by Xerox Corporation. All rights reserved. 
-- SendDefs.mesa - DEFS for client sending mail --

-- HGM, 19-Mar-86 19:55:25
-- Andrew Birrell  23-Jan-81 11:00:14 --

DIRECTORY
  BodyDefs USING [ItemType, Password, RName, Timestamp];

SendDefs: DEFINITIONS =
  BEGIN


  -- 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 [SIZE[LONG POINTER]];

  Create: PROCEDURE RETURNS [handle: Handle];

  Destroy: PROCEDURE [handle: Handle];


  -- 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, (...), . . .
  --	(GetStamp) Send
  -- Abort may be called at any point to abandon the sequence.


  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 = {ok, badPwd, badSender, badReturnTo, allDown};

  StartSend: PROC [
    handle: Handle, senderPwd: LONG STRING, sender: BodyDefs.RName,
    returnTo: BodyDefs.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), fromHost: [0..256),
    senderKey: BodyDefs.Password, sender: BodyDefs.RName,
    returnTo: BodyDefs.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: BodyDefs.RName];
  -- Adds to the recipient list. --


  CheckValidity: PROC [
    handle: Handle, notify: PROCEDURE [CARDINAL, BodyDefs.RName]]
    RETURNS [ok: CARDINAL];
  -- 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: BodyDefs.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: LONG DESCRIPTOR FOR PACKED ARRAY OF CHARACTER];
  -- Add the data to the current message body item. --


  GetStamp: PROC [handle: Handle] RETURNS [BodyDefs.Timestamp];
  -- Returns timestamp of current message.
  
  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 = {ok, notFound, individual, allDown};

  ExpandFailed: ERROR;

  Expand: PROC [name: BodyDefs.RName, work: PROC [BodyDefs.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.