From: labenrsa@ICIL64.CILEA.IT
Subject: amiga netwrk stdrd api
Organization: CILEA - v R. Sanzio 4 - Segrate - ITALY
Date: Wed, 18 Nov 1992 11:21:17 GMT
Reply-To: labenrsa@ICIL64.CILEA.IT



Amiga networking software is starting to bloom. Sadly, there seems to be
very little concern about the _integration_ of networking software in
the Amiga OS environment. So far, SANA has only addressed API standardization
at the data link layer (or whatever they call it in SANA), and even that
specification is not being followed by most networking software.

To provide both user and application programmer with a consistent
networking environment, we need more than just raw ports of lots of net
stacks.

Let me picture what I mean by getting a bit more technical.


Case 1 : Network-Aware Applications and APIs
============================================

Network-aware applications use some network API directly. Two well-known
examples are internet clients that use the BSD/SunOS sockets API with
TCP/IP protocols and Novell NetWare clients.

In all cases where existing network stacks have been ported to the Amiga
(e.g. see the socket.library), their APIs have been reproduced, with the
goal to minimize the effort of porting existing software from other OSs.

Like it or not, all existing network APIs are designed to work well with the
OS they were born in. Porting them over to another system often results in
poor integration with the new environment, incompatibilities with the original
implementation and resorting to gory hacks to get things working.

For example, BSD sockets fit in very well in BSD/SunOS systems or lookalikes
*because they're designed as part of that system*. They simply clash with
the Amiga programming model (signal/message IO vs. file descr. IO + fork()).
When implementing socket applications on the Amiga, you may have to change
quite a lot here and there. In the end, it's still some work and you'll end
up with some pretty nasty code (compared to 'good' Amiga code).

Seriously, the only applications that really benefit from an
'as-close-to-bsd-as-possible' approach are the standard internet servers and
their related console-oriented clients, which altogether stink when compared
to standard Amiga applications. Any serious Amiga TCP/IP package will want
to have them reworked from the ground up.

So, why not go for an All-Amiga networking API?

Please note that changing the API has nothing to do with the protocol you
are using. You should be able to use TCP/IP, or any other transport, from
a standard (well designed) Amiga network API.

Also note that it wouldn't be TOO hard to recode a socket (or other API)
application for a standard Amiga API. In fact the Amiga API would more or
less provide the same sort of services (connect/disconnect/accept/send/receive)
only through a *cleaner* interface.

Imagine an implementation layered like this:

          ------------------------------------------
          |                Applications            |
          ------------------------------------------

-----------             -------------------
DOS, Exec,|. ...........| network.library |                Standard API
-----------             -------------------
               -----------   ----------   ----------
               | Internet|   | Decnet |   | Novell |       Protocol stacks
               -----------   ----------   ----------

             -----------   ----------   ---------------- 
             | Ethernet|   |  SLIP  |   | Exec MsgPort |  SANA-2 dev drivers
             -----------   ----------   ----------------

Expected benefits :

1 - All applications that go through the network.library would be able
    to operate over any protocol stack.

2 - Let users configure their networking setup easily and even
    *choose* what transport to use for some services.

3 - Multiple protocol stacks would be able to operate on the same
    interface (already a goal of SANA).

4 - Maximize robustness and efficiency of Amiga-specific software in
    a networking environment.


Expected problems:

1 - Flame wars concerning the API calls (aw, come on... ;> )

2 - How do we provide a clean interface to protocol-specific services
    and options? (For options, taglists may work.)

3 - Efficiency: net sw is heavy, and having one more implementation layer
    isn't going to help.


Now let me picture how a sample Amiga network application should work. This
is NOT an API design (yet), but should clarify what I have in mind. No
flames, please. Comments are welcome.


/*
 * Sample Amiga networking application. -- connectionless client.
 *
 * use HYPOTHETICAL (how do you spell it?) network.library
 * PSEUDO-C PSEUDO CODE : all checks removed
 */

#include <sana.h>
#include <libraries/network.h>

