home *** CD-ROM | disk | FTP | other *** search
/ kermit.columbia.edu / kermit.columbia.edu.tar / kermit.columbia.edu / public_html / k95dll_c.txt < prev    next >
Text File  |  2001-11-25  |  9KB  |  329 lines
  1. /* Kermit 95 - External Network DLL specification
  2.  * July 16 1998
  3.  * Jeffrey Altman <jaltman@columbia.edu>
  4.  *
  5.  * The following specification defines a set of functions to be exported from
  6.  * a DLL in order for the DLL to work with Kermit 95 version 1.1.17 or higher.
  7.  *
  8.  * The DLL is loaded by Kermit 95 via use of the command:
  9.  *   SET NETWORK TYPE DLL <dllname>
  10.  *
  11.  * Notes:
  12.  *   The functions specified here must be thread safe.  It is possible
  13.  *   for multiple threads to be calling any combination of functions
  14.  *   simultaneously.
  15.  *
  16.  *   The 1.1.17 interface does not provide for the ability of the
  17.  *   DLL to query the user with echoing input, nor is the a method
  18.  *   for querying the values of Kermit variables such as 'userid'
  19.  *   or Kermit version number.  This will be added in a later release.
  20.  */
  21.  
  22. /*
  23.  * N E T O P E N - Network Open
  24.  *
  25.  * The network open function is called by Kermit 95 when a new connection
  26.  * is desired.  Usually in response to:
  27.  *    SET HOST <command_line>
  28.  *
  29.  * Parameters:
  30.  *   command_line - the command line specified in the SET HOST command
  31.  *                  after quoting rules and variables have been applied.
  32.  *   termtype     - a string representing either the currently selected
  33.  *                  terminal type or a user specified string as per
  34.  *                  SET TELNET TERMINAL <string>
  35.  *   height       - initial height of the terminal window (chars)
  36.  *   width        - initial width of the terminal window (chars)
  37.  *   readpass     - a pointer to a function to be used to read a password
  38.  *                  without echoing
  39.  *
  40.  * Return values:
  41.  *   0   on success
  42.  *   < 0 on failure
  43.  *
  44.  *   return codes should be defined such that they can be passed to
  45.  *   errorstr() to retrieve an appropriate error message for the user.
  46.  */
  47.  
  48. int
  49. netopen(char * command_line, char * termtype, int height, int width,
  50.         int (* readpass)(char * prompt,char * buffer, int length));
  51. /*
  52.  * N E T C L O S - Network Close
  53.  *
  54.  * The network close function is called by Kermit 95 when the user requests
  55.  * a disconnect or in response to fatal error.
  56.  *
  57.  * Parameters: None
  58.  *
  59.  * Return values:
  60.  *   0   on success
  61.  *   < 0 on failure
  62.  *
  63.  *   return codes should be defined such that they can be passed to
  64.  *   errorstr() to retrieve an appropriate error message for the user.
  65.  */
  66.  
  67. int
  68. netclos(void) ;
  69.  
  70. /*
  71.  * N E T T C H K - Network Terminal I/O Check
  72.  *
  73.  * The network terminal i/o check function is called regularly by Kermit 95
  74.  * to poll the status of the connection and to retrieve the number of input
  75.  * characters waiting to be processed.  Because it is called frequently this
  76.  * function should be designed to be low cost.
  77.  *
  78.  * Parameters: None
  79.  *
  80.  * Return values:
  81.  *   >= 0 number of characters waiting in the input queue
  82.  *   < 0  indicates a fatal error on the connection and the connection
  83.  *        should be closed.
  84.  *
  85.  *   return codes should be defined such that they can be passed to
  86.  *   errorstr() to retrieve an appropriate error message for the user.
  87.  */
  88.  
  89. int
  90. nettchk(void);
  91.  
  92. /*
  93.  * N E T F L U I - Network Flush Input
  94.  *
  95.  * The network flush input function should clear the connection's input
  96.  * queue.
  97.  *
  98.  * Parameters: None
  99.  *
  100.  * Return values:
  101.  *   0    indicates success
  102.  *   < 0  indicates an error
  103.  *
  104.  *   return codes should be defined such that they can be passed to
  105.  *   errorstr() to retrieve an appropriate error message for the user.
  106.  */
  107.  
  108. int
  109. netflui(void);
  110.  
  111. /*
  112.  * N E T B R E A K - Network Break
  113.  *
  114.  * The network break signal is called in response to a user initiated
  115.  * break command.  For example, on a serial device this should result in
  116.  * a Break signal and on a Telnet connection a Break Command is sent.
  117.  * For connection types without an equivalent simply return 0.
  118.  *
  119.  * Parameters: None
  120.  *
  121.  * Return values:
  122.  *   0    indicates success
  123.  *   < 0  indicates an error
  124.  *
  125.  *   return codes should be defined such that they can be passed to
  126.  *   errorstr() to retrieve an appropriate error message for the user.
  127.  */
  128.  
  129. int
  130. netbreak(void);
  131.  
  132. /*
  133.  * N E T I N C - Network Input Character
  134.  *
  135.  * The network input character is used to read the next character from
  136.  * the input queue.
  137.  *
  138.  * Parameters:
  139.  *   timeout - 0   indicates no timeout, block until the next character
  140.  *                 is available;
  141.  *             > 0 indicates a timeout value in seconds;
  142.  *             < 0 indicates a timeout value in milliseconds;
  143.  *
  144.  * Return values:
  145.  *   >= 0 is interpreted as a valid character
  146.  *   -1   is a timeout [errorstr() is not called]
  147.  *   < -1 is a fatal error
  148.  *
  149.  *   return codes < -1 should be defined such that they can be passed to
  150.  *   errorstr() to retrieve an appropriate error message for the user.
  151.  */
  152.  
  153. int
  154. netinc(int timeout);
  155.  
  156. /*
  157.  * N E T X I N - Network Extended Input
  158.  *
  159.  * The network extended input is called to read a large number of waiting
  160.  * input characters.  It will never be called with a number larger than
  161.  * reported as available and waiting by nettchk().  The function may return
  162.  * fewer characters than is requested.  This function should not block.
  163.  *
  164.  * Parameters:
  165.  *   count  - number of characters to be read
  166.  *   buffer - buffer of length count to be used to store the data
  167.  *
  168.  * Return values:
  169.  *   >= 0  the number of characters actually returned by the function
  170.  *   < 0  indicates an error
  171.  *
  172.  *   return codes should be defined such that they can be passed to
  173.  *   errorstr() to retrieve an appropriate error message for the user.
  174.  */
  175.  
  176. int
  177. netxin(int count, char * buffer);
  178.  
  179. /*
  180.  * N E T T O C - Network Terminal Output Character
  181.  *
  182.  * The network terminal output character transmits a single character
  183.  *
  184.  * Parameters:
  185.  *   c - a single character to be output
  186.  *
  187.  * Return values:
  188.  *   0    indicates success
  189.  *   < 0  indicates an error
  190.  *
  191.  *   return codes should be defined such that they can be passed to
  192.  *   errorstr() to retrieve an appropriate error message for the user.
  193.  */
  194.  
  195. int
  196. nettoc(int c);
  197.  
  198. /*
  199.  * N E T T O L - Network Terminal Output Line
  200.  *
  201.  * The network terminal output line is used to output one or more
  202.  * characters.
  203.  *
  204.  * Parameters:
  205.  *   buffer - contains the characters to be output
  206.  *   count  - the number of characters to be output from buffer
  207.  *
  208.  * Return values:
  209.  *   >= 0 the number of characters actually output.  The function
  210.  *        should make its best attempt to transmit all 'count'
  211.  *        characters.
  212.  *   < 0  indicates a fatal error
  213.  *
  214.  *   return codes should be defined such that they can be passed to
  215.  *   errorstr() to retrieve an appropriate error message for the user.
  216.  */
  217.  
  218. int
  219. nettol(char * buffer, int count);
  220.  
  221. /*
  222.  * T T V T - Terminal to Virtual Terminal Mode
  223.  *
  224.  * Terminal to Virtual Terminal Mode is called to notify the DLL that
  225.  * Kermit 95 is about to enter terminal mode communications.  This means
  226.  * either the CONNECT or DIAL commands will be sending output.  In most
  227.  * cases, this will be either printable text or escape sequences.
  228.  *
  229.  * Parameters: None
  230.  *
  231.  * Return values:
  232.  *   0    indicates success
  233.  *   < 0  indicates an error
  234.  *
  235.  *   return codes should be defined such that they can be passed to
  236.  *   errorstr() to retrieve an appropriate error message for the user.
  237.  */
  238.  
  239. int
  240. ttvt(void);
  241.  
  242. /*
  243.  * T T P K T - Terminal to Packet Mode
  244.  *
  245.  * Terminal to Packet Mode is called to notify the DLL that
  246.  * Kermit 95 is about to enter file transfer operations.
  247.  *
  248.  * Parameters: None
  249.  *
  250.  * Return values:
  251.  *   0    indicates success
  252.  *   < 0  indicates an error
  253.  *
  254.  *   return codes should be defined such that they can be passed to
  255.  *   errorstr() to retrieve an appropriate error message for the user.
  256.  */
  257.  
  258. int
  259. ttpkt(void);
  260.  
  261. /*
  262.  * T T R E S - Terminal Restore Mode
  263.  *
  264.  * Terminal Restore Mode is called to notify the DLL that it should
  265.  * Kermit 95 restore to default settings.
  266.  *
  267.  * Parameters: None
  268.  *
  269.  * Return values:
  270.  *   0    indicates success
  271.  *   < 0  indicates an error
  272.  *
  273.  *   return codes should be defined such that they can be passed to
  274.  *   errorstr() to retrieve an appropriate error message for the user.
  275.  */
  276.  
  277. int
  278. ttres(void);
  279.  
  280. /*
  281.  * T E R M I N F O - Terminal Information
  282.  *
  283.  * The terminal information function is called whenever the terminal
  284.  * type or window size is changed.
  285.  *
  286.  * Parameters:
  287.  *   termtype     - a string representing either the currently selected
  288.  *                  terminal type or a user specified string as per
  289.  *                  SET TELNET TERMINAL <string>
  290.  *   height       - initial height of the terminal window (chars)
  291.  *   width        - initial width of the terminal window (chars)
  292.  *
  293.  * Return values: None
  294.  */
  295.  
  296. void
  297. terminfo(char * termtype, int height, int width);
  298.  
  299. /*
  300.  * V E R S I O N - Version String
  301.  *
  302.  * Version is called to get a user displayable version string for use
  303.  * as part of the SHOW NETWORK command.
  304.  *
  305.  * Parameters: None
  306.  *
  307.  * Return values:
  308.  *   a string which will not be deleted by the caller.
  309.  */
  310.  
  311. const char *
  312. version(void);
  313.  
  314. /*
  315.  * E R R O R S T R - Error String
  316.  *
  317.  * Error string is called to retrieve a user displayable error message
  318.  * describing the type of error being reported by the function.
  319.  *
  320.  * Parameters:
  321.  *   error - the error value reported by the DLL function.
  322.  *
  323.  * Return values:
  324.  *   a string which will not be deleted by the caller.
  325.  */
  326.  
  327. const char *
  328. errorstr(int error);
  329.