Ubuntu Manpage: Ns_ConnPrintfHeader, Ns_ConnPuts, Ns_ConnSend, Ns_ConnSendChannel, Ns_ConnSendDString, Ns

Provided by: aolserver4-dev_4.5.1-16_amd64

NAME

       Ns_ConnPrintfHeader,  Ns_ConnPuts,  Ns_ConnSend,  Ns_ConnSendChannel,  Ns_ConnSendDString, Ns_ConnSendFd,
       Ns_ConnSendFdEx, Ns_ConnSendFp, Ns_ConnWrite, Ns_WriteConn - Routines to write data to the connection

SYNOPSIS

       #include "ns.h"

       int
       Ns_ConnPrintfHeader(conn, fmt, ...)

       int
       Ns_ConnPuts(conn, string)

       int
       Ns_ConnSend(conn, bufs, nbufs)

       int
       Ns_ConnSendChannel(conn, chan, nsend)

       int
       Ns_ConnSendDString(conn, dsPtr)

       int
       Ns_ConnSendFd(conn, fd, nsend)

       int
       Ns_ConnSendFdEx(conn, fd, off, nsend)

       int
       Ns_ConnSendFp(conn, fp, nsend)

       int
       Ns_ConnWrite(conn, buf, len)

       int
       Ns_WriteConn(conn, buf, len)

ARGUMENTS

       char           *buf           (in)      Pointer to bytes of specified length.

       Ns_Conn        conn           (in)      Open connection on which to send content.

       Ns_DString     dsPtr          (in)      Pointer to initialized dstring with content to send.

       int            fd             (in)      File descriptor opened for read.

       char           *fmt           (in)      Pointer to sprintf style format string which specifies the  types
                                               of the remaining variable number of arguments.

       FILE           *fp            (in)      Stdio FILE pointer opened for read.

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

       int            nbufs          (in)      Number of iovec structures pointed to by bufs.

       int            nsend          (in)      Number of bytes to send from object.

       off_t          off            (in)      Offset into open file descriptor to begin sending content.

       char           *string        (in)      Pointer to null-terminated string.

       struct iovec   bufs           (in)      Pointer to array of iovec structures.

       Tcl_Channel    chan           (in)      Pointer to Tcl channel open for read.
_________________________________________________________________

DESCRIPTION

These functions are the lowest level routines which support sending content directly to a connection
through the connection's communications driver (e.g., nssock or nsopenssl). They all attempt to send the
entire requested output, blocking the calling thread up to the driver-specific timeout if necessary.
Header data queued for send with Ns_ConnQueueHeaders, if any, will be sent before the requested user
data.

In practice, higher level routines such as the Ns_ConnReturn functions and Ns_ConnFlush are used to
generate complete responses instead of these lower level routines. The higher level routines construct
appropriate headers, manage output character encoding, and support gzip compression, calling these lower
level routines as needed.

int Ns_ConnPrintfHeader(conn, fmt, ...)
Contrary to it's name, this routine has nothing to do with HTTP headers. Instead, it simply calls
Ns_DStringPrintf with a temporary dstring, the given fmt argument, and any variables arguments and
then calls Ns_ConnSendDString with the temporary dstring. The result is NS_OK if all formatted
bytes were sent, otherwise NS_ERROR.

int Ns_ConnPuts(conn, string)
This routines sends a null-terminated string to the client and returns NS_OK if successful or
NS_ERROR on failure. It is equivalent to Ns_WriteConn(conn, string, strlen(string)).

int Ns_ConnSend(conn, bufs, nbufs)
This is the lowest level routine which calls the connection's communication driver to send an
array of zero or more buffers. The result is the total number of bytes sent which should equal
the total requested data or -1 on error. The number of bytes sent from queued header data, if
any, is not included in the result. The bufs argument is a pointer to an array of nbufs iovec
structures. The usage is similar to the the Unix writev system call. The iovec structure is
defined as:

struct iovec {
void *iov_base;
size_t iov_len
}

Each element of the structure should contain a pointer to valid user data specified by iov_base of length
iov_len. A NULL value for iov_base and a cooresponding value of zero for iov_len is valid and will
simply be skipped over when sending the total requested bytes.

int Ns_ConnSendChannel(conn, chan, nsend)
This routine copies nsend bytes from the open Tcl channel to the connection. The result is NS_OK
if all bytes available in the open channel or all bytes requested where sent, otherwise NS_ERROR.

int Ns_ConnSendDString(conn, dsPtr)
This routines sends all content which exists in the dstring pointed to by dsPtr. The result is
NS_OK if all bytes where sent, otherwise NS_ERROR.

int Ns_ConnSendFd(conn, fd, nsend)
This routine copies nsend bytes from the open file descriptor to the connection. The result is
NS_OK if all bytes available in the open file or all bytes requested where sent, otherwise
NS_ERROR. Copying begins from the current offset.

int Ns_ConnSendFp(conn, fp, nsend)
This routine copies nsend bytes from the open stdio FILE to the connection. The result is NS_OK
if all bytes available in the open file or all bytes requested where sent, otherwise NS_ERROR.
Copying begins from the current offset.

int Ns_ConnSendFdEx(conn, fd, off, nsend)
This routine copies nsend bytes from the open file descriptor to the connection. The result is
NS_OK if all bytes available in the open file or all bytes requested where sent, otherwise
NS_ERROR. Copying begins from the offset given in the off parameter. (NOTE: This routine is
currently not supported on Win32 and always returns NS_ERROR).

int Ns_ConnWrite(conn, buf, len)
This routine will send a single buffer pointed to by buf of length len. The result is the number
of bytes sent or -1 on error. It is equivalent to calling Ns_ConnSend with an single struct
iovec.

int Ns_WriteConn(conn, buf, len)
This routine will send a single buffer pointed to by buf of length len. The result is NS_OK if
all content was sent, otherwise NS_ERROR. It is equivalent to calling Ns_ConnWrite and mapping
the bytes sent or -1 error result to NS_OK or NS_ERROR.

EXMPLES

       The following example demonstrates crafting some headers and then sending two buffers of data.   In  this
       case,  Ns_ConnSend will actually call the communications driver with three buffers, the first pointing to
       header data queued for send by Ns_ConnQueueHeaders followed by the two user data  buffers.   The  result,
       assuming all three buffers are resonably small, is likely an efficient single send on the socket:

                struct iovec iov[2];
                int contentlength;

                iov[0].iov_base = firstbuf;
                iov[0].iov_len  = firstlen;
                iov[1].iov_base = secondbuf;
                iov[1].iov_len= secondlen;
                contentlength = iov[0].iov_len + iov[1].iov_len;
                Ns_ConnSetRequiredHeaders(conn, "text/html", contentlength);
                Ns_ConnQueueHeaders(conn, 200);
                if (Ns_ConnSend(conn, iov, contentlength) != contentlength) {
                   ... error, e.g., connection drop ...
                }
                Ns_ConnClose(conn);

KEYWORDS