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