1 <?xml version="1.0" encoding="iso-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml"><head> 4 <title>Request Parameters and Uploads</title> 5 <link href="styles.css" rel="stylesheet" type="text/css" /></head> 6 <body> 7 <h1>Request Parameters and Uploads</h1> 8 <p>Even though it is possible to expose different parts of an 9 application 10 using different <a href="paths.html">URLs and paths</a>, this usually 11 is only 12 enough for applications which model some kind of <a href="paths-filesystem.html">filesystem</a> or repository. 13 Applications which 14 involve user input through forms, for example, need to be able to 15 receive 16 such input by other means, and this is where request parameters come 17 in. For 18 example, when a user fills out a form in a Web browser, the following 19 happens:</p> 20 <ol> 21 <li>The browser collects the values in the form fields and puts them 22 in a request as request parameters.</li> 23 <li>The request is sent to the server environment and into the 24 application.</li> 25 <li>The application reads the field values using the WebStack API.</li> 26 </ol> 27 <h2>Parameter Origins</h2> 28 <p>Request parameters exist in two forms:</p> 29 <ul> 30 <li><a href="parameters-headers.html">Request header parameters</a> - parameters specified in the URL as a 31 "query string".</li> 32 <li><a href="parameters-body.html">Request body parameters</a> - parameters are found in the request body when the POST <a href="methods.html">request method</a> 33 is used.</li> 34 </ul> 35 <p>One useful application of parameters transferred in request bodies 36 is the 37 sending or uploading of file contents through such parameters - this is 38 described in "Request Body Parameters". Another way of uploading 39 content in 40 conjunction with the <code>PUT</code> <a href="methods.html">request 41 method</a> is mentioned below.</p> 42 <div class="WebStack"> 43 <h3>WebStack API - Getting All Parameters</h3> 44 <p>If the origin of the different parameters received in a request is 45 not 46 particularly interesting or important, WebStack provides a convenience 47 method 48 in transaction objects to get all known parameters from a request:</p> 49 <dl> 50 <dt><code>get_fields</code></dt> 51 <dd>This method returns a dictionary mapping field names to lists of 52 values for all known parameters. Each value will be a Unicode object.<br /> 53 An optional <code>encoding</code> parameter may be used to assist the 54 process of converting parameter values to Unicode objects - see <a href="parameters-body.html">"Request Body Parameters"</a> and <a href="encodings.html">"Character Encodings"</a> for more discussion of 55 this parameter.</dd> 56 <dt><code>get_query_string</code></dt> 57 <dd>This method returns the part of the URL which contains parameter 58 information. Such information will be "URL-encoded", meaning that 59 certain characters will have the form <code>%xx</code> where <code>xx</code> 60 is a two digit hexadecimal number referring to the byte value of the 61 unencoded character - see <a href="encodings.html">"Character 62 Encodings"</a> for information on how byte values should be 63 interpreted. </dd> 64 </dl> 65 </div> 66 <p>Generally, it is not recommended to just get all parameters since 67 there 68 may be some parameters from the request headers which have the same 69 names as 70 some other parameters from the request body. Consequently, confusion 71 could 72 arise about the significance of various parameter values.</p> 73 <h2>Using PUT Requests to Upload Files</h2> 74 <p>When handling requests in your application, instead of treating 75 request as 76 containers of parameters and using the WebStack API methods to access 77 those 78 parameters, you can instead choose to read directly from the data sent 79 by the 80 user and interpret that data in your own way. In most situations, this 81 is not 82 really necessary - those methods will decode request parameters (for 83 example, 84 form fields) in a way which is fairly convenient - but when files are 85 being 86 sent, and when the <a href="methods.html">request method</a> is 87 specified as 88 <code>PUT</code>, it is necessary to obtain the input stream from the 89 request 90 and to read the file contents from that stream.</p> 91 <div class="WebStack"> 92 <h3>WebStack API - Reading Directly from Requests</h3> 93 <p>When the request does not contain standard form-encoded parameter 94 information and instead contains the contents of an uploaded file, 95 methods 96 like <code>get_fields</code> and <code>get_fields_from_body</code> 97 should be 98 avoided and other methods in the transaction employed.</p> 99 <dl> 100 <dt><code>get_request_stream</code></dt> 101 <dd>This returns the input stream associated with the request. 102 Reading from this will result in the request body being obtained as a 103 plain Python string.</dd> 104 <dt><code>get_content_type</code></dt> 105 <dd>This returns a content type object (typically <code>WebStack.Generic.ContentType</code>) 106 which describes the request body's contents.</dd> 107 </dl> 108 </div> 109 <p>The purpose and behaviour of <code>PUT</code> <a href="methods.html">request methods</a> is described in the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP 110 specification</a>.</p> 111 </body></html>