@chapter Network Programming Guide
@label[chapter-doc-programs]

@section Host Objects - Brief Overview
@label[section-host-objects]

In keeping with the Flavors object-oriented programming methodology,
the concept of a ``host object type'' is actually grounded in the
operations such objects accept and the instance variables they hold.

Host objects have two major uses.  One, they identify a ``file computer'' to use inside a pathname.
Two, they serve to canonicalize
name and address mapping on networks.  
A comment at the start of
@l(SYS: IO; FILE; PATHNM) describes in more detail the pathname parsing
interaction with host objects.

The flavor @l(SI:BASIC-HOST) is included in host objects of all types.
The flavor @l(SI:HOST) is for hosts which actually correspond to a
particular machine on some network (as opposed to a logical host in
the pathname sense).

Additional information is provided in the @LMM@.

@subsection Obtaining a Host Object

Known network hosts are kept on a list, @l(si:host-alist).
To obtain the host object corresponding to a particular network host by name, use @l(si:parse-host).

@defun si:parse-host host &optional (no-error-p nil) (unknown-ok t)

Return a host object for name HOST, taken from the HOST-ALIST.
This is the right function to use for making network connections,
but is not right for parsing pathnames.  Use FS:GET-PATHNAME-HOST for that.
HOST can also be a host object already; then it's simply returned.
NO-ERROR-P says just return NIL if there is no such host known.
UNKNOWN-OK says call the UNKNOWN-HOST-FUNCTION (if that's not NIL)
to give it a chance to create a host and add it to the host table.
(This is NOT recommended; it is provided for internal system use.)
@end(defun)

@defvar si:host-alist
An association list, indexed by primary host name, containing the host object
and other relevant information (most of which can be obtained from the host
object itself).
@end(defvar)

To obtain the host object for any kind of pathname (including device pathnames),
use @l(fs:get-pathname-host).

@defun fs:get-pathname-host host-name &optional (no-error-p nil) (unknown-ok nil)
Parse a host for use in a pathname.
HOST-NAME can be a host object or a host name.
If NO-ERROR-P is non-NIL, we return NIL if given an undefined host name.
@end(defun)

@defvar fs:*pathname-host-list*
The list of established pathname host objects.
@end(defvar)

This distinction between pathname hosts and network host objects involves
an extension to the pathname system to support device pathnames.
It is possible to create pathnames with device- or application-oriented host objects
such as Unix streams and editor buffers.
For example:

@lisp
(pathname "ed:foo.lisp")       ;ZMacs editor buffer
(pathname "unix-stream-1:")    ;Unix stream
(pathname "sdu-serial-b:")     ;Serial port B
@end(lisp)

@subsection Host Object Operations

Here is a brief summary of the standard flavor operations
accepted by most host types
which return information that is useful to developers.

The following methods all operate on host objects:

@table 3
@item :NAME 
Returns the official name.
@c end (defmetamethod)

@item :SHORT-NAME
Returns the shortest host name.
@c end (defmetamethod)

@item :STRING-FOR-PRINTING
Generally the same as the official name, but this
method may be modified to perform special transformations.
@c end (defmetamethod)

@item :HOST-NAMES
Returns the entire list of names specified to @l(si:define-host).
@c end (defmetamethod)
@end(table)

The following methods return the respective host attribute
as specified to @l(si:define-host):

@table 3
@item   :SYSTEM-TYPE
@c end (defmetamethod)
@item :FILE-SYSTEM-TYPE
@c end (defmetamethod)
@item :MACHINE-TYPE
@c end (defmetamethod)

@c defmetamethod :PRIMARY-DEVICE
Returns the default device for the host, as specified by the
:HOST-DEFAULT-DEVICE-ALIST site option.
@c :DEFAULT-DEVICE ??? doesn't work???
@c end (defmetamethod)
@end(table)

The following methods return forms of the assigned network addresses:

@table 3
@item   :NETWORK-ADDRESSES
Return the list of defined network addresses;
this is a property-list with alternating pairs of network keywords and address(es).
@c end (defmetamethod)

@item :NETWORK-ADDRESS @i(<network>)
Returns the address for the specified NETWORK keyword.
@c end (defmetamethod)

@item   :CHAOS-ADDRESS
Returns the primary Chaos address for this host.
@c end (defmetamethod)

@item  :CHAOS-ADDRESSES
Returns the list of Chaos address(es) for this host.
@c end (defmetamethod)

@item   :INTERNET-ADDRESS
Return the primary Internet address for this host.
@c end (defmetamethod)

@item :INTERNET-ADDRESSES
Returns the list of assigned Internet addresses for this host.
@c end (defmetamethod)

@item   :NETWORK-TYPE
Returns the first network keyword of the host's network-addresses.
@c end (defmetamethod)

@item :NETWORK-TYPEP @i(<network>)
A predicate for determining whether the host has an address for the specified network.
@c end (defmetamethod)

@item :UNPARSED-NETWORK-ADDRESS @i(<network>)
Returns the unparsed primary network addresses for the specified network.
@c end (defmetamethod)

@item :UNPARSED-NETWORK-ADDRESSES @i(<network>)
Returns the list of unparsed network addresses for the specified network.
@c end (defmetamethod)

@item :CLOSE-ALL-FILES
Close all open file streams connected to the host.
@c end (defmetamethod)

@item :OPEN-STREAMS
Returns the list of open streams connected to the host.
@c end (defmetamethod)

@item :SAMPLE-PATHNAME
Returns a sample pathname object that applies to this host;
the components are not filled in, except for the host itself.
@c end (defmetamethod)
@end(table)

@section Obtaining Host Addresses

The following functions are useful for working with directly with host addresses.

@defun ip:parse-internet-address address
Return numeric Internet address, converting
from dotted decimal if necessary.
@end(defun)

@defun net:parse-address address network-type &optional (start '0) end

Given a string, return the parsed address for NETWORK-TYPE, a keyword
(e.g., :CHAOS or :INTERNET).
@end(defun)

@defun net:unparse-address address network-type

Given a parsed network ADDRESS and the keyword NETWORK-TYPE (e.g., :CHAOS or :INTERNET),
return the unparsed form.
This is useful, for example, when printing an address obtained from a host object.

Chaos addresses are translated into a string representation of the octal number.

Internet addresses are translated into the appropriate dotted-decimal string.

@end(defun)

@section Local Host Variables
@label[section-local-host-variables]

Several variables are defined to hold information related to tho local host.

@defvar si:local-host
The host object for this machine (the one that is running).
@end(defvar)

@defvar si:local-host-name
The full name of this Lisp machine as a host.
@end(defvar)

@defvar si:local-pretty-host-name
A pretty form of the name of this Lisp machine.
@end(defvar)

@defvar si:local-finger-location
A string saying where this Lisp machine is located.
Locations are stored in the file SYS: SITE; LMLOCS LISP.
@end(defvar)

@defvar si:local-floor-location
Ostensibly, a list of building-name and floor number
where this machine is located.
Actually, whatever location information is provided in LMLOCS.
@end(defvar)

@defvar si:associated-machine
Default machine to log in on from this Lisp machine
(a host object).
The associated machine is assigned for each host in LMLOCS.
@end(defvar)

@section Communications Streams

Communications streams provide a way to write programs that 
make ``direct contact'' with a specific network protocol or server.
Before attempting to write programs that use communications streams,
be sure to read the material on streams in @i(CommonLISP: The Language), and the @LMM@ .

Remember that file streams can be opened in the normal way (as described in the @LMM@ )
over the network, simply by using a remote host's pathname as part of the @l(OPEN) form you use.
The material in this section describes the use of streams at a lower level.

A typical application of these techniques is the development of a custom
server program, or development of a user program that needs to interface with a working
custom server on a remote host type.

@c subsection Chaosnet Streams

@c subsection TCP Streams















@c end programs