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