/* Kermit 95 - External Network DLL specification * July 16 1998 * Jeffrey Altman * * The following specification defines a set of functions to be exported from * a DLL in order for the DLL to work with Kermit 95 version 1.1.17 or higher. * * The DLL is loaded by Kermit 95 via use of the command: * SET NETWORK TYPE DLL * * Notes: * The functions specified here must be thread safe. It is possible * for multiple threads to be calling any combination of functions * simultaneously. * * The 1.1.17 interface does not provide for the ability of the * DLL to query the user with echoing input, nor is the a method * for querying the values of Kermit variables such as 'userid' * or Kermit version number. This will be added in a later release. */ /* * N E T O P E N - Network Open * * The network open function is called by Kermit 95 when a new connection * is desired. Usually in response to: * SET HOST * * Parameters: * command_line - the command line specified in the SET HOST command * after quoting rules and variables have been applied. * termtype - a string representing either the currently selected * terminal type or a user specified string as per * SET TELNET TERMINAL * height - initial height of the terminal window (chars) * width - initial width of the terminal window (chars) * readpass - a pointer to a function to be used to read a password * without echoing * * Return values: * 0 on success * < 0 on failure * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int netopen(char * command_line, char * termtype, int height, int width, int (* readpass)(char * prompt,char * buffer, int length)); /* * N E T C L O S - Network Close * * The network close function is called by Kermit 95 when the user requests * a disconnect or in response to fatal error. * * Parameters: None * * Return values: * 0 on success * < 0 on failure * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int netclos(void) ; /* * N E T T C H K - Network Terminal I/O Check * * The network terminal i/o check function is called regularly by Kermit 95 * to poll the status of the connection and to retrieve the number of input * characters waiting to be processed. Because it is called frequently this * function should be designed to be low cost. * * Parameters: None * * Return values: * >= 0 number of characters waiting in the input queue * < 0 indicates a fatal error on the connection and the connection * should be closed. * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int nettchk(void); /* * N E T F L U I - Network Flush Input * * The network flush input function should clear the connection's input * queue. * * Parameters: None * * Return values: * 0 indicates success * < 0 indicates an error * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int netflui(void); /* * N E T B R E A K - Network Break * * The network break signal is called in response to a user initiated * break command. For example, on a serial device this should result in * a Break signal and on a Telnet connection a Break Command is sent. * For connection types without an equivalent simply return 0. * * Parameters: None * * Return values: * 0 indicates success * < 0 indicates an error * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int netbreak(void); /* * N E T I N C - Network Input Character * * The network input character is used to read the next character from * the input queue. * * Parameters: * timeout - 0 indicates no timeout, block until the next character * is available; * > 0 indicates a timeout value in seconds; * < 0 indicates a timeout value in milliseconds; * * Return values: * >= 0 is interpreted as a valid character * -1 is a timeout [errorstr() is not called] * < -1 is a fatal error * * return codes < -1 should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int netinc(int timeout); /* * N E T X I N - Network Extended Input * * The network extended input is called to read a large number of waiting * input characters. It will never be called with a number larger than * reported as available and waiting by nettchk(). The function may return * fewer characters than is requested. This function should not block. * * Parameters: * count - number of characters to be read * buffer - buffer of length count to be used to store the data * * Return values: * >= 0 the number of characters actually returned by the function * < 0 indicates an error * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int netxin(int count, char * buffer); /* * N E T T O C - Network Terminal Output Character * * The network terminal output character transmits a single character * * Parameters: * c - a single character to be output * * Return values: * 0 indicates success * < 0 indicates an error * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int nettoc(int c); /* * N E T T O L - Network Terminal Output Line * * The network terminal output line is used to output one or more * characters. * * Parameters: * buffer - contains the characters to be output * count - the number of characters to be output from buffer * * Return values: * >= 0 the number of characters actually output. The function * should make its best attempt to transmit all 'count' * characters. * < 0 indicates a fatal error * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int nettol(char * buffer, int count); /* * T T V T - Terminal to Virtual Terminal Mode * * Terminal to Virtual Terminal Mode is called to notify the DLL that * Kermit 95 is about to enter terminal mode communications. This means * either the CONNECT or DIAL commands will be sending output. In most * cases, this will be either printable text or escape sequences. * * Parameters: None * * Return values: * 0 indicates success * < 0 indicates an error * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int ttvt(void); /* * T T P K T - Terminal to Packet Mode * * Terminal to Packet Mode is called to notify the DLL that * Kermit 95 is about to enter file transfer operations. * * Parameters: None * * Return values: * 0 indicates success * < 0 indicates an error * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int ttpkt(void); /* * T T R E S - Terminal Restore Mode * * Terminal Restore Mode is called to notify the DLL that it should * Kermit 95 restore to default settings. * * Parameters: None * * Return values: * 0 indicates success * < 0 indicates an error * * return codes should be defined such that they can be passed to * errorstr() to retrieve an appropriate error message for the user. */ int ttres(void); /* * T E R M I N F O - Terminal Information * * The terminal information function is called whenever the terminal * type or window size is changed. * * Parameters: * termtype - a string representing either the currently selected * terminal type or a user specified string as per * SET TELNET TERMINAL * height - initial height of the terminal window (chars) * width - initial width of the terminal window (chars) * * Return values: None */ void terminfo(char * termtype, int height, int width); /* * V E R S I O N - Version String * * Version is called to get a user displayable version string for use * as part of the SHOW NETWORK command. * * Parameters: None * * Return values: * a string which will not be deleted by the caller. */ const char * version(void); /* * E R R O R S T R - Error String * * Error string is called to retrieve a user displayable error message * describing the type of error being reported by the function. * * Parameters: * error - the error value reported by the DLL function. * * Return values: * a string which will not be deleted by the caller. */ const char * errorstr(int error);