WebStack

docs/headers.html

755:139b1412b9c3
2008-02-03 paulb [project @ 2008-02-03 19:58:01 by paulb] Added measures to permit the usage of non-ASCII characters in plaintexts.
     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   <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />     5   <title>Request Headers</title>     6   <link href="styles.css" rel="stylesheet" type="text/css" /></head>     7 <body>     8 <h1>Request Headers</h1>     9     10 <p>Request headers are pieces of information that describe certain aspects of a request, such as:</p>    11 <ul>    12   <li>The location to which the request is being sent.</li>    13   <li>The type of information in the request body.</li>    14   <li>Preferences about which kinds of information the sender would like to receive in return.</li>    15 </ul>    16 <p>The location and related query information is conveniently accessible through <a href="paths.html">path</a> information and <a href="parameters-headers.html">request header parameter</a> information. Other types of header information are made available through other WebStack API methods.</p>    17 <h2>Content Types</h2>    18 <p>When a Web application sends some information in a response, it    19 describes the content type of that information, and this is described    20 in the "Responses and Presentation" document. However, it is also    21 possible that information sent to the application is also described    22 using a content type, and such details may be investigated using code    23 similar to the following:</p>    24     25 <pre>class MyResource:<br />    def respond(self, trans):<br />        content_type = trans.get_content_type()   # returns a WebStack.Generic.ContentType object</pre>    26     27 <p>Unfortunately, such information is not always provided by Web browsers.</p>    28 <h2>Content Preferences</h2>    29 <p>Sometimes, Web browsers describe the kinds of information that    30 they are willing to receive, and WebStack provides various means to    31 query such preferences:</p>    32     33 <pre>        languages = trans.get_content_languages() # returns a list of language codes<br />        charsets = trans.get_content_charsets()   # returns a list of character set identifiers<br /></pre>    34 <p>This information permits us to send content which matches the    35 expectations of the user, or at least the expectations of the user's    36 software.</p>    37 <h2>Other Headers</h2>    38 <p>Various other pieces of information may be attached to the request    39 as headers, and such information can be accessed through the general    40 header access methods as described below. Each header has a particular    41 name which is associated with a corresponding value.</p>    42 <div class="WebStack">    43 <h3>WebStack API - Accessing Header Information</h3>    44     45 <p>Transaction objects provide the following methods to access request header information:</p>    46 <dl>    47   <dt><code>get_headers</code></dt>    48     <dd>This returns a    49       dictionary mapping header names to single string values.<br />    50 </dd>    51   <dt><code>get_header_values</code></dt>    52     <dd>Given a header name as parameter, this method returns a list of string values associated with that name.</dd><dt><code>get_content_type</code></dt>    53   <dd>This returns a content type object (typically <code>WebStack.Generic.ContentType</code>) describing the incoming request body content.</dd>    54   <dt><code>get_content_languages</code></dt>    55   <dd>This returns a list of language identifiers, in descending order    56 of preference, indicating in which languages the sender of the request    57 would prefer to receive information.</dd>    58   <dt><code>get_content_charsets</code></dt>    59   <dd>This returns a list of character set identifiers, in descending    60 order of preference, indicating in which character sets the sender of    61 the request would prefer to receive information.</dd>    62     63 </dl>    64 <p>It should be noted that the <code>get_headers</code> and <code>get_header_values</code> methods    65 present a slightly different view of the available header information,    66 in that only a single header value is made available through the <code>get_headers</code> method for each header name, whereas <code>get_header_values</code> provides potentially many values for the same header name. </p>    67     68 </div></body></html>