home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Netzwerk / PRONET30.LHA / ProNET / Developer / autodoc / pronet.doc
Encoding:
Text File  |  1996-08-09  |  6.2 KB  |  193 lines
  1. TABLE OF CONTENTS
  2.  
  3. pronet.device/--Overview--
  4. pronet.device/OpenDevice
  5. pronet.device/CMD_WRITE
  6. pronet.device/ReceivedData
  7. pronet.device/GetConfigString
  8. pronet.device/FreeConfigString
  9.  
  10. pronet.device/--Overview--                         pronet.device/--Overview--
  11.  
  12. This  AutoDoc  is  a  slightly  extended  version  of  V1  to  include  the
  13. differences in ProNET V2.
  14.  
  15. ProNET.device  is able to connect machines for transfering data between
  16. them.   For  the  transfer,  you must select a so-called PORT number, which
  17. must  be  specified  at  device  opening time, and when sending data to the
  18. corresponding port at the other machine, only the application that has this
  19. number will receive the data.  If the destination port doesn't exist on the
  20. other  Amiga,  the  data  will be buffered and will be sent at once when an
  21. application opens this port.
  22.  
  23. What  is  new  in V1, you must supply a Unit number, which corresponds to a
  24. certain hardware interface.
  25.  
  26.   This  device  differs  from  most  other devices in so far as the command
  27. CMD_READ  is  not recognized at all.  Instead, every chunk of data arriving
  28. at  your  port  will be sent to a MessagePort you also specified at opening
  29. time,  no  matter if you want it or not.  This message must be ReplyMsg()ed
  30. after evaluating the data.
  31.  
  32.   Future versions of the device (ProNET V4??) will work with the ordinary
  33. CMD_READ.
  34.  
  35.   The  configuration of the device and applications using it is done by the
  36. file DEVS:ProNET.config.  It is built as follows:
  37.     title data    or
  38.     ; Comment
  39. 'title'  is  a string ending with a colon (':'), and 'data' may be
  40. any string which can be got using the #?ConfigString-Functions.
  41.  
  42. Please  note  that the other side can reset at any time and restart sending
  43. packets.   So  prepare  your  applications  for  it  if  required  --  e.g.
  44. installing a Keyboard ResetHandler or similar notification algorithms.
  45.  
  46. pronet.device/OpenDevice                             pronet.device/OpenDevice
  47.  
  48.     NAME
  49.     OpenDevice -- a request to open a ProNET port
  50.  
  51.     SYNOPSIS
  52.     error = OpenDevice("pronet.device", unit, PNRequest, flags )
  53.     d0            a0               d0    a1         d1
  54.  
  55.     FUNCTION
  56.     Some components of the PNRequest structure must be filled in before
  57.     calling OpenDevice:
  58.  
  59.     pnr_MsgPort        Pointer to a Message Port where incoming
  60.                 data is sent to.
  61.  
  62.     pnr_NetSourcePort    Put your port number here. 0 is reserved
  63.                 for the pronet-handler/-server stuff.
  64.  
  65.     These two values MUST remain until closing the device.
  66.     
  67.     -1  in  pnr_NetSourcePort  has  a special meaning:  The port number
  68.     will  be  taken  from  the ProNET.config file.  pnr_Data1 must then
  69.     point  to  the title string introducing the line.  The first number
  70.     in  the  data  string will then be used as the port number.  If the
  71.     configuration    file   is   incomplete,  the  device  will  return
  72.     PNDERR_BADCONFIG! The title string must include the `:'!
  73.     -1 is also defined as PNP_NAME.
  74.  
  75.     -2  in  pnr_NetSourcePort  also has a  special meaning:  The device
  76.     takes the next free portnumber.
  77.     The new portnumber will then be put in pnr_NetSourcePort.
  78.     -2 is also defined as PNP_NEXTFREE.
  79.  
  80.     INPUTS
  81.     "pronet.device" a pointer to the name of the device to be opened.
  82.             May be another device as well as long as it emulates
  83.             the original !!
  84.     unit         An unsigned long number which will be associated
  85.             with a certain `pronet.config' line.
  86.     PNRequest    a pointer to a PNRequest block
  87.     flags        unused and should be set to 0 !!
  88.  
  89.     RESULTS
  90.     error        0 --> opening OK.
  91.             PNDERR_BADCONFIG - see descr. of pnr_NetSourcePort
  92.             PNDERR_PORTEXISTS - port number is already allocated
  93.             PNDERR_DRIVERTROUBLE - specified driver couldn't open
  94.  
  95. pronet.device/CMD_WRITE                               pronet.device/CMD_WRITE
  96.  
  97.     NAME
  98.     CMD_WRITE -- send data to the other Amiga
  99.     (also PND_WRITE)
  100.  
  101.     FUNCTION
  102.     Sends the data specified in the PNRequest structure as soon as
  103.     possible to other machine.
  104.     The data consists of the second chunk appended to the first one.
  105.     Both chunks added must NOT be longer than $4000 / 16K bytes !!
  106.  
  107.     If the destination port doesn't exist on the remote machine, it
  108.     will be buffered there until the port is opened. The data will
  109.     be then sent in the order it was sent off.
  110.  
  111.     IO REQUEST
  112.     io_Command    CMD_WRITE / PND_WRITE
  113.     pnr_NetDestPort    Destination port number
  114.     pnr_Data1    Pointer to first chunk
  115.     pnr_Length1    Length of first chunk
  116.     pnr_Data2    Pointer to second chunk
  117.     pnr_Length2    Length of second chunk
  118.  
  119.     If you just want to transfer one chunk, set pnr_Length2 to zero.
  120.  
  121.     RESULTS
  122.     io_Error    always zero.
  123.  
  124.     BUGS
  125.     Until now, the machine is freezed while sending. (Bug?)
  126.  
  127.     NOTE
  128.     I-M-P-O-R-T-A-N-T:
  129.     Maximum length is 16K !!
  130.  
  131.     Both lengths are rounded up to word boundaries.
  132.  
  133.     Besides that, the contents of the PNRequest will not be changed !
  134.  
  135.     SEE ALSO
  136.  
  137. pronet.device/ReceivedData                         pronet.device/ReceivedData
  138.  
  139. Received  Data  will  be  sent  to  the Message Port you specified when you
  140. opened 'pronet.device'.  The data part starts behind the Message structure.
  141. It first contains the source port as one word, then the real data. Besides
  142. that, MN_LENGTH contains the length of the data including the source port
  143. word, and the first word of the LN_NAME pointer contains the destination
  144. port number (which shouldn't be of any use at all..)
  145.  
  146. After evaluation of the message, it should be replied.
  147.  
  148. pronet.device/GetConfigString                   pronet.device/GetConfigString
  149.  
  150.    NAME
  151.     GetConfigString -- get string out of DEVS:ProNET.config
  152.  
  153.    SYNOPSIS
  154.     configstr = GetConfigString(titlestring);
  155.     D0                           A0
  156.  
  157.     APTR GetConfigString(char *);
  158.  
  159.    FUNCTION
  160.     Returns the data string corresponding to the title string.
  161.     Must be released by FreeConfigString().
  162.  
  163.    INPUTS
  164.     titlestring    Pointer to null-terminated string. Usually ending
  165.             with a colon (':').
  166.  
  167.    RESULT
  168.     configstr    Pointer to null-terminated string or NULL.
  169.  
  170.    SEE ALSO
  171.     FreeConfigString()
  172.  
  173. pronet.device/FreeConfigString                 pronet.device/FreeConfigString
  174.  
  175.    NAME
  176.     FreeConfigString -- free string got by GetConfigString()
  177.  
  178.    SYNOPSIS
  179.     FreeConfigString(configstring);
  180.               A0
  181.  
  182.     FreeConfigString(char *);
  183.  
  184.    FUNCTION
  185.     Frees memory used by the string got by GetConfigString().
  186.  
  187.    INPUTS
  188.     configstring    Pointer to string got by GetConfigString().
  189.  
  190.    SEE ALSO
  191.     GetConfigString()
  192.  
  193.