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 generated, 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 headers being constructed and sent first before any user data.  These headers
       include the basic headers constructed  via  Ns_ConnSetRequiredHeaders  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