mthl
/
texinfo


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418
							<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Functions for accessing HTTP requests</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Overall-Index.xhtml" title="Index"/>
    <link rel="next" href="HTTP-response.xhtml" title="Generating HTTP responses"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Functions for accessing HTTP requests" epub:type="subchapter" id="HTTP-requests">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Functions for accessing HTTP requests</h2>
          </div>
        </div>
      </div>
      <p>The following functions are useful for accessing
properties of a HTTP request, in a Kawa program that is
run either as a servlet or a CGI script.  These functions
can be used from plain Scheme, from KRL (whether
in BRL-compatible mode or not), and from XQuery.
</p>
      <p>The examples below assume the request <code class="literal">http://example.com:8080/myapp/foo/bar?val1=xyz&amp;val2=abc</code>, where <code class="literal">myapp</code> is the application context.
We also assume that this is handled by a script <code class="literal">foo/+default+</code>.
</p>
      <p>The file <code class="literal">testsuite/webtest/info/+default+</code> in the Kawa source distribution
calls most of these functions.
You can try it as described in <a class="link" href="Self-configuring-page-scripts.xhtml" title="Self-configuring web page scripts">Self-configuring page scripts</a>.
</p>
      <section class="sect2" title="Request URL components" epub:type="division" id="idm139667870271056">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Request URL components</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870269984" class="indexterm"/> <code class="function">request-URI</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the URI of the request, as a value of type <code class="literal">URI</code>.
This excludes the server specification,
but includes the query string.
(It is the combination of CGI variables <code class="literal">SCRIPT_NAME</code>,
<code class="literal">PATH_INFO</code>, and <code class="literal">QUERY_STRING</code>.
Using servlets terminology, it is the combination of
Context Path, Servlet Path, PathInfo, and Query String.)
</p>
            <pre class="screen">(request-URI) ⇒ "/myapp/foo/bar?val1=xyz&amp;val2=abc"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870264688" class="indexterm"/> <code class="function">request-path</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the URI of the request, as a value of type <code class="literal">URI</code>.
This excludes the server specification and the query string.
Equivalent to <code class="literal">(path-file (request-URI))</code>.
(It is the combination of CGI variables <code class="literal">SCRIPT_NAME</code>, and
<code class="literal">PATH_INFO</code>.
Same as the concatenation of <code class="literal">(request-context-path)</code>,
<code class="literal">(request-script-path)</code>, and <code class="literal">(request-local-path)</code>.
Using servlets terminology, it is the combination of
Context Path, Servlet Path, and PathInfo.)
</p>
            <pre class="screen">(request-path) ⇒ "/myapp/foo/bar"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870258112" class="indexterm"/> <code class="function">request-uri</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>This function is deprecated, because of possible confusion
with <code class="literal">request-URI</code>.  Use <code class="literal">request-path</code> instead.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870254208" class="indexterm"/> <code class="function">request-url</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the complete URL of the request, except the query string.
The result is a <code class="literal">java.lang.StringBuffer</code>.
</p>
            <pre class="screen">(request-url) ⇒ "http://example.com:8080/myapp/foo/bar"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870250352" class="indexterm"/> <code class="function">request-context-path</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the context path, relative to the server root.
This is an initial substring of the <code class="literal">(request-path)</code>.
Similar to the Context Path of a servlet request,
except that it ends with a <code class="literal">"/"</code>.
</p>
            <pre class="screen">(request-context-path) ⇒ "/myapp/"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870246064" class="indexterm"/> <code class="function">request-script-path</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the path of the script, relative to the context.
This is either an empty string, or a string that ends with <code class="literal">"/"</code>,
but does not start with one. (The reason for this is to produce URIs
that work better with operations like <code class="literal">resolve-uri</code>.)
This is conceptually similar to <code class="literal">request-servlet-path</code>,
though not always the same, and the <code class="literal">"/"</code> conventions differ.
</p>
            <pre class="screen">(request-script-path) ⇒ "foo/"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870240768" class="indexterm"/> <code class="function">request-local-path</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the remainder of the <code class="literal">request-path</code>,
relative to the <code class="literal">request-script-path</code>.
</p>
            <pre class="screen">(request-local-path) ⇒ "bar"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870236608" class="indexterm"/> <code class="function">request-query-string</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the query string from an HTTP request.  The query string is
the part of the request URL after a question mark.
Returns false if there was no query string.
Corresponds to the CGI variable <code class="literal">QUERY_STRING</code>.
</p>
            <pre class="screen">(request-query-string) ⇒ "val1=xyz&amp;val2=abc"
</pre>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Request parameters" epub:type="division" id="idm139667870232736">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Request parameters</h3>
            </div>
          </div>
        </div>
        <p>Request parameters are used for data returned from forms,
and for other uses.
They may be encoded in the query string or in the request body.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870231120" class="indexterm"/> <code class="function">request-parameter</code> <em class="replaceable"><code>name</code></em> [<em class="replaceable"><code>default</code></em>]</p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>If there is a parameter with the given name (a string),
return the (first) corresponding value, as a string.
Otherwise, return the <em class="replaceable"><code>default</code></em> value,
or <code class="literal">#!null</code> if there is no <em class="replaceable"><code>default</code></em>.
</p>
            <pre class="screen">(request-parameter "val1") ⇒ "xyz"
