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