DEFINITION MODULE IOLink;

  (* Types and procedures giving the standard implementation of channels *)

FROM IOChan     IMPORT ChanId, DeviceErrNum, ChanExceptions;
FROM IOConsts   IMPORT ReadResults;
FROM ChanConsts IMPORT FlagSet;
FROM SYSTEM     IMPORT ADDRESS;


(* Devices need to identify themselves in order to allow a check to be made
   that device-dependent operations are applied only for channels opened to
   that device: *)

TYPE
  DeviceId;  (* values of this type are used to identify new device modules
		and are normally obtained by them during their intialization *)


PROCEDURE AllocateDeviceId (VAR did : DeviceId);
(* Allocates a unique value of type DeviceId and assigns this value to
   the parameter did *)


(* a new device module open procedure obtains a channel by calling MakeChan *)

PROCEDURE MakeChan (    did : DeviceId;
                    VAR cid : ChanId);
(* Attempts to make a new channel for the device module identified by did.
   If no more channels can be made, the identity of the bad channel is
   assigned to cid. Otherwise, the identity ofa new channel is assigned to
   cid. *)


(* If a channel is allocated but the call of the device module open
   procedure is not successful, and on a successful call of a device module
   close procedure, the device module unmakes the channel and returns the
   value identifying the bad channel to its client: *)

PROCEDURE UnMakeChan (    did : DeviceId;
                      VAR cid : ChanId);
(* If the device module identified by the parameter did is not the module that
   made the channel identified by the parameter cid, the exception wrongDevice
   is raised.
   Otherwise, the channel is deallocated and the value identifying the bad
   channel is assigned to cid. *)



(* If the call of the device module open procedure is successful, the
   device module obtains a pointer to a device table for the channel, which
   will have been initialized by MakeChan. It then changes the fields of the
   device table to install its own values for the device data, supported
   operations, and flags, and returns to its client the identity of the
   channel. *)

TYPE
  DeviceTablePtr = POINTER TO DeviceTable;
    (* Values of this type are used to refer to device tables *)

(* Device modules supply procedures of the following types: *)

TYPE
  LookProc =	  PROCEDURE (DeviceTablePtr, VAR CHAR, VAR ReadResults);
  SkipProc =	  PROCEDURE (DeviceTablePtr);
  SkipLookProc =  PROCEDURE (DeviceTablePtr, VAR CHAR, VAR ReadResults);
  TextReadProc =  PROCEDURE (DeviceTablePtr, ADDRESS, CARDINAL, VAR CARDINAL);
  TextWriteProc = PROCEDURE (DeviceTablePtr, ADDRESS, CARDINAL);
  WriteLnProc =   PROCEDURE (DeviceTablePtr);
  RawReadProc =   PROCEDURE (DeviceTablePtr, ADDRESS, CARDINAL, VAR CARDINAL);
  RawWriteProc =  PROCEDURE (DeviceTablePtr, ADDRESS, CARDINAL);
  GetNameProc =   PROCEDURE (DeviceTablePtr, VAR ARRAY OF CHAR);
  ResetProc =	  PROCEDURE (DeviceTablePtr);
  FlushProc =	  PROCEDURE (DeviceTablePtr);
  FreeProc =	  PROCEDURE (DeviceTablePtr);
   (* Carry out the operations involved in closing the corresponding
      channel, including flushing buffers, but do not unmake the channel.
      This procedure is called for each open channel at program termination. *)


TYPE
  DeviceData = ADDRESS;

  DeviceTable = RECORD		(* Initialized by MakeChan to: *)
                  cd : DeviceData;         (* the value NIL *)
                  did : DeviceId;          (* the value given to MakeChan *)
                  cid : ChanId;            (* the identity of the channel *)
                  result : ReadResults;    (* the value notKnown *)
                  errNum : DeviceErrNum;   (* undefined *)
                  flags : FlagSet;         (* FlagSet{} *)
                  doLook : LookProc;       (* raise exception notAvailable *)
                  doSkip : SkipProc;       (* raise exception notAvailable *)
                  doSkipLook : SkipLookProc;   (* raise exception notAvailable *)
                  doTextRead : TextReadProc;   (* raise exception notAvailable *)
                  doTextWrite : TextWriteProc; (* raise exception notAvailable *)
                  doLnWrite : WriteLnProc;     (* raise exception notAvailable *)
                  doRawRead : RawReadProc;     (* raise exception notAvailable *)
                  doRawWrite : RawWriteProc;   (* raise exception notAvailable *)
                  doGetName : GetNameProc; (* return the empty string *)
                  doReset : ResetProc;     (* do nothing *)
                  doFlush : FlushProc;     (* do nothing *)
                  doFree : FreeProc;       (* do nothing *)
                END;


(* The pointer to the device table for a channel is obtained using the
   following procedure: *)

PROCEDURE DeviceTablePtrValue (cid : ChanId;
			       did : DeviceId): DeviceTablePtr;
(* If the device module identified by the parameter did is not the module
   that made the channel identified by the parameter cid, the exception
   wrongDevice is raised.
   Otherwise, a pointer to the device table for the channel is returned. *)


(* A device module can ask if it opened a given channel. It does this
   to implement a corresponding enquiry function that is exported from the
   device module: *)

PROCEDURE IsDevice (cid : ChanId;
                    did : DeviceId): BOOLEAN;
(* Tests if the device module identified by the parameter did is the
   module that made the channel identified by the parameter cid. *)



TYPE
  DevExceptionRange = ChanExceptions;  (* [notAvailable .. textParseError] *)

PROCEDURE RAISEdevException (cid : ChanId;
                             did : DeviceId;
                             x   : DevExceptionRange;
                             s   : ARRAY OF CHAR);
(* If the device module identified by the parameter did is not the module
   that made the channel identified by the parameter cid, the exception
   wrongDevice is raised. Otherwise the given exception is raised and the
   string value of the parameter s is included in the exception message. *)


PROCEDURE IsIOException (): BOOLEAN;
(* Returns TRUE if the current coroutine is in the exceptional execution state
   because of the raising of an exception from ChanExceptions
   Otherwise returns FALSE *)


PROCEDURE IOException (): ChanExceptions;
(* If the current coroutine is in the exceptional execution state because of
   the raising of an exception from ChanExceptions, returns the corresponding
   enumeration value, and otherwise raises an exception. *)

END IOLink.