'\"
'\" The contents of this file are subject to the AOLserver Public License
'\" Version 1.1 (the "License"); you may not use this file except in
'\" compliance with the License. You may obtain a copy of the License at
'\" http://aolserver.com/.
'\"
'\" Software distributed under the License is distributed on an "AS IS"
'\" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
'\" the License for the specific language governing rights and limitations
'\" under the License.
'\"
'\" The Original Code is AOLserver Code and related documentation
'\" distributed by AOL.
'\" 
'\" The Initial Developer of the Original Code is America Online,
'\" Inc. Portions created by AOL are Copyright (C) 1999 America Online,
'\" Inc. All Rights Reserved.
'\"
'\" Alternatively, the contents of this file may be used under the terms
'\" of the GNU General Public License (the "GPL"), in which case the
'\" provisions of GPL are applicable instead of those above.  If you wish
'\" to allow use of your version of this file only under the terms of the
'\" GPL and not to allow others to use your version of this file under the
'\" License, indicate your decision by deleting the provisions above and
'\" replace them with the notice and other provisions required by the GPL.
'\" If you do not delete the provisions above, a recipient may use your
'\" version of this file under either the License or the GPL.
'\" 
'\"
'\" $Header: /cvsroot/aolserver/aolserver/doc/Ns_Conn.3,v 1.4 2006/04/19 17:37:30 jgdavidson Exp $
'\"
'\" 
.so man.macros

.TH Ns_Conn 3 4.0 AOLserver "AOLserver Library Procedures"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
Ns_ConnAuthPasswd, Ns_ConnAuthUser, Ns_ConnHeaders, Ns_ConnHost, Ns_ConnId, Ns_ConnLocation, Ns_ConnOutputHeaders, Ns_ConnPeer, Ns_ConnPeerPort, Ns_ConnPort, Ns_ConnResponseLength, Ns_ConnResponseStatus, Ns_ConnServer, Ns_ConnSock \- Routines to access data about a connection
.SH SYNOPSIS
.nf
\fB#include "ns.h"\fR
.sp
char *
\fBNs_ConnAuthPasswd\fR(\fINs_Conn *conn\fR)
.sp
char *
\fBNs_ConnAuthUser\fR(\fINs_Conn *conn\fR)
.sp
Ns_Set *
\fBNs_ConnHeaders\fR(\fINs_Conn *conn\fR)
.sp
char *
\fBNs_ConnHost\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnId\fR(\fINs_Conn *conn\fR)
.sp
char *
\fBNs_ConnLocation\fR(\fINs_Conn *conn\fR)
.sp
Ns_Set *
\fBNs_ConnOutputHeaders\fR(\fINs_Conn *conn\fR)
.sp
char *
\fBNs_ConnPeer\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnPeerPort\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnPort\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnResponseLength\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnResponseStatus\fR(\fINs_Conn *conn\fR)
.sp
char *
\fBNs_ConnServer\fR(\fINs_Conn *conn\fR)
.sp
int
\fBNs_ConnSock\fR(\fINs_Conn *conn\fR)
.SH ARGUMENTS
.AS Ns_Conn *conn in
.AP Ns_Conn *conn in
Pointer to given connection.
.sp
.BE
.SH DESCRIPTION
.PP
These routines provide access to data stored within an active
connection.  All routines take as an argument a pointer to an
\fBNs_Conn\fR structure which is setup by the server and passed to
request handling procedures.

.SH "THE NS_CONN STRUCTURE"
.PP
The \fBNs_Conn\fR structure includes the following fields:
.sp
.CS 
typedef struct Ns_Conn {
    Ns_Request *request;
    Ns_Set     *headers;
    Ns_Set     *outputheaders;
    char       *authUser;
    char       *authPasswd;
    int         contentLength;
    int         flags; 
} Ns_Conn;
.CE

.PP
All fields of an \fINs_Conn\fR structure should be considered
read-only.  The \fIrequest\fR field contains a pointer to the parsed
HTTP request.  See the manual page for \fBNs_ParseRequest\fR for
details on what it contains.
.PP
The \fIheaders\fR and \fIoutputHeaders\fR fields point to \fBNs_Set\fR
structures for the input and output headers, respectively.  The
\fIoutputHeaders\fR set will generally not contain any fields until
after the request has been processed.  See the manual page on
\fBNs_Set\fR for details on the fields of the structure and routines
to access and manipulate them.
.PP
The \fIauthUser\fR and \fIauthPasswd\fR fields point to the decoded
username and password for the request or \fINULL\fR if no authorization
was sent.
.PP
The \fIcontentLength\fR field is the length of the content, if any,
sent with the request. See the man page on \fBNs_ConnContent\fR
for details on accessing the content.
.PP
The \fIflags\fR field is a bitmask with one or more \fINS_CONN\fR
bits:

