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