1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/headers.html Tue Sep 06 22:04:08 2005 +0000
1.3 @@ -0,0 +1,70 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml"><head>
1.6 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.7 +
1.8 +
1.9 + <title>Request Headers</title><meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.10 + <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.11 +<body>
1.12 +<h1>Request Headers</h1>
1.13 +
1.14 +
1.15 +<p>Request headers are pieces of information that describe certain aspects of a request, such as:</p>
1.16 +<ul>
1.17 + <li>The location to which the request is being sent.</li>
1.18 + <li>The type of information in the request body.</li>
1.19 + <li>Preferences about which kinds of information the sender would like to receive in return.</li>
1.20 +</ul>
1.21 +<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>
1.22 +<h2>Content Types</h2>
1.23 +<p>When a Web application sends some information in a response, it
1.24 +describes the content type of that information, and this is described
1.25 +in the "Responses and Presentation" document. However, it is also
1.26 +possible that information sent to the application is also described
1.27 +using a content type, and such details may be investigated using code
1.28 +similar to the following:</p>
1.29 +
1.30 +<pre>class MyResource:<br /> def respond(self, trans):<br /> content_type = trans.get_content_type() # returns a WebStack.Generic.ContentType object</pre>
1.31 +
1.32 +<p>Unfortunately, such information is not always provided by Web browsers.</p>
1.33 +<h2>Content Preferences</h2>
1.34 +<p>Sometimes, Web browsers describe the kinds of information that
1.35 +they are willing to receive, and WebStack provides various means to
1.36 +query such preferences:</p>
1.37 +
1.38 +<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>
1.39 +<p>This information permits us to send content which matches the
1.40 +expectations of the user, or at least the expectations of the user's
1.41 +software.</p>
1.42 +<h2>Other Headers</h2>
1.43 +<p>Various other pieces of information may be attached to the request
1.44 +as headers, and such information can be accessed through the general
1.45 +header access methods as described below. Each header has a particular
1.46 +name which is associated with a corresponding value.</p>
1.47 +<div class="WebStack">
1.48 +<h3>WebStack API - Accessing Header Information</h3>
1.49 +
1.50 +<p>Transaction objects provide the following methods to access request header information:</p>
1.51 +<dl>
1.52 + <dt><code>get_headers</code></dt>
1.53 + <dd>This returns a
1.54 + dictionary mapping header names to single string values.<br />
1.55 +</dd>
1.56 + <dt><code>get_header_values</code></dt>
1.57 + <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>
1.58 + <dd>This returns a content type object (typically <code>WebStack.Generic.ContentType</code>) describing the incoming request body content.</dd>
1.59 + <dt><code>get_content_languages</code></dt>
1.60 + <dd>This returns a list of language identifiers, in descending order
1.61 +of preference, indicating in which languages the sender of the request
1.62 +would prefer to receive information.</dd>
1.63 + <dt><code>get_content_charsets</code></dt>
1.64 + <dd>This returns a list of character set identifiers, in descending
1.65 +order of preference, indicating in which character sets the sender of
1.66 +the request would prefer to receive information.</dd>
1.67 +
1.68 +</dl>
1.69 +<p>It should be noted that the <code>get_headers</code> and <code>get_header_values</code> methods
1.70 +present a slightly different view of the available header information,
1.71 +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>
1.72 +
1.73 +</div></body></html>
1.74 \ No newline at end of file