.TP
\fBNS_CONN_CLOSED\fR
Connection is closed.
.TP
\fBNS_CONN_SKIPHDRS\fR
Pre-HTTP/1.0 connection which will not return headers.
.TP
\fBNS_CONN_SKIPBODY\fR
HTTP HEAD request which will return no content.
.TP
\fBNS_CONN_READHDRS\fR
Headers have been read (noramlly set).
.TP
\fBNS_CONN_SENTHDRS\fR
Result headers have been sent.
.TP
\fBNS_CONN_KEEPALIVE\fR
Connection should be kept alive for another request if possible.
.TP
\fBNS_CONN_WRITE_ENCODED\fR
Output could be encoded when directly sent.
.TP
\fBNS_CONN_FILECONTENT\fR
Connection contains content originally in a temp file.
.TP
\fBNS_CONN_RUNNING\fR
Connection is currently active in a request thread.
.TP
\fBNS_CONN_OVERFLOW\fR
Connection is being rejected due to overflow of a limit.
.TP
\fBNS_CONN_TIMEOUT\fR
Connection has timed out waiting for service.
.TP
\fBNS_CONN_GZIP\fR
Connection content will be compressed if possible.
.TP
\fBNS_CONN_CHUNK\fR
Content is being sent in chunked encoding mode.

.PP
These flags should be considered read-only.  Use the corresponding
routines, e.g., \fBNs_ConnSetKeepAlive\fR, to set the flags if
necessary.

.SH "CONNECTION ACCESS ROUTINES"
In addition to the public fields, the routines above can be used
to access data contained in the private components of the connection
(in retrospect, all fields should have been private).

.TP
char *\fBNs_ConnAuthPasswd\fR
Returns the \fIauthPassword\fR field for the \fINs_Conn\fR stucture.

.TP
char *\fBNs_ConnAuthUser\fR
Returns the \fIauthUser\fR field for the \fINs_Conn\fR stucture.

.TP
Ns_Set *\fBNs_ConnHeaders\fR
Returns the \fIheaders\fR field for the \fINs_Conn\fR stucture.

.TP
char *\fBNs_ConnHost\fR
Returns the IP address as a string that the communications driver
is listening on, e.g., \fI127.0.0.1\fR for a server listening for
connectionsn on \fIlocalhost\fR.

.TP
int \fBNs_ConnId\fR
Returns a unique integer ID for the connection.  The ids start at
zero and increase monotonically with each new connection accepted
by the server.

.TP
char *\fBNs_ConnLocation\fR
Returns a pointer to a string which is the HTTP location for the
connection, e.g., \fIhttp://www.mysite.com\fR.  The string can be
helpful to construct redirect messages.

.TP
Ns_Set *\fBNs_ConnOutputHeaders\fR
Returns the \fIoutputHeaders\fR field for the \fINs_Conn\fR stucture.

.TP
char *\fBNs_ConnPeer\fR
Returns a string with an IP address for the remote end of the
connection (e.g., the users browser).  Note this could also be the
IP address of a proxy server.

.TP
int \fBNs_ConnPeerPort\fR
Returns the port of the remote end of the connection.

.TP
int \fBNs_ConnPort\fR
Returns the port for the server end point of the connection, by
default port 80.

.TP
int \fBNs_ConnResponseLength\fR
Returns the length of content sent to the client.  The result will
be zero until a result has been generated.

.TP
int \fBNs_ConnResponseStatus\fR
Returns the HTTP status code of the responses sent to the client,
200 for normal responses.

.TP
char *\fBNs_ConnServer\fR
Returns a pointer to the string name of the virtual server used for
the connection. This string can then be passed to other virtual
server specific routines, e.g., \fBNs_TclAllocateInterp\fR.

.TP
int \fBNs_ConnSock\fR
Returns the underlying socket file descriptor for the connection.
This can be useful for diagnostic or introspection routines (e.g.,
getpeername). It should otherwise not be manipulated or closed.

.SH "SEE ALSO"
Ns_Set(3), Ns_ConnContent(3), Ns_ConnGetQuery(3), Ns_ParseRequest(3),
ns_conn(n)

.SH KEYWORDS
connection, location, headers