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 2010/11/06 07:31:10 UTC

svn commit: r778776 [18/21] - in /websites/staging/trafficserver/trunk/content/docs/trunk: admin/ sdk/

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginConfigurations.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginConfigurations.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginConfigurations.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginConfigurations.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,113 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="WritingHandlerFunctions">Prev</a> - Writing Handler Functions
+Chapter 14. Actions Guide - <a href="ActionsGuide">Next</a></p>
+<h2 id="chapter_13_plugin_configurations">Chapter 13. Plugin Configurations</h2>
+<p>This chapter contains the following section:</p>
+<ul>
+<li><a href="PluginConfigurations#Plugin_Configs" title="Plugin Configurations">Plugin Configurations</a></li>
+</ul>
+<h2 id="plugin_configurations">Plugin Configurations</h2>
+<p>The <code>INKConfig</code> family of functions provides a mechanism for
+accessing and changing global configuration information within a
+plugin.</p>
+<p>The functions discussed in this section do not examine or modify
+Traffic Server configuration variables. To examine Traffic Server
+configuration and statistics variables, see
+<a href="ReadTESettingStats" title="Reading Traffic Server Settings and Statistics">"Reading Traffic Server Settings and Statistics"</a>.</p>
+<p>The <code>INKConfig</code> family of functions is designed to provide a fast
+and efficient mechanism for accessing and changing global
+configuration information within a plugin. Such a mechanism is
+simple enough to provide in a single-threaded program, but the
+translation to a multi-threaded program such as Traffic Server is
+difficult. A common technique is to have a single mutex protect the
+global configuration information; however, the problem with this
+solution is that a single mutex becomes a performance bottleneck
+very quickly.</p>
+<p>The <code>INKConfig</code> family of functions define an interface to storing
+and retrieving an opaque data pointer. Internally, Traffic Server
+maintains reference count information about the data pointer so
+that a call to <code>INKConfigSet</code> will not disturb another thread using
+the current data pointer. The philosophy is that once a user has a
+hold of the configuration pointer, it is okay for it to be used
+even if the configuration changes; all that a user typically wants
+is a non-changing snapshot of the configuration. You should use
+<code>INKConfigSet</code> for all global data updates.</p>
+<p>Here's how the interface works:</p>
+<div class="codehilite"><pre><span class="o">/*</span> <span class="n">Assume</span> <span class="n">that</span> <span class="n">you</span> <span class="n">have</span> <span class="n">previously</span> <span class="nb">defined</span> <span class="n">a</span> <span class="n">plugin</span> <span class="n">configuration</span>
+ <span class="o">*</span> <span class="n">data</span> <span class="n">structure</span> <span class="n">named</span> <span class="n">ConfigData</span><span class="p">,</span> <span class="n">along</span> <span class="n">with</span> <span class="n">its</span> <span class="n">constructor</span>
+ <span class="o">*</span> <span class="n">plugin_config_allocator</span> <span class="p">()</span> <span class="ow">and</span> <span class="n">its</span> <span class="n">destructor</span> 
+ <span class="o">*</span> <span class="n">plugin_config_destructor</span> <span class="p">(</span><span class="n">ConfigData</span> <span class="o">*</span><span class="n">data</span><span class="p">)</span>
+ <span class="o">*/</span>
+<span class="n">ConfigData</span> <span class="o">*</span><span class="n">plugin_config</span><span class="p">;</span>
+
+<span class="o">/*</span> <span class="n">You</span> <span class="n">will</span> <span class="n">need</span> <span class="n">to</span> <span class="n">assign</span> <span class="n">plugin_config</span> <span class="n">a</span> <span class="n">unique</span> <span class="n">identifier</span> <span class="n">of</span> <span class="n">type</span>
+ <span class="o">*</span> <span class="n">unsigned</span> <span class="nb">int</span><span class="o">.</span> <span class="n">It</span> <span class="n">is</span> <span class="n">important</span> <span class="n">to</span> <span class="n">initialize</span> <span class="n">this</span> <span class="n">identifier</span> <span class="n">to</span> <span class="n">zero</span>
+ <span class="o">*</span> <span class="p">(</span><span class="n">see</span> <span class="n">the</span> <span class="n">documentation</span> <span class="n">of</span> <span class="n">the</span>  <span class="n">function</span><span class="p">)</span><span class="o">.</span> 
+ <span class="o">*/</span>
+<span class="n">static</span> <span class="n">unsigned</span> <span class="nb">int</span>   <span class="n">my_id</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+<span class="o">/*</span> <span class="n">You</span> <span class="n">will</span> <span class="n">need</span> <span class="n">an</span> <span class="n">INKConfig</span> <span class="n">pointer</span> <span class="n">to</span> <span class="n">access</span> <span class="n">a</span> <span class="n">snapshot</span> <span class="n">of</span> <span class="n">the</span> 
+ <span class="o">*</span> <span class="n">current</span> <span class="n">plugin_config</span><span class="o">.</span> 
+ <span class="o">*/</span>
+<span class="n">INKConfig</span> <span class="n">config_ptr</span><span class="p">;</span>
+
+<span class="sr">/* Initialize plugin_config. */</span>
+<span class="n">plugin_config</span> <span class="o">=</span> <span class="n">plugin_config_allocator</span><span class="p">();</span>
+
+<span class="sr">/* Assign plugin_config an identifier using INKConfigSet. */</span>
+<span class="n">my_id</span> <span class="o">=</span> <span class="n">INKConfigSet</span> <span class="p">(</span><span class="n">my_id</span><span class="p">,</span> <span class="n">plugin_config</span><span class="p">,</span> <span class="n">plugin_config_destructor</span><span class="p">);</span>
+
+<span class="sr">/* Get a snapshot of the current configuration using INKConfigGet. */</span>
+<span class="n">config_ptr</span> <span class="o">=</span> <span class="n">INKConfigGet</span> <span class="p">(</span><span class="n">my_id</span><span class="p">);</span>
+
+<span class="o">/*</span> <span class="n">With</span> <span class="n">an</span> <span class="n">INKConfig</span> <span class="n">pointer</span> <span class="n">to</span> <span class="n">the</span> <span class="n">current</span> <span class="n">configuration</span><span class="p">,</span> <span class="n">you</span> <span class="n">can</span> 
+ <span class="o">*</span> <span class="n">retrieve</span> <span class="n">the</span> <span class="n">configuration</span><span class="err">&#39;</span><span class="n">s</span> <span class="n">current</span> <span class="n">data</span> <span class="n">using</span> <span class="n">INKConfigDataGet</span><span class="o">.</span> 
+ <span class="o">*/</span>
+<span class="n">plugin_config</span> <span class="o">=</span> <span class="p">(</span><span class="n">ConfigData</span><span class="o">*</span><span class="p">)</span> <span class="n">INKConfigDataGet</span> <span class="p">(</span><span class="n">config_ptr</span><span class="p">);</span>
+
+<span class="sr">/* Do something with plugin_config here. */</span>
+
+<span class="o">/*</span> <span class="n">When</span> <span class="n">you</span> <span class="n">are</span> <span class="n">done</span> <span class="n">with</span> <span class="n">retrieving</span> <span class="ow">or</span> <span class="n">modifying</span> <span class="n">the</span> <span class="n">plugin</span> <span class="n">data</span><span class="p">,</span> <span class="n">you</span>
+ <span class="o">*</span> <span class="n">release</span> <span class="n">the</span> <span class="n">pointers</span> <span class="n">to</span> <span class="n">the</span> <span class="n">data</span> <span class="n">with</span> <span class="n">a</span> <span class="n">call</span> <span class="n">to</span> <span class="n">INKConfigRelease</span><span class="o">.</span>
+ <span class="o">*/</span>
+<span class="n">INKConfigRelease</span> <span class="p">(</span><span class="n">my_id</span><span class="p">,</span> <span class="n">config_ptr</span><span class="p">);</span>
+
+<span class="o">/*</span> <span class="n">Any</span> <span class="nb">time</span> <span class="n">you</span> <span class="n">want</span> <span class="n">to</span> <span class="n">modify</span> <span class="n">plugin_config</span><span class="p">,</span> <span class="n">you</span> <span class="n">must</span> <span class="n">repeat</span> <span class="n">these</span>
+ <span class="o">*</span> <span class="n">steps</span><span class="p">,</span> <span class="n">starting</span> <span class="n">with</span> 
+ <span class="o">*</span> <span class="n">my_id</span> <span class="o">=</span> <span class="n">INKConfigSet</span> <span class="p">(</span><span class="n">my_id</span><span class="p">,</span><span class="n">plugin_config</span><span class="p">,</span> <span class="n">plugin_config_destructor</span><span class="p">);</span>
+ <span class="o">*</span> <span class="ow">and</span> <span class="n">continuing</span> <span class="n">up</span> <span class="n">to</span> <span class="n">INKConfigRelease</span><span class="o">.</span> 
+ <span class="o">*/</span>
+</pre></div>
+
+
+<p>The configuration functions are:</p>
+<ul>
+<li>
+<p><code>&lt;a href="PluginConfigurationFunctions#INKConfigDataGet" title="INKConfigDataGet"&gt;INKConfigDataGet&lt;/a&gt;</code></p>
+</li>
+<li>
+<p><code>&lt;a href="INKConfigGet.html" title="INKConfigGet"&gt;INKConfigGet&lt;/a&gt;</code></p>
+</li>
+<li>
+<p><code>&lt;a href="INKConfigRelease.html" title="INKConfigRelease"&gt;INKConfigRelease&lt;/a&gt;</code></p>
+</li>
+<li>
+<p><code>&lt;a href="INKConfigSet.html" title="INKConfigSet"&gt;INKConfigSet&lt;/a&gt;</code></p>
+</li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginManagement.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginManagement.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginManagement.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PluginManagement.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,49 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="CacheAPI_Example">Prev</a> - Example
+Reading Traffic Server Settings and Statistics -
+<a href="ReadTESettingStats">Next</a></p>
+<h2 id="chapter_16_plugin_management">Chapter 16. Plugin Management</h2>
+<p>This chapter covers the following topics:</p>
+<ul>
+<li>
+<p><a href="ReadTESettingStats" title="Reading Traffic Server Settings and Statistics">Reading Traffic Server Settings and Statistics</a></p>
+<p>Using the functions in this chapter, plugins read Traffic Server
+configuration settings and statistics from the <code>records.config</code>
+file.</p>
+</li>
+<li>
+<p><a href="AccessPluginFiles" title="Accessing Installed Plugin Files">Accessing Installed Plugin Files</a></p>
+<p>Put plugin access-related files in the plugin installation
+directory and make sure your plugins are preserved during Traffic
+Server upgrades.</p>
+</li>
+<li>
+<p><a href="LicensingPlugin" title="Licensing Your Plugin">Licensing Your Plugin</a></p>
+<ul>
+<li><a href="SetUpLicensing">Setting Up Licensing</a></li>
+<li><a href="GenerateLicenseKey">Generating a License Key</a></li>
+</ul>
+</li>
+<li>
+<p><a href="LoggingAPI" title="Guide to the Logging API">Guide to the Logging API</a></p>
+<p>The logging API enables your plugin to log text entries in a custom
+Traffic Server log file. This section provides a basic overview of
+the logging interface.</p>
+</li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PlusingRegisAndVersionCkg.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PlusingRegisAndVersionCkg.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PlusingRegisAndVersionCkg.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/PlusingRegisAndVersionCkg.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,81 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="RestartingTS">Prev</a> - Restart Traffic Server
+Naming Conventions - <a href="NamingConventions">Next</a></p>
+<h2 id="plugin_registration_and_version_checking">Plugin Registration and Version Checking</h2>
+<p>Make sure that the functions in your plugin are supported in your
+version of Traffic Server.</p>
+<p>Use the following interfaces:</p>
+<ul>
+<li><a href="INKPluginRegister" title="INKPluginRegister">INKPluginRegister</a></li>
+<li><a href="INKTrafficServerVersionGet" title="INKTrafficServerVersionGet">INKTrafficServerVersionGet</a></li>
+</ul>
+<p>The following version of <code>hello-world</code> registers the plugin and
+ensures it's running with a compatible version of Traffic Server.</p>
+<div class="codehilite"><pre><span class="c1">#include &lt;stdio.h&gt;</span>
+<span class="c1">#include &lt;ts/ts.h&gt;</span>
+<span class="nb">int</span>
+<span class="n">check_ts_version</span><span class="p">()</span> 
+<span class="p">{</span>
+
+ <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">ts_version</span> <span class="o">=</span> <span class="n">INKTrafficServerVersionGet</span><span class="p">();</span>
+ <span class="nb">int</span> <span class="n">result</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+   <span class="k">if</span> <span class="p">(</span><span class="n">ts_version</span><span class="p">)</span> <span class="p">{</span>
+    <span class="nb">int</span> <span class="n">major_ts_version</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+    <span class="nb">int</span> <span class="n">minor_ts_version</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+    <span class="nb">int</span> <span class="n">patch_ts_version</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+   <span class="k">if</span> <span class="p">(</span><span class="n">sscanf</span><span class="p">(</span><span class="n">ts_version</span><span class="p">,</span> <span class="s">&quot;%d.%d.%d&quot;</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">major_ts_version</span><span class="p">,</span>
+      <span class="o">&amp;</span><span class="n">minor_ts_version</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">patch_ts_version</span><span class="p">)</span> <span class="o">!=</span> <span class="mi">3</span><span class="p">)</span> <span class="p">{</span>
+      <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+  <span class="p">}</span>
+
+  <span class="sr">/* We need at least Traffic Server 2.0 */</span>
+
+   <span class="k">if</span> <span class="p">(</span><span class="n">major_ts_version</span> <span class="o">&gt;=</span> <span class="mi">2</span><span class="p">)</span> <span class="p">{</span>
+      <span class="n">result</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+   <span class="p">}</span>
+
+  <span class="p">}</span>
+
+  <span class="k">return</span> <span class="n">result</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="n">void</span>
+<span class="n">INKPluginInit</span> <span class="p">(</span><span class="nb">int</span> <span class="n">argc</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">argv</span><span class="o">[]</span><span class="p">)</span>
+<span class="p">{</span>
+
+      <span class="n">INKPluginRegistrationInfo</span> <span class="n">info</span><span class="p">;</span>
+
+      <span class="n">info</span><span class="o">.</span><span class="n">plugin_name</span> <span class="o">=</span> <span class="s">&quot;hello-world&quot;</span><span class="p">;</span>
+      <span class="n">info</span><span class="o">.</span><span class="n">vendor_name</span> <span class="o">=</span> <span class="s">&quot;MyCompany&quot;</span><span class="p">;</span>
+      <span class="n">info</span><span class="o">.</span><span class="n">support_email</span> <span class="o">=</span> <span class="s">&quot;ts-api-support@MyCompany.com&quot;</span><span class="p">;</span>
+
+      <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">INKPluginRegister</span> <span class="p">(</span><span class="n">INK_SDK_VERSION_2_0</span> <span class="p">,</span> <span class="o">&amp;</span><span class="n">info</span><span class="p">))</span> <span class="p">{</span>
+         <span class="n">INKError</span> <span class="p">(</span><span class="s">&quot;Plugin registration failed. \n&quot;</span><span class="p">);</span>
+      <span class="p">}</span>
+
+      <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">check_ts_version</span><span class="p">())</span> <span class="p">{</span>
+         <span class="n">INKError</span> <span class="p">(</span><span class="s">&quot;Plugin requires Traffic Server 2.0 or later\n&quot;</span><span class="p">);</span>
+         <span class="k">return</span><span class="p">;</span>
+      <span class="p">}</span>
+
+      <span class="n">INKDebug</span> <span class="p">(</span><span class="s">&quot;debug-hello&quot;</span><span class="p">,</span> <span class="s">&quot;Hello World!\n&quot;</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Preface.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Preface.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Preface.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Preface.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,45 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="index">Prev</a> - Traffic Server Software Developers Kit
+How to Use This Book - <a href="pr01s02">Next</a></p>
+<h2 id="preface">Preface</h2>
+<p><strong>Table of Contents</strong></p>
+<p><a href="Preface#Audience" />
+<a href="pr01s02">How to Use This Book</a>
+<a href="Conventions">Typographical Conventions</a>
+The <em>Traffic Server Software Developer's Kit</em> is a reference for
+creating plugins. <strong>Plugins</strong> are programs that add services (such
+as filtering or content transformation) or entire features (such as
+new protocol support) to Traffic Server. If you are new to writing
+Traffic Server plugins, then read the first two chapters,
+<a href="GetingStarted#GettingStarted">Getting Started</a> and
+<a href="CreatingTSPlugins" title="Chapter 2. How to Create Traffic Server Plugins">Creating Traffic Server Plugins</a>,
+and use the remaining chapters as needed.
+<a href="HeaderBasedPluginEx" title="Chapter 4. Header-Based Plugin Examples">Header-Based Plugin Examples</a>
+provides details about plugins that work on HTTP headers, while
+<a href="HTTPTransformationPlugins" title="Chapter 5. HTTP Transformation Plugins">HTTP Transformation Plugins</a>
+explains how to write a plugin that transforms or scans the body of
+an HTTP response. If you want to support your own protocol on
+Traffic Server, then reference
+<a href="NewProtocolPlugins" title="Chapter 6. New Protocol Plugins">New Protocol Plugins</a>.</p>
+<h2 id="audience">Audience</h2>
+<p>This manual is intended for programmers who want to write plugin
+programs that add services or features to Traffic Server. It
+assumes a cursory knowledge of the C programming language,
+Hyper-Text Transfer Protocol (HTTP), and Multipurpose Internet Mail
+Extensions (MIME).</p>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ReadTESettingStats.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ReadTESettingStats.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ReadTESettingStats.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ReadTESettingStats.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,58 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="PluginManagement">Prev</a> - Chapter 16. Plugin Management
+Accessing Installed Plugin Files - <a href="AccessPluginFiles">Next</a></p>
+<h2 id="reading_traffic_server_settings_and_statistics">Reading Traffic Server Settings and Statistics</h2>
+<p>Your plugin might need to know information about Traffic Server's
+current configuration and performance. The functions described in
+this section read this information from the Traffic Server
+<code>records.config</code> file. Configuration settings are stored in
+<code>CONFIG</code> variables and statistics are stored in <code>PROCESS</code>
+variables.</p>
+<p><img alt="[Caution]" src="images/docbook/caution.png" />
+Caution
+Not all <code>CONFIG</code> and <code>PROCESS</code> variables in <code>records.config</code> are
+relevant to Traffic Server's configuration and statistics.
+Therefore, retrieve only the <code>records.config</code> variables that are
+documented in the
+<a href="../admin/">Traffic Server Administrator's Guide</a>.</p>
+<p>To retrieve a variable, you need to know its type (<code>int</code>,
+<code>counter</code>, <code>float</code>, or <code>string</code>). Plugins store the
+<code>records.config</code> values as an <code>INKMgmtInt</code>, <code>INKMgmtCounter</code>,
+<code>INKMgmtFloat</code>, or <code>INKMgmtString</code>. You can look up
+<code>records.config</code> variable types in the
+<a href="../admin/">Traffic Server Administrator's Guide</a>.</p>
+<p>Depending on the result type, you'll use <code>INKMgmtIntGet</code>,
+<code>INKMgmtCounterGet</code>, <code>INKMgmtFloatGet</code>, or <code>INKMgmtStringGet</code> to
+obtain the variable value (see the example for
+<a href="INKMgmtIntGet" title="INKMgmtIntGet">INKMgmtIntGet</a>).</p>
+<p>The <code>INKMgmt*Get</code> functions are:</p>
+<ul>
+<li>
+<p><a href="TEConfigReadFunctions#INKMgmtCounterGet" title="INKMgmtCounterGet">INKMgmtCounterGet</a></p>
+</li>
+<li>
+<p><a href="INKMgmtFloatGet" title="INKMgmtFloatGet">INKMgmtFloatGet</a></p>
+</li>
+<li>
+<p><a href="INKMgmtIntGet" title="INKMgmtIntGet">INKMgmtIntGet</a></p>
+</li>
+<li>
+<p><a href="INKMgmtStringGet" title="INKMgmtStringGet">INKMgmtStringGet</a></p>
+</li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RemapAPI_Example.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RemapAPI_Example.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RemapAPI_Example.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RemapAPI_Example.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,70 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="ch03">Prev</a> - Chapter 3. Remap Plugin: Getting Started
+Remap Plugin Function Reference <a href="ch03s02">Next</a></p>
+<h2 id="example_query_remap_plugin">Example: Query Remap Plugin</h2>
+<p>The sample remap plugin, <code>query_remap.c</code>, maps client requests to a
+number of servers based on a hash of the request's URL query
+parameter. This can be useful for spreading load for a given type
+of request among backend servers, while still maintaining
+"stickiness" to a single server for similar requests. For example,
+a search engine may want to send repeated queries for the same
+keywords to a server that has likely cached the result from a prior
+query.</p>
+<h3 id="configuration_of_query_remap">Configuration of query_remap</h3>
+<p>The query remap plugin will allow the query parameter name to be
+specified, along with the hostnames of the servers to hash across.
+Sample <code>remap.config</code> rules using <code>query_remap</code> will look like:</p>
+<div class="codehilite"><pre><span class="nb">map</span> <span class="n">http:</span><span class="sr">//</span><span class="n">www</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="sr">/search http://srch1.example.com/s</span><span class="n">earch</span> <span class="nv">@plugin</span><span class="o">=</span><span class="n">query_remap</span><span class="o">.</span><span class="n">so</span> <span class="nv">@pparam</span><span class="o">=</span><span class="sx">q @pparam=srch1.example.com </span><span class="nv">@pparam</span><span class="o">=</span><span class="n">srch2</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span> <span class="nv">@pparam</span><span class="o">=</span><span class="n">srch3</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>
+
+<span class="nb">map</span> <span class="n">http:</span><span class="sr">//</span><span class="n">www</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="sr">/profiles http://prof1.example.com/</span><span class="n">profiles</span> <span class="nv">@plugin</span><span class="o">=</span><span class="n">query_remap</span><span class="o">.</span><span class="n">so</span> <span class="nv">@pparam</span><span class="o">=</span><span class="n">user_id</span> <span class="nv">@pparam</span><span class="o">=</span><span class="n">prof1</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span> <span class="nv">@pparam</span><span class="o">=</span><span class="n">prof2</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>
+</pre></div>
+
+
+<p>The first <code>@pparam</code> specifies the query param key for which the
+value will be hashed. The remaining parameters list the hostnames
+of the servers. A request for
+<code>http://www.example.com/search?q=apache</code> will match the first rule.
+The plugin will look for the <code>&lt;em class="replaceable"&gt;q&lt;/em&gt;</code>
+parameter and hash the value '<code>apache</code>' to pick from among
+<code>srch&lt;em class="replaceable"&gt;[1-3]&lt;/em&gt;.example.com</code> to send the
+request.</p>
+<p>If the request does not include a <code>&lt;em class="replaceable"&gt;q&lt;/em&gt;</code>
+query parameter and the plugin decides not to modify the request,
+the default toURL '<code>http://srch1.example.com/search</code>' will be used
+by TS.</p>
+<p>The parameters are passed to the plugin's <code>tsremap_new_instance</code>
+function. In <code>query_remap</code>, <code>tsremap_new_instance</code> creates a
+plugin-defined <code>query_remap_info</code> struct to store its configuration
+parameters. The ihandle, an opaque pointer that can be used to pass
+per-instance data, is set to this struct pointer and will be passed
+to the <code>tsremap_remap</code> function when it is triggered for a
+request.</p>
+<p>Another way remap plugins may want handle more complex
+configuration is to specify a configuration filename as a <code>pparam</code>
+and parse the specified file during instance initialization.</p>
+<h3 id="performing_the_remap">Performing the Remap</h3>
+<p>The plugin implements the <code>tsremap_remap</code> function, which is called
+when TS has read the client HTTP request headers and matched the
+request to a remap rule configured for the plugin. The
+<code>TSRemapRequestInfo</code> struct contains input and output members for
+the remap operation.</p>
+<p><code>tsremap_remap</code> uses the configuration information passed via the
+<code>ihandle</code> and checks the <code>request_query</code> for the configured query
+parameter. If the parameter is found, the plugin sets a <code>new_host</code>
+to modify the request host:</p>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RestartingTS.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RestartingTS.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RestartingTS.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RestartingTS.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,45 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="SpecifyingPluginLocation">Prev</a> - Specify the Plugin's
+Location
+Plugin Registration and Version Checking -
+<a href="PlusingRegisAndVersionCkg">Next</a></p>
+<h3 id="restart_traffic_server">Restart Traffic Server</h3>
+<p>The last step is to start/restart Traffic Server. Shown below is
+the output displayed after you've created and loaded your
+<code>hello-world</code> plugin.</p>
+<div class="codehilite"><pre><span class="c1"># grep proxy.config.plugin.plugin_dir config/records.config</span>
+<span class="n">CONFIG</span> <span class="n">proxy</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">plugin</span><span class="o">.</span><span class="n">plugin_dir</span> <span class="n">STRING</span> <span class="n">config</span><span class="o">/</span><span class="n">plugins</span>
+<span class="c1"># ls config/plugins</span>
+<span class="n">hello</span><span class="o">-</span><span class="n">world</span><span class="o">.</span><span class="n">so</span><span class="o">*</span>
+<span class="c1"># bin/traffic_server</span>
+<span class="p">[</span><span class="n">Mar</span> <span class="mi">27</span> <span class="mi">19</span><span class="p">:</span><span class="mo">06</span><span class="p">:</span><span class="mi">31</span><span class="o">.</span><span class="mi">669</span><span class="p">]</span> <span class="n">NOTE:</span> <span class="n">updated</span> <span class="n">diags</span> <span class="n">config</span>
+<span class="p">[</span><span class="n">Mar</span> <span class="mi">27</span> <span class="mi">19</span><span class="p">:</span><span class="mo">06</span><span class="p">:</span><span class="mi">31</span><span class="o">.</span><span class="mi">680</span><span class="p">]</span> <span class="n">NOTE:</span> <span class="n">loading</span> <span class="n">plugin</span> <span class="s">&#39;config/plugins/hello-world.so&#39;</span>
+<span class="n">hello</span> <span class="n">world</span>
+<span class="p">[</span><span class="n">Mar</span> <span class="mi">27</span> <span class="mi">19</span><span class="p">:</span><span class="mo">06</span><span class="p">:</span><span class="mi">32</span><span class="o">.</span><span class="mo">046</span><span class="p">]</span> <span class="n">NOTE:</span> <span class="n">cache</span> <span class="n">disabled</span> <span class="p">(</span><span class="n">initializing</span><span class="p">)</span>
+<span class="p">[</span><span class="n">Mar</span> <span class="mi">27</span> <span class="mi">19</span><span class="p">:</span><span class="mo">06</span><span class="p">:</span><span class="mi">32</span><span class="o">.</span><span class="mo">053</span><span class="p">]</span> <span class="n">NOTE:</span> <span class="n">cache</span> <span class="n">enabled</span>
+<span class="p">[</span><span class="n">Mar</span> <span class="mi">27</span> <span class="mi">19</span><span class="p">:</span><span class="mo">06</span><span class="p">:</span><span class="mi">32</span><span class="o">.</span><span class="mi">526</span><span class="p">]</span> <span class="n">NOTE:</span> <span class="n">Traffic</span> <span class="n">Server</span> <span class="n">running</span>
+</pre></div>
+
+
+<p><strong>Note:</strong> in the example above, Traffic Server notes are directed
+to the console by specifying <code>E</code> for
+<code>proxy.config.diags.output.note</code> in <code>records.config</code>. The second
+note shows Traffic Server attempting to load the <code>hello-world</code>
+plugin. The third line of Traffic Server output is from your
+plugin.</p>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RlsMarshalBufHandles.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RlsMarshalBufHandles.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RlsMarshalBufHandles.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/RlsMarshalBufHandles.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,74 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="MIMEFldsBelongAssocMIMEHdr">Prev</a> - MIME Fields Always Belong
+to an Associated MIME Header
+Deprecated Functions - <a href="DeprecatedMarshBufFuncs">Next</a></p>
+<h3 id="release_marshal_buffer_handles">Release Marshal Buffer Handles</h3>
+<p>When you fetch a component object or create a new object, you get
+back a handle to the object location. The handle is either an
+<code>INKMLoc</code> for an object location or <code>char         *</code> for a string
+location. You can manipulate the object through these handles, but
+when you are finished you need to release the handle to free up
+system resources.</p>
+<p>The general guideline is to release all <code>INKMLoc</code> and string
+handles you retrieve. The one exception is the string returned by
+<code>INKUrlStringGet</code>, which must be freed by a call to <code>INKfree</code>.</p>
+<p>The handle release functions expect three arguments: the marshal
+buffer containing the data, the location of the parent object, and
+the location of the object to be released. The parent location is
+usually clear from the creation of the <code>INKMLoc</code> or string. For
+example, if your plugin had the following calls:</p>
+<div class="codehilite"><pre><span class="n">url_loc</span> <span class="o">=</span> <span class="n">INKHttpHdrUrlGet</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">);</span>
+<span class="n">host_string</span> <span class="o">=</span> <span class="n">INKUrlHostGet</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">url_loc</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">host_length</span><span class="p">);</span>
+</pre></div>
+
+
+<p>then your plugin would have to call:</p>
+<div class="codehilite"><pre><span class="n">INKHandleStringRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">url_loc</span><span class="p">,</span> <span class="n">host_string</span><span class="p">);</span>
+<span class="n">INKHandleMLocRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">,</span> <span class="n">url_loc</span><span class="p">);</span>
+</pre></div>
+
+
+<p>If an <code>INKMLoc</code> is obtained from a transaction, then it does not
+have a parent <code>INKMLoc</code>. Use the null <code>INKMLoc</code> constant
+<code>INK_NULL_MLOC</code> as its parent. For example, if your plugin calls:</p>
+<div class="codehilite"><pre><span class="n">INKHttpTxnClientReqGet</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">bufp</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">hdr_loc</span><span class="p">);</span>
+</pre></div>
+
+
+<p>then you must release <code>hdr_loc</code> with:</p>
+<div class="codehilite"><pre><span class="n">INKHandleMLocRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">);</span>
+</pre></div>
+
+
+<p>You need to use <code>INK_NULL_MLOC</code> to release any <code>INKMLoc</code> handles
+retrieved by the <code>INKHttpTxn*Get</code> functions.</p>
+<p>Here's an example using a new <code>INKMimeHdrField</code> function:</p>
+<div class="codehilite"><pre><span class="n">INKHttpTxnServerRespGet</span><span class="p">(</span> <span class="n">txnp</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">resp_bufp</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">resp_hdr_loc</span> <span class="p">);</span>
+<span class="n">new_field_loc</span> <span class="o">=</span> <span class="n">INKMimeHdrFieldCreate</span> <span class="p">(</span><span class="n">resp_bufp</span><span class="p">,</span> <span class="n">resp_hdr_loc</span><span class="p">);</span>
+<span class="n">INKHandleMLocRelease</span> <span class="p">(</span> <span class="n">resp_bufp</span><span class="p">,</span> <span class="n">resp_hdr_loc</span><span class="p">,</span> <span class="n">new_field_loc</span><span class="p">);</span>
+<span class="n">INKHandleMLocRelease</span> <span class="p">(</span> <span class="n">resp_bufp</span><span class="p">,</span> <span class="n">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">resp_hdr_loc</span><span class="p">);</span>
+</pre></div>
+
+
+<p>See the sample plugins for many more examples.</p>
+<p><img alt="[Tip]" src="images/docbook/tip.png" />
+Tip
+You should release handles before reenabling the HTTP transaction.
+In other words, call <code>INKHandleMLocRelease</code> or
+<code>INKHandleStringRelease</code> before <code>INKHttpTxnReenable</code>.</p>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Roadmap_CreatingPlugins.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Roadmap_CreatingPlugins.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Roadmap_CreatingPlugins.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Roadmap_CreatingPlugins.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,102 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="CreatingTSPlugins">Prev</a> - Chapter 2. How to Create Traffic
+Server Plugins
+Chapter 3. Remap Plugin - <a href="ch03">Next</a></p>
+<h2 id="roadmap_for_creating_plugins">Roadmap for Creating Plugins</h2>
+<p>This chapter has provided an overview of Traffic Server's HTTP
+processing, API hooks, and the asynchronous event model. Next, you
+must understand the capabilities of Traffic Server API functions.
+These are quite broad:</p>
+<ul>
+<li>
+<p><strong>HTTP header manipulation functions</strong></p>
+<p>Obtain information about and manipulate HTTP headers, URLs, &amp; MIME
+headers.</p>
+</li>
+<li>
+<p><strong>HTTP transaction functions</strong></p>
+<p>Get information about and modify HTTP transactions (for example:
+get the client IP associated to the transaction; get the server IP;
+get parent proxy information)</p>
+</li>
+<li>
+<p><strong>IO functions</strong></p>
+<p>Manipulate vconnections (virtual connections, used for network and
+disk I/O)</p>
+</li>
+<li>
+<p><strong>Network connection functions</strong></p>
+<p>Open connections to remote servers.</p>
+</li>
+<li>
+<p><strong>Statistics functions</strong></p>
+<p>Define and compute statistics for your plugin's activity.</p>
+</li>
+<li>
+<p><strong>Traffic Server management functions</strong></p>
+<p>Obtain values for Traffic Server configuration and statistics
+variables.</p>
+</li>
+</ul>
+<p>Below are some guidelines for creating a plugin:</p>
+<ol>
+<li>
+<p>Decide what you want your plugin to do, based on the
+    capabilities of the API and Traffic Server. Two main kinds of
+    example plugins provided with this SDK are HTTP-based (includes
+    header-based and response transform plugins), and non-HTTP-based (a
+    protocol plugin). These examples are discussed in the next three
+    chapters.</p>
+</li>
+<li>
+<p>Determine where your plugin needs to hook on to Traffic
+    Server's HTTP processing (view the
+    <a href="HTTPHooksAndTransactions#Fig_HHTTPTxStateDiag" title="Figure 8.1. HTTP Transaction State Diagram">HTTP Transaction State Diagram</a>).</p>
+</li>
+<li>
+<p>Read
+    <a href="HeaderBasedPluginEx" title="Chapter 4. Header-Based Plugin Examples">Header-Based Plugin Examples</a>
+    to learn the basics of writing plugins: creating continuations and
+    setting up hooks. If you want to write a plugin that transforms
+    data, then read
+    <a href="HTTPTransformationPlugins" title="Chapter 5. HTTP Transformation Plugins">HTTP Transformation Plugins</a>.</p>
+</li>
+<li>
+<p>Figure out what parts of the Traffic Server API you need to use
+    and then read about the details of those APIs in this manual's
+    reference chapters.</p>
+</li>
+<li>
+<p>Compile and load your plugin (see
+    <a href="GetingStarted#GettingStarted">Getting Started</a>).</p>
+</li>
+<li>
+<p>Depending on your plugin's functionality, you might start
+    testing it by issuing requests by hand and checking for the desired
+    behavior in Traffic Server log files. See the
+    <strong><em>Traffic Server Administrator's Guide</em></strong> for information about
+    Traffic Server logs.</p>
+</li>
+<li>
+<p>You can test the performance of Traffic Server running with
+    your plugin using SDKTest. You can also customize SDKTest to
+    perform functional testing on your plugin; for more information see
+    the <strong><em>Traffic Server SDKTest User's Guide</em></strong>.</p>
+</li>
+</ol>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SampleBufferedNullTransformPlugin.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SampleBufferedNullTransformPlugin.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SampleBufferedNullTransformPlugin.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SampleBufferedNullTransformPlugin.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,213 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="AppendTransformPlugin">Prev</a> - The Append-Transform Plugin
+Chapter 6. New Protocol Plugins - <a href="NewProtocolPlugins">Next</a></p>
+<h2 id="the_sample_buffered_null_transform_plugin">The Sample Buffered Null Transform Plugin</h2>
+<p>The buffered null transform, <code>bnull-transform.c</code>, reads the
+response content into a buffer and then writes the full buffer out
+to the client. Many examples of transformations, such as
+compression, require you to gather the full response content in
+order to perform the transformation.</p>
+<p>The buffered null transform uses a state variable to keep track of
+when it is (a) reading data into the buffer and (b) writing the
+data from the buffer to the downstream vconnection.</p>
+<p>The following is a step-by-step walk through the buffered null
+transform:</p>
+<ol>
+<li>
+<p>Gets a handle to HTTP transactions.</p>
+<div class="codehilite"><pre><span class="n">void</span>
+     <span class="n">INKPluginInit</span> <span class="p">(</span><span class="nb">int</span> <span class="n">argc</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">argv</span><span class="o">[]</span><span class="p">)</span> <span class="p">{</span>
+          <span class="n">INKHttpHookAdd</span> <span class="p">(</span><span class="n">INK_HTTP_READ_RESPONSE_HDR_HOOK</span><span class="p">,</span>
+               <span class="n">INKContCreate</span> <span class="p">(</span><span class="n">transform_plugin</span><span class="p">,</span> <span class="n">NULL</span><span class="p">));</span> <span class="p">}</span>
+</pre></div>
+
+
+<p>With this <code>INKPluginInit</code> routine, the plugin is called back every
+time Traffic Server reads a response header.</p>
+</li>
+<li>
+<p>Checks to see if the transaction response is transformable.</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="nb">int</span> <span class="n">transform_plugin</span> <span class="p">(</span><span class="n">INKCont</span> <span class="n">contp</span><span class="p">,</span> <span class="n">INKEvent</span> <span class="n">event</span><span class="p">,</span> <span class="n">void</span> <span class="o">*</span><span class="n">edata</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">INKHttpTxn</span> <span class="n">txnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">INKHttpTxn</span><span class="p">)</span> <span class="n">edata</span><span class="p">;</span>
+     <span class="n">switch</span> <span class="p">(</span><span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+          <span class="k">case</span> <span class="n">INK_EVENT_HTTP_READ_RESPONSE_HDR:</span>
+          <span class="k">if</span> <span class="p">(</span><span class="n">transformable</span> <span class="p">(</span><span class="n">txnp</span><span class="p">))</span> <span class="p">{</span>
+          <span class="n">transform_add</span> <span class="p">(</span><span class="n">txnp</span><span class="p">);}</span>
+</pre></div>
+
+
+<p>The default behavior for transformations is to cache the
+transformed content (if desired, you also can tell Traffic Server
+to cache untransformed content). Therefore, only responses received
+directly from an origin server need to be transformed. Objects
+served from the cache are already transformed. To determine whether
+the response is from the origin server, the routine transformable
+checks the response header for the "200 OK" server response.</p>
+<div class="codehilite"><pre><span class="p">{</span>
+     <span class="n">INKMBuffer</span> <span class="n">bufp</span><span class="p">;</span>
+     <span class="n">INKMLoc</span> <span class="n">hdr_loc</span><span class="p">;</span>
+     <span class="n">INKHttpStatus</span> <span class="n">resp_status</span><span class="p">;</span>
+
+     <span class="n">INKHttpTxnServerRespGet</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">bufp</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">hdr_loc</span><span class="p">);</span>
+
+     <span class="k">if</span><span class="p">(</span><span class="n">INK_HTTP_STATUS_OK</span><span class="o">==</span>
+          <span class="p">(</span><span class="n">resp_status</span><span class="o">=</span><span class="n">INKHttpHdrStatusGet</span><span class="p">(</span><span class="n">bufp</span><span class="p">,</span><span class="n">hdr_loc</span><span class="p">)))</span>
+          <span class="p">{</span>
+               <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+          <span class="p">}</span>
+          <span class="k">else</span> <span class="p">{</span>
+               <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+          <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>If the response is transformable, then the plugin creates a
+    transformation vconnection that gets called back when the response
+    data is ready to be transformed (as it is streaming from the origin
+    server).</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="n">void</span> <span class="n">transform_add</span> <span class="p">(</span><span class="n">INKHttpTxn</span> <span class="n">txnp</span><span class="p">)</span>
+<span class="p">{</span>
+     <span class="n">INKVConn</span> <span class="n">connp</span><span class="p">;</span>
+     <span class="n">connp</span> <span class="o">=</span> <span class="n">INKTransformCreate</span> <span class="p">(</span><span class="n">bnull_transform</span><span class="p">,</span> <span class="n">txnp</span><span class="p">);</span>
+     <span class="n">INKHttpTxnHookAdd</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_HTTP_RESPONSE_TRANSFORM_HOOK</span><span class="p">,</span> <span class="n">connp</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The previous code fragment shows that the handler function for the
+transformation vconnection is <code>bnull_transform</code>.</p>
+</li>
+<li>
+<p>The <code>bnull_transform</code> function has to handle <code>ERROR</code>,
+    <code>WRITE_COMPLETE</code>, <code>WRITE_READY</code>, and <code>IMMEDIATE</code> events. If the
+    transform is just beginning, the event received is probably
+    <code>IMMEDIATE</code>. The <code>bnull_transform</code> function calls
+    <code>handle_transform</code> to handle <code>WRITE_READY</code> and <code>IMMEDIATE</code>.</p>
+</li>
+<li>
+<p>The <code>handle_transform</code> function examines the data parameter for
+    the continuation passed to it (the continuation passed to
+    <code>handle_transform</code> is the transformation vconnection). The data
+    structure keeps track of two states: copying the data into the
+    buffer (<code>STATE_BUFFER_DATA</code>) and writing the contents of the buffer
+    to the output vconnection (<code>STATE_OUTPUT_DATA</code>).</p>
+</li>
+<li>
+<p>Get a handle to the input VIO (see the <code>handle_buffering</code>
+    function).</p>
+<div class="codehilite"><pre><span class="n">input_vio</span> <span class="o">=</span> <span class="n">INKVConnWriteVIOGet</span> <span class="p">(</span><span class="n">contp</span><span class="p">);</span>
+</pre></div>
+
+
+<p>This is so that the transformation can get information about the
+upstream vconnection's write operation to the input buffer.</p>
+</li>
+<li>
+<p>Copy data from the input buffer to the output buffer. See the
+    <code>handle_buffering</code> function for the following code fragment:</p>
+<div class="codehilite"><pre><span class="n">INKIOBufferCopy</span> <span class="p">(</span><span class="n">data</span><span class="o">-&gt;</span><span class="n">output_buffer</span><span class="p">,</span>
+     <span class="n">INKVIOReaderGet</span> <span class="p">(</span><span class="n">write_vio</span><span class="p">),</span> <span class="n">towrite</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>Tell the input buffer that the transformation has read the
+    data. See the <code>handle_buffering</code> function for the following code
+    fragment:</p>
+<div class="codehilite"><pre><span class="n">INKIOBufferReaderConsume</span> <span class="p">(</span><span class="n">INKVIOReaderGet</span> <span class="p">(</span><span class="n">write_vio</span><span class="p">),</span> <span class="n">towrite</span><span class="p">);</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>Modify the input VIO to tell it how much data has been read
+    (increase the value of <code>ndone</code>). See the <code>handle_buffering</code>
+    function for the following code fragment:</p>
+<div class="codehilite"><pre><span class="n">INKVIONDoneSet</span> <span class="p">(</span><span class="n">write_vio</span><span class="p">,</span> <span class="n">INKVIONDoneGet</span> <span class="p">(</span><span class="n">write_vio</span><span class="p">)</span> <span class="o">+</span> <span class="n">towrite</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>If there is more data left to read
+    (<code>if ndone &lt;           nbytes</code>), then the <code>handle_buffering</code>
+    function wakes up the upstream vconnection by sending it
+    <code>WRITE_READY</code>:</p>
+<div class="codehilite"><pre><span class="k">if</span> <span class="p">(</span><span class="n">INKVIONTodoGet</span> <span class="p">(</span><span class="n">write_vio</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+     <span class="k">if</span> <span class="p">(</span><span class="n">towrite</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+          <span class="n">INKContCall</span> <span class="p">(</span><span class="n">INKVIOContGet</span> <span class="p">(</span><span class="n">write_vio</span><span class="p">),</span>
+               <span class="n">INK_EVENT_VCONN_WRITE_READY</span><span class="p">,</span> <span class="n">write_vio</span><span class="p">);</span>
+     <span class="p">}</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+</pre></div>
+
+
+<p>The process of passing data through the transformation is
+illustrated in the following diagram. The transformation sends
+<code>WRITE_READY</code> events when it needs more data; when data is
+available, the upstream vconnection reenables the transformation
+with an <code>IMMEDIATE</code> event.</p>
+<p><strong>Figure 5.4. Reading Data Into the Buffer (the <code>STATE_BUFFER_DATA</code> State)</strong></p>
+<p><img alt="Reading Data Into the Buffer (the STATEklzzwxh:0024BUFFERklzzwxh:0025DATA State)" src="images/vconn_buffer.jpg" />
+11. When the data is read into the output buffer, the
+<code>handle_buffering</code> function sets the state of the transformation's
+data structure to <code>STATE_OUTPUT_DATA</code> and calls the upstream
+vconnection back with the <code>WRITE_COMPLETE</code> event.</p>
+<div class="codehilite"><pre><span class="n">data</span><span class="o">-&gt;</span><span class="n">state</span> <span class="o">=</span> <span class="n">STATE_OUTPUT_DATA</span><span class="p">;</span>
+<span class="n">INKContCall</span> <span class="p">(</span><span class="n">INKVIOContGet</span> <span class="p">(</span><span class="n">write_vio</span><span class="p">),</span>
+     <span class="n">INK_EVENT_VCONN_WRITE_COMPLETE</span><span class="p">,</span> <span class="n">write_vio</span><span class="p">);</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>The upstream vconnection will probably shut down the write
+    operation when it receives the <code>WRITE_COMPLETE</code> event. The handler
+    function of the transformation, <code>bnull_transform</code>, receives an
+    <code>IMMEDIATE</code> event and calls the <code>handle_transform</code> function. This
+    time, the state is <code>STATE_OUTPUT_DATA</code>, so <code>handle_transform</code> calls
+    <code>handle_output</code>.</p>
+</li>
+<li>
+<p>The <code>handle_output</code> function gets a handle to the output
+    vconnection:</p>
+<div class="codehilite"><pre><span class="n">output_conn</span> <span class="o">=</span> <span class="n">INKTransformOutputVConnGet</span> <span class="p">(</span><span class="n">contp</span><span class="p">);</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>The <code>handle_output</code> function writes the buffer to the output
+    vconnection:</p>
+<div class="codehilite"><pre><span class="n">data</span><span class="o">-&gt;</span><span class="n">output_vio</span> <span class="o">=</span>
+<span class="n">INKVConnWrite</span> <span class="p">(</span><span class="n">output_conn</span><span class="p">,</span> <span class="n">contp</span><span class="p">,</span> <span class="n">data</span><span class="o">-&gt;</span><span class="n">output_reader</span><span class="p">,</span>
+<span class="n">INKIOBufferReaderAvail</span> <span class="p">(</span><span class="n">data</span><span class="o">-&gt;</span><span class="n">output_reader</span><span class="p">)</span> <span class="p">);</span>
+</pre></div>
+
+
+<p>The following diagram illustrates the write to the output
+vconnection:</p>
+<p><strong>Figure 5.5. Writing the Buffered Data to the Output Vconnection</strong></p>
+<p><img alt="Writing the Buffered Data to the Output Vconnection" src="images/vconn_buf_output.jpg" /></p>
+</li>
+</ol>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SampleNullTransformPlugin.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SampleNullTransformPlugin.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SampleNullTransformPlugin.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SampleNullTransformPlugin.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,214 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="HTTPTransformationPlugins">Prev</a> - Chapter 5. HTTP
+Transformation Plugins
+The Append-Transform Plugin - <a href="AppendTransformPlugin">Next</a></p>
+<h2 id="the_sample_null_transform_plugin">The Sample Null Transform Plugin</h2>
+<p>This section provides a step-by-step description of what the null
+transform plugin does, along with sections of code that apply. For
+context, you can find each code snippet in the complete source
+code. Some of the error checking details are left out - to give the
+description a step-by-step flow, only the highlights of the
+transform are included.</p>
+<p>Below is an overview of the null transform plugin:</p>
+<ol>
+<li>
+<p>Gets a handle to HTTP transactions.</p>
+<div class="codehilite"><pre><span class="n">void</span>
+     <span class="n">INKPluginInit</span> <span class="p">(</span><span class="nb">int</span> <span class="n">argc</span><span class="p">,</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">argv</span><span class="o">[]</span><span class="p">)</span> <span class="p">{</span>
+          <span class="n">INKHttpHookAdd</span> <span class="p">(</span><span class="n">INK_HTTP_READ_RESPONSE_HDR_HOOK</span><span class="p">,</span>
+               <span class="n">INKContCreate</span> <span class="p">(</span><span class="n">transform_plugin</span><span class="p">,</span> <span class="n">NULL</span><span class="p">));</span>
+</pre></div>
+
+
+<p>With this <code>INKPluginInit</code> routine, the plugin is called back every
+time Traffic Server reads a response header.</p>
+</li>
+<li>
+<p>Checks to see if the transaction response is transformable.</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="nb">int</span> <span class="n">transform_plugin</span> <span class="p">(</span><span class="n">INKCont</span> <span class="n">contp</span><span class="p">,</span> <span class="n">INKEvent</span> <span class="n">event</span><span class="p">,</span> <span class="n">void</span> <span class="o">*</span><span class="n">edata</span><span class="p">)</span> <span class="p">{</span>
+     <span class="n">INKHttpTxn</span> <span class="n">txnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">INKHttpTxn</span><span class="p">)</span> <span class="n">edata</span><span class="p">;</span>
+     <span class="n">switch</span> <span class="p">(</span><span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+          <span class="k">case</span> <span class="n">INK_EVENT_HTTP_READ_RESPONSE_HDR:</span>
+          <span class="k">if</span> <span class="p">(</span><span class="n">transformable</span> <span class="p">(</span><span class="n">txnp</span><span class="p">))</span> <span class="p">{</span>
+               <span class="n">transform_add</span> <span class="p">(</span><span class="n">txnp</span><span class="p">);}</span>
+</pre></div>
+
+
+<p>The default behavior for transformations is to cache the
+transformed content (you can also tell Traffic Server to cache
+untransformed content, if you want). Therefore, only responses
+received directly from an origin server need to be transformed.
+Objects served from cache are already transformed. To determine
+whether the response is from the origin server, the routine
+<code>transformable</code> checks the response header for the "200 OK" server
+response.</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="nb">int</span> <span class="n">transformable</span> <span class="p">(</span><span class="n">INKHttpTxn</span> <span class="n">txnp</span><span class="p">)</span>
+<span class="p">{</span>
+     <span class="n">INKMBuffer</span> <span class="n">bufp</span><span class="p">;</span>
+     <span class="n">INKMLoc</span> <span class="n">hdr_loc</span><span class="p">;</span>
+     <span class="n">INKHttpStatus</span> <span class="n">resp_status</span><span class="p">;</span>
+     <span class="n">INKHttpTxnServerRespGet</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">bufp</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">hdr_loc</span><span class="p">);</span>
+
+     <span class="k">if</span> <span class="p">(</span><span class="n">INK_HTTP_STATUS_OK</span> <span class="o">==</span> <span class="p">(</span><span class="n">resp_status</span> <span class="o">=</span>
+          <span class="n">INKHttpHdrStatusGet</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">))</span> <span class="p">)</span> <span class="p">{</span>
+          <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+     <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+          <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+     <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>If the response is transformable, then the plugin creates a
+    transformation vconnection that gets called back when the response
+    data is ready to be transformed (as it is streaming from the origin
+    server).</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="n">void</span> <span class="n">transform_add</span> <span class="p">(</span><span class="n">INKHttpTxn</span> <span class="n">txnp</span><span class="p">)</span>
+<span class="p">{</span>
+     <span class="n">INKVConn</span> <span class="n">connp</span><span class="p">;</span>
+     <span class="n">connp</span> <span class="o">=</span> <span class="n">INKTransformCreate</span> <span class="p">(</span><span class="n">null_transform</span><span class="p">,</span> <span class="n">txnp</span><span class="p">);</span>
+     <span class="n">INKHttpTxnHookAdd</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_HTTP_RESPONSE_TRANSFORM_HOOK</span><span class="p">,</span> <span class="n">connp</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The previous code fragment shows that the handler function for the
+transformation vconnection is <code>null_transform</code>.</p>
+</li>
+<li>
+<p>Get a handle to the output vconnection (that receives data from
+    the tranformation).</p>
+<div class="codehilite"><pre><span class="n">output_conn</span> <span class="o">=</span> <span class="n">INKTransformOutputVConnGet</span> <span class="p">(</span><span class="n">con</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>Get a handle to the input VIO. (See the <code>handle_transform</code>
+    function.)</p>
+<div class="codehilite"><pre><span class="n">input_vio</span> <span class="o">=</span> <span class="n">INKVConnWriteVIOGet</span> <span class="p">(</span><span class="n">contp</span><span class="p">);</span>
+</pre></div>
+
+
+<p>This is so that the transformation can get information about the
+upstream vconnection's write operation to the input buffer.</p>
+</li>
+<li>
+<p>Initiate a write to the output vconnection of the specified
+    number of bytes. When the write is initiated, the transformation
+    expects to receive <code>WRITE_READY</code>, <code>WRITE_COMPLETE</code>, or <code>ERROR</code>
+    events from the output vconnection.</p>
+<p>See the <code>handle_transform</code> function for the following code
+fragment:</p>
+<div class="codehilite"><pre><span class="n">data</span><span class="o">-&gt;</span><span class="n">output_vio</span> <span class="o">=</span> <span class="n">INKVConnWrite</span> <span class="p">(</span><span class="n">output_conn</span><span class="p">,</span> <span class="n">contp</span><span class="p">,</span>
+     <span class="n">data</span><span class="o">-&gt;</span><span class="n">output_reader</span><span class="p">,</span> <span class="n">INKVIONBytesGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">));</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>Copy data from the input buffer to the output buffer. See the
+    <code>handle_transform</code> function for the following code fragment:</p>
+<div class="codehilite"><pre><span class="n">INKIOBufferCopy</span> <span class="p">(</span><span class="n">INKVIOBufferGet</span> <span class="p">(</span><span class="n">data</span><span class="o">-&gt;</span><span class="n">output_vio</span><span class="p">),</span>
+     <span class="n">INKVIOReaderGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">),</span> <span class="n">towrite</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>Tell the input buffer that the transformation has read the
+    data. See the <code>handle_transform</code> function for the following code
+    fragment:</p>
+<div class="codehilite"><pre><span class="n">INKIOBufferReaderConsume</span> <span class="p">(</span><span class="n">INKVIOReaderGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">),</span> <span class="n">towrite</span><span class="p">);</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>Modify the input VIO to tell it how much data has been read
+    (increase the value of <code>ndone</code>). See the <code>handle_transform</code>
+    function for the following code fragment:</p>
+<div class="codehilite"><pre><span class="n">INKVIONDoneSet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">,</span> <span class="n">INKVIONDoneGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">)</span> <span class="o">+</span> <span class="n">towrite</span><span class="p">);</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>If there is more data left to read
+    (<code>if ndone &lt;           nbytes</code>), then the <code>handle_transform</code>
+    function wakes up the downstream vconnection with a reenable and
+    wakes up the upstream vconnection by sending it <code>WRITE_READY</code>:</p>
+<div class="codehilite"><pre><span class="k">if</span> <span class="p">(</span><span class="n">INKVIONTodoGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+     <span class="k">if</span> <span class="p">(</span><span class="n">towrite</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+          <span class="n">INKVIOReenable</span> <span class="p">(</span><span class="n">data</span><span class="o">-&gt;</span><span class="n">output_vio</span><span class="p">);</span>
+
+          <span class="n">INKContCall</span> <span class="p">(</span><span class="n">INKVIOContGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">),</span>
+               <span class="n">INK_EVENT_VCONN_WRITE_READY</span><span class="p">,</span> <span class="n">input_vio</span><span class="p">);</span>
+          <span class="p">}</span>
+     <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+</pre></div>
+
+
+<p>The process of passing data through the transformation is
+illustrated in the following diagram. The downstream vconnections
+send <code>WRITE_READY</code> events when they need more data; when data is
+available, the upstream vconnections reenable the downstream
+vconnections. In this instance, the <code>INKVIOReenable</code> function sends
+<code>INK_EVENT_IMMEDIATE</code>.</p>
+<p><strong>Figure 5.2. Passing Data Through a Transformation</strong></p>
+<p><img alt="Passing Data Through a Transformation" src="images/vconnection1.jpg" />
+11. If the <code>handle_transform</code> function finds there is no more data
+to read, then it sets <code>nbytes</code> to <code>ndone</code> on the output
+(downstream) VIO and wakes up the output vconnection with a
+reenable. It then triggers the end of the write operation from the
+upstream vconnection by sending the upstream vconnection a
+<code>WRITE_COMPLETE</code> event.</p>
+<div class="codehilite"><pre><span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+
+<span class="n">INKVIONBytesSet</span> <span class="p">(</span><span class="n">data</span><span class="o">-&gt;</span><span class="n">output_vio</span><span class="p">,</span> <span class="n">INKVIONDoneGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">));</span>
+<span class="n">INKVIOReenable</span> <span class="p">(</span><span class="n">data</span><span class="o">-&gt;</span><span class="n">output_vio</span><span class="p">);</span>
+<span class="n">INKContCall</span> <span class="p">(</span><span class="n">INKVIOContGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">),</span>
+     <span class="n">INK_EVENT_VCONN_WRITE_COMPLETE</span><span class="p">,</span> <span class="n">input_vio</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>When the upstream vconnection receives the <code>WRITE_COMPLETE</code> event,
+it will probably shut down the write operation.</p>
+</li>
+<li>
+<p>Similarly, when the downstream vconnection has consumed all of
+    the data, it sends the transformation a <code>WRITE_COMPLETE</code> event. The
+    transformation handles this event with a shut down (the
+    transformation shuts down the write operation to the downstream
+    vconnection). See the <code>null_plugin</code> function for the following code
+    fragment:</p>
+<div class="codehilite"><pre><span class="k">case</span> <span class="n">INK_EVENT_VCONN_WRITE_COMPLETE:</span>
+     <span class="n">INKVConnShutdown</span> <span class="p">(</span><span class="n">INKTransformOutputVConnGet</span> <span class="p">(</span><span class="n">contp</span><span class="p">),</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span>
+     <span class="n">break</span><span class="p">;</span>
+</pre></div>
+
+
+<p>The following diagram illustrates the flow of events:</p>
+<p><strong>Figure 5.3. Ending the Transformation</strong></p>
+<p><img alt="Ending the Transformation" src="images/vconnection2.jpg" /></p>
+</li>
+</ol>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SetTransactionHook.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SetTransactionHook.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SetTransactionHook.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/SetTransactionHook.en.html Sat Nov  6 06:31:06 2010
@@ -4,17 +4,52 @@
 <html>
   <!-- This template is for the bulk of the site! -->
   <head>
+    <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
     
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0 (the &quot;License&quot;); you may not use this file except in compliance with the License.  You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the specific language governing permissions and limitations under the License. -->
   </head>
 
   <body>
-    <h1></h1>
+    <h1>Apache Traffic Server™ Software Developers Kit</h1>
 
   <div id="content">
-      
+      <p><a href="WorkWithHTTPHeaders">Prev</a> - Working With HTTP Headers
+Chapter 5. HTTP Transformation Plugins -
+<a href="HTTPTransformationPlugins">Next</a></p>
+<h3 id="setting_a_transaction_hook">Setting a Transaction Hook</h3>
+<p>If the request does not have the <code>Proxy-Authorization</code> field set to
+Basic authorization or a valid username/password, then the plugin
+sends the <code>407 Proxy         authorization</code> <code>required</code> status code
+back to the client. The client will then prompt the user for a
+username and password, and then resend the request.</p>
+<p>In the <code>handle_dns</code> routine, the following lines handle the
+authorization error case:</p>
+<div class="codehilite"><pre><span class="err">done:</span>
+     <span class="err">INKHttpTxnHookAdd</span> <span class="err">(txnp,</span> <span class="err">INK_HTTP_SEND_RESPONSE_HDR_HOOK,</span> <span class="err">contp);</span>
+     <span class="err">INKHttpTxnReenable</span> <span class="err">(txnp,</span> <span class="err">INK_EVENT_HTTP_ERROR);</span>
+</pre></div>
+
+
+<p>If <code>handle_dns</code> does not find the <code>Proxy-Authorization</code> field set
+to Basic authorization or a valid username/password, then it adds a
+<code>SEND_RESPONSE_HDR_HOOK</code> to the transaction being processed. This
+means that Traffic Server will call the plugin back when sending
+the client response. <code>handle_dns</code> reenables the transaction with
+<code>INK_EVENT_HTTP_ERROR</code>, which means that the plugin wants Traffic
+Server to terminate the transaction.</p>
+<p>When Traffic Server terminates the transaction, it sends the client
+an error message. Because of the <code>SEND_RESPONSE_HDR_HOOK</code>, Traffic
+Server calls the plugin back. The <code>auth-plugin</code> routine calls
+<code>handle_response</code> to send the client a <code>407</code> status code. When the
+client resends the request with the <code>Proxy-         Authorization</code>
+field, a new transaction begins.</p>
+<p><code>handle_dns</code> calls <code>base64_decode</code> to decode the username and
+password; <code>handle_dns</code> also calls <code>authorized</code> to validate the
+username and password. In this plugin, sample NT code is provided
+for password validation. UNIX programmers can supply their own
+validation mechanism.</p>
   </div>
 
   <div id="footer">