home *** CD-ROM | disk | FTP | other *** search
/ AMOS PD CD / amospdcd.iso / dnet / dnetlib.doc < prev    next >
Text File  |  1994-02-11  |  5KB  |  150 lines
  1.  
  2.                DNET LINK LIBRARY
  3.  
  4.     Link with your server's and client programs.
  5.  
  6.  
  7.     listenport    = DListen(port#)                listen for connections
  8.     chanport    = DAccept(listenport)           accept a new connection
  9.           DNAAccept(listenport)         or refuse a new connection
  10.     chanport    = DOpen(host, port#, txpri, rxpri) open a new channel
  11.           DPri(chanport, priority)      (not implemented yet)
  12.         act = DNRead(chanport, buf, bytes)  (see below)
  13.         act = DRead(chanport, buf, bytes)   (see below)
  14.         act = DWrite(chanport, buf, bytes)  act = -1 or bytes
  15.           DEof(chanport)                send eof (amiga<>amiga only)
  16.           DQueue(chanport, maxq)        set asynchronous queue write
  17.                         queue size (default 0)
  18.           DClose(chanport)              close a channel
  19.           DUnListen(listenport)         stop listening on a channel
  20.  
  21.           DQuit(host)                   cause remote end to quit out
  22.                         of the DNET protocol.
  23.  
  24. General notes:
  25.     The calls have a notion of ownership.  The task which created
  26.     the listen port or openned the channel owns it.  Foreign tasks
  27.     may DAccept() connections on somebody elses listen port (i.e.
  28.     your server creates a task to handle the accept).  In fact, this
  29.     is the only way you can spawn off tasks to handle new connections
  30.     as only the owner of a channel (caller of DAccept()/DOpen()) may
  31.     use the channel.
  32.  
  33.     The calls are not extremely efficient at the momement, but since
  34.     the network, by virtue of being on a serial line, is so slow,
  35.     it doesn't really matter.
  36.  
  37.     You are guarenteed a signal will be present whenever there is
  38.     pending data, even if you only partially read what is available.
  39.     NOTE that you *will* get signals sometimes even when no data is
  40.     available, and should thus take into account DNRead() returning
  41.     0...  Usually DNRead() is used in conjuction with Wait()ing on
  42.     the signal bit of the channel port.
  43.  
  44.     DEOF()
  45.  
  46.     Eof a channel.    Implemented ONLY for the Amiga.  You cannot EOF
  47.     a channel if running between the Amiga and a UNIX machine.   This
  48.     is essentially an unsupported call, and you should use DCLose()
  49.     to close(and send an eof) on a channel.  The network handles it
  50.     just fine, but the UNIX side has no way of sending an EOF over
  51.     a socket without closing the socket.
  52.  
  53.     DLISTEN()
  54.  
  55.     This call listens on a virtual port # (0-65535) for connections
  56.     from a remote host.  NULL is returned if the port is already
  57.     being listened on by somebody else.
  58.  
  59.     DACCEPT()
  60.  
  61.     Accepts connections over a virtual port #.  Several connections
  62.     may be accepted and worked on simultaniously.  NULL is returned if
  63.     there are no pending connections.  You can WaitPort() on the
  64.     listenport to wait for new connections, but should note that
  65.     even after a WaitPort(), DAccept() might return NULL every
  66.     once in a while.
  67.  
  68.     DAccept() will set the signal bit associated with the port if
  69.     further connections are pending.
  70.  
  71.     DNAACCEPT()
  72.  
  73.     Don't accept connections over a virtual port #.  If there is a
  74.     connection pending, it will return an error on the other end.
  75.     Returns 1 if a connection was refused, 0 if there were no
  76.     pending connections.
  77.  
  78.     DUNLISTEN()
  79.  
  80.     Stop listening on a virtual port #.  Any pending requests are
  81.     automatically DNAAccept()ed.
  82.  
  83.     DPRI()
  84.  
  85.     Set the priority of a channel (-128 lowest to 127 highest).
  86.     The priority only effects throughput when two or more channels
  87.     at different priorities are transfering data at the same time.
  88.  
  89.     Not currently implemented.. priority is what you set in DOpen()
  90.  
  91.     DNREAD()
  92.  
  93.     Read data from a channel.  0 is a valid return value, meaning that
  94.     no data is currently ready to read.  You can WaitPort() on the
  95.     channel port to wait for data (or EOF).  A negative value is
  96.     returned on EOF or failure.
  97.  
  98.     error codes:
  99.             -1    EOF on channel
  100.             -2    Remote end CLOSED the channel (not implemented)
  101.  
  102.     DREAD()
  103.  
  104.     Read data from a channel.  The number of bytes requested are
  105.     returned, unless the other end closed it's side in which case
  106.     fewer than the number of bytes requested will be returned.  That
  107.     is, this call will BLOCK waiting for data.
  108.  
  109.     A negative value is returned on EOF or failure.
  110.  
  111.  
  112.     DWRITE()
  113.  
  114.     Write data to a channel.  The return value is either the # bytes
  115.     written, or a negative error code.
  116.  
  117.             -1    Remote end REOF'd the channel
  118.             -2    Remote end CLOSED the channel
  119.  
  120.             note: not much distinction between the two
  121.             currently.
  122.  
  123.     DCLOSE()
  124.  
  125.     Close a channel.
  126.  
  127.     DOPEN()
  128.  
  129.     Application side OPEN().... Open a port# on a remote host.  Returns
  130.     a channel port or NULL.  Two priorities are given.  Each may be
  131.     in the range (lowest) -127 to 126 (highest) inclusive.  The first
  132.     priority is for transmitting data client->server, the second
  133.     for receiving data server->client.
  134.  
  135.     The host field should be NULL for now.    In future versions, you
  136.     will be able to run multiple DNET's on your Amiga and this will
  137.     field will determine which one you are attempting to connect
  138.     through.
  139.  
  140.     DQUIT()
  141.  
  142.     Causes DNET on the remote side to quit out.  If running on a
  143.     4.2BSD UNIX machine, the DNET will exit.  If running on another
  144.     Amiga, the DNET will return to terminal-window mode.
  145.  
  146.     The host has the same definition as for DOpen().
  147.  
  148.  
  149.  
  150.