Ns conn

From AOLserver Wiki
Revision as of 00:53, 11 October 2009 by Akhassin (talk | contribs)
Jump to navigation Jump to search

<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. If you modify the ns_set returned by ns_conn form, subsequent calls to ns_conn form will return the same ns_set id and
  • 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