-- PacketExchange.mesa (last edited by: BLyon on: January 20, 1981  3:00 PM)

  Environment USING [Block],
    ExchangeClientType, ExchangeID, maxDataBytePerExchange, WaitTime],
  SpecialSystem USING [SocketNumber],
  System USING [NetworkAddress];

PacketExchange: DEFINITIONS =

  -- The Packet Exchange Protocol is a request/reply protocol that provides a little more
  -- reliability than raw packets transmitetd from a socket, and less reliabilty than the
  -- Sequenced Packet Protocol.  Usually one end will provide some service at a
  -- well known socket or at a network address that is available through a binding
  -- process involving the Clearinghouse.  The other end acquires a socket and sends a
  -- request.  The request will be retransmitted a number of times with the interval
  -- between retransmissions based on the delay to the remote entity.

  -- definitions
  -- types and constants.
  ExchangeHandle: TYPE [2];
  RequestHandle: TYPE = LONG POINTER TO RequestObject;
  -- returned by WaitForRequest
  RequestObject: TYPE = RECORD [
    nBytes: CARDINAL, -- the byte size of the request Block
    requestType: OISCPTypes.ExchangeClientType,
    -- the next to fields are used in the reply;  clients should not touch these.
    requestersExchangeID: PRIVATE OISCPTypes.ExchangeID,
    requestersAddress: PRIVATE System.NetworkAddress];
  maxBlockLength: CARDINAL = OISCPTypes.maxDataBytePerExchange; -- in bytes
  ErrorReason: TYPE = {
    blockTooBig, blockTooSmall, noDestinationSocket, noRouteToDestination,
    hardwareProblem, aborted, timeout};
  defaultWaitTime: OISCPTypes.WaitTime = 60000; -- in msecs

  -- interface
  -- errors and signals
  Error: ERROR [why: ErrorReason];
  Timeout: SIGNAL; -- this may be RESUMEd

  -- procedures
  -- the requestor
  CreateRequestor: PROCEDURE [waitTime: OISCPTypes.WaitTime ← defaultWaitTime]
    RETURNS [ExchangeHandle]; -- at any socket number

    h: ExchangeHandle, remote: System.NetworkAddress,
    requestBlk, replyBlk: Environment.Block,
    requestType: OISCPTypes.ExchangeClientType ← unspecified]
    RETURNS [nBytes: CARDINAL, replyType: OISCPTypes.ExchangeClientType];

  -- the replyer
  CreateReplyer: PROCEDURE [
    localSocket: SpecialSystem.SocketNumber, requestCount: CARDINAL ← 1,
    waitTime: OISCPTypes.WaitTime ← defaultWaitTime] RETURNS [ExchangeHandle];
  -- requestCount is estimate of number of "to be queued" requests

  -- user must save rH inorder to send a reply
  WaitForRequest: PROCEDURE [
    h: ExchangeHandle, requestBlk: Environment.Block,
    requiredRequestType: OISCPTypes.ExchangeClientType ← unspecified]
    RETURNS [rH: RequestHandle];

  -- upon success return of SendReply, rH is invalid.  
    h: ExchangeHandle, rH: RequestHandle, replyBlk: Environment.Block,
    replyType: OISCPTypes.ExchangeClientType ← unspecified];

  -- request and reply can both point to the same piece of storage.
  Delete: PROCEDURE [h: ExchangeHandle];
  SetWaitTime: PROCEDURE [h: ExchangeHandle, waitTime: OISCPTypes.WaitTime];


Time: October 23, 1980  1:50 PM  By: Dalal  Action: created file.
Time: January 13, 1981  5:01 PM  By: BLyon  Action: moved file to Pilot Communication.