Ns conn

<manpage>ns_conn</manpage>

NAME

ns_conn - Find information about the current HTTP connection.

SYNOPSIS

ns_conn option ?arg arg ...?

DESCRIPTION

This command is used to retrieve various pieces of information about a connection. For backward compatibility with AOLserver 2.x, ns_conn command can accept an optional deprecated connid argument (i.e. [ns_conn form $connid]). With the exception of the isconnected option, ns_conn will throw an error if there is no connection.

The legal options (which may be abbreviated) are:

• ns_conn authpassword

Returns the decoded user password from the authorization data.

• ns_conn authuser

Returns the decoded user name from the authorization data.

• ns_conn channel

New in 4.5.1: Return a Tcl channel from the current connection. This channel can be used to talk via raw Tcl I/O to the remote client afterwards. Output cannot be mixed with ns_write.

• ns_conn close

Closes the connection so the script (or ADP) can do any time-consuming processing without making the client wait. If you use ns_conn close in an ADP, streaming should be turned on before closing the connection (i.e. <SCRIPT RUNAT=SERVER STREAM=ON>) or nothing will get sent out at all.

• ns_conn content ?offset? ?length?

Returns the content of the HTTP request body, optionally a substring of that content starting at offset and extending length characters.

• ns_conn contentchannel

New in 4.5: Returns a Tcl file channel to a temporary file containing the content of the HTTP request body. This is most useful for large POSTs that AOLserver 4.5+ spools to this temporary file when the contentlength exceeds the driver maxinput parameter. If AOLserver did not create the temporary file when processing a connection and you call this command, the temporary file is created and current request content is written to it. Since the content was already in memory, this is probably undesirable. To avoid this, prior to calling ns_conn contentchannel, check for the NS_CONN_FILECONTENT flag (see examples under the flags option). Note that both this option and the entire temporary file spooling mechanism is currently (as of 4.5.1) non-functional on Windows. In NaviServer, this option is absent and there is a similar but not identical option called contentfile, which returns the name of the temporary file if content was spooled to it (if not on Windows and contentlength exceeded driver maxupload parameter) but you have to delete it yourself when done.

• ns_conn contentlength

Returns the number of bytes in the content passed in.

• ns_conn contentsentlength ?bytes?

New in 4.5.1: Query or set the number of octets sent to the client. This command can be used in connection with "ns_conn channel" to adjust the length entry in a log file in cases, the file was sent via raw Tcl I/O.

• ns_conn copy off len chan

Copies data from the current connection to chan starting at byte off for len bytes - mostly for internal use by ns_getform and ns_getformfile

• ns_conn driver

Returns the name of the module (nssock or nsssl) that is acting as the communications driver for this connection.

• ns_conn encoding

Returns the TCL-encoding for the connection which is used to convert the output of ns_write.

• ns_conn files
• ns_conn fileoffset fileUploadFormFieldName
• ns_conn filelength fileUploadFormFieldName
• ns_conn fileheaders fileUploadFormFieldName

These four options are mostly for internal use by ns_getform and ns_getformfile for processing multi-part form submissions (i.e. browser file uploads)

• ns_conn form

Returns any submitted form data as an ns_set. This form data may have been submitted with a POST or appended to the URL in a GET request. Note: ns_conn form is not suitable for multipart formdata file upload widgets - use the ns_getform wrapper instead. In AOLserver versions prior to 4.0, this returned a blank string if there was no formdata or querystring but now it always returns a valid ns_set. You can modify the ns_set returned by ns_conn form and subsequent calls to ns_conn form in this connection will return the same ns_set id and will retain your modifications.

• ns_conn headers

Returns all the header data as an ns_set. The keys of the ns_set represent the field names. The case of the returned field names depends on the HeaderCase configuration parameter. By default, HeaderCase is "Preserve", which means case is preserved.

• ns_conn host

Returns the host part of the URL in the HTTP request.

• ns_conn isconnected

Returns 1 if you're in a connection thread, and you are therefore allowed to make calls to ns_conn. It returns 0 if you're not in a connection thread (such as when you're in a schedule procedure) and you are not allowed to make calls to ns_conn.

• ns_conn location

Returns the location string for this virtual server in the form: protocol://hostname[:port] as configured for the driver (may be different from the actual Host header).

• ns_conn method

Returns the HTTP method, e.g. GET.

• ns_conn outputheaders

Returns an ns_set that will be used in building the headers that will be sent out when a result is returned to the client. This ns_set can be manipulated like any other ns_set. You can also use this command to write to the set of output headers. For example: ns_set put [ns_conn outputheaders] key value. Keys that exist in the standard set of output headers will be overwritten by user-specified values in this ns_set if any.

• ns_conn peeraddr

Returns the IP address of the client, i.e. the "other side" of the HTTP connection. The IP address is returned in the form of a string separated with periods (e.g., 155.164.59.75).

• ns_conn port

Returns the port specified explicitly in the URL of the HTTP request. If the browser does not explicity send the ":port" part of the URL, the port number returned will be 0.

• ns_conn protocol

Returns the protocol of the URL in the HTTP request (usually unspecified).

• ns_conn query

Returns any query data that was part of the HTTP request.

• ns_conn request

Returns the HTTP request line as presented by the client, e.g. GET / HTTP/1.1.

• ns_conn start

Returns the time the connection request started in "sec:usec" (aka ns_time) format.

• ns_conn sock

Returns the underlying socket for the connection.

• ns_conn urlencoding

Returns the TCL-encoding for the connection which is used to convert input forms to proper UTF.

• ns_conn url

Returns the URL of the HTTP request. This is the portion of the request after the hostname, for example [ns_conn url] on http://aolserver.com/ returns /index.adp.

• ns_conn urlc

Returns the number of elements (delimited by `/') in the URL of the HTTP request.

• ns_conn urlv

Returns a list containing the pieces of the URL delimited by `/'.

• ns_conn version

Returns the version of the HTTP request. This is usually 1.0 or 1.1.

EXAMPLES

SEE ALSO

ns_getform, ns_queryget, ns_time