
                             nipc.library Overview


Definition

The nipc.library provides reliable, transaction-oriented networking abilities
to an Amiga, with a familiar API.

Concepts

To fully understand the library, a knowledge of a few essential NIPC concepts
is required:

Entity: A communications endpoint.  A single Entity can be part of a number of
different communications paths - meaning that one Entity may be communicating
with many other Entities at the same time.  While it's useful for the purposes
of descriptions to illustrate a pair of Entities communicating, it's important
to understand that this isn't a limitation.  An Entity is identified by both
it's name, and the name of the machine on which it exists.

Communications Path: An imaginary line drawn between two Entities defining a
line of data transfer.

Transaction: The process used to transfer data in NIPC.  A Transaction is made
up of two distinct phases - the time in which a Transaction is a request and
the time in which it is a response.  A Transaction always takes place on a
communications path between two Entities.  See Figure A. as a reference.


                                    Request
            +-------------+  ------------------->  +-------------+
            |             |                        |             |
            |  Entity A   |                        |  Entity B   |
            |             |                        |             |
            +-------------+  <-------------------  +-------------+
               (source)             Response            (dest)

                                Figure A.
                The flow of a Transaction between Entities.


Request: The first phase of a Transaction, where a source Entity (Entity A,
above) sends a request packet to a destination Entity (Entity B, above).  A
Request can be identified by a single-byte command and a variable length data
section.

Response: The second phase of a Transaction, where a destination Entity
processes a request packet, provides an Error code, and (if required) provides
a variable length data section.


Operation

The nipc.library provides operations for communicating between Entities,
regardless of whether the communications path involves transferring data
from one machine to another, or merely transferring data between two Entities
on a single machine.  The operations as seen by the application program are
identical, though the library obviously processes the data in different ways.

Figure B. shows the modelling of how a Transaction appears when operated
through a networked device.


                                   Network
                                     \ \
            +-------------+  ------->/ /-------->  +-------------+
            |             |          \ \           |             |
            |  Entity A   |          / /           |  Entity B   |
            |             |          \ \           |             |
            +-------------+  <-------/ /<--------  +-------------+
                                     \ \

                                  Figure B.
                         A Transaction's conceptual
                            flow over a network.

When refer encing the diagram above, keep in mind that this is only a
model -- the transfer of data only appears to work in this way.  Knowledge
of this model is all that is necessary for using the library.  While this
model is straightfoward and simple enough to expect developers to understand
 thoroughly, it's too simplistic to use for the actual library
implementation - which presents a more complex situation.  However, the
model serves an important role by insulating the developer from the
complexities of networking.  In our implementation, for each communications
path in use there exists something called a Link Entity.  It is between
these Link Entities that networked communications actually occur.  Each
Entity may have several Link Entities -- one for the local side of each
communications path.  This scheme is shown in Figure C.  This scheme lends
itself quite well to NIPC.  Each Link Entity might be considered a local
extension of the Entity on the other side of the communications path.
For instance, the leftmost Link (shorthand for "Link Entity") in Figure C.
might be considered the local extension of Entity B.  Thus, for library
function calls, when a program attempts to reference a remote Entity (one
on another machine), it actually references the Link that symbolizes the
remote Entity.  The networking portion of nipc.library fills in the rest.

                                   Network
                               +----+\ \+----+
            +-------------+  ->|    |/ /|    |-->  +-------------+
            |             |    |    |\ \|    |     |             |
            |  Entity A   |    |LINK|/ /|LINK|     |  Entity B   |
            |             |    |    |\ \|    |     |             |
            +-------------+  <-|    |/ /|    |<--  +-------------+
                               +----+\ \+----+

                                  Figure C.
                           A Transaction's actual
                            flow over a network.

For a local transaction (where the source and destination Entities are on
the same machine), there's very little overhead; the Transaction structure
is simply passed to the destination Entity.

