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.
SEE ALSO
- InetTCP
-
implementation that supports IPv4 TCP sockets
- Loader
-
interfaces the runtime module loader
- PersistentObjects
-
input and output of persistent objects
- SMStreams
-
implements bidirectional communication streams which are based upon
shared memory
- StreamConditions
-
conditions which allow to wait until a stream
becomes ready for input or output
- UnixDomainSockets
-
interfaces UNIX domain sockets
Edited by: borchert, last change: 2005/02/24, revision: 1.5, converted to HTML: 2005/02/24
Oberon ||
Library ||
Module Index ||
Search Engine ||
Definition ||
Module