(request-parameter "val9" "(missing)") ⇒ "(missing)"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870225376" class="indexterm"/> <code class="function">request-parameters</code> <em class="replaceable"><code>name</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>If there is are one or more parameter with the given name (a string),
return them all (as multiple values).
Otherwise, return no values (i.e. <code class="literal">(values)</code>).
</p>
            <pre class="screen">(request-parameters "val1") ⇒ "xyz"
(request-parameters "val9") ⇒ #!void
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870221056" class="indexterm"/> <code class="function">request-parameter-map</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Request a map of all the parameters.
This is a map from strings to a sequence of strings.
(Specifically, a <code class="literal">java.util.Map&lt;String,java.util.List&lt;String&gt;&gt;</code>.)
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Request headers" epub:type="division" id="idm139667870217504">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Request headers</h3>
            </div>
          </div>
        </div>
        <p>The request headers are a set of (keyword, string)-pairs
transmitted as part of the HTTP request, before the request body.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870215904" class="indexterm"/> <code class="function">request-header</code> <em class="replaceable"><code>name</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>If there is a header with the given <em class="replaceable"><code>name</code></em> (a string),
return the corresponding value string.
Otherwise, return <code class="literal">#!null</code>.
</p>
            <pre class="screen">(request-header "accept-language") ⇒ "en-us,en;q=0.5"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870211248" class="indexterm"/> <code class="function">request-header-map</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Request a map of all the headers.
This is a map from strings to a sequence of strings.
(Specifically, a <code class="literal">java.util.Map&lt;String,java.util.List&lt;String&gt;&gt;</code>.)
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Request body" epub:type="division" id="idm139667870207696">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Request body</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870206624" class="indexterm"/> <code class="function">request-input-port</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Return a textual input port for reading the request body,
as a sequence of characters.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870203600" class="indexterm"/> <code class="function">request-input-stream</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Return a binary input stream for reading the request body,
as a sequence of bytes.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870200576" class="indexterm"/> <code class="function">request-body-string</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Return the entire request body as a string
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Request IP addresses and ports" epub:type="division" id="idm139667870197584">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Request IP addresses and ports</h3>
            </div>
          </div>
        </div>
        <p>Information about the interface and port on which the request was received.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870196016" class="indexterm"/> <code class="function">request-local-socket-address</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>The local address on which the request was received.
This is the combination of <code class="literal">(request-local-host)</code>
and <code class="literal">(request-local-port)</code>, as an instance of
<code class="literal">java.net.InetSocketAddress</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870191760" class="indexterm"/> <code class="function">request-local-host</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Get the IP address of the interface on which request was received,
as an <code class="literal">java.net.InetAddress</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870188448" class="indexterm"/> <code class="function">request-local-IP-address</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Get the IP address of the interface on which request was received,
a string in numeric form:
</p>
            <pre class="screen">(request-local-host) ⇒ "127.0.0.1"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870185184" class="indexterm"/> <code class="function">request-local-port</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Get the port this request was received on.
</p>
            <pre class="screen">(request-local-port) ⇒ 8080
</pre>
          </blockquote>
        </div>
        <p>Information about the interface and port of the remote client that invoked the request.
</p>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870181376" class="indexterm"/> <code class="function">request-remote-socket-address</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>The address of the remote client (usually a web browser)
which invoked the request.
This is the combination of <code class="literal">(request-remove-host)</code>
and <code class="literal">(request-remote-port)</code>, as an instance of
<code class="literal">java.net.InetSocketAddress</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870177088" class="indexterm"/> <code class="function">request-remote-host</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Get the IP address of the remote client which invoked the request,
as an <code class="literal">java.net.InetAddress</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870173776" class="indexterm"/> <code class="function">request-remote-IP-address</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Get the IP address of the remote client which invoked the request,
as a string in numeric form.
</p>
            <pre class="screen">(request-remote-host) ⇒ "123.45.6.7"
</pre>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870170512" class="indexterm"/> <code class="function">request-remote-port</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>The port used by the remote client.
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Miscellaneous request properties" epub:type="division" id="idm139667870167536">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Miscellaneous request properties</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870166448" class="indexterm"/> <code class="function">request-path-translated</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Map the request-path to a file name (a string)
in the server application directory.
Corresponds to the CGI variable <code class="literal">PATH_TRANSLATED</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870162976" class="indexterm"/> <code class="function">request-method</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the method of the HTTP request, usually <code class="literal">"GET"</code>
or <code class="literal">"POST"</code>.  Corresponds to the CGI variable <code class="literal">REQUEST_METHOD</code>.
</p>
          </blockquote>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667870158656" class="indexterm"/> <code class="function">request-scheme</code></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Returns the scheme (protocol) of the request.
Usually <code class="literal">"http"</code>, or <code class="literal">"https"</code>.
</p>
          </blockquote>
        </div>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="HTTP-requests.xhtml#idm139667870271056">Request URL components</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="HTTP-requests.xhtml#idm139667870232736">Request parameters</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="HTTP-requests.xhtml#idm139667870217504">Request headers</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="HTTP-requests.xhtml#idm139667870207696">Request body</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="HTTP-requests.xhtml#idm139667870197584">Request IP addresses and ports</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="HTTP-requests.xhtml#idm139667870167536">Miscellaneous request properties</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="XML-tools.xhtml">Working with XML and HTML</a></p>
        <p>
        Previous: <a accesskey="p" href="CGI-scripts.xhtml">Installing Kawa programs as CGI scripts</a></p>
        <p>
        Next: <a accesskey="n" href="HTTP-response.xhtml">Generating HTTP responses</a></p>
      </div>
    </footer>
  </body>
</html>