Ns_Conn(3)

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

SYNOPSIS
#include "ns.h"

char *
Ns_ConnAuthPasswd(Ns_Conn *conn)

char *
Ns_ConnAuthUser(Ns_Conn *conn)

Ns_Set *
Ns_ConnHeaders(Ns_Conn *conn)

char *
Ns_ConnHost(Ns_Conn *conn)

int
Ns_ConnId(Ns_Conn *conn)

char *
Ns_ConnLocation(Ns_Conn *conn)

Ns_Set *
Ns_ConnOutputHeaders(Ns_Conn *conn)

char *
Ns_ConnPeer(Ns_Conn *conn)

int
Ns_ConnPeerPort(Ns_Conn *conn)

int
Ns_ConnPort(Ns_Conn *conn)

int
Ns_ConnResponseLength(Ns_Conn *conn)

int
Ns_ConnResponseStatus(Ns_Conn *conn)

char *
Ns_ConnServer(Ns_Conn *conn)

int
Ns_ConnSock(Ns_Conn *conn)

ARGUMENTS
Pointer to given connection.

DESCRIPTION

These routines provide access to data stored within an active connection. All routines take as an argument a pointer to an Ns_Conn structure which is setup by the server and passed to request handling procedures.

THE NS_CONN STRUCTURE

The Ns_Conn structure includes the following fields:

typedef struct Ns_Conn {
    Ns_Request *request;
    Ns_Set *headers;
    Ns_Set *outputheaders;
    char *authUser;
    char *authPasswd;
    int contentLength;
    int flags; } Ns_Conn;

All fields of an Ns_Conn structure should be considered read-only. The request field contains a pointer to the parsed HTTP request. See the manual page for Ns_ParseRequest for details on what it contains.

The headers and outputHeaders fields point to Ns_Set structures for the input and output headers, respectively. The outputHeaders set will generally not contain any fields until after the request has been processed. See the manual page on Ns_Set for details on the fields of the structure and routines to access and manipulate them.

The authUser and authPasswd fields point to the decoded username and password for the request or NULL if no authorization was sent.

The contentLength field is the length of the content, if any, sent with the request. See the man page on Ns_ConnContent for details on accessing the content.

The flags field is a bitmask with one or more NS_CONN bits:

NS_CONN_CLOSED
    Connection is closed.

NS_CONN_SKIPHDRS
    Pre-HTTP/1.0 connection which will not return headers.

NS_CONN_SKIPBODY
    HTTP HEAD request which will return no content.

NS_CONN_READHDRS
    Headers have been read (noramlly set).

NS_CONN_SENTHDRS
    Result headers have been sent.

NS_CONN_KEEPALIVE
    Connection should be kept alive for another request if possible.

NS_CONN_WRITE_ENCODED
    Output could be encoded when directly sent.

NS_CONN_FILECONTENT
    Connection contains content originally in a temp file.

NS_CONN_RUNNING
    Connection is currently active in a request thread.

NS_CONN_OVERFLOW
    Connection is being rejected due to overflow of a limit.

NS_CONN_TIMEOUT
    Connection has timed out waiting for service.

NS_CONN_GZIP
    Connection content will be compressed if possible.

NS_CONN_CHUNK
    Content is being sent in chunked encoding mode.

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

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).

char *Ns_ConnAuthPasswd
    Returns the authPassword field for the Ns_Conn stucture.

char *Ns_ConnAuthUser
    Returns the authUser field for the Ns_Conn stucture.

Ns_Set *Ns_ConnHeaders
    Returns the headers field for the Ns_Conn stucture.

char *Ns_ConnHost
    Returns the IP address as a string that the communications driver is listening on, e.g., 127.0.0.1 for a server listening for connectionsn on localhost.

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

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

Ns_Set *Ns_ConnOutputHeaders
    Returns the outputHeaders field for the Ns_Conn stucture.

char *Ns_ConnPeer
    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.

int Ns_ConnPeerPort
    Returns the port of the remote end of the connection.

int Ns_ConnPort
    Returns the port for the server end point of the connection, by default port 80.

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

int Ns_ConnResponseStatus
    Returns the HTTP status code of the responses sent to the client, 200 for normal responses.

char *Ns_ConnServer
    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., Ns_TclAllocateInterp.

int Ns_ConnSock
    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.

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

KEYWORDS
connection, location, headers