Ns_ConnFlush(3aolserver)				   AOLserver Library Procedures 				  Ns_ConnFlush(3aolserver)

__________________________________________________________________________________________________________________________________________________

NAME

       Ns_ConnFlush, Ns_ConnFlushDirect - Flush content to an open connection

SYNOPSIS

       #include "ns.h"

       int
       Ns_ConnFlush(conn, buf, len, stream)

       int
       Ns_ConnFlushDirect(conn, buf, len, stream)

ARGUMENTS

       char	 *buf	(in)	  Pointer to buffer to send.

       Ns_Conn	 conn	(in)	  Pointer to current connection.

       int	 len	(in)	  Length of bytes pointed to by buf.

       int	 stream (in)	  Boolean value to indicate a streamed response.
_________________________________________________________________

DESCRIPTION

       These  routines	support sending content to the client through the connection's communcation driver.  They support generating both complete
       single responses or streaming content through multiple calls.  They both take a pointer to the current connection  specified  by  the  conn
       argument  and  a  pointer  to  content  to send specified by buf of length len.	If len is negative, buf is assumed to be a null terminated
       string and len is calculated by strlen.

       The stream argument, if zero, indicates a single response should be generated.  In this case, an appropriate content-length header is  gen-
       erated,	the  content  is  sent,  and  the connection is closed with Ns_ConnClose.  If stream is not zero, the call is assumed to be one of
       potential multiple calls which will send content incrementally to the client.  Content streamed in this case  is  sent  either  in  chunked
       encoding  mode  for  HTTP/1.1 clients or directly, without a content-length as was common in pre-HTTP/1.1 applications.	Applications which
       stream content should be sure to make a final call Ns_ConnFlush or Ns_ConnFlushDirect with stream set to zero to correctly flush and  close
       the connection.

       The  Ns_ConnFlush  and Ns_ConnFlushDirect differ in their treatment of the given content before sending.  Ns_ConnFlushDirect does not alter
       the content in anyway, treating is as an arbitrary array of bytes.  Ns_ConnFlush assumes the content is UTF-8 text, e.g., the result of	an
       ADP  page  execution. In this case, if the connection has an associated output encoding set with the Ns_ConnSetEncoding routine, it will be
       used to encode the content in the requested character set (e.g., from UTF-8 to iso8859-1).  In addition, if the server has gzip compression
       enabled,  the nszlib module is loaded, the connection has been marked for gzip compression with the Ns_ConnSetGzipFlag, and the size of the
       output data is greater than the server configured minimun gzip compression size, the content will be compressed and an  appropriate  header
       will be generated for the client.  Gzip compression is not supported when content is streamed to the client.

       The  first call to Ns_ConnFlush or Ns_ConnFlushDirect for a connection, in stream or single response mode, will result in appropriate head-
       ers being constructed and sent first before any user data.  These headers include the basic headers constructed via Ns_ConnSetRequiredHead-
       ers  plus  any  additional application specific headers queued for output via Ns_ConnSetHeaders or Ns_ConnCondSetHeaders.  The Ns_ConnFlush
       routine may add additional headers as needed to specify chunked and/or gzip encoding.

EXAMPLE

       The following example generates a simple text response:

		Ns_ConnSetStatus(conn, 200);
		Ns_ConnSetType(conn, "text/plain");
		Ns_ConnFlush(conn, "Hello", 5, 0);

       The following example demonstrates streaming:

		Ns_ConnSetStatus(conn, 200);
		Ns_ConnSetType(conn, "text/plain");
		for (i = 0; i < 10; ++i) {
		   sprintf(buf, "stream: %d0, i);
		   Ns_ConnFlush(conn, buf, -1, 1);
		}
		Ns_ConnFlush(conn, "done!", 5, 0);

SEE ALSO

       Ns_ConnSend(n), Ns_ConnClose(3), Ns_ConnSetRequiredHeaders(3), Ns_ConnQueueHeaders(3)

KEYWORDS

       connection i/o, gzip, stream, encoding, flush

AOLserver								4.5						  Ns_ConnFlush(3aolserver)