[Indigo]<Cedar>OISCP>PacketExchange.mesa!1

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

PacketExchange: DEFINITIONS =
BEGIN

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

SendRequest: PUBLIC PROCEDURE [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.
SendReply: PUBLIC PROCEDURE [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];
END.