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 2013/12/24 19:32:22 UTC
svn commit: r891679 [12/24] - in /websites/staging/trafficserver/trunk:
cgi-bin/ content/ content/docs/ content/docs/trunk/
content/docs/trunk/admin/ content/docs/trunk/admin/cluster-howto/
content/docs/trunk/admin/configuration-files/ content/docs/tru...
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/GetingStarted.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/GetingStarted.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/GetingStarted.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,230 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 1. Getting Started</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="Conventions.html">Prev</a> - Typographical Conventions</div>
+<div class="navnext">A Simple Plugin - <a accesskey="n" href="ASimplePlugin.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="GetingStarted"></a>Chapter 1. Getting Started</h2></div></div></div>
+<p>The Traffic Server API enables you to create plugins, using the C
+ programming language, that customize the behavior of your Traffic Server
+ installation. This chapter contains the following sections:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p><a href="GetingStarted.html#UnderstandingTSPlugins" title="Understanding Traffic Server Plugins">Understanding Traffic Server Plugins</a> - a brief introduction
+ to plugins. For more details, see <a href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">How to Create Traffic Server Plugins</a></p></li>
+<li>
+ <p><a href="ASimplePlugin.html" title="A Simple Plugin">A Simple Plugin</a> - walks through compiling and
+ loading an example <code>hello world</code> plugin.</p></li>
+<li>
+ <p><a href="PlusingRegisAndVersionCkg.html" title="Plugin Registration and Version Checking">Plugin Registration and Version Checking</a> - shows you how to
+ register your plugin and make sure it's compatible with the version
+ of Traffic Server you're using.</p></li>
+<li>
+ <p><a href="NamingConventions.html" title="Naming Conventions">Naming Conventions</a> - outlines Traffic Server API
+ naming conventions. For guidelines on creating plugin source code, see
+ <a href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">How to Create Traffic Server Plugins</a>.</p></li>
+</ul></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="UnderstandingTSPlugins"></a>Understanding Traffic Server Plugins</h2></div></div></div>
+<p>Traffic Server enables sophisticated caching and processing of
+ web-related traffic, such as DNS and HTTP requests and responses.</p>
+<p>Traffic Server itself consists of an event-driven loop that can be
+ simplified as follows:</p>
+<pre class="programlisting">for (;;) {
+event = get_next_event();
+handle_event (event);
+}</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="RoleOfPlugins"></a>The Role of Plugins</h3></div></div></div>
+<p>You compile your plugin source code to create a shared library
+ that Traffic Server loads when it is started. Your plugin contains
+ callback functions that are registered for specific Traffic Server
+ events. When Traffic Server needs to process an event, it invokes any
+ and all call-back functions you've registered for that event
+ type.</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>Since plugins add object code to Traffic Server, programming
+ errors in a plugin can have serious implications. Bugs in your
+ plugin, such as an out-of-range pointer, can cause Traffic Server
+ processes to crash and may ultimately result in unpredictable
+ behavior.</p></td></tr>
+</table></div>
+<div class="figure">
+<a name="Fig_PluginProcess"></a><p class="title"><b>Figure 1.1. Plugin Process</b></p>
+<div class="mediaobject"><img src="images/plugin_process.jpg" alt="Plugin Process" /></div>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="PossibleUses"></a>Possible Uses for Plugins</h3></div></div></div>
+<p>Possible uses for plugins include the following:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p>HTTP processing: plugins can filter, blacklist, authorize
+ users, transform content</p></li>
+<li>
+ <p>Protocol support: plugins can enable Traffic Server to
+ proxy-cache new protocol content</p></li>
+</ul></div>
+<p>Some examples of plugins include:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><b>Blacklisting plugin</b>: denies attempts to access web sites
+ that are off-limits.</p></li>
+<li><p><b>Append transform plugin</b>: adds text to HTTP response
+ content.</p></li>
+<li><p><b>Image conversion plugin</b>: transforms JPEG images to GIF
+ images.</p></li>
+<li><p><b>Compression plugin</b>: sends response content to a compression
+ server that compresses the data (alternatively, a compression
+ library local to the Traffic Server host machine could do the
+ compression).</p></li>
+<li>
+ <p><b>Authorization plugin</b>: checks a user's permissions to access
+ particular web sites. The plugin could consult a local
+ authorization program or send queries to an authorization
+ server.</p></li>
+<li><p><b>A plugin that gathers client information</b> from request
+ headers and enters this information in a database.</p></li>
+<li>
+ <p><b>Protocol plugin</b>: listens for specific protocol requests on a
+ designated port and then uses Traffic Server's proxy server &
+ cache to serve client requests.</p></li>
+</ul></div>
+<p>The figure below, <a href="GetingStarted.html#Fig_PossibleTSPlugins" title="Figure 1.2. Possible Traffic Server Plugins">Possible Traffic Server Plugins</a>, illustrates several
+ types of plugins.</p>
+<div class="figure">
+<a name="Fig_PossibleTSPlugins"></a><p class="title"><b>Figure 1.2. Possible Traffic Server Plugins</b></p>
+<div class="mediaobject"><img src="images/Uses.jpg" alt="Possible Traffic Server Plugins" /></div>
+</div>
+<p>You can find basic examples for many plugins in the SDK sample
+ code:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p><code class="filename">append-transform.c</code> adds text from a
+ specified file to HTTP/text responses. This plugin is explained in <a href="AppendTransformPlugin.html" title="The Append-Transform Plugin"> The Append-Transform Plugin</a>.</p></li>
+<li>
+ <p>The compression plugin in the figure communicates with the
+ server that actually does the compression. The
+ <code class="filename">server-transform.c</code> plugin shows how to open a
+ connection to a transformation server, have the server do the
+ transformation, and send transformed data back to the client. Although the transformation is null in
+ <code class="filename">server-transform.c</code>, a compression or image translation plugin could be
+ implemented in a similar way.</p></li>
+<li><p><code class="filename">basic-auth.c</code> performs basic HTTP proxy
+ authorization.</p></li>
+<li>
+ <p><code class="filename">blacklist-1.c</code> reads blacklisted servers
+ from a configuration file and denies client access to these
+ servers. This plugin is explained
+ in <a href="BlacklistPlugin.html" title="The Blacklist Plugin">The Blacklist Plugin</a>.</p></li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="PluginLoading"></a>Plugin Loading</h3></div></div></div>
+<p>When Traffic Server is first started, it consults the
+ <code class="filename">plugin.config</code> file to determine the names of all
+ shared plugin libraries that need to be loaded. The
+ <code class="filename">plugin.config</code> file also defines arguments that
+ are to be passed to each plugin's initialization function,
+ <code class="function">INKPluginInit</code>. The
+ <code class="filename">records.config</code> file defines the path to each
+ plugin shared library, as described in <a href="SpecifyingPluginLocation.html" title="Specify the Plugin's Location">Specify the Plugin's Location</a>.</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>The path for each of these files is
+ <code class="filename"><code class="varname"><<i class="replaceable">root_dir</i>></code>/config/</code>,
+ where <code class="varname"><<span class="replaceable">root_dir</span>></code> is where you installed
+ Traffic Server.</p></td></tr>
+</table></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="PluginConfiguration"></a>Plugin Configuration<a class="indexterm" name="id306433"></a></h3></div></div></div>
+<p>The sample <code class="filename">plugin.config</code> file below
+ contains a comment line, a blank line, and two plugin
+ configurations:</p>
+<pre class="programlisting"># This is a comment line.
+
+my-plugin.so www.junk.com www.trash.com www.garbage.com
+some-plugin.so arg1 arg2 $proxy.config.http.cache.on</pre>
+<p>Each plugin configuration in the
+ <code class="filename">plugin.config</code> file resembles a UNIX or DOS shell
+ command; each line in <code class="filename">plugin.config</code> cannot exceed
+ 1023 characters.</p>
+<p>The first plugin configuration is for a plugin named
+ <code class="filename">my-plugin.so</code>. It contains three arguments that
+ are to be passed to that plugin's initialization routine. The second
+ configuration is for a plugin named
+ <code class="filename">some-plugin.so</code>; it contains three arguments.
+ The last argument, <em class="parameter"><code>$proxy.config.http.cache.on</code></em>,
+ is actually a configuration variable. Traffic Server will look up the
+ specified configuration variable and substitute its value.</p>
+<p><a name="MultipleEntries_SamePlugin"></a>Plugins with global
+ variables should not appear more than once in
+ <code class="filename">plugin.config</code>. For example, if you enter:</p>
+<pre class="programlisting">add-header.so header1
+add-header.so header2</pre>
+<p>then the second global variable, <code>header2</code>, will be used for both
+ instances. A simple workaround is to give different names to different
+ instances of the same plugin. For example:</p>
+<pre class="programlisting">cp add-header.so add-header1.so
+cp add-header.so add-header2.so</pre>
+<p>These entries will produce the desired result
+ below:</p>
+<pre class="programlisting">add-header1.so header1
+add-header2.so header2</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="ConfigFileRules"></a>Configuration File Rules</h3></div></div></div>
+<div class="itemizedlist"><ul type="disc">
+<li><p>Comment lines begin with <span class="bold"><strong>#</strong></span>
+ and continue to the end of the line.</p></li>
+<li><p>Blank lines are ignored.</p></li>
+<li><p>Plugins are loaded and initialized by Traffic Server in the
+ order they appear in the <code class="filename">plugin.config</code>
+ file.</p></li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="PluginInitialization"></a>Plugin Initialization</h3></div></div></div>
+<p>Each plugin must define an initialization function named
+ <code class="function">INKPluginInit</code> that Traffic Server invokes when the plugin is loaded. The <code class="function">INKPluginInit</code>
+ function is commonly used to read configuration information and
+ register hooks for event notification.</p>
+<p>The <code class="function">INKPluginInit</code> function has two
+ arguments:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>The <code class="code">argc</code> argument represents the number of
+ arguments defined in the <code class="filename">plugin.config</code> file
+ for that particular plugin</p></li>
+<li><p>The <code class="code">argv</code> argument is an array of pointers to
+ the actual arguments defined in the
+ <code class="filename">plugin.config</code> file for that plugin</p></li>
+</ul></div>
+<p>See <a href="InitializationFunctions.html#INKPluginInit" title="INKPluginInit">INKPluginInit</a> for details about
+ <code class="function">INKPluginInit</code>.</p>
+</div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/GetingStarted.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/GuideTSHTTPHdrSyst.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/GuideTSHTTPHdrSyst.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/GuideTSHTTPHdrSyst.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,54 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Guide to Traffic Server HTTP Header System</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="HTTPHeaders.html">Prev</a> - Chapter 10. HTTP Headers</div>
+<div class="navnext">Duplicate MIME Fields Are Not Coalesced - <a accesskey="n" href="DuplicateMIMEFlds.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="GuideTSHTTPHdrSyst"></a>Guide to Traffic Server HTTP Header System</h2></div></div></div>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="NoNullTerminatedStrings"></a>No Null-Terminated Strings<a class="indexterm" name="id380931"></a></h3></div></div></div>
+<p>It's not safe to assume that
+ string data contained in marshal buffers (such as URLs and MIME
+ fields) is stored in null-terminated string copies. Therefore,
+ your plugins should always use the length parameter when retrieving or
+ manipulating these strings. You <span class="bold"><strong>cannot</strong></span> pass in <code class="code">NULL</code> for
+ string-length return values; string values returned from marshall
+ buffers are not null-terminated. If you need a null-terminated value,
+ then use <code class="function">INKstrndup</code> to automatically null-terminate a
+ string. The strings that come back and are not null-terminated
+ <span class="bold"><strong>cannot</strong></span> be passed into the common
+ <code class="code">str*()</code> routines</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>Values returned from a marshall buffer can be
+ <code class="code">NULL</code>, which means the field or object requested does
+ not exist.</p>
+<p>For example (from the <code class="code">blacklist-1</code> sample):</p>
+<pre class="programlisting">char *host_string;
+int host_length;
+host_string = INKUrlHostGet (bufp, url_loc, &host_length);
+for (i = 0; i < nsites; i++) {
+if (strncmp (host_string, sites[i], host_length) == 0) {
+...
+}</pre>
+<p>See the sample plugins for additional examples.</p>
+</td></tr>
+</table></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/GuideTSHTTPHdrSyst.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPAlternateSelection.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPAlternateSelection.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPAlternateSelection.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,185 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>HTTP Alternate Selection</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="InitiateHTTPConnection.html">Prev</a> - Initiate HTTP Connection</div>
+<div class="navnext">Chapter 9. Miscellaneous Interface Guide - <a accesskey="n" href="MiscellaneousInterfaceGuide.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HTTPAlternateSelection"></a>HTTP Alternate Selection</h2></div></div></div>
+<p>The HTTP alternate selection functions provide a mechanism for
+ hooking into Traffic Server's alternate selection mechanism and
+ augmenting it with additional information. <b>HTTP alternate selection</b> refers to the process of choosing between several alternate versions of
+ a document for a specific URL. Alternates arise because the HTTP 1.1
+ specification allows different documents to be sent back for the same
+ URL (depending on the clients request). For example, a server might send
+ back a GIF image to a client that only accepts GIF images, and might send
+ back a JPEG image to a client that only accepts JPEG images.</p>
+<p>The alternate selection mechanism is invoked when Traffic Server
+ looks up a URL in its cache. For each URL, Traffic Server stores a vector
+ of alternates. For each alternate in this vector, Traffic Server
+ computes a quality value between 0 and 1 that represents how "good" the alternate
+ is. A quality value of 0 means that the alternate is unacceptable;
+ a value of 1 means that the alternate is a perfect match.</p>
+<p>If a plugin hooks onto <code class="code">theINK_HTTP_SELECT_ALT_HOOK</code>, then it
+ will be called back when Traffic Server performs alternate selection.
+ You cannot register locally to the hook
+ <code class="code">INK_HTTP_SELECT_ALT_HOOK</code> by using <code>INKHttpTxnHookAdd</code> - you can only do so by
+ using only <code>INKHttpHookAdd</code>. Since Traffic Server does not
+ actually have an HTTP transaction or an HTTP session on hand when
+ alternate selection is performed, it is only valid to hook onto the global list
+ of <code class="code">INK_HTTP_SELECT_ALT_HOOK</code>. Traffic Server calls each of the
+ select alternate hooks with the <code class="code">INK_EVENT_HTTP_SELECT_ALT</code> event. The <code>void *edata</code> argument
+ that is passed to the continuation is a pointer to an <code class="code">INKHttpAltInfo</code><a class="indexterm" name="id379481"></a> structure. It can be used later to call the HTTP
+ alternate selection functions listed at the end of this section. Unlike
+ other hooks, this alternate selection callout is non-blocking; the
+ expectation is that the quality value for the alternate will be changed
+ by a call to <code class="function">INKHttpAltInfoQualitySet</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>HTTP SM does not have to be reenabled using
+ <code class="function">INKHttpTxnReenable</code> or any other APIs; just return
+ from the function.</p></td></tr>
+</table></div>
+<p>The sample code below shows how to call the
+ alternate APIs.</p>
+<pre class="programlisting">static void handle_select_alt(INKHttpAltInfo infop)
+{
+ INKMBuffer client_req_buf, cache_resp_buf;
+ INKMLoc client_req_hdr, cache_resp_hdr;
+
+ INKMLoc accept_transform_field;
+ INKMLoc content_transform_field;
+
+ int accept_transform_len = -1, content_transform_len = -1;
+ const char* accept_transform_value = NULL;
+ const char* content_transform_value = NULL;
+ int content_plugin, accept_plugin;
+
+ float quality;
+
+ /* get client request, cached request and cached response */
+ INKHttpAltInfoClientReqGet (infop, &client_req_buf, &client_req_hdr);
+ INKHttpAltInfoCachedRespGet(infop, &cache_resp_buf, &cache_resp_hdr);
+
+ /* get the Accept-Transform field value from the client request */
+ accept_transform_field = INKMimeHdrFieldFind(client_req_buf,
+client_req_hdr, "Accept-Transform", -1);
+ if (accept_transform_field) {
+ INKMimeHdrFieldValueStringGet(client_req_buf, client_req_hdr,
+ accept_transform_field, 0, &accept_transform_value,
+ &accept_transform_len);
+ INKDebug(DBG_TAG, "Accept-Transform = |%s|",
+ accept_transform_value);
+ }
+
+ /* get the Content-Transform field value from cached server response
+*/
+ content_transform_field = INKMimeHdrFieldFind(cache_resp_buf,
+cache_resp_hdr, "Content-Transform", -1);
+ if (content_transform_field) {
+ INKMimeHdrFieldValueStringGet(cache_resp_buf, cache_resp_hdr,
+ content_transform_field,
+ 0, &content_transform_value,
+ &content_transform_len);
+ INKDebug(DBG_TAG, "Content-Transform = |%s|",
+ content_transform_value);
+ }
+
+ /* compute quality */
+ accept_plugin = (accept_transform_value && (accept_transform_len > 0) &&
+ (strncmp(accept_transform_value, "plugin",
+accept_transform_len) == 0));
+
+ content_plugin = (content_transform_value && (content_transform_len >0) &&
+ (strncmp(content_transform_value, "plugin",
+content_transform_len) == 0));
+
+ if (accept_plugin) {
+ quality = content_plugin ? 1.0 : 0.0;
+ } else {
+ quality = content_plugin ? 0.0 : 0.5;
+ }
+
+ INKDebug(DBG_TAG, "Setting quality to %3.1f", quality);
+
+ /* set quality for this alternate */
+ INKHttpAltInfoQualitySet(infop, quality)/
+
+ /* cleanup */
+ if (accept_transform_field)
+ INKHandleMLocRelease(client_req_buf, client_req_hdr,
+ accept_transform_field);
+ INKHandleMLocRelease(client_req_buf, INK_NULL_MLOC, client_req_hdr);
+
+ if (content_transform_field)
+ INKHandleMLocRelease(cache_resp_buf, cache_resp_hdr,
+ content_transform_field);
+ INKHandleMLocRelease(cache_resp_buf, INK_NULL_MLOC, cache_resp_hdr);
+ }
+
+
+ static int alt_plugin(INKCont contp, INKEvent event, void *edata)
+ {
+ INKHttpAltInfo infop;
+
+ switch (event) {
+ case INK_EVENT_HTTP_SELECT_ALT:
+ infop = (INKHttpAltInfo)edata;
+ handle_select_alt(infop);
+ break;
+
+ default:
+ break;
+ }
+
+ return 0;
+ }
+
+ void INKPluginInit (int argc, const char *argv[])
+ {
+ INKHttpHookAdd(INK_HTTP_SELECT_ALT_HOOK, INKContCreate (alt_plugin,
+ NULL));
+}</pre>
+<p>Traffic Server augments the alternate selection through these
+ callouts using the following algorithm:</p>
+<div class="orderedlist"><ol type="1">
+<li>
+ <p>Traffic Server computes its own quality value for the
+ alternate, taking into account the quality of the
+ accept match, the encoding match, and the language match.</p></li>
+<li><p>Traffic Server then calls out each of the continuations on the
+ global <code class="code">INK_HTTP_SELECT_ALT_HOOK</code>'s list.</p></li>
+<li>
+ <p>It multiplies its quality value with the value returned by
+ each callout. Since all of the values are clamped to be between 0
+ and 1, the final value will be between 0 and 1 as well.</p></li>
+<li><p>This algorithm also ensures that a single callout can block
+ the usage of a given alternate by specifying a quality value of
+ 0.</p></li>
+</ol></div>
+<p>A common usage for the alternate selection mechanism is when a
+ plugin transforms a document for some clients and not for others, but
+ wants to store both the transformed and unchanged document. The
+ client's request will specify whether it accepted the transformed
+ document. The plugin will then determine if the alternate matches
+ this specification and then set the appropriate quality level for the alternate.</p>
+<p>The HTTP alternate selection functions are:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="AlternateSelectionFunctions.html#INKHttpAltInfoCachedReqGet" title="INKHttpAltInfoCachedReqGet">INKHttpAltInfoCachedReqGet</a></p></li>
+<li><p><a href="AlternateSelectionFunctions.html#INKHttpAltInfoCachedRespGet" title="INKHttpAltInfoCachedRespGet">INKHttpAltInfoCachedRespGet</a></p></li>
+<li><p><a href="AlternateSelectionFunctions.html#INKHttpAltInfoClientReqGet" title="INKHttpAltInfoClientReqGet">INKHttpAltInfoClientReqGet</a></p></li>
+<li><p><a href="AlternateSelectionFunctions.html#INKHttpAltInfoQualitySet" title="INKHttpAltInfoQualitySet">INKHttpAltInfoQualitySet</a></p></li>
+</ul></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPAlternateSelection.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPFunctions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,180 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>HTTP Functions</title>
+<!--#include file="top.html" -->
+</head><div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKThreadSelf.html">Prev</a> - INKThreadSelf</div>
+<div class="navnext">Session Functions - <a accesskey="n" href="HTTPSessionFunctions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HTTPFunctions"></a>HTTP Functions</h2></div></div></div>
+
+<p><b>Table of Contents</b></p>
+<b><ul>
+<li><span class="section"><a href="HTTPFunctions.html#GeneralHTTPFunctions">General HTTP Functions</a></span></li>
+<ul>
+ <li><a href="HTTPFunctions.html#INKHttpIsInternalRequest">INKHttpIsInternalRequest</a></li>
+ <li><a href="HTTPFunctions.html#INKHttpSchedule">INKHttpSchedule</a></li>
+</ul>
+
+<li><span class="section"><a href="HTTPFunctions.html#HTTPHookFunctions">Hook Functions</a></span></li>
+<ul><li><a href="HTTPFunctions.html#INKHttpHookAdd">INKHttpHookAdd</a></li></ul>
+
+<li><span class="section"><a href="HTTPSessionFunctions.html">Session Functions</a></span></li>
+<ul>
+<li><a href="HTTPSessionFunctions.html#INKHttpSsnHookAdd">INKHttpSsnHookAdd</a> </li>
+<li><a href="HTTPSessionFunctions.html#INKHttpSsnReenable">INKHttpSsnReenable</a> </li>
+</ul>
+
+<li><span class="section"><a href="HTTPTransactionFunctions.html">HTTP Transaction Functions</a></span></li>
+
+<ul>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnCacheLookupStatusGet">INKHttpTxnCacheLookupStatusGet</a></li>
+<li><b><a href="HTTPTransactionFunctions.html#INKHttpTxnCacheLookupStatusSet">INKHttpTxnCacheLookupStatusSet</a></b></li>
+ <li><a href="HTTPTransactionFunctions.html#INKHttpTxnCachedReqGet">INKHttpTxnCachedReqGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnCachedRespGet">INKHttpTxnCachedRespGet</a></li>
+
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnClientIncomingPortGet">INKHttpTxnClientIncomingPortGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnClientIPGet ">INKHttpTxnClientIPGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnClientRemotePortGet">INKHttpTxnClientRemotePortGet</a></li>
+
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnClientReqGet">INKHttpTxnClientReqGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnClientRespGet">INKHttpTxnClientRespGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnErrorBodySet">INKHttpTxnErrorBodySet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnHookAdd">INKHttpTxnHookAdd</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnNextHopIPGet">INKHttpTxnNextHopIPGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnParentProxyGet">INKHttpTxnParentProxyGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnParentProxySet">INKHttpTxnParentProxySet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnPristineUrlGet"><b>INKHttpTxnPristineUrlGet</b></a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnReenable">INKHttpTxnReenable</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnServerIPGet">INKHttpTxnServerIPGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnServerReqGet">INKHttpTxnServerReqGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnServerRespGet">INKHttpTxnServerRespGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnSetRespCacheableSet">INKHttpTxnSetRespCacheableSet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnSkipRww">INKHttpTxnSkipRww</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnSsnGet">INKHttpTxnSsnGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnTransformedRespCache">INKHttpTxnTransformedRespCache</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnTransformRespGet">INKHttpTxnTransformRespGet</a></li>
+<li><a href="HTTPTransactionFunctions.html#INKHttpTxnUntransformedRespCache">INKHttpTxnUntransformedRespCache</a></li>
+
+</ul>
+
+
+</ul></b>
+
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="GeneralHTTPFunctions"></a>General HTTP Functions</h3></div></div></div>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpIsInternalRequest"></a>INKHttpIsInternalRequest</h4></div></div></div>
+<p>Checks if the state machine/request is internal.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd>
+ <p><code class="code">bool INKHttpIsInternalRequest (INKHttpTxn <span class="replaceable">txnp</span>);</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Checks if the request being handled originated from a Traffic Server process; provides an API to distinguish between internal and external requests.
+An internal request is any request that comes in through a connection created by <code>INKHttpConnect</code>.</p>
+<p><u><i>Background Info:</i></u> Some plugins (like those modifying cache-control behaviors) need to know whether the current state machine they are running within was originated by an external connection (through the HTTP port) or by an internal one (such as one created by <code>INKHttpConnect</code>). Formerly there was no way for the state machine to know whether it was created by an external or internal connection. Since the state machine itself didn't know how it was created, plugins had no way of knowing, either. <span class="title"><code>INKHttpIsInternalRequest</code></span> solves this problem.</p>
+</dd>
+
+
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">true </code>if the request originated from within a Traffic Server process.</p>
+</dd>
+
+<dt><span class="term"><b>Example Use-Case Scenario</b></span></dt>
+<dd>
+<p>A plugin that implements stale-while-revalidate (SWR) makes a background fetch request when the data in cache is stale. The background fetch request is made on the <code>INKVConn</code> returned by <code>INKHttpConnect</code>. When the SWR plugin sees this background fetch request, it needs to turn off read while write. </p>
+<p>In addition to checking for the special header that is inserted for the background fetch request, the plugin must
+ check to see if the request was internal or not (this is because the header can be spoofed).</p>
+</dd>
+
+<dd>
+
+</dd>
+</dl>
+</div>
+</div>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpSchedule"></a>INKHttpSchedule</h4></div></div></div>
+<p>Schedules an HTTP continuation to receive an event.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd>
+ <p><code class="code"> INKAction INKHttpSchedule (INKCont <span class="replaceable">contp</span>, INKHttpTxn <span class="replaceable">txnp</span>, unsigned int <span class="replaceable"> time</span>) </code></p></dd>
+
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Schedules the HTTP continuation (represented by <code class="code"><span class="replaceable"> contp </span></code>) to receive an event.</p></dd>
+<dd>
+ <p> The timeout refers to a time from the present (in milliseconds) at which to send the
+ event. </p>
+</dd>
+<dd>
+ <p>If the timeout is 0 when <code class="code"><span class="replaceable"> contp </span></code> is called back, then the event sent is
+ <code>INK_EVENT_IMMEDIATE</code>. If timeout is greater than 0, then the event sent is
+ <code>INK_EVENT_TIMEOUT</code>. </p>
+</dd>
+
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>An <code>INKAction</code> object.</p>
+<p><code class="code">INK_ERROR_PTR</code> if there is an error.</p>
+</dd>
+
+</dl></div>
+</div>
+
+</div>
+</div>
+
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="HTTPHookFunctions"></a>Hook Functions</h3></div></div></div>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHookAdd"></a>INKHttpHookAdd</h4></div></div></div>
+<p>Adds an HTTP hook.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHookAdd (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 global HTTP hooks specified by
+ <code class="code"><em class="replaceable"><code>id</code></em></code>. Since
+ <code class="function">INKHttpHookAdd</code> adds
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> to a global list,
+ this function is only safe to call from the plugin
+ initialization routine.</p></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>
+
+
+
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaderFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaderFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaderFunctions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,863 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>HTTP Header Functions</title>
+<!--#include file="top.html" -->
+</head><div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKMBufferDestroy.html">Prev</a> - INKMBufferDestroy</div>
+<div class="navnext">URL Functions - <a accesskey="n" href="URLFunctions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="HTTPHeaderFunctions"></a>HTTP Header Functions</h3></div></div></div>
+<p>The HTTP header functions are listed below:
+<b>
+<ul>
+
+<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>
+</ul>
+</b>
+<div class="section" lang="en">
+ <div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHdrClone"></a>INKHttpHdrClone</h4></div></div></div>
+<p>Copies an HTTP header to a marshal buffer and returns the
+ <code>INKMLoc</code> location of the copied header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKHttpHdrClone (INKMBuffer
+ <em class="replaceable"><code>dest_bufp</code></em>, INKMBuffer
+ <em class="replaceable"><code>src_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>src_hdr</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Copies the contents of the HTTP header located at
+ <code class="code"><em class="replaceable"><code>src_hdr </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> to the
+ marshal buffer located at
+ <code class="code"><em class="replaceable"><code>dest_bufp</code></em></code>. If the HTTP
+ header located at the
+ <code class="code"><em class="replaceable"><code>src_hdr </code></em></code> is an HTTP
+ request header, then make sure that it has a valid <em>method</em>, <em>url</em>,
+ <em>protocol</em>, and <em>version</em>. If the HTTP header located at the <code class="code"><em class="replaceable"><code>src_hdr </code></em></code> is a HTTP
+ response header, then make sure that it has a valid <em>protocol</em>, <em>version</em>, <em>status</em>, and <em>reason</em>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+<p>Release the returned handle with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>Returns the <code class="function">INKMLoc</code> location of the
+ copied header.</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="INKHttpHdrCopy"></a>INKHttpHdrCopy</h4></div></div></div>
+<p>Copies an HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHdrCopy (INKMBuffer
+ <em class="replaceable"><code>dest_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>dest_hdr_loc</code></em>, INKMBuffer
+ <em class="replaceable"><code>src_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>src_hdr_loc</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Copies the contents of the HTTP header located at
+ <code class="code"><em class="replaceable"><code>src_hdr_loc </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> to the HTTP
+ header located at
+ <code class="code"><em class="replaceable"><code>dest_hdr_loc </code></em></code> within
+ the marshal buffer
+ <code class="code"><em class="replaceable"><code>dest_bufp</code></em></code>.
+ <code class="function">INKHttpHdrCopy</code> works correctly even if
+ <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> and
+ <code class="code"><em class="replaceable"><code>dest_bufp </code></em></code> point to
+ different marshal buffers. Make sure that the destination HTTP
+ header exists (has been created) before copying into it.
+ <code class="function">INKHttpHdrCopy</code> automatically makes sure
+ the types for the source and destination HTTP headers match;
+ if the destination type is not equal to the source type, then
+ <code class="function">INKHttpHdrCopy</code> calls
+ <code class="function">INKHttpHdrTypeSet</code>. Do not call
+ <code class="function">INKHttpHdrTypeSet</code> on the destination
+ header after using <code class="function">INKHttpHdrCopy</code>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</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><code class="function">INKHttpHdrCopy</code> appends the port
+ number to the domain of the URL portion of the header. For
+ example, <code><u>http://www.dianes-goanaut.com</u></code> appears as <code><u>http://www.dianes-goanaut.com:80/</u></code> in the destination buffer.</p></td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</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="INKHttpHdrCreate"></a>INKHttpHdrCreate</h4></div></div></div>
+<p>Creates a new HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKHttpHdrCreate (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Creates a new HTTP header with the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>. When newly-created, the HTTP header is assigned an
+ <code class="function">INKHttpType</code> value of
+ <code class="code">INK_HTTP_TYPE_UNKNOWN</code>. You can change the type
+ after creating the header using
+ <code class="function">INKHttpHdrTypeSet</code>, but you can only
+ change the type once. You cannot modify the type after setting
+ it.</p>
+<p>Release with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd><p>A pointer to the new HTTP header.</p></dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHdrDestroy"></a>INKHttpHdrDestroy</h4></div></div></div>
+<p>Destroys an HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHdrDestroy (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>Destroys the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></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 forget to use
+ <code class="function">INKHandleMLocRelease</code> to release the
+ handle
+ <code class="code"><em class="replaceable"><code>hdr_loc</code></em></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_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="INKHttpHdrLengthGet"></a>INKHttpHdrLengthGet</h4></div></div></div>
+<p>Calculates the length of an HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpHdrLengthGet (INKMBuffer bufp, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Calculates the length of the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code> if
+ it was returned as a string. This is the length of the HTTP
+ header in its unparsed form and is also the number of bytes
+ that will be added to the IO buffer by a call to
+ <code class="function">INKHttpHdrPrint</code>.</p>
+<p>The header could be a request header, response header,
+ or a standalone header that you have created. Be sure to call
+ this function appropriately. For example: if you want the length of a
+ request header, then call this function after
+ <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The length of the specified HTTP header.</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="INKHttpHdrMethodGet"></a>INKHttpHdrMethodGet</h4></div></div></div>
+<p>Gets the method portion of an HTTP request header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">const char* INKHttpHdrMethodGet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, int
+ *<em class="replaceable"><code>length</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the method from the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ The length of the returned string is placed in the length
+ argument. The string returned is not guaranteed to be
+ NULL terminated.</p>
+<p>It is an error to try to retrieve the method from an
+ HTTP header that is not of type
+ <code class="code">INK_HTTP_TYPE_REQUEST</code>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A pointer to the method portion of the specified HTTP
+ request header.</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="INKHttpHdrMethodSet"></a>INKHttpHdrMethodSet</h4></div></div></div>
+<p>Sets the HTTP method.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHdrMethodSet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, const char
+ *<em class="replaceable"><code>value</code></em>, int
+ <em class="replaceable"><code>length</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets the method in the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ If <code class="code"><em class="replaceable"><code>length </code></em></code> is -1, then
+ it is assumed the value is null-terminated. Otherwise, the
+ length of the string value is taken to be length. The string
+ is copied to within
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>, so it is okay to
+ modify or delete value after calling
+ <code class="function">INKHttpHdrMethodSet</code>. It is an error to
+ try to set the method in an HTTP header that is not of type
+ <code class="code">INK_HTTP_TYPE_REQUEST</code>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</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="INKHttpHdrPrint"></a>INKHttpHdrPrint</h4></div></div></div>
+<p>Prints the HTTP header to an IO buffer.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHdrPrint (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKIOBuffer
+ <em class="replaceable"><code>iobufp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Formats the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code>
+ into the IO buffer
+ <code class="code"><em class="replaceable"><code>iobufp</code></em></code>. See IO
+ buffers for information about allocating an IO
+ buffer and retrieving data from within one.</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="INKHttpHdrReasonGet"></a>INKHttpHdrReasonGet</h4></div></div></div>
+<p>Gets the reason phrase from an HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">const char* INKHttpHdrReasonGet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, int
+ *<em class="replaceable"><code>length</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the reason phrase from the HTTP header located
+ at <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ The length of the returned string is placed in the
+ <code class="code"><em class="replaceable"><code>length </code></em></code> argument. It is
+ an error to try to retrieve the reason phrase from an HTTP
+ header that is not of type
+ <code class="code">INK_HTTP_TYPE_RESPONSE</code>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</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>The returned string is not guaranteed to be
+ null-terminated.</p></td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>Pointer to the reason phrase in the specified HTTP
+ header.</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="INKHttpHdrReasonLookup"></a>INKHttpHdrReasonLookup</h4></div></div></div>
+<p>Provides the default reason phrase for a specified Traffic
+ Server HTTP status code.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">const char* INKHttpHdrReasonLookup (INKHttpStatus
+ <em class="replaceable"><code>status</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Returns the default reason phrase for the status code
+ <code class="code"><em class="replaceable"><code>status</code></em></code>.</p>
+<p><code class="function">INKHttpHdrReasonLookup</code> returns a
+ string that is null-terminated. It should not be freed or
+ released; it's a global shared value.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>Pointer to the default reason phrase for the specified
+ Traffic Server status code.</p>
+<p><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="INKHttpHdrReasonSet"></a>INKHttpHdrReasonSet</h4></div></div></div>
+<p>Sets the reason phrase in an HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHdrReasonSet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, const char
+ *<em class="replaceable"><code>value</code></em>, int
+ <em class="replaceable"><code>length</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets the reason phrase in the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ If <code class="code"><em class="replaceable"><code>length </code></em></code> is -1, then
+ it is assumed that
+ <code class="code"><em class="replaceable"><code>value </code></em></code> is
+ null-terminated. Otherwise, the length of the string value is
+ taken to be <code class="code"><em class="replaceable"><code>length</code></em></code>.
+ The string is copied to within
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>, so it is okay to
+ modify or delete <code class="code"><em class="replaceable"><code>value </code></em></code>
+ after calling <code class="function">INKHttpHdrReasonSet</code>. It is
+ an error to try to set the reason phrase in an HTTP header
+ that is not of type
+ <code class="code">INK_HTTP_TYPE_RESPONSE</code>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_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 the operation does not
+ complete successfully.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHdrStatusGet"></a>INKHttpHdrStatusGet</h4></div></div></div>
+<p>Retrieves the status code from an HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKHttpStatus INKHttpHdrStatusGet (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 status code from the HTTP header located
+ at <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ It is an error to try and retrieve the status code from an
+ HTTP header that is not of type
+ <code class="code">INK_HTTP_TYPE_RESPONSE</code>.
+ <code class="function">INKHttpStatus</code> is an enumerated
+ type.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The status code from the specified HTTP header.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+<dt><span class="term"><b>Example</b></span></dt>
+<dd>
+<p>Values of <code class="function">INKHttpStatus</code> are the
+ following:</p>
+<pre class="programlisting">
+typedef enum
+{
+ INK_HTTP_STATUS_NONE = 0,
+
+ INK_HTTP_STATUS_CONTINUE = 100,
+ INK_HTTP_STATUS_SWITCHING_PROTOCOL = 101,
+
+ INK_HTTP_STATUS_OK = 200,
+ INK_HTTP_STATUS_CREATED = 201,
+ INK_HTTP_STATUS_ACCEPTED = 202,
+ INK_HTTP_STATUS_NON_AUTHORITATIVE_INFORMATION = 203,
+ INK_HTTP_STATUS_NO_CONTENT = 204,
+ INK_HTTP_STATUS_RESET_CONTENT = 205,
+ INK_HTTP_STATUS_PARTIAL_CONTENT = 206,
+
+ INK_HTTP_STATUS_MULTIPLE_CHOICES = 300,
+ INK_HTTP_STATUS_MOVED_PERMANENTLY = 301,
+ INK_HTTP_STATUS_MOVED_TEMPORARILY = 302,
+ INK_HTTP_STATUS_SEE_OTHER = 303,
+ INK_HTTP_STATUS_NOT_MODIFIED = 304,
+ INK_HTTP_STATUS_USE_PROXY = 305,
+
+ INK_HTTP_STATUS_BAD_REQUEST = 400,
+ INK_HTTP_STATUS_UNAUTHORIZED = 401,
+ INK_HTTP_STATUS_PAYMENT_REQUIRED = 402,
+ INK_HTTP_STATUS_FORBIDDEN = 403,
+ INK_HTTP_STATUS_NOT_FOUND = 404,
+ INK_HTTP_STATUS_METHOD_NOT_ALLOWED = 405,
+ INK_HTTP_STATUS_NOT_ACCEPTABLE = 406,
+ INK_HTTP_STATUS_PROXY_AUTHENTICATION_REQUIRED = 407,
+ INK_HTTP_STATUS_REQUEST_TIMEOUT = 408,
+ INK_HTTP_STATUS_CONFLICT = 409,
+ INK_HTTP_STATUS_GONE = 410,
+ INK_HTTP_STATUS_LENGTH_REQUIRED = 411,
+ INK_HTTP_STATUS_PRECONDITION_FAILED = 412,
+ INK_HTTP_STATUS_REQUEST_ENTITY_TOO_LARGE = 413,
+ INK_HTTP_STATUS_REQUEST_URI_TOO_LONG = 414,
+ INK_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE = 415,
+
+ INK_HTTP_STATUS_INTERNAL_SERVER_ERROR = 500,
+ INK_HTTP_STATUS_NOT_IMPLEMENTED = 501,
+ INK_HTTP_STATUS_BAD_GATEWAY = 502,
+ INK_HTTP_STATUS_SERVICE_UNAVAILABLE = 503,
+ INK_HTTP_STATUS_GATEWAY_TIMEOUT = 504,
+ INK_HTTP_STATUS_HTTPVER_NOT_SUPPORTED = 505
+} INKHttpStatus;</pre>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHdrStatusSet"></a>INKHttpHdrStatusSet</h4></div></div></div>
+<p>Sets the status code within an HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHdrStatusSet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKHttpStatus
+ <em class="replaceable"><code>status</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets the status code in the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ It is an error to try and set the
+ <code class="code"><em class="replaceable"><code>status </code></em></code> code in an HTTP
+ header that is not of type
+ <code class="code">INK_HTTP_TYPE_RESPONSE</code>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</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="INKHttpHdrTypeGet"></a>INKHttpHdrTypeGet</h4></div></div></div>
+<p>Retrieves the HTTP header type.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKHttpType INKHttpHdrTypeGet (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 type of the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ <code class="function">INKHttpType</code> is an enumerated type.</p>
+<pre class="programlisting">typedef enum
+{
+ INK_HTTP_TYPE_UNKNOWN,
+ INK_HTTP_TYPE_REQUEST,
+ INK_HTTP_TYPE_RESPONSE
+} INKHttpTyp</pre></dd>
+<dd> </dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd><p>The type of the specified HTTP header.</p>
+<p><code class="code">INK_ERROR</code> if there is error.</p>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHdrTypeSet"></a>INKHttpHdrTypeSet</h4></div></div></div>
+<p>Sets the HTTP header type.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHdrTypeSet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKHttpType
+ <em class="replaceable"><code>type</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Sets the type of the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code> to
+ <code class="code"><em class="replaceable"><code>type</code></em></code>. Use
+ <code class="function">INKHttpHdrTypeSet</code> only after you create
+ an HTTP header. The <code class="function">INKHttpHdrCreate</code>
+ function automatically assigns the new header a type of
+ <code class="code">INK_HTTP_TYPE_UNKNOWN</code>. You would only use
+ <code class="function">INKHttpHdrTypeSet</code> to change the type of a
+ header from <code class="code">INK_HTTP_TYPE_UNKNOWN</code> to either
+ <code class="code">INK_HTTP_TYPE_REQUEST</code> or
+ <code class="code">INK_HTTP_TYPE_RESPONSE.</code> You can only change the
+ type once and you cannot modify the type after setting it.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</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="INKHttpHdrUrlGet"></a>INKHttpHdrUrlGet</h4></div></div></div>
+<p>Gets the location for the URL portion of an HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKHttpHdrUrlGet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>req_hdr_loc</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the URL from the HTTP header located at
+ <code class="code"><em class="replaceable"><code>req_hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ It is an error to try to retrieve the URL from an HTTP header
+ that is not of type
+ <code class="code">INK_HTTP_TYPE_REQUEST</code>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+<p>Release with a call to
+ <code class="function">INKHandleMLocRelease</code>. When you release
+ the handle created by <code class="function">INKHttpHdrUrlGet</code>,
+ the parent should be
+ <code class="code"><em class="replaceable"><code>req_hdr_loc</code></em></code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The URL from the specified HTTP header.</p>
+<p><code class="code">INK_ERROR_PTR</code> if there is an error.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHdrUrlSet"></a>INKHttpHdrUrlSet</h4></div></div></div>
+<p>Sets a URL location within an HTTP request header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHdrUrlSet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>url</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets the URL in the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ It is an error to try to set the URL in an HTTP header that
+ is not of type <code class="code">INK_HTTP_TYPE_REQUEST</code>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</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="INKHttpHdrVersionGet"></a>INKHttpHdrVersionGet</h4></div></div></div>
+<p>Retrieves the HTTP version of the specified HTTP
+ header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpHdrVersionGet (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 version from the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ An HTTP version is composed of a major and a minor version.
+ Traffic Server encodes the major version in the upper 16 bits
+ of the returned integer and the minor version in the lower 16
+ bits. The macros <code class="code">INK_HTTP_MAJOR</code><code> (ver) </code>and <code class="code">INK_HTTP_MINOR</code><code> (ver) </code>can be used to extract the
+ major and minor versions, respectively.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The HTTP version from the specified HTTP header.</p>
+<p><code class="code">INK_ERROR</code> if there is an error.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHdrVersionSet"></a>INKHttpHdrVersionSet</h4></div></div></div>
+<p>Sets the HTTP version of the specified HTTP header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpHdrVersionSet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, int
+ <em class="replaceable"><code>ver</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets the version in the HTTP header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code> to
+ <code class="code"><em class="replaceable"><code>ver</code></em></code>. An HTTP version
+ is composed of a major and a minor version. Traffic Server
+ encodes the major version in the upper 16 bits of the returned
+ integer and the minor version in the lower 16 bits. The macro
+ <code class="code">INK_HTTP_VERSION</code> <code>(maj, min) </code>can be used to encode
+ a major and minor version into the single integer expected by <code class="function">INKHttpHdrVersionSet</code>.</p>
+<p>If it is a transaction header, then call after <code class="code">READ_REQUEST_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 the operation does not
+ complete successfully.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpParserClear"></a>INKHttpParserClear</h4></div></div></div>
+<p>Clears an HTTP parser.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpParserClear (INKHttpParser
+ <em class="replaceable"><code>parser</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Clears the specified HTTP
+ <code class="code"><em class="replaceable"><code>parser </code></em></code> so it can be
+ used again.</p>
+<p>Call after <code class="code">READ_REQUEST_HDR_HOOK</code> if it is
+ a transaction header.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</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="INKHttpParserCreate"></a>INKHttpParserCreate</h4></div></div></div>
+<p>Creates a parser for HTTP headers.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKHttpParser INKHttpParserCreate
+ (void)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd><p>Creates an HTTP parser. The parser's data structure
+ contains information about the header being parsed. A single
+ HTTP parser can be used multiple times, though not
+ simultaneously. Before being used again, the parser must be
+ cleared by calling
+ <code class="function">INKHttpParserClear</code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>Parser structure for HTTP headers.</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="INKHttpParserDestroy"></a>INKHttpParserDestroy</h4></div></div></div>
+<p>Destroys an HTTP parser.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKHttpParserDestroy (INKHttpParser
+ <em class="replaceable"><code>parser</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Destroys the specified HTTP
+ <code class="code"><em class="replaceable"><code>parser </code></em></code> and frees the
+ associated memory.</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 the operation does not
+ complete successfully.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHdrParseReq"></a>INKHttpHdrParseReq</h4></div></div></div>
+<p>Parses an HTTP request header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code"> int INKHttpHdrParseReq (INKHttpParser
+ <em class="replaceable"><code>parser</code></em>, INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, const char
+ **<em class="replaceable"><code>start</code></em>, const char
+ *<em class="replaceable"><code>end</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Parses an HTTP request header. The HTTP header
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> must already
+ be created and must reside inside the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>. The
+ <code class="code"><em class="replaceable"><code>start </code></em></code> argument points
+ to the current position of the string buffer being parsed and
+ the <code class="code"><em class="replaceable"><code>end </code></em></code> argument
+ points to one byte after the end of the buffer to be parsed.
+ On return, <code class="code"><em class="replaceable"><code>start </code></em></code> is
+ modified to point past the last character parsed.</p>
+<p>It is possible to parse an HTTP request header a single
+ byte at a time using repeated calls to
+ <code class="function">INKHttpHdrParseReq</code>. As long as an error
+ does not occur, the <code class="function">INKHttpHdrParseReq</code>
+ function will consume that single byte and ask for
+ more.</p>
+<p>Call after <code class="code">READ_REQUEST_HDR_HOOK</code> if it is
+ a transaction header.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_PARSE_ERROR</code> is returned if there is an
+ error.</p>
+<p><code class="code">INK_PARSE_DONE</code> is returned when a <code>\r\n\r\n </code>pattern is encountered, indicating the end of the
+ header.</p>
+<p><code>INK_PARSE_CONT</code> is returned if parsing of the header
+ stopped because the end of the buffer was reached.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKHttpHdrParseResp"></a>INKHttpHdrParseResp</h4></div></div></div>
+<p>Parses an HTTP response header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKHttpHdrParseResp (INKHttpParser
+ <em class="replaceable"><code>parser</code></em>, INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, const char
+ **<em class="replaceable"><code>start</code></em>, const char
+ *<em class="replaceable"><code>end</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Parses an HTTP response header. The HTTP header
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> must already
+ be created and must reside inside the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>. The
+ <code class="code"><em class="replaceable"><code>start </code></em></code> argument points
+ to the current position of the string buffer being parsed and
+ the <code class="code"><em class="replaceable"><code>end </code></em></code> argument
+ points to one byte after the end of the buffer to be parsed.
+ On return, <code class="code"><em class="replaceable"><code>start </code></em></code> is
+ modified to point past the last character parsed.</p>
+<p>It is possible to parse an HTTP response header a single
+ byte at a time using repeated calls to
+ <code class="function">INKHttpHdrParseResp</code>. As long as an error
+ does not occur, the <code class="function">INKHttpHdrParseResp</code>
+ function consumes that single byte and asks for
+ more.</p>
+<p>Call after <code class="code">READ_RESPONSE_HDR_HOOK</code> if it is
+ a transaction header.</p>
+</dd>
+<dt><b><span class="term">Returns</span></b></dt>
+<dd>
+<p><code class="code">INK_PARSE_ERROR</code> is returned if there is an
+ error.</p>
+<p><code class="code">INK_PARSE_DONE</code> is returned when a
+ <code class="code">\r\n\r\n</code> pattern is encountered, indicating the
+ end of the header.</p>
+<p><code class="code">INK_PARSE_CONT</code> is returned if parsing of
+ the header stopped because the end of the buffer was
+ reached</p>
+</dd>
+<dt> </dt>
+</dl></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPHeaderFunctions.html
------------------------------------------------------------------------------
svn:executable = *