english
version "1.0"
identify "xyz"

#: Copyright (c) 1998-2005 by Wayne C. Gramlich.
#, All rights reserved.

#: This module provides an interface to network facilities.

module network

define internet_address			#: An IPv4 or IPv6 internet address
    record
	address unsigned		#: IPv4 (32-bit) address for now
	host_name string		#: Host_name (or "" if not known)
    generate allocate, erase, identical

define network
    record
	in_stream input_stream		#: Input stream
	input_file_set file_set		#: Input {file_set}
	out_stream output_stream	#: Output stream
	output_file_set file_set	#: Output {file_set}
	unix_system unix_system		#: {unix_system} object
    generate allocate, erase, identical, print



#: {internet_address} routines:

procedure format@internet_address
    takes
	internet_address internet_address
	out_stream out_stream
	format string
	offset unsigned
    returns_nothing

    #: This procedure will output {internet_address} to {out_stream}.
    #, For now, the formatting information in {format} at {offset} is
    #, ignored.


procedure local_host@internet_address
    takes_nothing
    returns internet_address

    #: This procedure will return the {internet_address} object for
    #, the local host.


procedure lookup@internet_address
    takes
	host_name string
	errors errors
    returns internet_address

    #: This proceure will lookup the internet address for {host_name}
    #, and return its corresponding {internet_address} object.  If
    #, {host_name} can not be looked up, ??@{internet_address} is returned
    #, and an error message is entered into {errors}.

    #, form "d.d.d.d", where "d" a decimal number between 0 and 255
    #, inclusive:

procedure print@internet_address
    takes
	internet_address internet_address
	out_stream out_stream
    returns_nothing

    #: This procedure will print {internet_address} to {out_stream}.


procedure version4_create@internet_address
    takes
	address unsigned
    returns internet_address

    #: This procedure will create and return a version 4 (IPv4)
    #, internet address.  When IPv6 comes along, it will be
    #, be possible to load one into an {internet_address} object
    #, using {version6_create}@{internet_address}().


procedure version6_create@internet_address
    takes_nothing
    returns_nothing

    #: This is a place holder routine that does nothting except fail.
    #, When IPv6 support starts to show up, this procedure will actually
    #, be implemented.


#: {network} routines:

procedure create@network
    takes_nothing
    returns network

    #: This procedure will create and return a new {network} object.


procedure host_name_connect@network
    takes
	network network
	host_name string
	port unsigned
	errors errors
    returns logical

    #: This procedure will setup a TCP connection to {host_name} on {port}
    #, using {network}.  ??@{input_stream} and ??@{output_stream} are
    #, returned if no connection is successfully set up.  Any error
    #, information is reported to {errors}.


procedure internet_address_connect@network
    takes
	network network
	internet_address internet_address
	host_name string
	port unsigned
	errors errors
    returns input_stream, output_stream

    #: This routine sets up a TCP connection to {internet_address} on {port}
    #, using {network}.  ??@{input_stream} and ??@{output_stream} are
    #, returned if no connection is successfully set up.  Any error
    #, information is reported to {errors}.  {host_name} is only used
    #, for reporting error information in {errors}.