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 immediately after the option name (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 flags

Returns the decimal value of the current conn flags, which can have one or more of the following values (AOLserver 4.5+):

set NS_CONN_CLOSED	   0x1
set NS_CONN_SKIPHDRS	   0x2
set NS_CONN_SKIPBODY	   0x4
set NS_CONN_READHDRS	   0x8
set NS_CONN_SENTHDRS	   0x10
set NS_CONN_KEEPALIVE	   0x20
set NS_CONN_WRITE_ENCODED  0x40
set NS_CONN_FILECONTENT    0x80
set NS_CONN_RUNNING        0x100
set NS_CONN_OVERFLOW	   0x200
set NS_CONN_TIMEOUT	   0x400
set NS_CONN_GZIP	   0x800
set NS_CONN_CHUNK	   0x1000

if {[ns_conn flags] & $NS_CONN_FILECONTENT} {
    # get content from temp file with [ns_conn contentchannel]
}

• 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 UNLESS you change the charset/urlencoding in between with ns_conn urlencoding, ns_getform (with charset specified) or ns_urlcharset.

For GET requests, parameters passed in the query string are parsed into the ns_set in order of appearance in the URI. For application/x-www-form-urlencoded (i.e. normal) POST requests, parameters passed on the query string are ignored (you can still access them with ns_conn query). Form inputs are parsed into the ns_set in order of appearance in the client request. This is usually, but not always, in order of appearance in the DOM of the HTML document, but it depends on the client (i.e. browser) rather than the server. For both querystring and formdata, both keys and values are ns_urldecoded and converted to UTF from the character encoding previously set with ns_conn urlencoding or ns_urlcharset.

• 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 id

Returns the integer portion of the connid of the current connection and can serve as a counter of serviced connections from startup. In AOLserver 4.0, the counter was per-pool, per virtual server and only got incremented for successfully queued connections. In AOLserver 4.5 connids are now process-wide global for all pools and provide a counter of all requests, including those that did not get to be queued and processed.

• 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 peerport
• 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 server

Returns the virtual server name - same as ns_info server

• 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 status ?code?

If code is specified, sets (and returns) the status code that will be used in the HTTP response. If omitted, returns the previously set status or 0 if one has not yet been set. The status code is not used in ns_return* responses but is used by the first call to ns_adp_flush or ns_adp_close or in general when an adp file is requested. You can use this to set the status code in an adp designated as a 404 redirect, for example.

• ns_conn times

New in 4.5.2: Returns a map (list in array get format) with accept, read, ready, queue, run and close timestamps in ns_time get format for the current connection. queue is the same as what's returned by ns_conn start. accept is actually the timestamp for the socket accept and so isn't guaranteed to be specific to this particular connection.

• ns_conn urlencoding ?tclencoding?

Returns the TCL-encoding for the connection which is used to convert input forms and query strings to proper UTF. Or if tclencoding is specified, changes the encoding that will be used by subsequent calls to ns_conn form, etc. If you previously used ns_getform or ns_getformfile for processing multipart file upload submissions (which you can determine with ns_isformcached, after changing the encoding, you should call ns_resetcachedform. Alternatively, use the ns_urlcharset wrapper to set the urlencoding from a mime charset (as opposed to a tclencoding) and it will call it for you.

• 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 ?index?

Returns a list containing the pieces of the URL delimited by `/' or if index is specified, returns only the indexth element of that list. Only integer indexes are supported, 'end' is not.

• ns_conn version

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

• ns_conn write_encoded ?0|1?

Gets or Sets the NS_CONN_WRITE_ENCODED flag which is used to tell ns_write that the content is not binary and is safe to encode. This option has been removed in NaviServer which automatically detects when trying to ns_write binary content. Usually, you do not need to call this yourself and you will use ns_startcontent to set this flag for you instead. However, in AOLserver 4.5, ns_startcontent's behavior has changed, so it may be convenient to use this option to reimplement ns_startcontent to be backward compatible as follows:

 if {[ns_info version] >= 4.5} {
   catch {rename ns_startcontent {}}
   proc ns_startcontent {args} {
   #
   # Re-implement ns_startcontent in Tcl in AOLserver 4.5
   # because the -type option no longer falls back to
   # server's default encoding like it did in 4.0.
   # Luckily, in 4.5, ns_adp_mimetype now just
   # calls Ns_ConnSetType() which still does
   # and works outside of adps
   #
       if {[llength $args]} {
           switch [string range [lindex $args 0] 1 end] {
               charset {
                   ns_conn encoding [ns_encodingforcharset [lindex $args 1]]
               }
               type {
                   ns_adp_mimetype [lindex $args 1]
               }
           }
       }
       # NaviServer removed write_encoded
       catch {ns_conn write_encoded 1}
       return ""
   }
 }

EXAMPLES

SEE ALSO

ns_getform, ns_queryget, ns_time

---