web_stream.c

   File         : web_stream.c
   Description  : Stream Handling Functions for web_server
   Category     : Web Internal
   Author       : Charles Yates

   WEB_STREAM STREAM_Init( WEB_COMMON common, int io )
 
   Function     : STREAM_Init
   Description  : Initialises the stream.
   Input        : WEB_COMMON common - common structure for external event info
                  int io - Input/Output file descriptor from socket
   Output       : void
   Returns      : WEB_STREAM - An initialised WEB_STREAM strcuture

   WEB_STREAM STREAM_Connect( WEB_COMMON common, char *server, int port )
 
   Function     : STREAM_Connect
   Description  : Initialises a stream to a given server and port.
   Input        : WEB_COMMON common - common structure for external event info
                  char *server - server to connect to
                  int port - port to connect to
   Output       : void
   Returns      : WEB_STREAM - An initialised WEB_STREAM strcuture or 
                  NULL if failed

   int STREAM_Read( WEB_STREAM stream, char *buffer, int length )
 
   Function     : STREAM_Read
   Description  : Reads raw data from the stream
   Input        : WEB_STREAM stream - Input/Output stream to use
                  char *buffer - buffer to write to
                  int length - length of buffer
   Output       : buffer contains up to length bytes
   Returns      : int - number of bytes read

   int STREAM_ReadLine( WEB_STREAM stream, char *line, int max )
 
   Function     : STREAM_ReadLine
   Description  : Reads a line of input from the input stream.
   Input        : WEB_STREAM stream - Stream to use
                  char *line - Location to write the results back
                  int max - The maximum number of characters to read
   Output       : line contains the characters read
   Returns      : int - 0 indicates no error, != 0 indicates an error

   int STREAM_ReadChomp( WEB_STREAM buffer, char *line, int max )
 
   Function     : STREAM_ReadChomp
   Description  : Reads a line of input from the input stream and removes the line feed.
   Input        : WEB_STREAM stream - Stream to use
                  char *line - Location to write the results back
                  int max - The maximum number of characters to read
   Output       : line contains the characters read
   Returns      : int - 0 indicates no error, != 0 indicates an error

   int STREAM_GetLine( WEB_STREAM stream, char **line )
 
   Function     : STREAM_GetLine
   Description  : Reads a line of input of unlimited length from the input stream
   Input        : WEB_STREAM stream - Stream to use
                  char **line - Location to write the results back
   Output       : line contains the characters read
   Returns      : int - 0 indicates no error, != 0 indicates an error
   Special Logic: It's the callers responsibilty to free the memory allocated. 
                  The pointer must be initialised (to NULL or malloc) before calling.

   int STREAM_WriteLine( WEB_STREAM stream, char *line )
 
   Function     : STREAM_WriteLine
   Description  : Writes a nul terminated string to the output stream
   Input        : WEB_STREAM stream - Stream to use
                  char *line - Location of string to write
   Output       : void
   Returns      : int - 0 indicates no error, != 0 indicates an error

   int STREAM_WriteString( WEB_STREAM stream, char *line )
 
   Function     : STREAM_WriteString
   Description  : Writes a nul terminated string to the output stream
   Input        : WEB_STREAM stream - Stream to use
                  char *line - Location of string to write
   Output       : void
   Returns      : int - 0 indicates no error, != 0 indicates an error

   int STREAM_Write( WEB_STREAM stream, char *data, int count )
 
   Function     : STREAM_Write
   Description  : Writes an arbritrary block of data to a stream
   Input        : WEB_STREAM stream - Stream to use
                  char *data - Location of data to write
                  int count - number of bytes
   Output       : void
   Returns      : int - 0 indicates no error, != 0 indicates an error

   int STREAM_Printf( WEB_STREAM stream, char *format, ... )
 
   Function     : STREAM_Printf
   Description  : Printf style printing to a stream
   Input        : WEB_STREAM stream - stream to use
                  char *format - format string
                  ... - variable arguments
   Output       : Formatted string is written to the stream
   Returns      : int - the number of bytes written

   int STREAM_Flush( WEB_STREAM buffer )
 
   Function     : STREAM_Flush
   Description  : Flushes the pending output to the output stream
   Input        : WEB_STREAM stream - Stream to read from
   Output       : void
   Returns      : an int indicating success or failure
   Special Logic:
  
   In the current implementation of the WEB_STREAM, direct/non-buffered
   io is applied - this method does nothing.

   char *STREAM_GetClientAddress( WEB_STREAM stream )
 
   Function     : STREAM_GetClientAddress
   Description  : Get IP address of the client 
   Input        : WEB_STREAM stream - stream to obtain info from
   Output       : void
   Returns      : The IP Address of the other side of the stream

   void STREAM_Close( WEB_STREAM buffer )
 
   Function     : STREAM_Closes
   Description  : Closes the stream
   Input        : WEB_STREAM stream - Stream to use
   Output       : stream is closed
   Returns      : void