Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
Networks

NAME

Networks - general abstraction for bidirectional network connections

SYNOPSIS

TYPE Network = POINTER TO NetworkRec;
TYPE NetworkRec = RECORD (PersistentDisciplines.ObjectRec) END;
TYPE Address = POINTER TO AddressRec;
TYPE AddressRec =
   RECORD
      (PersistentDisciplines.ObjectRec)
      network: Network;
   END;
TYPE Socket = POINTER TO SocketRec;
TYPE SocketRec = RECORD (Disciplines.ObjectRec) END;



TYPE OpenProc = PROCEDURE (VAR s: Streams.Stream; address: Address;
                           bufmode: Streams.BufMode;
                           errors: RelatedEvents.Object) : BOOLEAN;
TYPE CreateOpenConditionProc = PROCEDURE(VAR condition: Conditions.Condition;
                                         address: Address);
TYPE TestAndOpenProc = PROCEDURE (VAR s: Streams.Stream;
                                  condition: Conditions.Condition;
                                  bufmode: Streams.BufMode;
                                  errors: RelatedEvents.Object) : BOOLEAN;
TYPE CreateSomeSocketProc = PROCEDURE (VAR socket: Socket;
                                       VAR address: Address;
                                       errors: RelatedEvents.Object) : BOOLEAN;
TYPE ListenProc = PROCEDURE (VAR socket: Socket; address: Address;
                             errors: RelatedEvents.Object) : BOOLEAN;
TYPE ReleaseProc = PROCEDURE (socket: Socket);
TYPE AcceptProc = PROCEDURE (socket: Socket; VAR s: Streams.Stream;
                             bufmode: Streams.BufMode) : BOOLEAN;
TYPE AcceptConditionProc = PROCEDURE (VAR condition: Conditions.Condition;
                                      socket: Socket);
TYPE Interface = POINTER TO InterfaceRec;
TYPE InterfaceRec =
   RECORD
      (Objects.ObjectRec)
      open: OpenProc;
      createOpenCondition: CreateOpenConditionProc;
      testAndOpen: TestAndOpenProc;
      createSomeSocket: CreateSomeSocketProc;
      listen: ListenProc;
      release: ReleaseProc;
      accept: AcceptProc;
      acceptCondition: AcceptConditionProc;
   END;



CONST unknownNetwork = 0;
CONST corruptedInput = 1;
CONST errors = 2;
TYPE ErrorCode = SHORTINT;
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errorcode: ErrorCode;
   END;
VAR error: Events.EventType;
VAR errormsg: ARRAY errors OF Events.Message;



PROCEDURE Register(VAR network: Network;
                   name: ARRAY OF CHAR; if: Interface);
PROCEDURE GetNetwork(name: ARRAY OF CHAR; VAR network: Network;
                     VAR errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE GetName(network: Network; VAR name: ARRAY OF CHAR);
PROCEDURE GetNetworks(VAR iterator: Iterators.Iterator);



PROCEDURE Open(VAR s: Streams.Stream;
               address: Address;
               bufmode: Streams.BufMode;
               errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE CreateOpenCondition(VAR condition: Conditions.Condition;
                              address: Address);
PROCEDURE TestAndOpen(VAR s: Streams.Stream;
                      address: Address;
                      condition: Conditions.Condition;
                      bufmode: Streams.BufMode;
                      errors: RelatedEvents.Object) : BOOLEAN;



PROCEDURE CreateSomeSocket(VAR socket: Socket;
                           network: Network;
                           VAR address: Address;
                           errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Listen(VAR socket: Socket; address: Address;
                 errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Release(socket: Socket);
PROCEDURE Accept(socket: Socket;
                 VAR s: Streams.Stream;
                 bufmode: Streams.BufMode) : BOOLEAN;
PROCEDURE CreateAcceptCondition(VAR condition: Conditions.Condition;
                                socket: Socket);

DESCRIPTION

Networks provides a general abstraction for bidirectional network connections which is independent from a particular network. Each network is supported by a module which registers its network during its initialization time together with its module name. Network addresses consist of a network reference (which points to the associated module) and a network specific part which is covered by extensions of Address. Networks and addresses are persistent objects (see PersistentObjects). Sockets represent access points where other processes may plug in. Note that one socket allows multiple connections simultaneously.

Providing a Network

RegisterNetwork is to be called by modules which exports a specific network. The name of a network should be its associated module. This assures that the name remains unique and that the associated module may be loaded at runtime by the network name (see Loader). The interface if is expected to meet following specification:

open: PROCEDURE(VAR s: Streams.Stream; address: Address; bufmode: Streams.BufMode; errors: RelatedEvents.Object) : BOOLEAN;: try to establish a network connection to the given address and, if successful, open a bidirectional stream with the given buffering mode bufmode for the connection. This procedure may block the calling task (see Tasks).
createOpenCondition: PROCEDURE(VAR condition: Conditions.Condition; address: Address);: initiate a connection to address and return a condition which allows to wait for the connection to be established. Note that the condition must return TRUE even if a connection cannot be set up.
testAndOpen: PROCEDURE(VAR s: Streams.Stream; condition: Conditions.Condition; bufmode: Streams.BufMode; errors: RelatedEvents.Object) : BOOLEAN;: test a connection which has been initiated by createOpenCondition, and return, if successful, a bidirectional stream with the given buffering mode.
createSomeSocket: PROCEDURE(VAR socket: Socket; VAR address: Address; errors: RelatedEvents.Object) : BOOLEAN;: create a socket for an arbitrary address which is to be returned in address.
listen: PROCEDURE(VAR socket: Socket; address: Address; errors: RelatedEvents.Object) : BOOLEAN;: create a socket for the given address.
release: PROCEDURE(socket: Socket);: release the socket and its associated resources.
accept: PROCEDURE(socket: Socket; VAR s: Streams.Stream; bufmode: Streams.BufMode) : BOOLEAN;: wait until another process plugs into the socket (by calling Open) and, if successfully, open a bidirectional stream for the connection with the given buffering mode. Errors are to be related to socket. The streams returned by open, testAndOpen and accept are expected to support the messages of StreamConditions.
acceptCondition: PROCEDURE(VAR condition: Conditions.Condition; socket: Socket);: create a condition which evaluates to TRUE when a subsequent accept will return immediately.

GetNetwork returns the network for the given network name which is usually the name of the supporting module. GetName returns the name of the given network. GetNetworks returns an iterator which allows to iterate through all networks which are currently supported by already loaded modules.

Using a network

Open tries to establish a network connection to the given address and returns, if successful, an opened bidirectional stream. While Open is free to block the calling task, CreateOpenCondition returns a condition which returns TRUE either if a connection to address is established, or if a connection cannot be set up. TestAndOpen allows then to check for a successful connection, and (like Open) to open a bidirectional stream (if successful).

Listen creates a socket for the given address which may be later used to wait for incoming connections. CreateSomeSocket works like Listen but chooses an address itself which is returned. Accept waits for incoming connections for socket and opens a bidirectional stream for it. CreateAcceptCondition creates a condition which evaluates to TRUE if a subsequent Accept would not block for socket.

DIAGNOSTICS

All procedures (except CreateOpenCondition and CreateAcceptCondition) return FALSE and relate their error events to errors (or to socket in case of Accept) in error case. Usually, the error events which are related to socket will be queued.

Additionally, following error events may be generated on reading persistent objects of Networks:

unknownNetwork: The network or address references a unknown or unsupported network name.
corruptedInput: An object couldn't be read because of corrupted or badly formatted input.

Ulm's Oberon Library: Networks