You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bu...@apache.org on 2011/12/19 23:58:08 UTC
svn commit: r800542 [12/23] - in
/websites/staging/trafficserver/trunk/content/docs/v2: ./ admin/
admin/images/ sdk/ sdk/css/ sdk/images/ sdk/images/docbook/ sdk/js/
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaders.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaders.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaders.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,124 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 10. HTTP Headers</title>
+<!--#include file="top.html" -->
+</head><div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="Interface_ThreadFunctions.html">Prev</a> - Thread Functions</div>
+<div class="navnext">Guide to Traffic Server HTTP Header System - <a accesskey="n" href="GuideTSHTTPHdrSyst.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HTTPHeaders"></a>Chapter 10. HTTP Headers</h2></div></div></div>
+<p>This chapter explains the functions used to manipulate HTTP
+ headers.</p>
+<div class="itemizedlist"><ul type="disc"><b>
+<li><a href="HTTPHeaders.html#AboutHTTPHeaders" title="About HTTP Headers">About HTTP Headers</a></li>
+<li><a href="GuideTSHTTPHdrSyst.html" title="Guide to Traffic Server HTTP Header System">Guide to Traffic Server HTTP Header System</a></li>
+<ul><li><span class="section"><a href="DuplicateMIMEFlds.html">Duplicate MIME Fields Are Not Coalesced</a></span></li>
+<li><span class="section"><a href="MIMEFldsBelongAssocMIMEHdr.html">MIME Fields Always Belong to an Associated MIME
+ Header</a></span></li>
+<li><span class="section"><a href="RlsMarshalBufHandles.html">Release Marshal Buffer Handles</a></span></li>
+<li><span class="section"><a href="DeprecatedMarshBufFuncs.html">Deprecated Functions</a></span></li></ul>
+<li><a href="MarshalBuffers.html" title="Marshal Buffers">Marshal Buffers</a></li>
+<li><a href="HTTPHeaders2.html" title="HTTP Headers">HTTP Headers</a></li>
+<li><a href="URLs.html" title="URLs">URLs</a></li>
+<li><a href="MIMEHeaders.html" title="MIME Headers">MIME Header</a></li>
+</b>
+</ul></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="AboutHTTPHeaders"></a>About HTTP Headers</h2></div></div></div>
+<p>An <u><b>HTTP message</b></u> consists of the following:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>HTTP header<a class="indexterm" name="id380485"></a></li>
+<li>body</li>
+<li>trailer</li>
+</ul></div>
+<p>The <b><u>HTTP header</u></b> consists of:
+<div class="itemizedlist"><ul type="disc">
+<li>A request or response line</li>
+<ul>
+<li>An HTTP <b>request line</b> contains a method, URL, and version</li>
+<li>A <b>response line</b> contains a version, status code, and reason phrase</li>
+</ul>
+<li>A MIME header<a class="indexterm" name="id380540"></a></li>
+</ul></div></p>
+<p>A <b>MIME header </b>is comprised of zero or more MIME fields. A <b>MIME
+ field</b><a class="indexterm" name="id380553"></a> is composed of a field name, a colon, and (zero or more)
+ field values. The values in a field are separated by commas. An HTTP header containing a request line is usually referred to as
+ a <b>request</b>. The following example shows a typical request header.</p>
+<pre class="programlisting">GET http://www.tiggerwigger.com/ HTTP/1.0
+Proxy-Connection: Keep-Alive
+User-Agent: Mozilla/5.0 [en] (X11; I; Linux 2.2.3 i686)
+Host: www.tiggerwigger.com
+Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */
+*
+
+Accept-Encoding: gzip
+Accept-Language: en
+Accept-Charset: iso-8859-1, *, utf-8</pre>
+<p>The <b>response header </b>for the above request might look like the
+ following:</p>
+<pre class="programlisting">HTTP/1.0 200 OK
+Date: Fri, 13 Nov 2009 06:57:43 GMT
+Content-Location: http://locutus.tiggerwigger.com/index.html
+Etag: "07db14afa76be1:1074"
+Last-Modified: Thu, 05 Nov 2009 20:01:38 GMT
+Content-Length: 7931
+Content-Type: text/html
+Server: Microsoft-IIS/4.0
+Age: 922
+Proxy-Connection: close</pre>
+<p>The following figure illustrates an HTTP message with an expanded HTTP
+ header.</p>
+<div class="figure">
+<a name="Fig_ReqRespHeaderStruc"></a><p class="title"><b>Figure 10.1. HTTP Request/Response and Header Structure</b></p>
+<div class="mediaobject"><img src="images/http_header_struct.jpg" alt="HTTP Request/Response and Header Structure" /></div>
+</div>
+<p>The figure below shows example HTTP request and response
+ headers.</p>
+<div class="figure">
+<a name="Fig_HTTPReqRespHdrs"></a><p class="title"><b>Figure 10.2. Examples of HTTP Request and Response Headers</b></p>
+<div class="mediaobject"><img src="images/http_headers.jpg" alt="Examples of HTTP Request and Response Headers" /></div>
+</div>
+<p>The marshal buffer or <code class="code">INKMBuffer</code> is a heap data
+ structure that stores parsed URLs, MIME headers, and HTTP headers. You
+ can allocate new objects out of marshal buffers and change the values
+ within the marshal buffer. Whenever you manipulate an object, you
+ must require the handle to the object (<code class="code">INKMLoc</code>) and the marshal
+ buffer containing the object (<code class="function">INKMBuffer</code>).</p>
+<div class="figure">
+<a name="Fig_MarshalBufsHdrLocations"></a><p class="title"><b>Figure 10.3. Marshal Buffers and Header Locations</b></p>
+<div class="mediaobject"><img src="images/marshall_buffers.jpg" alt="Marshal Buffers and Header Locations" /></div>
+</div>
+<p>The figure above shows the following:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>The marshal buffer containing the HTTP request,
+ <code class="code">reqest_bufp</code></p></li>
+<li><p><code class="function">INKMLoc</code> location pointer for the HTTP
+ header (<code class="code">http_hdr_loc</code>)</p></li>
+<li><p><code class="function">INKMLoc</code> location pointer for the request
+ URL (<code>url_loc</code>)</p></li>
+<li><p><code class="function">INKMLoc</code> location pointers for the MIME
+ header (<code class="code">mime_hdr_loc</code>)</p></li>
+<li><p><code class="function">INKMLoc</code> location pointers for MIME fields
+ (<code class="code">fieldi_loc</code>)</p></li>
+<li><p><code class="function">INKMLoc</code> location pointer for the next
+ duplicate MIME field (<code class="code">next_dup_loc</code>)</p></li>
+</ul></div>
+<p>The diagram also shows that an HTTP header contains pointers to
+ the URL location and the MIME header location. You can obtain the URL
+ location from an HTTP header using the function
+ <code class="function">INKHttpHdrUrlGet</code>. To work with MIME headers, you
+ can pass either a MIME header location or an HTTP header location to
+ MIME header functions . If you pass an HTTP header to a MIME header
+ function, then the system locates the associated MIME header and executes the
+ MIME header function on the MIME header location.</p>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaders.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaders2.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaders2.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaders2.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,228 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>HTTP Headers</title>
+<!--#include file="top.html" -->
+</head><div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="MarshalBuffers.html">Prev</a> - Marshal Buffers</div>
+<div class="navnext">URLs - <a accesskey="n" href="URLs.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HTTPHeaders2"></a>HTTP Headers<a class="indexterm" name="id382144"></a></h2></div></div></div>
+<p>The Traffic Server API HTTP header functions enable you to work
+ with HTTP header data stored in marshal buffers.</p>
+<p>The HTTP header data structure is a parsed version of the HTTP
+ header defined in the HTTP protocol specification. An HTTP header is
+ composed of a request or response line followed by zero or more MIME
+ fields. In fact, an HTTP header is a subclass of a MIME header; all
+ of the MIME header routines operate on HTTP headers.</p>
+<p>An HTTP <b>request line</b> is composed of a method, a URL, and version. A <b>response line</b> is composed of a version, status code, and reason
+ phrase. See <a href="HTTPHeaders.html#AboutHTTPHeaders" title="About HTTP Headers">About HTTP Headers </a> for additional details and examples.</p>
+<p>To facilitate fast comparisons and reduce storage
+ size, Traffic Server defines several pre-allocated method names. These
+ names correspond to the methods defined in the HTTP 1.1
+ specification</p>
+<div class="informaltable"><table border="1">
+<colgroup>
+<col />
+<col />
+</colgroup>
+<tbody>
+<tr>
+<td align="center"><span class="bold"><strong>Pre-Allocated Method
+ Names</strong></span></td>
+<td align="center"><span class="bold"><strong>HTTP 1.1
+ Method</strong></span></td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_CONNECT</code></td>
+<td>"CONNECT"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_DELETE</code></td>
+<td>"DELETE"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_GE</code></td>
+<td>"GET"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_HEAD</code></td>
+<td>"HEAD"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_ICP_QUERY</code></td>
+<td>"ICP_QUERY"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_OPTIONS</code></td>
+<td>"OPTIONS"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_POST</code></td>
+<td>"POST"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_PURGE</code></td>
+<td>"PURGE"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_PUT</code></td>
+<td>"PUT"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_METHOD_TRACE</code></td>
+<td>"TRACE"</td>
+</tr>
+</tbody>
+</table></div>
+<p> </p>
+<p>Traffic Server also defines several common values that appear in
+ HTTP headers.</p>
+<div class="informaltable"><table border="1">
+<colgroup>
+<col />
+<col />
+</colgroup>
+<tbody>
+<tr>
+<td align="center"><span class="bold"><strong>Traffic Server
+ Definition</strong></span></td>
+<td align="center"><span class="bold"><strong>HTTP Header
+ Value</strong></span></td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_BYTES</code></td>
+<td>"bytes"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_CHUNKED</code></td>
+<td>"chunked"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_CLOSE</code></td>
+<td>"close"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_COMPRESS</code></td>
+<td>"compress"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_DEFLATE</code></td>
+<td>"deflate"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_GZIP</code></td>
+<td>"gzip"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_IDENTITY</code></td>
+<td>"identity"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_KEEP_ALIVE</code></td>
+<td>"keep-alive"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_MAX_AGE</code></td>
+<td>"max-age"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_MAX_STALE</code></td>
+<td>"max-stale"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_MIN_FRESH</code></td>
+<td>"min-fresh"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_MUST_REVALIDATE</code></td>
+<td>"must-revalidate"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_NONE</code></td>
+<td>"none"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_NO_CACHE</code></td>
+<td>"no-cache"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_NO_STORE</code></td>
+<td>"no-store"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_NO_TRANSFORM</code></td>
+<td>"no-transform"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_ONLY_IF_CACHED</code></td>
+<td>"only-if-cached"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_PRIVATE</code></td>
+<td>"private"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_PROXY_REVALIDATE</code></td>
+<td>"proxy-revalidate"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_PUBLIC</code></td>
+<td>"public"</td>
+</tr>
+<tr>
+<td><code>INK_HTTP_VALUE_S_MAX_AGE</code></td>
+<td>"s-maxage"</td>
+</tr>
+</tbody>
+</table></div>
+<p> </p>
+<p>The method names and header values above are defined in
+ <code class="filename">ts.h</code> as <code class="code"> const char* </code>strings. When
+ Traffic Server sets a method or a header value, it checks to make sure that the new value is one of the known values. If it is, then it stores a pointer into a global table (instead of
+ storing the known value in the marshal buffer). The method names and header values listed above are also
+ pointers into this table. This allows simple pointer comparison of the
+ value returned from <code class="function">INKHttpMethodGet</code> with one of
+ the values listed above. It is also recommended that you use the above
+ values when referring to one of the known schemes, since this removes
+ the possibility of a spelling error.</p>
+<p>The <a href="HTTPHeaderFunctions.html"><b>HTTP Header Functions</b></a> are listed below:</p>
+<div class="itemizedlist"><ul type="disc">
+<p>
+
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrClone">INKHttpHdrClone</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrCopy">INKHttpHdrCopy</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrCreate">INKHttpHdrCreate</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrDestroy">INKHttpHdrDestroy</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrLengthGet">INKHttpHdrLengthGet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrMethodGet">INKHttpHdrMethodGet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrMethodSet">INKHttpHdrMethodSet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrPrint">INKHttpHdrPrint</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrReasonGet">INKHttpHdrReasonGet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrReasonLookup">INKHttpHdrReasonLookup</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrReasonSet">INKHttpHdrReasonSet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrStatusGet">INKHttpHdrStatusGet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrStatusSet">INKHttpHdrStatusSet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrTypeGet">INKHttpHdrTypeGet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrTypeSet">INKHttpHdrTypeSet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrUrlGet">INKHttpHdrUrlGet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrUrlSet">INKHttpHdrUrlSet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrVersionGet">INKHttpHdrVersionGet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrVersionSet">INKHttpHdrVersionSet</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpParserClear">INKHttpParserClear</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpParserCreate">INKHttpParserCreate</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpParserDestroy">INKHttpParserDestroy</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrParseReq">INKHttpHdrParseReq</a></li>
+<li><a href="HTTPHeaderFunctions.html#INKHttpHdrParseResp">INKHttpHdrParseResp</a></li>
+
+</p>
+</ul></div>
+</div>
+</body>
+</html>
+
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaders2.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHooksAndTransactions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHooksAndTransactions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHooksAndTransactions.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,69 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 8. HTTP Hooks and Transactions</title>
+<!--#include file="top.html" -->
+</head><div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="ch07s05.html">Prev</a> - Cache Events</div>
+<div class="navnext">Adding Hooks - <a accesskey="n" href="AddingHooks.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HTTPHooksAndTransactions"></a>Chapter 8. HTTP Hooks and Transactions</h2></div></div></div>
+<p>Hooks are points in Traffic Server transaction processing where
+ plugins can step in and do some work. Registering a plugin function for
+ callback amounts to "adding" the function to a hook. You can register your
+ plugin to be called back for every single transaction or only for specific
+ transactions.</p>
+<p>This chapter contains the following sections:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="AddingHooks.html" title="Adding Hooks">Adding Hooks</a></li>
+<li><a href="HTTPSessions.html" title="HTTP Sessions">HTTP Sessions</a></li>
+<li><a href="HTTP_Transactions.html" title="HTTP Transactions">HTTP Transactions</a></li>
+<li><a href="InterceptingHTTPTransactionFuncs.html" title="Intercepting HTTP Transaction Functions">Intercepting HTTP Transaction Functions</a></li>
+<li><a href="InitiateHTTPConnection.html" title="Initiate HTTP Connection">Initiate HTTP Connection</a></li>
+<li><a href="HTTPAlternateSelection.html" title="HTTP Alternate Selection">HTTP Alternate Selection</a></li>
+</ul></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="SetOfHooks"></a>The Set of Hooks</h2></div></div></div>
+<p>To understand hooks and transactions, you should be familiar with the following terminology:</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b><u>HTTP Transaction</u></b></span></dt>
+<dd>
+<p>A <b>transaction</b> consists of a single HTTP request from a
+ client and the response Traffic Server sends to that client.
+ Thus, a transaction begins when Traffic Server receives a request and
+ ends when Traffic Server sends the response.</p>
+<p>Traffic Server uses <b>HTTP state machines</b> to process
+ transactions. The state machines follow a complex set of states
+ involved in sophisticated caching and document retrieval (taking
+ into account, for example, alternate selection, freshness
+ criteria, and hierarchical caching). The Traffic Server API
+ provides hooks to a subset of these states, as illustrated in the <a href="HTTPHooksAndTransactions.html#Fig_HHTTPTxStateDiag" title="Figure 8.1. HTTP Transaction State Diagram">HTTP Transaction State Diagram</a> below.</p>
+</dd>
+<dt><span class="term"><b><u>Transform hooks</u></b></span></dt>
+<dd>
+ <p>The two <b>transform hooks</b>, <code class="code">INK_HTTP_REQUEST_TRANSFORM_HOOK</code> and
+ <code class="code">INK_HTTP_RESPONSE_TRANSFORM_HOOK</code>, are called in the
+ course of an HTTP transform. To see where in the HTTP transaction
+ they are called, look for the "set up transform" ovals in the <a href="HTTPHooksAndTransactions.html#Fig_HHTTPTxStateDiag" title="Figure 8.1. HTTP Transaction State Diagram">HTTP Transaction State Diagram</a> below.</p></dd>
+<dt><span class="term"><b><u>HTTP session</u></b></span></dt>
+<dd>
+ <p>A <b>session</b> consists of a single client connection to Traffic
+ Server; it may consist of a single transaction or several transactions in
+ succession. The session starts when the client connection opens
+ and ends when the connection closes.</p></dd>
+</dl></div>
+<div class="figure">
+<a name="Fig_HHTTPTxStateDiag"></a>
+<p class="title"><b>Figure 8.1. HTTP Transaction State Diagram (**not yet updated**)</b></p>
+<div class="mediaobject"><img src="images/http_state2.jpg" alt="HTTP Transaction State Diagram" /></div>
+</div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHooksAndTransactions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPSessionFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPSessionFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPSessionFunctions.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,135 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Session Functions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="HTTPFunctions.html">Prev</a> - HTTP Functions</div>
+<div class="navnext">HTTP Transaction Functions - <a accesskey="n" href="HTTPTransactionFunctions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="HTTPSessionFunctions"></a>Session Functions</h3></div></div></div>
+
+
+<ul>
+ <li><b><a href="HTTPSessionFunctions.html#INKHttpSsnHookAdd">INKHttpSsnHookAdd</a></b></li>
+ <li><b><a href="HTTPSessionFunctions.html#INKHttpSsnReenable">INKHttpSsnReenable</a></b><a href="HTTPSessionFunctions.html#INKHttpSsnReenable"></a></li>
+</ul>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpSsnHookAdd"></a>INKHttpSsnHookAdd</h4></div></div></div>
+<p>Adds an HTTP session hook.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpSsnHookAdd (INKHttpSsn
+ <em class="replaceable"><code>ssnp</code></em>, INKHttpHookID
+ <em class="replaceable"><code>id</code></em>, INKCont
+ <em class="replaceable"><code>contp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Adds <code class="code"><em class="replaceable"><code>contp </code></em></code> to
+ the end of the list of HTTP transaction hooks specified by
+ <code class="code"><em class="replaceable"><code>id</code></em></code>. This means that
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is called back
+ for every transaction within the session, at the point
+ specified by the hook ID. Since
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is added to a
+ session, it is not possible to call
+ <code class="function">INKHttpSsnHookAdd</code> from the plugin
+ initialization routine. Therefore, the plugin needs a handle to an HTTP
+ session (see the <a href="HTTPSessionFunctions.html#INKEvent_1">example</a> below).</p></dd>
+<dt><span class="term"><a name="INKEvent_1"></a><b>Example</b></span></dt>
+<dd>
+ <pre class="programlisting">#include ts.h
+
+static void txn_handler (INKHttpTxn txnp, INKCont contp)
+{
+ //handle transaction
+}
+
+static void handle_session (INKHttpSsn ssnp, INKCont contp)
+{
+ INKHttpSsnHookAdd (ssnp, INK_HTTP_TXN_START_HOOK, contp);
+}
+
+static int ssn_handler (INKCont contp, INKEvent event, void *edata)
+{
+ INKHttpSsn ssnp;
+ INKHttpTxn txnp;
+
+ switch (event){
+ case INK_EVENT_HTTP_SSN_START:
+ ssnp = (INKHttpSsn) edata;
+ handle_session (ssnp, contp);
+ INKHttpSsnReenable (ssnp, INK_EVENT_HTTP_CONTINUE);
+ return 0;
+
+ case INK_EVENT_HTTP_TXN_START:
+ txnp = (INKHttpTxn) edata;
+ txn_handler (txnp, contp);
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_CONTINUE);
+ return 0;
+
+ default:
+ break;
+ }
+ return 0;
+}
+
+void INKPluginInit (int argc, const char *argv[])
+{
+ INKCont contp;
+ contp = INKContCreate (ssn_handler, NULL);
+ INKHttpHookAdd (INK_HTTP_SSN_START_HOOK, contp);
+}</pre></dd>
+<dt><span class="term"> </span></dt>
+<dd> </dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd><p><code class="code">INK_SUCCESS</code> if the hook is successfully
+ added.</p>
+ <p><code class="code">INK_ERROR</code> if the hook is not added.</p>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpSsnReenable"></a>INKHttpSsnReenable</h4></div></div></div>
+<p>Reenables an HTTP session.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpSsnReenable (INKHttpSsn
+ <em class="replaceable"><code>ssnp</code></em>, INKEvent
+ <em class="replaceable"><code>event</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Notifies the HTTP session
+ <code class="code"><em class="replaceable"><code> ssnp </code></em></code> that the plugin
+ is done processing the current hook. </p></dd>
+<dd>
+ <p>If <code class="code">INK_EVENT_HTTP_CONTINUE</code> is specified for
+ <code class="code"><em class="replaceable"><code>event</code></em></code>, then the plugin
+ wants the session to continue. If
+ <code class="code">INK_EVENT_HTTP_ERROR</code> is specified for
+ <code class="code"><em class="replaceable"><code> event</code></em></code>, then the plugin
+ wants the session to be terminated. An error is then sent
+ back to the client if no response has already been
+ sent.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the session is successfully
+ reenabled.</p>
+<p><code class="code">INK_ERROR</code> if the hook is not added.</p>
+</dd>
+</dl></div>
+</div>
+</div>
+</body>
+</html>
+
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPSessionFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPSessions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPSessions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPSessions.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,51 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>HTTP Sessions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="AddingHooks.html">Prev</a> - Adding Hooks</div>
+<div class="navnext">HTTP Transactions - <a accesskey="n" href="HTTP_Transactions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HTTPSessions"></a>HTTP Sessions</h2></div></div></div>
+<p>An <b>HTTP session</b> is an object that is defined for the lifetime of a
+ client's TCP session. The Traffic Server API enables you to add a global
+ hook to the start or end of an HTTP session, as well as add session
+ hooks that call back your plugin for every transaction within a given
+ session. When a client connects to Traffic Server, it opens up a TCP
+ connection and sends one or more HTTP requests. An individual request
+ and its response comprise the HTTP transaction. The <a class="indexterm" name="id378839"></a><b>HTTP session</b><a class="indexterm" name="id378848"></a> begins when the client opens the connection and ends
+ when the connection closes.</p>
+<p>The HTTP session hooks are:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<p><code class="code">INK_HTTP_SSN_START_HOOK<a class="indexterm" name="id378868"></a></code></p>
+<p>Called when an HTTP session is started (a session starts when
+ a client connects to Traffic Server). This hook must be added as a
+ global hook.</p>
+</li>
+<li>
+<p><code class="code">INK_HTTP_SSN_CLOSE_HOOK<a class="indexterm" name="id378886"></a></code></p>
+<p>Called when an HTTP session ends (a session ends when the
+ client connection is closed). This hook must be added as a global
+ hook.</p>
+</li>
+</ul></div>
+<p>Use the session hooks to get a handle to a session (an
+ <code class="code">INKHttpSsn</code> object). If you want your plugin to be
+ called back for each transaction within the session, then use
+ <code class="code">INKHttpSsnHookAdd</code>.</p>
+<p><b>Note:</b> you must reenable the session with <code class="code">INKHttpSsnReenable</code> after processing a session hook.</p>
+<p>The session hook functions are listed below:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="HTTPSessionFunctions.html#INKHttpSsnHookAdd" title="INKHttpSsnHookAdd">INKHttpSsnHookAdd</a></li>
+<li><a href="HTTPSessionFunctions.html#INKHttpSsnReenable" title="INKHttpSsnReenable">INKHttpSsnReenable</a></li>
+</ul></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPSessions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPTransactionFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPTransactionFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPTransactionFunctions.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,1010 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>HTTP Transaction Functions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="HTTPSessionFunctions.html">Prev</a> - Session Functions</div>
+<div class="navnext">Initiate Connection - <a accesskey="n" href="InitiateConnectionFunctions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="HTTPTransactionFunctions"></a>HTTP Transaction Functions</h3></div></div></div>
+
+<ul>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnCacheLookupStatusGet">INKHttpTxnCacheLookupStatusGet</a></b></li>
+ <li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnCacheLookupStatusSet">INKHttpTxnCacheLookupStatusSet</a></b></li>
+ <li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnCachedReqGet">INKHttpTxnCachedReqGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnCachedRespGet">INKHttpTxnCachedRespGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnClientIncomingPortGet">INKHttpTxnClientIncomingPortGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnClientIPGet ">INKHttpTxnClientIPGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnClientRemotePortGet">INKHttpTxnClientRemotePortGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnClientReqGet">INKHttpTxnClientReqGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnClientRespGet">INKHttpTxnClientRespGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnErrorBodySet">INKHttpTxnErrorBodySet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnHookAdd">INKHttpTxnHookAdd</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnNextHopIPGet">INKHttpTxnNextHopIPGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnParentProxyGet">INKHttpTxnParentProxyGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnParentProxySet">INKHttpTxnParentProxySet</a></b></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnPristineUrlGet"><b>INKHttpTxnPristineUrlGet</b></a></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnReenable">INKHttpTxnReenable</a><a href="HTTPTransactionFunctions.html#INKHttpTxnReenable"></a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnServerIPGet">INKHttpTxnServerIPGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnServerReqGet">INKHttpTxnServerReqGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnServerRespGet">INKHttpTxnServerRespGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnSetRespCacheableSet">INKHttpTxnSetRespCacheableSet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnSkipRww">INKHttpTxnSkipRww</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnSsnGet">INKHttpTxnSsnGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnTransformedRespCache">INKHttpTxnTransformedRespCache</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnTransformRespGet">INKHttpTxnTransformRespGet</a></b></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnUntransformedRespCache">INKHttpTxnUntransformedRespCache</a></b></li>
+</ul>
+<div class="section" lang="en">
+ <div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnCacheLookupStatusGet"></a>INKHttpTxnCacheLookupStatusGet</h4></div></div></div>
+<p>Stores the current cache lookup status for the ongoing
+ transaction. Also stores the number of cache lookup operations
+ already performed.</p>
+<div class="variablelist"><dl>
+ <dt><span class="term"><b>Prototype</b></span></dt>
+ <dd><p><code class="code">INKReturnCode INKHttpTxnCacheLookupStatusGet
+ (INKHttpTxn <em class="replaceable"><code>txnp</code></em>, int
+ *<em class="replaceable"><code>lookup_status</code></em>)</code></p></dd>
+ <dt><span class="term"><b>Arguments</b></span></dt>
+ <dd>
+ <p><code>INKHttpTxn <i>txnp </i></code> is the ongoing transaction.</p>
+ <p><code>int <i>*lookup_status </i></code> is set to the lookup status.</p>
+ </dd>
+ <dt><span class="term"><b>Description</b></span></dt>
+ <dd>
+ <p>Obtains the status of the current cache lookup for the
+ ongoing transaction
+ <code class="code"><em class="replaceable"><code>txnp </code></em></code> in the
+ <code class="code"><em class="replaceable"><code>lookup_status </code></em></code>
+ variable.</p>
+ <p>This function should only be called from
+ <code class="code">INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK</code>.</p>
+ <p>Possible status values returned in
+ <code class="code"><em class="replaceable"><code>lookup_status </code></em></code>
+ are:
+ </p><ul>
+ <li><code class="code">INK_CACHE_LOOKUP_MISS</code> - Document was not in
+ the cache, so it will be fetched from the origin server.</li>
+ <li><code class="code">INK_CACHE_LOOKUP_HIT_STALE</code> - Document was
+ present in the cache but was stale. A fresher version will be
+ fetched from the origin server (IMS request).</li>
+ <li><code class="code">INK_CACHE_LOOKUP_HIT_FRESH</code> - Document was
+ present in the cache and was fresh. Document will be served
+ from the cache.</li>
+ <li><code class="code">INK_CACHE_LOOKUP_SKIPPED</code> - Traffic Server
+ didn't perform a cache lookup because the request wasn't cacheable
+ (this can happen when the URL looks dynamic or the request is marked as noncacheable).</li>
+ </ul>
+ </dd>
+</dl>
+
+ <dl>
+ <dt><span class="term"><b>Returns</b></span></dt>
+ <dd>
+ <p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+ <p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+ </dd>
+ </dl>
+</div>
+</div>
+
+
+<div class="section" lang="en">
+ <div class="titlepage"><div><div>
+ <h4 class="title">
+<a name="INKHttpTxnCacheLookupStatusSet"></a>INKHttpTxnCacheLookupStatusSet</h4></div></div></div>
+<p>Sets the cache lookup status to the status that is passed in.</p>
+<div class="variablelist"><dl>
+ <dt><span class="term"><b>Prototype</b></span></dt>
+ <dd>
+ <p><code class="code">int INKHttpTxnCacheLookupStatusSet
+ (INKHttpTxn <em class="replaceable"><code>txnp</code></em>, int <em class="replaceable"><code>lookup_status</code></em>)</code></p></dd>
+ <dt><span class="term"><b>Arguments</b></span></dt>
+ <dd>
+ <p><code>INKHttpTxn </code><code class="code"><em class="replaceable"><code>txnp </code></em></code><i> </i> is the ongoing transaction.</p>
+ <p> </p>
+ </dd>
+ <dt><span class="term"><b>Description</b></span></dt>
+ <dd>
+ <p>Sets the status of the current cache lookup for the ongoing transaction <code class="code"><em class="replaceable"><code>txnp </code></em></code> to whatever is specified in the <code class="code"><em class="replaceable"><code>lookup_status </code></em></code> variable. Changing the status from <code>INK_CACHE_LOOKUP_MISS</code> is not allowed. </p>
+ </dd>
+ <dd>
+ <p>For example, consider the following use-case scenario: A 'stale while revalidate' plugin has to serve stale data from the cache while it makes a request for new data asynchronously. The plugin forces the core to serve stale data by setting the cache lookup status to <code>INK_CACHE_LOOKUP_HIT_FRESH</code>.</p>
+
+<p>Possible status values for
+ <code class="code"><em class="replaceable"><code>lookup_status </code></em></code>
+ are:
+ </p>
+<ul>
+ <li><code class="code">INK_CACHE_LOOKUP_MISS</code> - Document was not in
+ the cache, so it will be fetched from the origin server.</li>
+ <li><code class="code">INK_CACHE_LOOKUP_HIT_STALE</code> - Document was
+ present in the cache but was stale. A fresher version will be
+ fetched from the origin server (IMS request).</li>
+ <li><code class="code">INK_CACHE_LOOKUP_HIT_FRESH</code> - Document was
+ present in the cache and was fresh. Document will be served
+ from the cache.</li>
+ <li><code class="code">INK_CACHE_LOOKUP_SKIPPED</code> - Traffic Server
+ didn't perform a cache lookup because the request was not cacheable
+ (this can happen when the URL looks dynamic or the request is marked as noncacheable).</li>
+ </ul>
+</dd>
+</dl>
+
+ <dl>
+ <dt><span class="term"><b>Returns</b></span></dt>
+ <dd>
+ <p><code class="code">1</code> if the API is called
+ successfully.</p>
+ <p><code class="code">0</code> if an error occurs.</p>
+ </dd>
+ </dl>
+</div>
+</div>
+
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnCachedReqGet"></a>INKHttpTxnCachedReqGet</h4></div></div></div>
+<p>Gets the cached request header for a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpTxnCachedReqGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, INKMBuffer
+ *<em class="replaceable"><code>bufp</code></em>, INKMLoc
+ *<em class="replaceable"><code>hdr_loc</code></em>) </code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="code">INKHttpTxn</code>
+ <code class="code"><em class="replaceable"><code>txnp </code></em></code> is the ongoing
+ transaction.</p>
+<p><code class="code">int <i>*</i></code><i><code class="code">lookup_status </code></i> is set to
+ the lookup status.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Obtains the status of the current cache lookup for the
+ ongoing transaction
+ <code class="code"><em class="replaceable"><code>txnp </code></em></code> in the
+ <code class="code"><i>lookup_status </i></code> variable.</p>
+<p>This function should only be called from
+ <code class="code">INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK</code>.</p>
+<p>The possible status values returned in
+ <code class="code"><i>lookup_status </i></code> are:</p>
+ <ul>
+ <li>
+<code class="code">INK_CACHE_LOOKUP_MISS</code> - Document was not in
+ the cache; it will be fetched from the origin server.</li>
+<li><code class="code">INK_CACHE_LOOKUP_HIT_STALE</code> - Document was
+ present in the cache but was stale. A fresher version will be
+ fetched from the origin server (IMS request).</li>
+<li><code class="code">INK_CACHE_LOOKUP_HIT_FRESH</code> - Document was
+ present in the cache and was fresh. Document will be served
+ from the cache.</li>
+<li><code class="code">INK_CACHE_LOOKUP_SKIPPED</code> - Traffic Server
+ didn't perform a cache lookup because the request was not cacheable
+ (this can happen when the URL looks dynamic or the request is marked as noncacheable).</li>
+ </ul>
+ </dd>
+</dl>
+
+ <dl>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnCachedRespGet"></a>INKHttpTxnCachedRespGet</h4></div></div></div>
+<p>Gets the cached response header for a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpTxnCachedRespGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, INKMBuffer
+ *<em class="replaceable"><code>bufp</code></em>, INKMLoc
+ *<em class="replaceable"><code>hdr_loc</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the cached response header from the HTTP
+ transaction <code class="code"><em class="replaceable"><code>txnp </code></em></code> and
+ stores the cached response header in <code>bufp</code>, at location <code class="code"><em class="replaceable"><code>hdr_loc</code></em></code>.</p>
+<p>Call after <code class="code">SEND_RESPONSE_HDR_HOOK</code>.</p>
+<div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="images/docbook/caution.png" /></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>Do not modify any cached response headers returned by
+ <code class="function">INKHttpTxnCachedRespGet</code>; the underlying
+ data structure is read-only. Release the returned
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> with a call
+ to <code class="function">INKHandleMLocRelease</code>.</p></td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>If the cached response header does not exist, then
+ <code class="function">INKHttpTxnCachedRespGet</code> returns <code>0</code>.</p>
+<p>Otherwise, it returns <code>1</code>.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnClientIncomingPortGet"></a>INKHttpTxnClientIncomingPortGet</h4></div></div></div>
+<p>Gets the port on which the incoming request is
+ received.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpTxnClientIncomingPortGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Returns the port on which the HTTP transaction
+ <code class="code"><em class="replaceable"><code>txnp </code></em></code> was received.
+ This is not the destination port in the URL; it is the proxy
+ port to which the client browser is pointed.</p>
+<p>Call after <code class="code">TXN_START_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The port number in host byte order.</p>
+<p>Returns <code>-1</code> if an error occurred.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnClientIPGet"></a>INKHttpTxnClientIPGet</h4></div></div></div>
+<p>Gets the client IP address for a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">unsigned int INKHttpTxnClientIPGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Returns the IP address of the client for the HTTP
+ transaction
+ <code class="code"><em class="replaceable"><code>txnp</code></em></code>.</p>
+<p><code class="function">INKHttpTxnClientIPGet</code> returns the
+ IP address in network byte order.</p>
+<p>Call after <code class="code">TXN_START_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The client IP address.</p>
+<p>Returns <code>0</code> if an error occurred.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnClientRemotePortGet"></a>INKHttpTxnClientRemotePortGet</h4></div></div></div>
+<p>Gets the remote host's port number for a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode
+ INKHttpTxnClientRemotePortGet(INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, int
+ *<em class="replaceable"><code>port</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="code">INKHttpTxn</code>
+ <code class="code"><code class="code"><em class="replaceable"><code>txnp </code></em></code></code> is
+ an HTTP transaction.</p>
+<p><code class="code">int
+ *</code><code class="code"><em class="replaceable"><code>port </code></em></code> is set to
+ the client's remote port value (port number used by the client
+ when creating a socket connection with the proxy for the
+ transaction <code class="code"><em class="replaceable"><code>txnp </code></em></code>) in
+ network byte order.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Obtains the port number of the remote host for the
+ specified HTTP transaction. The port number is returned in
+ network byte order.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>This is an exception to the rule that port numbers are
+ retrieved in host byte order.</p></td></tr>
+</table></div>
+<p>The proxy port on which the connection was accepted can
+ be retrieved using
+ <code class="function">INKHttpTxnClientIncomingPortGet</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnClientReqGet"></a>INKHttpTxnClientReqGet</h4></div></div></div>
+<p>Gets the client request header for a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpTxnClientReqGet (INKHttpTxn txnp,
+ INKMBuffer *bufp, INKMLoc *hdr_loc) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the client request header from the HTTP
+ transaction <code class="code"><em class="replaceable"><code>txnp</code></em></code>.
+ <code class="function">INKHttpTxnClientReqGet</code> stores the client
+ request header in
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>, at location
+ <code class="code"><em class="replaceable"><code>hdr_loc</code></em></code>.</p>
+<p>Call after <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+<p>Release the returned
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>If the client request header does not exist or if there is an error, then <code class="function">INKHttpTxnClientReqGet</code>
+ returns <code>0</code>.</p>
+<p>Otherwise, <code>1</code> is returned.</p>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnClientRespGet"></a>INKHttpTxnClientRespGet</h4></div></div></div>
+<p>Gets the client response header for a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpTxnClientRespGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, INKMBuffer
+ *<em class="replaceable"><code>bufp</code></em>, INKMLoc
+ *<em class="replaceable"><code>hdr_loc</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the client response header from the HTTP
+ transaction <code class="code"><em class="replaceable"><code>txnp</code></em></code>.
+ <code class="function">INKHttpTxnClientRespGet</code> stores the client
+ response header in
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>, at location
+ <code class="code"><em class="replaceable"><code>hdr_loc</code></em></code>.</p>
+<p>Call after <code class="code">SEND_RESPONSE_HOOK</code>.</p>
+<p>Release the returned
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>If the client response header does not exist or if there is an error, then
+ <code class="function">INKHttpTxnClientRespGet</code> returns <code>0</code>.</p>
+<p>Otherwise, <code>1</code> is returned.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnErrorBodySet"></a>INKHttpTxnErrorBodySet</h4></div></div></div>
+<p>Sets the format and content of the error body (or response
+ data) that Traffic Server sends to clients.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpTxnErrorBodySet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, char
+ *<em class="replaceable"><code>buf</code></em>, int
+ <em class="replaceable"><code>buflength</code></em>, char
+ *<em class="replaceable"><code>mimetype</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="code"><em class="replaceable"><code>txnp </code></em></code> is the HTTP
+ transaction to act upon.</p>
+<p><code class="code"><em class="replaceable"><code>buf </code></em></code> contains the
+ error (or response) body. The error body can be text, an HTML
+ document, image, or another format. Before you call
+ <code class="function">INKHttpTxnErrorBodySet,</code> be sure to
+ allocate <code class="code"><em class="replaceable"><code>buf </code></em></code> using
+ <code class="function">INKmalloc</code>.</p>
+<p><code class="code"><em class="replaceable"><code>buflength </code></em></code> is the
+ length of the error body.</p>
+<p><code class="code"><em class="replaceable"><code>mimetype </code></em></code>
+ contains the format of the error body. If you want to set the
+ <code class="code"><em class="replaceable"><code>mimetype </code></em></code> to a value
+ other than <code class="code">NULL</code>, then you must allocate
+ <code class="code"><em class="replaceable"><code>mimetype </code></em></code> using
+ <code class="function">INKmalloc</code> before you call
+ <code class="function">INKHttpTxnErrorBodySet</code>.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets the format of the error body that Traffic Server
+ sends back when sending an error or response to a client. The
+ error body data is stored in the buffer
+ <code class="code"><em class="replaceable"><code>buf</code></em></code>. If the error body
+ is just plain text, then setting <code class="code"><em class="replaceable"><code>mimetype </code></em></code> to <code class="code">NULL</code>
+ is sufficient. If the error body is HTML, then
+ <code class="code"><em class="replaceable"><code>mimetype </code></em></code> should be
+ "<code class="code">text/html</code>". If the error body is a JPEG image,
+ then <code class="code"><em class="replaceable"><code>mimetype </code></em></code> should
+ be "<code>image/jpeg</code>".</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>Traffic Server automatically calls
+ <code class="function">INKfree</code> to free
+ <code class="code"><em class="replaceable"><code>buf </code></em></code> when it is no longer
+ needed; make sure that the buffer
+ <code class="code"><em class="replaceable"><code>buf </code></em></code> is allocated by
+ a call to <code class="function">INKmalloc</code>. Similarly, if you
+ want to set <code class="code"><em class="replaceable"><code>mimetype </code></em></code>
+ to something other than <code class="code">NULL</code>, then make sure
+ you allocate
+ <code class="code"><em class="replaceable"><code>mimetype </code></em></code> with a call
+ to <code class="function">INKmalloc</code>. Traffic Server
+ automatically calls <code class="function">INKfree</code> to free
+ <code class="code"><em class="replaceable"><code>mimetype</code></em></code>.</p></td></tr>
+</table></div>
+<p>Call after <code class="code">SEND_RESPONSE_HDR_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the operation completes
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnHookAdd"></a>INKHttpTxnHookAdd</h4></div></div></div>
+<p>Adds a continuation to the list of HTTP transaction hooks for
+ a specified HTTP transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpTxnHookAdd (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, INKHttpHookID
+ <em class="replaceable"><code>id</code></em>, INKCont
+ <em class="replaceable"><code>contp</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Adds <code class="code"><em class="replaceable"><code>contp </code></em></code> to
+ the end of the list of HTTP transaction hooks specified by
+ <code class="code"><em class="replaceable"><code>id</code></em></code>. Since
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is added to a
+ transaction, it is not possible to call
+ <code class="function">INKHttpTxnHookAdd</code> from the plugin
+ initialization routine unless the plugin has a handle
+ to an HTTP transaction.</p>
+<p>Call after <code class="code">HTTP_TXN_START_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the operation completes
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnNextHopIPGet"></a>INKHttpTxnNextHopIPGet</h4></div></div></div>
+<p>Gets the IP address of the next server from which Traffic
+ Server tries to retrieve requested HTTP content.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">unsigned int INKHttpTxnNextHopIPGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Returns the IP address of the next server from which
+ Traffic Server attempts to retrieve the requested document, in
+ network byte order. The IP address returned could be the origin server
+ IP address or it could be the parent proxy's IP
+ address.</p>
+<p>Call after <code class="code">SEND_REQUEST_HDR_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>Returns the IP address of the next server from which
+ Traffic Server attempts to retrieve the request, in network
+ byte order.</p>
+<p>Returns <code>0</code> if an error occurred.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnParentProxyGet"></a>INKHttpTxnParentProxyGet</h4></div></div></div>
+<p>Gets the parent proxy name and port, if parent proxying is
+ enabled.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpTxnParentProxyGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, char
+ **<em class="replaceable"><code>hostname</code></em>, int
+ *<em class="replaceable"><code>port</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the value set previously by
+ <code class="function">INKHttpParentProxySet</code>. Does not return
+ values set in
+ <code class="filename">parent.config</code> or <code class="filename">records.config</code> for the
+ <code><i>proxy.config.http.parent_proxies </i></code>parameter.</p>
+<p>This function can be called from within any<code> </code>transaction hook.</p>
+<p>The <code class="replaceable"><i>hostname </i></code> string returned must not be
+ deallocated.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>If parent proxying is not enabled, then
+ <code class="function">INKHttpTxnParentProxyGet</code> returns
+ <code class="code">NULL</code> for <code class="code"><em class="replaceable"><code>hostname</code></em></code><i><code> </code></i>and <code>-1</code> for <code class="replaceable"><i>port</i></code>.</p></td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the operation completes
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnParentProxySet"></a>INKHttpTxnParentProxySet</h4></div></div></div>
+<p>Sets the parent proxy name and port.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpTxnParentProxySet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, char
+ *<em class="replaceable"><code>hostname</code></em>, int
+ <em class="replaceable"><code>port</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>This can be used to overwrite the value set in the
+ <code class="filename">parent.config</code> file, or in <code class="filename">records.config</code> for the parameter
+ <code><i>proxy.config.http.parent_proxies</i></code>.</p>
+<p>Call before or within
+ <code class="code">CACHE_LOOKUP_COMPLETE</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the operation completes
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div>
+ <h4 class="title">
+<a name="INKHttpTxnPristineUrlGet"></a>INKHttpTxnPristineUrlGet</h4></div></div></div>
+<p>Gets the pristine URL (the URL that came in from the client request, before remap) for a specified HTTP transaction. </p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd>
+ <p><code>INKReturnCode INKHttpTxnPristineUrlGet (INKHttpTxn <span class="replaceable">txnp</span>, INKMBuffer *<span class="replaceable">bufp</span>, INKMLoc *<span class="replaceable">url_loc</span>);</code></p>
+</dd>
+<dt><span class="term"><b>Arguements</b></span></dt>
+<dd>
+ <p><code>INKHttpTxn <span class="replaceable">txnp </span></code> is the ongoing transaction.</p>
+ <p><code>INKMBuffer *<span class="replaceable">bufp </span></code> is the header buffer pointer</p>
+ <p><code>INKMLoc *<span class="replaceable">url_loc </span></code> is the pointer to the location where the pristine URL will be written.</p>
+</dd>
+</dl>
+ <dl>
+
+
+ <dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>After remap, the URL returned by <code>INKHttpHdrUrlGet</code> may not be the same as the original URL.
+ This API provides a way to access the URL that was part of the client request header. </p>
+ <p>Retrieves the pristine URL from the HTTP transaction <span class="replaceable">txnp</span>. <code>INKHttpTxnPristineUrlGet</code> stores the pristine URL in <span class="replaceable">bufp</span>, at
+ location <span class="replaceable">url_loc</span>. Call after <code>READ_REQUEST_HDR_HOOK</code>.</p>
+ <p>Release the returned <span class="replaceable">url_loc</span> with a call to <code>INKHandleMLocRelease</code>.</p>
+</dd>
+</dl>
+ <dl>
+
+ <dt><span class="term"><b>Returns</b></span></dt>
+ <dd>
+ <p><code>INK_SUCCESS</code> if the operation completes successfully.</p>
+
+ <p><code>INK_ERROR</code> if there is an error.</p></dd>
+
+
+ <dt><span class="term"><b>Example</b></span></dt>
+
+ <dd>
+
+
+ <pre class="programlisting"> if (INKHttpTxnPristineUrlGet(txnp, &bufp, &url_loc) == INK_SUCCESS)
+ {value = INKUrlHostGet(bufp, url_loc, &len); INKDebug (DEBUG_TAG, "Pristine Host: %s", value); INKHandleMLocRelease (bufp, INK_NULL_MLOC, url_loc);}
+ else {INKError ("INKHttpTxnPristineUrlGet returns 0.\n");</pre>
+
+ </dd>
+ </dl>
+</div>
+</div>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnReenable"></a>INKHttpTxnReenable</h4></div></div></div>
+<p>Tells a transaction if the processing of a
+ particular hook has completed.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpTxnReenable (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, INKEvent
+ <em class="replaceable"><code>event</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Notifies the HTTP transaction <code class="replaceable"><i>txnp </i></code> that the plugin is
+ finished processing the current hook. If <code class="code">INK_EVENT_HTTP_CONTINUE</code> is specified for
+ <code class="code"><em class="replaceable"><code>event</code></em></code>, then the plugin
+ wants the transaction to continue. If
+ <code class="code">INK_EVENT_HTTP_ERROR</code> is specified for
+ <code class="code"><em class="replaceable"><code>event</code></em></code>, then the plugin
+ wants the transaction to be terminated and an error is
+ sent back to the client (if no response has already been
+ sent).</p>
+ <p>You must always reenable the HTTP transaction after
+ each transaction event is processed. However, you should never reenable
+ twice - this is a serious error.</p>
+ <p>When <code class="code"><em class="replaceable"><code>event </code></em></code> is set to <code class="code">INK_EVENT_HTTP_ERROR</code>,
+ Traffic Server performs different processing depending on the
+ type of hook involved.</p>
+ <ul>
+ <li><code class="code">INK_HTTP_TXN_START_HOOK</code>: the transaction is
+ stopped right away, then the client connection is closed
+ and no response is sent back to the origin server.</li>
+ <li><code class="code">INK_HTTP_READ_REQUEST_HDR_HOOK</code>: Traffic
+ Server does not send a request to the origin server; it
+ directly sends a 500 to the client.</li>
+ <li><code class="code">INK_HTTP_SEND_REQUEST_HDR_HOOK</code>: Traffic
+ Server opens a connection to the origin server, sends an empty
+ request to it, and sends a <code>500</code> status message back to the
+ client. The connection to the origin server is
+ then closed.</li>
+ <li><code class="code">INK_HTTP_READ_RESPONSE_HDR_HOOK</code>,
+ <code class="code">INK_HTTP_SEND_RESPONSE_HOOK</code>,
+ <code class="code">INK_HTTP_OS_DNS_HOOK</code>,
+ <code class="code">INK_HTTP_READ_CACHE_HDR_HOOK</code>, and
+ <code class="code">INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK</code>: Traffic
+ Server receives all headers in the origin server's response, closes the connection to the origin server,
+ and sends a <code>500</code> status message back to the client. Traffic Server does not receive the
+ response body.</li>
+ <li><code class="code">INK_HTTP_TXN_CLOSE_HOOK</code>: the client
+ receives whatever answer was sent by the origin server because
+ with this hook, the response has already been sent to the
+ clie</li></ul></dd>
+<dt> </dt>
+<dt><span class="term"><b>Returns</b></span></dt>
+
+ <dd>
+ <p><code class="code">INK_SUCCESS</code> if the operation completes
+ successfully.</p>
+ <p><code class="code">INK_ERROR</code> if an error occurs.</p>
+ </dd>
+ </dl>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnServerIPGet"></a>INKHttpTxnServerIPGet</h4></div></div></div>
+<p>Gets the origin server IP address for a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">unsigned int INKHttpTxnServerIPGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Returns the IP address of the origin server specified by
+ the client request in network byte order.
+ <code class="function">INKHttpTxnServerIPGet</code> returns <code>0</code> if it is
+ called before <code class="code">INK_HTTP_OS_DNS_HOOK</code> in a
+ transaction.</p>
+<p>Call after <code class="code">INK_HTTP_OS_DNS_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>Returns the origin server IP address in network byte
+ order.</p>
+<p>Returns <code>0</code> if an error occurred.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnServerReqGet"></a>INKHttpTxnServerReqGet</h4></div></div></div>
+<p>Gets the server request header from a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpTxnServerReqGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, INKMBuffer
+ *<em class="replaceable"><code>bufp</code></em>, INKMLoc
+ *<em class="replaceable"><code>hdr_loc</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the server request header from the HTTP
+ transaction <code class="code"><em class="replaceable"><code>txnp</code></em></code>.
+ <code class="function">INKHttpTxnServerReqGet</code> stores the server
+ request header in
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>, at location
+ <code class="code"><em class="replaceable"><code>hdr_loc</code></em></code>.</p>
+<p>Call after <code class="code">SEND_REQUEST_HDR_HOOK</code>.</p>
+<p>Release the returned
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>If the server request header does not exist or in the
+ case of an error, then
+ <code class="function">INKHttpTxnServerReqGet</code> returns <code>0</code>.</p>
+<p>Otherwise, it returns <code>1</code>.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnServerRespGet"></a>INKHttpTxnServerRespGet</h4></div></div></div>
+<p>Gets the server response header from a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpTxnServerRespGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, INKMBuffer
+ *<em class="replaceable"><code>bufp</code></em>, INKMLoc
+ *<em class="replaceable"><code>hdr_loc</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the server response header from the HTTP
+ transaction <code class="code"><em class="replaceable"><code>txnp</code></em></code>.
+ <code class="function">INKHttpTxnServerRespGet</code> stores the server
+ response header in
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>, at location
+ <code class="code"><em class="replaceable"><code>hdr_loc</code></em></code>.</p>
+<p>Call after <code class="code">READ_RESPONSE_HDR_HOOK</code>.</p>
+<p>Release the returned
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>If the server response header does not exist or if there
+ is an error, then
+ <code class="function">INKHttpTxnServerRespGet</code> returns <code>0</code>.</p>
+<p>Otherwise, <code>1</code> is returned.</p>
+</dd>
+</dl></div>
+</div>
+
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div>
+ <h4 class="title">
+<a name="INKHttpTxnSetRespCacheableSet"></a>INKHttpTxnSetRespCacheableSet</h4></div></div></div>
+<p>Makes a request/response cacheable.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd>
+ <p><code>void INKHttpTxnSetRespCacheableSet (INKHttpTxn <span class="replaceable">txnp</span>)</code></p>
+<p><code>void INKHttpTxnSetReqCacheableSet (INKHttpTxn <span class="replaceable">txnp</span>);</code></p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets the request/response as cacheable for a given transaction <code><span class="replaceable"> txnp</span></code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>No values are returned by this function.</p>
+</dd>
+</dl></div>
+</div>
+
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div>
+ <h4 class="title">
+<a name="INKHttpTxnSkipRww"></a>INKHttpTxnSkipRww</h4></div></div></div>
+<p>Turns off read while writing for a transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code>INKReturnCode INKHttpTxnSkipRww (INKHttpTxn <span class="replaceable">txnp</span>)</code></p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>((TBD: pending additional info from developer))</p>
+<p>((TBD: ts-259))</p>
+<p>((TBD))</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>INK_SUCCESS if successful.</p>
+<p>INK_ERROR if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnSsnGet"></a>INKHttpTxnSsnGet</h4></div></div></div>
+<p>Returns the session handle associated with a specific HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKHttpSsn INKHttpTxnSsnGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the <code class="function">INKHttpSsn</code> handle
+ associated with the HTTP transaction
+ <code class="code"><em class="replaceable"><code>txnp</code></em></code>.</p>
+<p>Call after <code class="code">TXN_START_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The session handle associated with the specified HTTP
+ transaction.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnTransformedRespCache"></a>INKHttpTxnTransformedRespCache</h4></div></div></div>
+<p>Indicates whether Traffic Server writes transformed
+ documents to the cache.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpTxnTransformedRespCache
+ (INKHttpTxn <em class="replaceable"><code>txnp</code></em>, int
+ <em class="replaceable"><code>on</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Specifies whether the transformed document should be
+ written to the cache. If a transformation is occurring, then
+ the default is for the transformed copy to be written to the
+ cache. The default maintains a rule that only a single version
+ of a document is written to the cache for a single
+ transaction. It is valid for that rule to be broken if you
+ specify that both the transformed and untransformed
+ documents be written to the cache. Calls need to be made prior
+ to the actual transformation, (i.e. at the time of creating
+ the transformation) rather than in the transformation.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>This function does not overwrite HTTP directives (like
+ <code class="code">Cache-Control</code> or <code class="code">Expires</code>) that
+ determine whether a document is cached. If the
+ document can be cached, then this function determines if the transformed version should be cached. Untransformed and
+ transformed documents are cached as HTTP alternates.</p></td></tr>
+</table></div>
+<p>Call from within or after the hook
+ <code class="code">TXN_START_HOOK</code>.</p>
+<p>If called after hook <code class="code">SEND_RESPONSE_HDR</code>,
+ then this function is not taken into account by Traffic Server.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the operation completes
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnTransformRespGet"></a>INKHttpTxnTransformRespGet</h4></div></div></div>
+<p>Gets the transform response header from a specified HTTP
+ transaction.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpTxnTransformRespGet (INKHttpTxn
+ <em class="replaceable"><code>txnp</code></em>, INKMBuffer
+ *<em class="replaceable"><code>bufp</code></em>, INKMLoc
+ *<em class="replaceable"><code>offset</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the transform response header from the HTTP
+ transaction <code class="code"><em class="replaceable"><code>txnp </code></em></code> and
+ stores the transform response header in
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>, at location
+ <code class="code"><em class="replaceable"><code>offset</code></em></code>.</p>
+<p>Call from within your transformation, before transform
+ data is written to the downstream vconnection.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>If the transform response header does not exist, then
+ <code class="function">INKHttpTxnTransformRespGet</code> returns
+ <code>0</code>.</p>
+<p>Otherwise, <code>1</code> is returned.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpTxnUntransformedRespCache"></a>INKHttpTxnUntransformedRespCache</h4></div></div></div>
+<p>Indicates whether Traffic Server writes untransformed
+ documents to cache.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpTxnUntransformedRespCache
+ (INKHttpTxn <em class="replaceable"><code>txnp</code></em>, int
+ <em class="replaceable"><code>on</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Specifies whether the untransformed document should be
+ written to the cache. If there is no transformation
+ occurring, then the untransformed copy is written to the cache (by default). If a transformation is occurring, then the untransformed copy is not written to
+ the cache (by default). The default rules dictate that only a single
+ version of a document is written to the cache for a
+ single transaction. It is valid for that rule to be broken by
+ specifying that both the transformed and untransformed
+ document be written to the cache. Calls need to be made prior
+ to the actual transformation (i.e. at the time of creating
+ the transformation), rather than in the transformation.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>This function does not overwrite HTTP directives (ike
+ <code>Cache-Control</code> or <code>Expires</code>) that determine if a
+ document can be cached. If the document can be cached, then this
+ function determines if the untransformed version should be cached. Untransformed and transformed
+ documents are cached as HTTP alternates.</p></td></tr>
+</table></div>
+<p>Call from within or after hook
+ <code class="code">TXN_START_HOOK</code>.</p>
+<p>If called after hook <code class="code">SEND_RESPONSE_HDR</code>,
+ then Traffic Server does not take this function into account.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the operation completes
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPTransactionFunctions.html
------------------------------------------------------------------------------
svn:executable = *