View source for 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 ''option''s (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 [http://www.tcl.tk/man/tcl8.4/TclCmd/encoding.htm 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:
 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

* '''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_urldecode]]d 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 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 [http://www.tcl.tk/man/tcl8.4/TclCmd/encoding.htm 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]]


[[Category:Core Tcl API]]