ICELIB0.NLM   →   ICE_SockReadLine()

ICE_SockReadLine

Description:

Reads a single line of text from the socket specified, and uses select() to provide a fine degree of control over the timeout.
 

Syntax for C:

int ICE_SockReadLine (
  void *buffer,
  unsigned int size,
  unsigned int socketHandle,
  unsigned int keyTimeout,
  unsigned int lineTimeout,
  int flags,
);
 

Syntax for Assembly:

Call ICE_SockReadLine C, offset buffer, [size], [socketHandle], [keyTimeout], [lineTimeout], [flags]
 

Parameters:

buffer

(IN) Pointer to buffer to save input in.  This buffer is automatically zero-filled unless Flag 32 is set.  If set to NULL, an error code of -1 is returned immediately.
 

size

(IN) Size of buffer (maximum length of input text)
 

socketHandle

(IN) Handle of socket to use for I/O.
 

keyTimeout

(IN) Number of seconds to wait between keystrokes before timing out
 

lineTimeout

(IN) Number of seconds to wait for end of line before timing out
 

flags

(IN) Some rules to be enforced during the query.  All undocumented bit flags are considered reserved for future use, and should remain cleared (0) to ensure upward compatibility with newer versions of ICELIB0.NLM.  Currently supported flags are as follows:

1 = Allow long lines (enables Return Code 1)

2 = Allow user to press [Esc] key (enables Return Code 2)

4 = Interactive mode (echo text back to user)

8 = Enable support for BackSpace key (ASCII 8)

16 = Enable support for Destructive BackSpace key (ASCII 127)

32 = Don't pre-clear the buffer (continue editing existing text)

64 = Transmit existing text (if any) over socket

128...256 = Case conversion:
          0 = Don't change anything
          128 = Convert everything to lower case
          256 = Convert everything to upper case
          128 + 256 = Convert first byte after every space to upper case

512 = Send BELL (ASCII 7) on error (see Note 1)

1024 = Filter out leading spaces

2048 = Filter out 8-bit ASCII characters (allow only 7-bit ASCII)

4096 = Filter out control characters (ignore ASCII 0...31)

8192 = Display "*" in when Flag 4 is set (useful for password entry)

16384 = Convert tab (ASCII 9) to one space (ASCII 32)

32768 = Unix mode, completely ignore Carriage Returns (ASCII 13)
 

Returns:

2 = Successful, but aborted by user due to [Esc] keystroke
1 = Successful, but line length exceeds specified size
0 = Successful, line length is less than or equal to maximum
-1 = No buffer ("buffer" is NULL)
-2 = Not enough memory, malloc() failed
-3 = Failed to select socket
-4 = Connection timed out (keyboard), some data may be present
-5 = Failed to read() from socket
-6 = Failed to write() to socket
 

Remarks:

The need to select() on a line of text is not available with the current implementation of BSD sockets, so this function was created to address this issue.  The ability to control, to a limited degree, the user's input, and to provide support for the [BackSpace] key is also very useful.

Note 1

Errors include invalid keys being pressed, timeout expiry, or lost text when End Of Line is reached while Flag 1 is clear (e.g., user presses keys which are ignored because buffer is full).