websh/quickref/request_data

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Request data handling</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.1"><link rel="home" href="index.html" title="Websh Reference 3.6.0b5"><link rel="up" href="index.html" title="Websh Reference 3.6.0b5"><link rel="prev" href="command_dispatching_and_session_management.html" title="Command dispatching and session management"><link rel="next" href="response_data_handling.html" title="Response data handling"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Request data handling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="command_dispatching_and_session_management.html">Prev</a>�</td><th width="60%" align="center">�</th><td width="20%" align="right">�<a accesskey="n" href="response_data_handling.html">Next</a></td></tr></table><hr></div><div class="section" title="Request data handling"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="request_data_handling"></a>Request data handling</h2></div></div></div><div class="section" title="web::request"><div class="titlepage"><div><div><h3 class="title"><a name="web::request"></a><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::request</code></span> ?<em class="replaceable"><code>options</code></em>? ?<em class="replaceable"><code>key</code></em>? ?<em class="replaceable"><code>value</code></em>?</span></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::request</code></span> ?<em class="replaceable"><code>key</code></em>? ?<em class="replaceable"><code>default</code></em>?</span></div><p style="width:90%"> </p><p style="width:90%"> Options are: <tt>-count</tt>, <tt>-set</tt>, <tt>-lappend</tt>, <tt>-names</tt>, <tt>-unset</tt>, <tt>-reset</tt> and <tt>-channel</tt> </p><p style="width:90%"> <span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> is an accessor to request specific information: either CGI related (stand alone Websh) or Apache related (mod_websh). </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>-names</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns a list of all known keys. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt><em class="replaceable"><code>key</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>default</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the value for <tt>key</tt>. Can be a list. In case that <tt>key</tt> does not exist, return <tt>default</tt>, if it is given, or an empty string. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>-count</tt> <tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns number of items in list for <tt>key</tt>; returns 0 if <tt>key</tt> does not exist. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>-set</tt> <tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Does the same as <span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>key</tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>-set</tt> <tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>? ?<span class="optional"><tt><em class="replaceable"><code>...</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Adds the parameter <tt>key</tt> to the <span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> data. Any existing parameters with <tt>key</tt> are overwritten. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>-lappend</tt> <tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>? ?<span class="optional"><tt><em class="replaceable"><code>...</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Appends parameters with the same <tt>key</tt> to the <span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> data. In this case the existing <tt>value</tt> is not overwritten. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>-unset</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Deletes all parameters from the <span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> data. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>-unset</tt> <tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Deletes a parameter from the <span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> data. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>-reset</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Deletes all parameters from the <span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> data (like '<span style="font-family:monospace"><span class="command"><strong>web::request -unset</strong></span></span>'), removes all static parameters (like '<span style="font-family:monospace"><span class="command"><strong>web::cmdurlcfg -unset</strong></span></span>'), all form variables (like '<span style="font-family:monospace"><span class="command"><strong>web::formvar -unset</strong></span></span>'), all query string parameters (like '<span style="font-family:monospace"><span class="command"><strong>web::param -unset</strong></span></span>'), and all temporary files created by HTTP form upload. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>-channel</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the preset default channel for the current request. (Note that this is not necessarily the currently selected channel.) </div></div></dd></dl></div><p style="width:90%"> Special case for handling Basic Auth: </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>AUTH_USER</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> 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). </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::request</strong></span></span> <tt>AUTH_PW</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> 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). </div></div></dd></dl></div><p style="width:90%"> The following example provides a basic app that requires Basic Auth and completely bypasses Apache's auth mechanisms. </p><div class="example"><a name="id2736478"></a><p class="title"><b>Example�7.�<span style="font-family:monospace"><span class="command">web::request AUTH_USER</span></span> and <span style="font-family:monospace"><span class="command">web::request AUTH_PW</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> # 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 </pre></div></div><p style="width:90%"><br class="example-break"> <span class="emphasis"><em>Note:</em></span> 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): </p><div class="example"><a name="id2736538"></a><p class="title"><b>Example�8.�Apache configuration for AUTH_USER and AUTH_PW to work under CGI</b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> SetEnvIf Authorization "^(Basic .+)$" AUTH_BASIC=$1 </pre></div></div><p style="width:90%"><br class="example-break"> <span class="emphasis"><em>Important security consideration:</em></span> 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! </p></div><div class="section" title="web::param"><div class="titlepage"><div><div><h3 class="title"><a name="web::param"></a><span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::param</code></span> ?<em class="replaceable"><code>option</code></em>? ?<em class="replaceable"><code>key</code></em>? ?<em class="replaceable"><code>value</code></em>? ?<em class="replaceable"><code>...</code></em>?</span></div><p style="width:90%"> Options are: <tt>-count</tt>, <tt>-set</tt>, <tt>-lappend</tt>, <tt>-names</tt>, and <tt>-unset</tt> </p><p style="width:90%"> <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> is an accessor to state information from the querystring. Suppose the querystring is "lang=EN". After <span style="font-family:monospace"><span class="command"><strong>web::dispatch</strong></span></span> has parsed the querystring, <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt>lang</tt> will report <code class="literal">EN</code>. Additionaly, <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> can manage this data and add, append, and delete parameters as needed. </p><div class="variablelist"><dl><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt>-names</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns a list of all known keys. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt><em class="replaceable"><code>key</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>default</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns the value for <tt>key</tt>. Can be a list. In case that <tt>key</tt> does not exist, return <tt>default</tt>, if it is given, or an empty string. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt>-count</tt> <tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Returns number of items in list of <tt>key</tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt>-set</tt> <tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Does the same as <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt>key</tt>. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt>-set</tt> <tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>? ?<span class="optional"><tt><em class="replaceable"><code>...</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Adds the parameter <tt>key</tt> to the <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> data. Any existing parameters with <tt>key</tt> are overwritten. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt>-lappend</tt> <tt><em class="replaceable"><code>key</code></em></tt> <tt><em class="replaceable"><code>value</code></em></tt> ?<span class="optional"><tt><em class="replaceable"><code>value</code></em></tt></span>? ?<span class="optional"><tt><em class="replaceable"><code>...</code></em></tt></span>?</span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Appends parameters with the same <tt>key</tt> to the <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> data. In this case the existing <tt>value</tt> is not overwritten. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt>-unset</tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Deletes all parameters from the <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> data. </div></div></dd><dt><span style="background:#bbbbff"><span class="term"><span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> <tt>-unset</tt> <tt><em class="replaceable"><code>key</code></em></tt></span></span></dt><dd><div style="padding:4 ; margin-top:3 ; margin-bottom:3 ; width:75%"><div style="margin-bottom:6"> Deletes a parameter from the <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span> data. </div></div></dd></dl></div><p style="width:90%"> </p></div><div class="section" title="web::formvar"><div class="titlepage"><div><div><h3 class="title"><a name="web::formvar"></a><span style="font-family:monospace"><span class="command"><strong>web::formvar</strong></span></span></h3></div></div></div><p style="width:90%"> </p><div class="cmdsynopsis"><span style="background:#bbbbff"><span style="font-weight:bold"><code class="command">web::formvar</code></span> ?<em class="replaceable"><code>options</code></em>? ?<em class="replaceable"><code>key</code></em>? ?<em class="replaceable"><code>value</code></em>?</span></div><p style="width:90%"> </p><p style="width:90%"> Exactly like <span style="font-family:monospace"><span class="command"><strong>web::param</strong></span></span>. </p><p style="width:90%"> <span style="font-family:monospace"><span class="command"><strong>web::formvar</strong></span></span> is an accessor to HTML FORM data. After <span style="font-family:monospace"><span class="command"><strong>web::dispatch</strong></span></span> has parsed the POST data, you can access all form fields using <span style="font-family:monospace"><span class="command"><strong>web::formvar</strong></span></span>. </p><p style="width:90%"> In addition to this, <span style="font-family:monospace"><span class="command"><strong>web::formvar</strong></span></span> can also handle files uploaded via Netscape 2.0 file upload mechanism. In this case, the result of <span style="font-family:monospace"><span class="command"><strong>web::formvar</strong></span></span> 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 <span style="font-family:monospace"><span class="command"><strong>web::config uploadfilesize</strong></span></span>) 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. </p><p style="width:90%"> Note that the temporary files are created with the permissions configured by <span style="font-family:monospace"><span class="command"><strong>web::config filepermissions</strong></span></span>, which defaults to 0644. </p><div class="example"><a name="id2737104"></a><p class="title"><b>Example�9.�<span style="font-family:monospace"><span class="command">web::param</span></span></b></p><div class="example-contents"><pre style="background:#bbffbb ; width:75%" class="programlisting"> % 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 % </pre></div></div><br class="example-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="command_dispatching_and_session_management.html">Prev</a>�</td><td width="20%" align="center">�</td><td width="40%" align="right">�<a accesskey="n" href="response_data_handling.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Command dispatching and session management�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Response data handling</td></tr></table></div></body></html>

websh/quickref/request_data_handling.html (205 lines of code) (raw):