home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / rxtelnet.zip / nvt / readme < prev    next >
Text File  |  1997-09-01  |  5KB  |  167 lines
  1. A Rexx Telnet API
  2. by Ben Ravago <bjr@hq.sequel.net>
  3.  
  4.  
  5.  
  6. DESCRIPTION
  7. """""""""""
  8.  
  9. This package provides a simple Network Virtual Terminal (NVT)
  10. as defined by the "Telnet Protocol Specification (RFC 854)".
  11. It provides both C and Rexx callable functions in a .dll.
  12.  
  13.  
  14.  
  15. CONTENTS
  16. """"""""
  17.  
  18. 1. README    - this file
  19. 2. NVT         - makefile
  20. 3. NVT.C     - contains Network Virtual Terminal functions
  21. 4. NVT.H     - NVT functions
  22. 5. RNVT.C    - contains Rexx interface to NVT functions
  23. 6. TNVT.C    - example telnet client showing use of nvt..() functions
  24. 7. XNVT.CMD  - example telnet client showing use of rexx telnet api
  25. 8. ASCII.H   - some ASCII definitions
  26. 9. TELNET.H  - TELNET definitions; copied from BSD system
  27.  
  28.  
  29.  
  30.  
  31. C API
  32. """""
  33.  
  34. The C api provides basic functions for accessing a telnet 'stream'.
  35. It is patterned from the standard C fopen/fclose/fgets/fputs functions.
  36.  
  37.  
  38. 1. HNVT nvtopen( char *hostname, int port );
  39.  
  40.        nvtopen() starts a telnet session.  'hostname' specifies
  41.        the name, alias, or internet address of a remote host.
  42.        'port' can be 0, in which case the default telnet port is used.
  43.  
  44.        nvtopen() returns a handle to the telnet session if successful,
  45.        otherwise it returns a -1.  Multiple telnet sessions can be open
  46.        at the same time.
  47.  
  48.  
  49. 2. int nvtclose( HNVT hnvt );
  50.  
  51.        nvtclose() stops a telnet session identified by the nvt handle.
  52.  
  53.  
  54. 3. int nvtgets( HNVT hnvt, char *buf, int bufsize );
  55.  
  56.        nvtgets() reads a line from the nvt's input queue and copies it
  57.        into 'buf' to a maximum of 'bufsize'.  If no data is in the
  58.        input queue, nvtgets() blocks until a line is available.
  59.  
  60.        A line consists of all characters up to the new-line sequence
  61.        (generally CRLF).  The new line sequence is replaced by a null
  62.        character (\0) in 'buf'.
  63.  
  64.        nvtgets() returns the length of the string copied to 'buf'.
  65.  
  66.        If the string returned by nvtgets() begins with an EOT (\4)
  67.        then this indicates that the nvtgets() has timed out.
  68.  
  69.        If the string returned by nvtgets() begins with an ACK (\6)
  70.        then the rest of the string is an echo of the preceding nvtputs().
  71.  
  72.  
  73. 4. int nvtputs( HNVT hnvt, char *buf, int bufsize );
  74.  
  75.  
  76.        nvtputs() writes a line to the nvt's output queue.
  77.        The line is copied from 'buf' for a length of 'bufsize'.
  78.        A new-line sequence is appended to the string.
  79.  
  80.        nvtputs() returns the length of the string transmitted from 'buf'.
  81.  
  82.  
  83. 5. int nvtpeek( HNVT hnvt, int timeout );
  84.  
  85.        nvtpeek() waits for a line to appear in the nvt's input queue.
  86.        If there is a line ready, nvtpeek() returns immediately.
  87.        If the input queue doesn't have a line ready, nvtpeek() waits
  88.        until the queue has a line up to 'timeout' milliseconds.
  89.  
  90.        nvtpeek() returns 1 if a line is ready or 0 if a timeout occurred
  91.        and no data is available.
  92.  
  93.  
  94. 6. int nvtcommand( HNVT hnvt, char *command );
  95.  
  96.        nvtcommand() sends a telnet out-of-band command (such as 'BREAK').
  97.  
  98.        nvtcommand() returns a non-zero if it was able to send the command;
  99.        else it returns a zero.
  100.  
  101.  
  102. 7. int nvtquery( HNVT hnvt, LNVT *link );
  103.  
  104.        nvtquery() fills link information from the nvt's session.
  105.  
  106.  
  107.  
  108. REXX API
  109. """"""""
  110.  
  111. The Rexx api builds on the C nvt functions above.
  112.  
  113.  
  114. 1. nvt = TELNET(──hostname─┬───────┬──)
  115.                            └─,port─┘
  116.  
  117.    Telnet() starts a telnet session.  If successful, it returns
  118.    an NVT handle.  If not, it returns a null string.
  119.  
  120.    Multiple telnet sessions can be simultaneously active.
  121.  
  122.  
  123. 2. string = TGET(──nvt──┬──────────┬──)
  124.                         └─,timeout─┘
  125.  
  126.    Tget() retrieves a string from the nvt's input queue.
  127.    'timeout' can be specified to override the default timeout
  128.    (which is 1000 milliseconds).
  129.  
  130.  
  131. 3. result = TPUT(──nvt──,──string───)
  132.  
  133.    Tput() inserts a string into the nvt's output queue.
  134.  
  135.  
  136. 4. result = TCTL(──nvt──┬─────────────┬──)
  137.                         └─,─┬─'AO'────┤
  138.                             ├─'AYT'───┤
  139.                             ├─'BRK'───┤
  140.                             ├─'IP'────┤
  141.                             ├─'SYNCH'─┤
  142.                             └──etc.───┘
  143.  
  144.  
  145.    Tctl() returns link information about the nvt session or,
  146.    if the second argument is specified, sends an out-of-band
  147.    telnet command.
  148.  
  149.  
  150. 5. result = TQUIT(──nvt──)
  151.  
  152.    Tquit() closes the specified nvt session.
  153.  
  154.  
  155.  
  156.  
  157. DISCLAIMER
  158. """"""""""
  159.  
  160.  This software is freeware.  It's not intended for commercial
  161.  purposes.  It has been tested in a working (production)
  162.  environment but is not guaranteed to work anywhere else. ;-)
  163.  
  164.  If you have any comments or suggestions feel free to contact me
  165.  at bjr@hq.sequel.net
  166.  
  167.