void main (int argc, char *argv[])
{ 
    NetProtocolSpec   default_prot = {"netbios", 0,0}; /*...or whatever */
    NetProtocolSpec   *pr_list, *pr_chosen;

    NetProtocol       *pr;

    NetObject         *nobj;
    NetAddress        *target_addr;

    TEXT              target_name = argv[1];
    TEXT              message     = argv[2];


    NetBase = OpenLibrary ("network.library", 0);


    /* open user interface, etc.... */


    if (prompt_user_for_transport)
    {
        pr_list = LockProtocolList();

        pr_chosen = request_protocol (mywindow, "Choose Transport", pr_list);

        pr = OpenProtocol (pr_chosen);

        UnlockProtocolList (pr_list);
    }

    else
    {
        pr = OpenProtocol (&default_prot);
    }


    /* open a communication endpoint (equivalent to a socket) */
    nobj = NewNetObject (pr, NTAG_OBJ_FLAGS,      my_netobj_flags,
                             NTAG_PROTOCOL_FLAGS, my_protocol_flags,
                             .......................................
                             TAG_DONE ); 

    /* find out whom we wanna talk to */
    target_addr = NetResolve (pr, target, NTAG_RESOLVE_OPTS, ...., TAG_DONE);


    /* post message to target */
    NetSend (nobj, target_addr, message, strlen(message) );

    /* handle post and user interface Amiga-style */
    net_sigmask = NetObjectSignal (nobj);

    mask = window_sigmask | timer_sigmask | 

    for (;;)
    {
        sig_received = Wait (mask);
    
        if (sig_received & net_sigmask)
            size_read = NetRead (nobj, reply_buf, bufsize);
        
        else if (sig_received & timer_sigmask)
            break;

        /* etc... */
    }

    /* make sure we don't have any pending net I/O */
    NetWaitIO (nobj);

    /* clean up */
    DisposeNetObject (nobj);
    CloseProtocol (pr);

    CloseLibrary (NetBase);
}

A connection-oriented application would need different calls, and so would
the clients. It is pointless to try to sketch them here. Basically, get
the flavor of this sample and apply it to the different communication models.

The main points I want to get through are : 
  1) I want to access multiple protocol stacks through the same API
  2) I want the API to be *designed for the Amiga OS*, specifically
     supporting synchronous and asynchronous I/O, signals & c....

ISSUES :

The example above is a complete mess, since it mixes several
Amiga programming approaches. Several options are indeed available :

- Should the  network.library actually be complemented by a network.device
  so that we can do I/O via Exec calls : SendIO/DoIO, etc.... ?
  (this is the sort of approach used by VMS/DECNET at the nontransparent
   level. I may be wrong but maybe DNET does something like this...)

- Should the network.library actually have a network.handler, so that
  we can do straight AmigaDOS I/O (both packet and file-oriented) ?
  This option somewhat overlays the case of 'transparent' network
  communication, discussed below.

- Make it just a no-fuss library which resembles either but is none of
  them (as I sort-of did in the example)?



Case 2 : Network-Transparent Applications
==========================================

Another big issue is the need to have standard AmigaDOS applications
operate over a network transparently, without calling a networking API.

It seems that the current approach taken by most Amiga networking software
works like "mount the remote file/device, then use it as if it were a
local filesystem". This scheme, notably used by NFS and most MS-DOS
networks, is fine for many applications, but not for all.

If the network gets very large and a lot of services are available which
you will not use on a regular basis, you definitely do _not_ want to
have them all mounted at all times, or to have to mount and dismount them
explicitely on occasion.

For instance, suppose you have a large LAN, where a single server hosts
most of the application software. You install a new release on the server
and that's fine. But then you have to install a license or just a 100 byte
preference file in _every client_ node. Would you want to mount them all
on the server, or walk to every machine with a disk, or just sit at the
server and type something like:

   -- scheme 1

   COPY mydatabase.prefs vulcan"sysadm password"::sys:preferences
   COPY mydatabase.prefs juno"sysadm password"::sys:preferences
   .... etc ....

Many other examples could be provided where a remote mount is unsuitable.
(I know *you* would use rcp or ftp, but, once again, let me point out
 I'm talking about NATIVE, non-network aware AmigaDOS sw...).

What I'm suggesting is that there should be a _standard_ syntax to reference
remote file systems in a normal AmigaDOS path _without_ needing to mount
them.

This access method _does not replace_ remote mounts, but rather _complements_
them where they are not suitable.

Scheme 1 shows just one the many possible extended pathname syntaxes. This
one is patterned after DECNET usage, and is probably very poorly chosen.
If a pathname syntax extension is used, the AmigaDOS library should have
the DeviceProc() (and maybe others) call patched to detect a remote
filesystem specification in the path name and go through a special
dos handler.

Naturally, it would be best if we could maintain the current AmigaDOS
syntax and use something like this:

   -- scheme 2
   COPY mydatabase.prefs "NET_DEV:node/volume/path/account=xxx/passwd=yyy"

ISSUES:

 -  Can scheme 2 be made to work with all transport protocols and
    remote operating systems (which may be unix/vms/dos/....) file
    specification?

 -  In case we must resort to a pathname syntax extension, which syntax
    is less likely to break pathname parsers in existing software?


                              ---- o ----


                         Tnx for your attention

---------------
Andy Zanna                           e-mail:   SDEVAX::ZANNA@icil64.cilea.it