NIPC LIBRARY



NIPC is a new library designed to provide a high level 
interface to networking hardware.  By using NIPC, programmers 
will not have to deal with all of the issues involved in 
networked communications such as sequencing, reliability, etc.  
NIPC has also been designed to be both easy to use and yet very 
powerful.

The NIPC API was designed in such a way that it would seem 
familiar to Amiga programmers that are familiar with Exec 
Messages and Device I/O.  Many NIPC function calls such as 
GetTransaction(), DoTransaction() and ReplyTransaction strongly 
resemble function calls already present in the Amiga OS.

At the lowest level, NIPC uses standard SANA-II device 
drivers so that it is capable of running on virtually any 
networking hardware, including Arcnet, Ethernet and even serial 
ports via SLIP.



NIPC CONCEPTS



NIPC shares many of the same concepts with Exec messages and 
device I/O.  One such concept is the idea that appications 
communicate with other applications or devices by sending and 
receiving finite pieces of data, usually in the form of an Exec 
Message. NIPC also shares the concept of a communications 
endpoint similar to the Exec Message Port. 

In NIPC, the communications endpoint is known as an Entity.  
Entities are used as both the source and destinations of data 
being sent between two applications.  The data being sent between 
applications is known in NIPC as a Transaction.

Shown below in beautiful ASCII artwork are two diagrams that 
illustrate how Messages and Ports relate to Transactions and 
Entities.



Application<-->MsgPort<----Message----->MsgPort<-->Application



Application<-->Entity<---Transactions--->Entity<-->Application

   

Unfortunately, it gets more complicated than the above 
diagram can show.  Unlike Exec Messages, NIPC Transactions are 
not guaranteed to arrive at a destination Entity in a preset 
amount of time.  In fact, it is possible that a Transaction will 
never make it to it's destination due to machine and/or network 
failures.  NIPC does make a good effort at delivering 
transactions, however.  The lower level protocols used in NIPC 
help to provide this functionality.

Another difference between NIPC communications and Exec 
Messages is that NIPC is designed around a client-server model.  
In many cases the two applications communicating will be a client 
and a server, such as the case with a print spooler or a network 
filesystem.  Because of this, clients have more control over the 
transactions than the servers do.  This will become apparent 
later on.



USING NIPC



Before communication via NIPC can begin, each application 
that will be involved must create an Entity.  This is done by 
calling CreateEntity().  Once an application has created it's own 
entity, it must find the other application's entity.  Typically, 
the entity to be found is a public Entity created by a server. 

To find an Entity created by another program, you call 
FindEntity().  FindEntity() has parameters that allow you to 
specify the name of the Entity, the name of the host that you are 
trying to find the Entity on, and the Entity that you will be 
using for the source of your Transactions.

The reason that FindEntity() also requires a pointer to your 
program's Entity is that NIPC communication is connection 
oriented.  This means that a connection forms between your Entity 
and the Entity you found.   This connection will continue to 
exist until you no longer need it or until a permanent network 
failure or machine failure occurs.  When you are done 
communicating with the other Entity, you call LoseEntity().  The 
concept of a connection does not exist with Exec Messages.  This 
is why you must use a Forbid()/Permit() pair when communicating 
with public message ports to guarantee that the port does not go 
away in between the time you call FindPort() and PutMsg().

Once you have created your entity and found the remote 
entity, you must allocate a Transaction structure.  The only 
supported way of doing this is to call the NIPC function 
AllocTransaction().

AllocTransaction() allows you to optionally specify buffer 
sizes for any data being sent and/or any data that may be 
received that the Transaction is complete.  You may also allocate 
your own buffers, but you are responsible for freeing them 
yourself.

A Transaction is sent on it's way by calling either 
BeginTransaction() or DoTransaction().  BeginTransaction() will 
return immediately unless you are trying to send more data than 
the network protocols are capable of handling at the moment.  
Once your Transaction has begun, BeginTransaction() will return.  
It should be noted that the amount of time that 
BeginTransaction() will block will usually be quite small.  
Therefore, BeginTransaction() should be considered an 
asynchronous call.

DoTransaction() will block until either the Transaction has 
completed or an error occured.  Because your program will not be 
able to anything until DoTransaction() returns, it is strongly 
suggested that you try to avoid it, or spawn a separate task or 
process to call DoTransaction().

When the Transaction returns, you should examine it to 
determine how much, if any, data was returned and whether or not 
an error condition occured.

Programs acting as servers usually do not call 
AllocTransaction(), BeginTransaction() or DoTransaction().  
Typically, a server will wait for a Transaction to arrive at it's 
public Enitity.  This may be done by using either WaitEntity() or 
by using the Exec Wait() function.  To see if a Transaction is 
available at your Entity, you should call GetTransaction() which 
will eithe return a pointer to a Transaction or NULL if there are 
not more transactions to be processd.

For each transaction you receive, you should examine it to 
determine what you should do with the data in it, or if you need 
to return some data to a client.  Once you have finished 
processing the transaction, you must return it to it's sender by 
calling ReplyTransaction().

For an example NIPC client and server, please see the two 
files named RemoteRequest.c and RequestServer.c.  These two 
programs allow you to put up a requester on a remote machine 
running NIPC.



ADVANCED NIPC USAGE





