Request data handling

Request data handling
Prev	QuickRef / Websh	Next

web::request

web::request ?options? ?key? ?value?

web::request ?key? ?default?

Options are: -count, -set, -lappend, -names, -unset, -reset and -channel

web::request is an accessor to request specific information: either CGI related (stand alone Websh) or Apache related (mod_websh).

web::request -names: returns a list of all known keys.
web::request key ?default?: returns the value for key. Can be a list. In case that key does not exist, return default, if it is given, or an empty string.
web::request -count key: returns number of items in list for key; returns 0 if key does not exist.
web::request -set key: does the same as web::request key.
web::request -set key value ?value? ?...?: adds the parameter key to the web::request data. Any existing parameters with key are overwritten.
web::request -lappend key value ?value? ?...?: append parameters with the same key to the web::request data. In this case the existing value is not overwritten.
web::request -unset: deletes all parameters from the web::request data.
web::request -unset key: deletes a parameter from the web::request data.
web::request -reset: deletes all parameters from the web::request data (like 'web::request -unset'), removes all static parameters (like 'web::cmdurlcfg -unset'), all form variables (like 'web::formvar -unset'), all query string parameters (like 'web::param -unset'), and all temporary files created by HTTP form upload.
web::request -channel: returns the preset default channel for the current request. (Note that this is not necessarily the currently selected channel.)

Special case for handling Basic Auth:

web::request AUTH_USER: returns the username provided by the user when Basic Auth is requested and Apache does not handle it (i.e. if Apache does not provide REMOTE_USER).
web::request AUTH_PW: returns the password provided by the user when Basic Auth is requested and Apache does not handle it (i.e. if Apache does not provide REMOTE_USER).

The following example provides a basic app that requires Basic Auth and completely bypasses Apache's auth mechanisms.

Example 7. web::request AUTH_USER and web::request AUTH_PW

# returns 1 if user/pass provided is websh/websh
proc isAuthenticated {} {
    if {[web::request -count AUTH_USER]} {
	set user [web::request AUTH_USER]
	set pass [web::request AUTH_PW]
	if {[string eq $user "websh"] && [string eq $pass "websh"]} {
	    return 1
	}
    }
    return 0
}

# the default command requests Basic Auth unless provided correctly
web::command default {
    if {![isAuthenticated]} {
	web::response -set Status {401 Authorization Required}
	web::response -set WWW-Authenticate {Basic realm="Websh auth"}
	web::put "Sorry, you're out"
    } else {
	web::put "You're in"
    }
}

# command dispath
web::dispatch

Note: CGI usually does not expose the Basic Auth Authorization header for security reasons. The following configuration for Apache (as of version 2.0.51) will allow Websh to also provide the same functionality when running in CGI (requires mod_setenvif):

Example 8. Apache configuration for AUTH_USER and AUTH_PW to work under CGI

SetEnvIf Authorization "^(Basic .+)$" AUTH_BASIC=$1

Important security consideration: This configuration will also expose the authentication information to Websh when Apache does handle the authentication. Although Websh hides the information in that case, it is always available in the CGI environment. Use this configuration carefully!

web::param

web::param ?option? ?key? ?value? ?...?

Options are: -count, -set, -lappend, -names, and -unset

web::param is an accessor to state information from the querystring. Suppose the querystring is "lang=EN". After web::dispatch has parsed the querystring, web::param lang will report EN. Additionaly, web::param can manage this data and add, append, and delete parameters as needed.

web::param -names: returns a list of all known keys.
web::param key ?default?: returns the value for key. Can be a list. In case that key does not exist, return default, if it is given, or an empty string.
web::param -count key: returns number of items in list of key.
web::param -set key: does the same as 'web::param key'.
web::param -set key value ?value? ?...?: add the parameter key to the web::param data. Any existing parameters with key are overwritten.
web::param -lappend key value ?value? ?...?: append parameters with the same key to the web::param data. In this case the existing value is not overwritten.
web::param -unset: deletes all parameters from the web::param data.
web::param -unset key: delete a parameter from the web::param data.

web::formvar

web::formvar ?options? ?key? ?value?

Exactly like web::param.

web::formvar is an accessor to HTML FORM data. After web::dispatch has parsed the POST data, you can access all form fields using web::formvar.

In addition to this, web::formvar can also handle files uploaded via Netscape 2.0 file upload mechanism. In this case, the result of web::formvar is a list with four elements: The first element contains the name of the locally saved file; the second element contains the remote file name; the third element is set to 0 if the upload was successful, -1 if upload is disabled (see web::config uploadfilesize) and n > 0 if n Bytes have been truncated, because the file was too big. The last element contains the mime type of the file.

Note that the temporary files are created with the permissions configured by web::config filepermissions, which defaults to 0644.

Example 9. web::param

% web::request CONTENT_LENGTH
% web::dispatch -querystring "cmd=default&t=100" -postdata "" -cmd ""
% web::param -names
t cmd
% web::param cmd
default
% web::param -set k v
v
% web::param -names
t cmd k
%

Prev		Next
Command dispatching and session management	Home QuickRef / Websh	Response data handling