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 [21/21] - in
/websites/staging/trafficserver/trunk/content/docs/trunk: admin/ sdk/
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/WorkWithHTTPHeaders.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/WorkWithHTTPHeaders.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/WorkWithHTTPHeaders.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/WorkWithHTTPHeaders.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,97 @@
<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 "License"); 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 "AS IS" 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="ImplementHandler_GetTransHandle">Prev</a> - Implementing the
+Handler and Getting a Handle to the Transaction
+Setting a Transaction Hook - <a href="SetTransactionHook">Next</a></p>
+<h3 id="working_with_http_headers">Working With HTTP Headers</h3>
+<p>The plugin checks all client request headers for the
+Proxy-Authorization MIME field, which should contain the user name
+and password. The plugin's continuation handler, <code>auth-plugin</code>,
+calls <code>handle_dns</code> to check the <code>Proxy-Authorization</code> field. The
+<code>handle_dns</code> routine uses <code>INKHttpTxnClientReqGet</code> and
+<code>INKMimeHdrFieldFind</code> to obtain the <code>Proxy-Authorization</code> field:</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">INKMLoc</span> <span class="n">field_loc</span><span class="p">;</span>
+ <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">val</span><span class="p">;</span>
+ <span class="n">char</span> <span class="o">*</span><span class="n">user</span><span class="p">,</span> <span class="o">*</span><span class="n">password</span><span class="p">;</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">INKHttpTxnClientReqGet</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="o">&</span><span class="n">bufp</span><span class="p">,</span> <span class="o">&</span><span class="n">hdr_loc</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">INKError</span> <span class="p">(</span><span class="s">"couldn't retrieve client request header\n"</span><span class="p">);</span>
+ <span class="nb">goto</span> <span class="n">done</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">field_loc</span> <span class="o">=</span> <span class="n">INKMimeHdrFieldFind</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">INK_MIME_FIELD_PROXY_AUTHORIZATION</span><span class="p">);</span>
+</pre></div>
+
+
+<p>If the <code>Proxy-Authorization</code> field is present, then the plugin
+checks that the authentication type is "Basic", and the user name
+and password are present and valid:</p>
+<div class="codehilite"><pre><span class="n">val</span> <span class="o">=</span> <span class="n">INKMimeHdrFieldValueStringGet</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">field_loc</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="o">&</span><span class="n">authval_length</span><span class="p">);</span>
+<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">val</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKError</span> <span class="p">(</span><span class="s">"no value in Proxy-Authorization field\n"</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">field_loc</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">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">);</span>
+ <span class="nb">goto</span> <span class="n">done</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">strncmp</span> <span class="p">(</span><span class="n">val</span><span class="p">,</span> <span class="s">"Basic"</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKError</span> <span class="p">(</span><span class="s">"no Basic auth type in Proxy-Authorization\n"</span><span class="p">);</span>
+ <span class="n">INKHandleStringRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">field_loc</span><span class="p">,</span> <span class="n">val</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">field_loc</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">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">);</span>
+ <span class="nb">goto</span> <span class="n">done</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">val</span> <span class="o">+=</span> <span class="mi">5</span><span class="p">;</span>
+ <span class="k">while</span> <span class="p">((</span><span class="o">*</span><span class="n">val</span> <span class="o">==</span> <span class="s">' '</span><span class="p">)</span> <span class="o">||</span> <span class="p">(</span><span class="o">*</span><span class="n">val</span> <span class="o">==</span> <span class="s">'\t'</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">val</span> <span class="o">+=</span> <span class="mi">1</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">user</span> <span class="o">=</span> <span class="n">base64_decode</span> <span class="p">(</span><span class="n">val</span><span class="p">);</span>
+ <span class="n">password</span> <span class="o">=</span> <span class="n">strchr</span> <span class="p">(</span><span class="n">user</span><span class="p">,</span> <span class="s">':'</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">password</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKError</span> <span class="p">(</span><span class="s">"no password in authorization information\n"</span><span class="p">);</span>
+ <span class="n">INKfree</span> <span class="p">(</span><span class="n">user</span><span class="p">);</span>
+ <span class="n">INKHandleStringRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">field_loc</span><span class="p">,</span> <span class="n">val</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">field_loc</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">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">);</span>
+ <span class="nb">goto</span> <span class="n">done</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="o">*</span><span class="n">password</span> <span class="o">=</span> <span class="s">'\0'</span><span class="p">;</span>
+ <span class="n">password</span> <span class="o">+=</span> <span class="mi">1</span><span class="p">;</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">authorized</span> <span class="p">(</span><span class="n">user</span><span class="p">,</span> <span class="n">password</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">INKError</span> <span class="p">(</span><span class="s">"%s:%s not authorized\n"</span><span class="p">,</span> <span class="n">user</span><span class="p">,</span> <span class="n">password</span><span class="p">);</span>
+ <span class="n">INKfree</span> <span class="p">(</span><span class="n">user</span><span class="p">);</span>
+ <span class="n">INKHandleStringRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">field_loc</span><span class="p">,</span> <span class="n">val</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">field_loc</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">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">);</span>
+ <span class="nb">goto</span> <span class="n">done</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">INKfree</span> <span class="p">(</span><span class="n">user</span><span class="p">);</span>
+ <span class="n">INKHandleStringRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">field_loc</span><span class="p">,</span> <span class="n">val</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">field_loc</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">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">);</span>
+ <span class="n">INKHttpTxnReenable</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">INK_EVENT_HTTP_CONTINUE</span><span class="p">);</span>
+ <span class="k">return</span><span class="p">;</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/WritingHandlerFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/WritingHandlerFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/WritingHandlerFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/WritingHandlerFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,192 @@
<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 "License"); 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 "AS IS" 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="ActivateContinuations">Prev</a> - How to Activate Continuations
+Chapter 13. Plugin Configurations -
+<a href="PluginConfigurations">Next</a></p>
+<h2 id="writing_handler_functions">Writing Handler Functions</h2>
+<p>The handler function is the key component of a continuation. It is
+supposed to examine the event and event data, and then do something
+appropriate. The probable action might be to schedule another event
+for the continuation to received, to open up a connection to a
+server, or simply to destroy itself.</p>
+<p>The continuation's handler function is a function of type
+<code>INKEventFunc</code>. Its arguments are a continuation, an event, and a
+pointer to some data (this data is passed to the continuation by
+the caller - do not confuse this data with the continuation's own
+data, associated by <code>INKContDataSet</code>). When the continuation is
+called back, the continuation and an event are passed to the
+handler function. The continuation is a handle to the same
+continuation that is invoked. The handler function typically has a
+switch statement to handle the events it receives:</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="nb">int</span> <span class="n">some_handler</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="o">.....</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_SOME_EVENT_1:</span>
+ <span class="n">do_some_thing_1</span><span class="p">;</span>
+ <span class="k">return</span><span class="p">;</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_SOME_EVENT_2:</span>
+ <span class="n">do_some_thing_2</span><span class="p">;</span>
+ <span class="k">return</span><span class="p">;</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_SOME_EVENT_3:</span>
+ <span class="n">do_some_thing_3</span><span class="p">;</span>
+ <span class="k">return</span><span class="p">;</span>
+ <span class="n">default:</span> <span class="n">break</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>
+</pre></div>
+
+
+<p><img alt="[Caution]" src="images/docbook/caution.png" />
+Caution
+You might notice that a continuation cannot determine if more
+events are "in flight" toward it. Do not use <code>INKContDestroy</code> to
+delete a continuation before you make sure that all incoming
+events, such as those sent because of <code>INKHttpTxnHookAdd</code>, have
+been handled.</p>
+<p>The following table lists events and the corresponding type of
+<code>void *</code>data passed to handler functions:</p>
+<p><strong>Event</strong>
+<strong>Hook or API Function That Sends the Event</strong>
+<strong><code>void *</code> Data Type</strong>
+<code>INK_EVENT_HTTP_READ_REQUEST_HDR</code>
+<code>INK_HTTP_READ_REQUEST_HDR_HOOK</code>
+<code>INKHttpTxn</code>
+<code>INK_EVENT_HTTP_OS_DNS</code>
+<code>INK_HTTP_OS_DNS_HOOK</code>
+<code>INKHttpTxn</code>
+<code>INK_EVENT_HTTP_SEND_REQUEST_HDR</code>
+<code>INK_HTTP_SEND_REQUEST_HDR_HOOK</code>
+<code>INKHttpTxn</code>
+<code>INK_EVENT_HTTP_READ_CACHE_HDR</code>
+<code>INK_HTTP_READ_CACHE_HDR_HOOK</code>
+<code>INKHttpTxn</code>
+<code>INK_EVENT_HTTP_READ_RESPONSE_HDR</code>
+<code>INK_HTTP_READ_RESPONSE_HDR_HOOK</code>
+<code>INKHttpTxn</code>
+<code>INK_EVENT_HTTP_SEND_RESPONSE_HDR</code>
+<code>INK_HTTP_SEND_RESPONSE_HDR_HOOK</code>
+<code>INKHttpTxn</code>
+<code>INK_EVENT_HTTP_SELECT_ALT</code>
+<code>INK_HTTP_SELECT_ALT_HOOK</code>
+<code>INKHttpTxn</code>
+<code>INK_EVENT_HTTP_TXN_START</code>
+<code>INK_HTTP_TXN_START_HOOK</code>
+<code>INKHttpTxn</code>
+<code>INK_EVENT_HTTP_TXN_CLOSE</code>
+<code>INK_HTTP_TXN_CLOSE_HOOK</code>
+<code>INKHttpTxn</code>
+<code>INK_EVENT_HTTP_SSN_START</code>
+<code>INK_HTTP_SSN_START_HOOK</code>
+<code>INKHttpSsn</code>
+<code>INK_EVENT_HTTP_SSN_CLOSE</code>
+<code>INK_HTTP_SSN_CLOSE_HOOK</code>
+<code>INKHttpSsn</code>
+<code />
+<code>`INK_EVENT_NONE`</code>
+<code>`INK_EVENT_CACHE_LOOKUP_COMPLETE`
+`INK_HTTP_CACHE_LOOKUP_COMPLETE_HOOK`
+`INKHttpTxn`
+`INK_EVENT_IMMEDIATE`
+`INKVConnClose, INKVIOReenable, INKContSchedule`</code>
+<code>INK_EVENT_IMMEDIATE</code>
+<code>INK_HTTP_REQUEST_TRANSFORM_HOOK</code>
+<code>`INK_EVENT_IMMEDIATE`
+`INK_HTTP_RESPONSE_TRANSFORM_HOOK`</code>
+<code>INK_EVENT_CACHE_OPEN_READ</code>
+<code>INKCacheRead</code>
+Cache VC
+<code>INK_EVENT_CACHE_OPEN_READ_FAILED</code>
+<code>INKCacheRead</code>
+Error code, see <code>INK_CACHE_ERROR_XXX</code>
+<code>INK_EVENT_CACHE_OPEN_WRITE</code>
+<code>INKCacheWrite</code>
+Cache VC
+<code>INK_EVENT_CACHE_OPEN_WRITE_FAILED</code>
+<code>INKCacheWrite</code>
+Error code, see <code>INK_CACHE_ERROR_XXX</code>
+<code>INK_EVENT_CACHE_REMOVE</code>
+<code>INKCacheRemove</code>
+Nothing
+<code>INK_EVENT_CACHE_REMOVE_FAILED</code>
+<code>INKCacheRemove</code>
+Error code, see <code>INK_CACHE_ERROR_XXX</code>
+<code>INK_EVENT_NET_ACCEPT</code>
+<code>INKNetAccept, INKHttpTxnServerIntercept, INKHttpTxnIntercept</code>
+Net VConnection
+<code>INK_EVENT_NET_ACCEPT_FAILED</code>
+<code>INKNetAccept, INKHttpTxnServerIntercept, INKHttpTxnIntercept</code>
+Nothing
+<code>INK_EVENT_HOST_LOOKUP</code>
+<code>INKHostLookup</code>
+Null pointer - error Non null pointer - <code>INKHostLookupResult</code>
+<code>INK_EVENT_TIMEOUT</code>
+<code>INKContSchedule</code>
+<code>`INK_EVENT_ERROR`</code>
+<code />
+<code />
+<code>INK_EVENT_VCONN_READ_READY</code>
+<code>INKVConnRead</code>
+<code>INKVConn</code>
+<code>INK_EVENT_VCONN_WRITE_READY</code>
+<code>INKVConnWrite</code>
+<code>INKVConn</code>
+<code>INK_EVENT_VCONN_READ_COMPLETE</code>
+<code>INKVConnRead</code>
+<code>INKVConn</code>
+<code>INK_EVENT_VCONN_WRITE_COMPLETE</code>
+<code>INKVConnWrite</code>
+<code>INKVConn</code>
+<code>INK_EVENT_VCONN_EOS</code>
+<code>INKVConnRead</code>
+<code>INKVConn</code>
+<code>INK_EVENT_NET_CONNECT</code>
+<code>INKNetConnect</code>
+<code>INKVConn</code>
+<code>INK_EVENT_NET_CONNECT_FAILED</code>
+<code>INKNetConnect</code>
+<code>INKVConn</code>
+<code />
+<code>`INK_EVENT_HTTP_CONTINUE`</code>
+<code>`INK_EVENT_HTTP_ERROR`</code>
+<code>`</code>INK_EVENT_MGMT_UPDATE<code />INKMgmtUpdateRegister<code />NULL`
+The continuation functions are listed below:</p>
+<ul>
+<li>
+<p><code>INKContCall</code></p>
+</li>
+<li>
+<p><code>INKContCreate</code></p>
+</li>
+<li>
+<p><code>INKContDataGet</code></p>
+</li>
+<li>
+<p><code>INKContDataSet</code></p>
+</li>
+<li>
+<p><code>INKContDestroy</code></p>
+</li>
+<li>
+<p><code>INKContMutexGet</code></p>
+</li>
+<li>
+<p><code>INKContSchedule</code></p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03.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 "License"); 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 "AS IS" 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="Roadmap_CreatingPlugins">Prev</a> - Roadmap for Creating Plugins
+Example: Query Remap Plugin - <a href="RemapAPI_Example">Next</a></p>
+<h2 id="chapter_3_remap_plugin">Chapter 3. Remap Plugin</h2>
+<p><strong>Table of Contents</strong></p>
+<ul>
+<li><a href="ch03#GettingStarted">Getting Started</a></li>
+<li>
+<ul>
+<li>
+<p><a href="ch03#RemapHeaderFile">Remap Header File</a></p>
+</li>
+<li>
+<p><a href="ch03#RequiredFunctions">Required Functions</a></p>
+</li>
+<li><a href="ch03#Configuration">Configuration</a></li>
+</ul>
+</li>
+<li>
+<p><a href="RemapAPI_Example">Example: Query Remap</a></p>
+</li>
+<li><a href="ch03s02">API Function Reference</a></li>
+</ul>
+<p>The Remap plugin provides a more flexible, dynamic way of
+specifying remap rules. It is not built on top of the Traffic
+Server APIs and exists solely for the purpose of URL remapping. The
+remap plugin is not global --it is configured on a per-remap rule
+basis, which enables you to customize how URLs are redirected based
+on individual rules in the <code>remap.config</code> file.</p>
+<p>The Traffic Server Remap API enables a plugin to dynamically map a
+client request to a target URL. Each plugin is associated with one
+or more remap rules in <code>remap.config</code> (an "instance"). If a request
+URL matches a remap rule's "fromURL", then Traffic Server calls the
+plugin-defined remap function for that request.</p>
+<p>((Editor's note: additional text TBD; text in this chapter is still
+under development))</p>
+<h2 id="getting_started">Getting Started</h2>
+<h3 id="remap_header_file">Remap Header File</h3>
+<p>The <code>remap.h</code> header file contains the Traffic Server remap API. By
+default, the header file location is:
+<code>/usr/local/include/ts/remap.h</code></p>
+<h3 id="required_functions">Required Functions</h3>
+<p>A remap plugin is required to implement the following functions:</p>
+<ul>
+<li><a href="ch03s02#tsremap_init"><code><b>tsremap_init</b></code></a>: the remap
+ initialization function, called once when the plugin is loaded</li>
+<li><a href="ch03s02#tsremap_new_instance"><code><b>tsremap_new_instance</b></code></a>:
+ a new instance is created for each rule associated with the plugin.
+ Called each time the plugin used in a remap rule (this function is
+ what processes the pparam values)</li>
+<li><a href="ch03s02#tsremap_remap"><code><b>tsremap_remap</b></code></a>: the entry
+ point used by Traffic Server to find the new URL to which it
+ remaps; called every time a request comes in</li>
+</ul>
+<h3 id="configuration">Configuration</h3>
+<p>To associate a remap plugin with a remap rule, use the <code>@plugin</code>
+parameter. See the Admin Guide section (?TBD?) for details on
+configuring remap plugins</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s02.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s02.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s02.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s02.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,220 @@
<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 "License"); 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 "AS IS" 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="RemapAPI_Example">Prev</a> - Example: Query Remap Plugin
+Chapter 4: Header-Based Plugin Examples -
+<a href="HeaderBasedPluginEx">Next</a></p>
+<h2 id="remap_plugin_function_reference">Remap Plugin Function Reference</h2>
+<ul>
+<li><a href="#tsremap_init">tsremap_init</a></li>
+<li><a href="#tsremap_new_instance">tsremap_new_instance</a></li>
+<li><a href="#tsremap_remap">tsremap_remap</a></li>
+<li><a href="#tsremap_delete_instance">tsremap_delete_instance</a></li>
+<li><a href="#tsremap_os_response">tsremap_os_response</a></li>
+</ul>
+<h4 id="tsremap_init">tsremap_init</h4>
+<p>The remap plugin initialization function.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int tsremap_init(TSRemapInterface *<span class="replaceable">api_info</span>, char *<span class="replaceable">errbuf</span>, int <span class="replaceable">errbuf_size</span>);</code></p>
+<p><strong>Arguments</strong>
+ ~ <code><em class="replaceable">api_info </em></code> is a
+ <code>TSRemapInterface</code> struct containing remap API interface version
+ information.</p>
+<div class="codehilite"><pre>`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>errbuf <span class="nt"></em></span>` is a buffer to which the
+plugin may write error messages about initialization errors.
+
+`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>errbuf_size <span class="nt"></em></span>` is the size, in bytes,
+of the buffer pointed to by `errbuf`.
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Traffic Server calls this initialization routine once per remap
+ plugin. All remap plugins are required to implement this function.</p>
+<p><strong>Returns</strong>
+ ~ The function must return <code>0</code> upon successful plugin
+ initialization.</p>
+<h4 id="tsremap_new_instance">tsremap_new_instance</h4>
+<p>The remap instance initialization function.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int tsremap_new_instance(int <em class="replaceable">argc</em>, char *<em class="replaceable">argv</em>[], ihandle *<em class="replaceable">ih</em>, char *<em class="replaceable">errbuf</em>, int <span class="replaceable"> </span><em class="replaceable">errbuf_size</em>);</code></p>
+<p><strong>Arguments</strong>
+ ~ <code><em class="replaceable">argc </em></code> is a count of the number
+ of arguments in the argument
+ vector,<code><em class="replaceable"> argv</em></code>.</p>
+<div class="codehilite"><pre>`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>argv <span class="nt"></em></span>` is the vector of arguments.
+The number of arguments in the vector is `argc`. `argv[0]` and
+`argv[1]` contain the `fromURL` and `toURL`, respectively, from the
+remap rule in canonical form. Additional plugin parameters can be
+passed to the plugin by using `@pparam=plugin_name` in the
+configuration file.
+
+The `<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>ih, <span class="nt"></em></span>` or `ihandle`, is a opaque
+pointer that can be used by the plugin to store per-instance data.
+Traffic Server passes this handle to `tsremap_remap`,
+`tsremap_os_response`, and `tsremap_delete_instance` for operations
+on this instance. If memory is allocated for the ihandle, then it
+can be freed via `tsremap_delete_instance`.
+
+`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>errbuf <span class="nt"></em></span>` is a buffer to which the
+plugin may write informational error messages about instance
+initialization errors.
+
+`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>errbuf_size <span class="nt"></em></span>` is the size, in bytes,
+of the buffer pointed to by
+`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span> errbuf<span class="nt"></em></span>`.
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Traffic Server calls this initialization routine once per remap
+ instance for which the plugin is configured (i.e. once per rule in
+ <code>remap.config</code> that has <code>@plugin=</code>). All remap plugins are required
+ to implement this function.</p>
+<p><strong>Returns</strong>
+ ~ The function must return <code>0</code> on successful instance
+ initialization.</p>
+<h4 id="tsremap_remap">tsremap_remap</h4>
+<p>Remap request function.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int tsremap_remap(ihandle<em class="replaceable"> ih</em>, rhandle <span class="replaceable"> </span><em class="replaceable">rh</em>, TSRemapRequestInfo *<em class="replaceable">rri</em>)</code></p>
+<p><strong>Arguments</strong>
+ ~ <code><em class="replaceable">ih </em></code> is the ihandle for the
+ instance set during <code>tsremap_new_instance</code>.</p>
+<div class="codehilite"><pre>`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>rh <span class="nt"></em></span>` is the `INKHttpTxn` for the
+request. This allows remap plugins to use APIs from`ts.h`.
+
+`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>rri <span class="nt"></em></span>` is the `TSRemapRequestInfo`
+struct contains input and output parameters for the remap operation
+for a single request. The struct members are as follows:
+
+##### Input (read-only) members
+
+ unsigned long size; /* sizeof(TSRemapRequestInfo) */
+
+ int request_port; /* request port number */
+ int remap_from_port; /* fromURL port number (from remap rule) */
+ int remap_to_port; /* toURL port number (from remap rule) */
+
+ const char *orig_url; /* request URL */
+ int orig_url_size; /* request URL size */
+
+ const char *request_host; /* request host string (not NULL terminated) */
+ int request_host_size; /* request host string size */
+
+ const char *remap_from_host; /* fromURL host (from remap rule, not NULL terminated) */
+ int remap_from_host_size; /* fromURL host size */
+
+ const char *remap_to_host; /* toURL host (from remap rule, not NULL terminated) */
+ int remap_to_host_size; /* toURL host size */
+
+ const char *request_path; /* request path (from client, not NULL terminated) */
+ int request_path_size; /* request path size */
+
+ const char *remap_from_path; /* fromURL path (from remap rule, not NULL terminated) */
+ int remap_from_path_size; /* fromURL path size */
+
+ const char *remap_to_path; /* toURL path (from remap rule, not NULL terminated) */
+ int remap_to_path_size; /* toURL path size */
+
+ const char *request_cookie; /* request 'Cookie:' value string (from client, not NULL terminated) */
+ int request_cookie_size; /* request cookie header size */
+
+ const char *request_query; /* request query string (from client, not NULL terminated) */
+ int request_query_size; /* request query string size. */
+
+ const char *request_matrix; /* request matrix string (from client, not NULL terminated) */
+ int request_matrix_size; /* request matrix string size. */
+
+ const char *from_scheme; /* The "from" scheme (e.g. http) */
+ int from_scheme_len; /* The len of the "from" scheme */
+
+ const char *to_scheme; /* The "to" scheme (e.g. http) */
+ int to_scheme_len; /* The len of the "to" scheme */
+
+ unsigned int client_ip; /* The client IP is an unsigned 32-bit network byte order (big-endian) value */
+
+##### Output members
+
+ char new_host[TSREMAP_RRI_MAX_HOST_SIZE]; /* new host string */
+ int new_host_size; /* new host string size (if 0 - do not change request host) */
+ int new_port; /* new port number (0 - do not change request port) */
+ char new_path[TSREMAP_RRI_MAX_PATH_SIZE]; /* new path string */
+ int new_path_size; /* new path string size (0 - do not change request path) */
+ char new_query[TSREMAP_RRI_MAX_PATH_SIZE]; /* new query string */
+ int new_query_size; /* new query string size (0 - do not change request query) */
+ char new_matrix[TSREMAP_RRI_MAX_PATH_SIZE]; /* new matrix parameter string */
+ int new_matrix_size; /* new matrix parameter string size (0 - do not change matrix parameters) */
+ char redirect_url[TSREMAP_RRI_MAX_REDIRECT_URL]; /* redirect url (to redirect/reject request) */
+ int redirect_url_size; /* redirect url size (0 - empty redirect url string) */
+ int require_ssl; /* Require the toScheme to become SSL (e.g. HTTPS). */
+ /* 0 -> Disable SSL if toScheme is SSL */
+ /* 1 -> Enable SSL if toScheme is not SSL */
+ /* -1 (default) -> Don't modify scheme */
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ A non-zero return value indicates that the plugin modified the
+ output members of the <code>rri</code> argument. Traffic Server uses those
+ values to modify the client request. Otherwise, the plugin can
+ return <code>0</code> to indicate that Traffic Server should use the default
+ <code>toURL</code> from the remap rule.</p>
+<p><strong>Description</strong>
+ ~ This is the main remap function in which the plugin can modify
+ the client request based on the <code>rri</code> input members. The function
+ must be reentrant, as TS may call the remap function concurrently
+ from multiple threads.</p>
+<div class="codehilite"><pre><span class="n">The</span> <span class="n">function</span> <span class="n">is</span> <span class="n">called</span> <span class="k">for</span> <span class="n">client</span> <span class="n">requests</span> <span class="n">matching</span> <span class="n">the</span> <span class="n">remap</span> <span class="n">rule</span>
+<span class="n">associated</span> <span class="n">with</span> <span class="n">the</span> <span class="n">plugin</span> <span class="p">(</span><span class="n">based</span> <span class="n">on</span> <span class="sb">`fromURL`</span><span class="p">)</span><span class="o">.</span> <span class="n">If</span> <span class="n">multiple</span> <span class="n">rules</span>
+<span class="n">match</span> <span class="n">the</span> <span class="n">client</span> <span class="n">request</span><span class="p">,</span> <span class="k">then</span> <span class="n">Traffic</span> <span class="n">Server</span> <span class="n">uses</span> <span class="n">the</span> <span class="n">first</span> <span class="n">match</span><span class="o">.</span>
+<span class="n">In</span> <span class="n">relation</span> <span class="n">to</span> <span class="n">Traffic</span> <span class="n">Server</span><span class="err">'</span><span class="n">s</span> <span class="n">HTTP</span> <span class="n">transaction</span> <span class="n">APIs</span><span class="p">,</span>
+<span class="sb">`tsremap_remap`</span> <span class="n">is</span> <span class="n">invoked</span> <span class="n">before</span> <span class="sb">`INK_HTTP_READ_REQUEST_HDR_HOOK`</span>
+<span class="ow">and</span> <span class="n">before</span> <span class="n">a</span> <span class="n">cache</span> <span class="n">lookup</span><span class="o">.</span> <span class="n">Thus</span><span class="p">,</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">lookup</span> <span class="n">key</span> <span class="n">is</span> <span class="n">altered</span> <span class="k">if</span>
+<span class="n">the</span> <span class="n">plugin</span> <span class="n">modifies</span> <span class="n">the</span> <span class="n">request</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="tsremap_delete_instance">tsremap_delete_instance</h4>
+<p><strong>Prototype</strong>
+ ~ <code>void tsremap_delete_instance(ihandle <span class="replaceable">ih</span>)</code></p>
+<p><strong>Arguments</strong>
+ ~ <code><em class="replaceable">ih </em></code> is the ihandle for the
+ instance set during <code>tsremap_new_instance</code>.</p>
+<p><strong>Description</strong>
+ ~ The plugin can optionally define this function, which is called
+ when a remap instance is released. For example: when <code>remap.config</code>
+ is reloaded, all existing instances are released and new instances
+ are created.</p>
+<h4 id="tsremap_os_response">tsremap_os_response</h4>
+<p><strong>Prototype</strong>
+ ~ <code>void tsremap_os_response(ihandle <span class="replaceable">ih</span>, rhandle <span class="replaceable">rh</span>, int <span class="replaceable">os_response_type</span>)</code></p>
+<p><strong>Arguments</strong>
+ ~ <code><em class="replaceable">ih </em></code> is the ihandle for the
+ instance set during <code>tsremap_new_instance</code>.</p>
+<div class="codehilite"><pre>`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>rh <span class="nt"></em></span>` is the `INKHttpTxn` for the
+request. It enables remap plugins to use APIs from `ts.h`
+
+`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>os_response_type <span class="nt"></em></span>` is the value of
+`INKServerState` that indicates the state of the response.
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ This optional function is called after Traffic Server receives
+ a response from the origin server. If the request is served from
+ cache, then the function is not called.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s03.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s03.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s03.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s03.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,43 @@
<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 "License"); 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 "AS IS" 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="ch03s02">Prev</a> - Remap.API.h
+Examples - <a href="ch03s04">Next</a></p>
+<h2 id="functions_you_need_to_implement">Functions You Need to Implement</h2>
+<p>In order to use a remap plugin, you must implement the functions
+below:</p>
+<ul>
+<li>
+<p><strong>Initialization function</strong>: called only once, when the plugin
+ is loaded
+ <a href="GetingStarted#PluginInitialization" title="Plugin Initialization">Plugin Initialization</a></p>
+</li>
+<li>
+<p><strong>Instantiation function:</strong>called each time it's used in a
+ remap rule (this function is what processes the pparam values)</p>
+</li>
+<li>
+<p><strong>"Processing" function:</strong> the entry point used by Traffic
+ Server to find the new URL to which it remaps; called every time a
+ request comes in</p>
+</li>
+<li>
+<p>(Destruction function<strong>?</strong>): (optional) a "cleanup" function
+ called only if/when the plugin is unloaded</p>
+</li>
+</ul>
+<p>((Editor's note: text TBD; above text still under development))</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s04.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s04.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s04.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch03s04.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,22 @@
<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 "License"); 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 "AS IS" 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="ch03s03">Prev</a> - Functions You Need to Implement
+Chapter 4. Header-Based Plugin Examples -
+<a href="HeaderBasedPluginEx">Next</a></p>
+<h2 id="examples">Examples</h2>
+<p>((Editor's note: text TBD))</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,35 @@
<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 "License"); 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 "AS IS" 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="NewProtocolPlugins">Prev</a> - Chapter 6. New Protocol Plugins
+Reads and Writes - <a href="ch07s02">Next</a></p>
+<h2 id="chapter_7_cache_plugin">Chapter 7. Cache Plugin</h2>
+<p><strong>Table of Contents</strong></p>
+<ul>
+<li><a href="ch07#id378027">Getting Started</a></li>
+<li><a href="ch07s02">Reads and Writes</a></li>
+<li><a href="ch07s03">State Diagram</a></li>
+<li><a href="ch07s04">Sample Plugin</a></li>
+<li><a href="ch07s05">Cache Events</a></li>
+</ul>
+<p>The Traffic Server cache plugin replaces the cache engine and the
+underlying storage of Traffic Server's built-in cache. Writing your
+own plugin enables you to control the storage mechanisms (ie,
+memory, disk, network storage) as well as the cache replacement
+policy (ie, LRU, LFU).</p>
+<h2 id="getting_started">Getting Started</h2>
+<p>((Editor's note: text TBD))</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s02.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s02.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s02.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s02.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,21 @@
<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 "License"); 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 "AS IS" 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="ch07">Prev</a> - Chapter 7. Cache Plugin
+State Diagram - <a href="ch07s03">Next</a></p>
+<h2 id="reads_and_writes">Reads and Writes</h2>
+<p>((Editor's note: text TBD))</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s03.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s03.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s03.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s03.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,21 @@
<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 "License"); 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 "AS IS" 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="ch07s02">Prev</a> - Reads and Writes
+Sample Plugin - <a href="ch07s04">Next</a></p>
+<h2 id="state_diagram">State Diagram</h2>
+<p>((Editor's note: text forthcoming))</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s04.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s04.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s04.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s04.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,21 @@
<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 "License"); 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 "AS IS" 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="ch07s03">Prev</a> - State Diagram
+Cache Events - <a href="ch07s05">Next</a></p>
+<h2 id="sample_plugin">Sample Plugin</h2>
+<p>((Editor's Note: text forthcoming))</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s05.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s05.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s05.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch07s05.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,23 @@
<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 "License"); 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 "AS IS" 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="ch07s04">Prev</a> - Sample Plugin
+Chapter 8. HTTP Hooks and Transactions -
+<a href="HTTPHooksAndTransactions">Next</a></p>
+<h2 id="cache_events">Cache Events</h2>
+<p>((Editor's Note: This section may be added to Cache plugin chapter
+or elsewhere in the doc))</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch18s09s04.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch18s09s04.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch18s09s04.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ch18s09s04.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,76 @@
<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 "License"); 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 "AS IS" 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="AlternateSelectionFunctions">Prev</a> - Alternate Selection
+Functions
+Marshal Buffers - <a href="MarshallBuffersFunctions">Next</a></p>
+<h3 id="handle_release_functions">Handle Release Functions</h3>
+<hr />
+<p><a href="ch18s09s04#INKHandleMLocRelease">INKHandleMLocRelease</a>
+<a href="ch18s09s04#INKHandleStringRelease">INKHandleStringRelease</a></p>
+<h4 id="inkhandlemlocrelease">INKHandleMLocRelease</h4>
+<p>Releases <code>INKMLoc</code> handles.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKHandleMLocRelease (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>parent</code></em>, INKMLoc <em><code>mloc</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code><em class="replaceable"><code>bufp</code> is the marshal buffer
+ containing the <code>INKMLoc</code> to be released.</p>
+<div class="codehilite"><pre><span class="sb">`<em class="replaceable"><code>parent`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">location</span> <span class="n">of</span> <span class="n">the</span>
+<span class="n">parent</span> <span class="n">object</span> <span class="n">from</span> <span class="n">which</span> <span class="n">the</span> <span class="n">handle</span> <span class="n">was</span> <span class="n">created</span><span class="o">.</span>
+
+<span class="sb">`<em class="replaceable"><code>mloc`</span> <span class="n">is</span> <span class="n">the</span> <span class="sb">`INKMLoc`</span> <span class="n">to</span> <span class="n">be</span>
+<span class="n">released</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Releases the <code>INKMLoc</code> mloc created from the <code>INKMLoc</code> parent.
+ If there is no parent <code>INKMLoc</code>, then use <code>INK_NULL_MLOC</code>. See
+ <a href="RlsMarshalBufHandles" title="Release Marshal Buffer Handles">Release Marshal Buffer Handle</a>
+ for details about parent <code>INKMLocs</code> and the use of the null
+ parent.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the handle is successfully released.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">hook</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">added</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkhandlestringrelease">INKHandleStringRelease</h4>
+<p>Releases string handles.</p>
+<p><strong>Prototype</strong>
+ ~ <code>InkReturnCode INKHandleStringRelease (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>parent</code></em>, const char *<em><code>str</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code><em class="replaceable"><code>bufp</code> is the marshal buffer
+ containing the string to be released.</p>
+<div class="codehilite"><pre><span class="sb">`<em class="replaceable"><code>parent`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">location</span> <span class="n">of</span> <span class="n">the</span>
+<span class="n">parent</span> <span class="n">object</span> <span class="n">from</span> <span class="n">which</span> <span class="n">the</span> <span class="n">handle</span> <span class="n">was</span> <span class="n">created</span><span class="o">.</span>
+
+<span class="sb">`<em class="replaceable"><code>str`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">string</span> <span class="n">to</span> <span class="n">be</span> <span class="n">released</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Releases the string <code><em class="replaceable"><code>str</code> created
+ from the <code>INKMLoc</code> parent. Do not use <code>INKHandleStringRelease</code> for
+ strings created by <code>INKUrlStringGet</code> (in that special case, use
+ <code>INKfree</code>).</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the string handle is successfully released.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">hook</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">added</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/index.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/index.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/index.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/index.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,30 @@
<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 "License"); 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 "AS IS" 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>Preface - <a href="Preface">Next</a></p>
+<h1 id="apache_traffic_server+_software_developers_kit">Apache Traffic Server⢠Software Developers Kit</h1>
+<h2 id="programmers_guide">Programmers Guide</h2>
+<p><em>In progress</em></p>
+<p><strong>Abstract</strong></p>
+<p>The <em>Traffic Server Software Developers Kit</em> shows you how to
+create plugins using the Traffic Server SDK.</p>
+<hr />
+<p>This documentation is a work in progress. It was originally written
+for a previous, commercially-available version of Traffic Server
+that supported different operating systems and more functions than
+the current version. As a result, some of the sections may refer to
+functionality that no longer exists.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/pr01s02.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/pr01s02.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/pr01s02.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/pr01s02.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,158 @@
<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 "License"); 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 "AS IS" 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="Preface">Prev</a> - Preface
+Typographical Conventions - <a href="Conventions">Next</a></p>
+<h2 id="how_to_use_this_book">How to Use This Book</h2>
+<p>This book has the following basic components:</p>
+<ul>
+<li>
+<p>Introduction and overview</p>
+</li>
+<li>
+<p>Tutorials about writing specific kinds of plugins: HTTP
+ header-based plugins, content transformation plugins, and protocol
+ plugins</p>
+</li>
+<li>
+<p>Guides about specific interfaces</p>
+</li>
+<li>
+<p>Reference material</p>
+</li>
+</ul>
+<p>If you're new to writing Traffic Server plugins, then read
+<a href="GetingStarted" title="Chapter 1. Getting Started">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.
+<a href="NewProtocolPlugins" title="Chapter 6. New Protocol Plugins">New Protocol Plugins</a>
+provides essential information if you want to support your own
+protocol on Traffic Server.</p>
+<p>You can look up information in the following reference sections:</p>
+<ul>
+<li><a href="ConceptIndex">Index</a>: lists information by subject</li>
+<li><a href="FunctionIndex" title="Appendix D. Function Index">Function Index</a>:
+ lists all Traffic Server API calls</li>
+<li><a href="TypeIndex" title="Appendix E. Type Index">Type Index</a></li>
+<li><a href="App_SampleSourceCode" title="Appendix A. Sample Source Code">Sample Source Code</a></li>
+<li><a href="App_DeprecatedFunctions" title="Appendix B. Deprecated Functions">Deprecated Functions</a></li>
+</ul>
+<p>Below is a section-by-section breakdown of this guide:</p>
+<ul>
+<li>
+<p><a href="GetingStarted#GettingStarted">Getting Started</a></p>
+<p>How to compile and load plugins. Walks through a simple "hello
+world" example; explains how to initialize and register plugins.</p>
+</li>
+<li>
+<p><a href="CreatingTSPlugins" title="Chapter 2. How to Create Traffic Server Plugins">How to Create Traffic Server Plugins</a>
+ Basic structures that all plugins use: events, continuations, and
+ how to hook on to Traffic Server processes. Detailed explication of
+ a sample blacklisting plugin.</p>
+</li>
+<li>
+<p><a href="ch03#RemapPlugin">Remap Plugin</a></p>
+<p>(( Remap plugin description here ))</p>
+</li>
+<li>
+<p><a href="HeaderBasedPluginEx" title="Chapter 4. Header-Based Plugin Examples">Header-Based Plugin Examples</a></p>
+<p>Detailed explanation about writing plugins that work on HTTP
+headers; discusses sample blacklisting and basic authorization
+plugins.</p>
+</li>
+<li>
+<p><a href="HTTPTransformationPlugins" title="Chapter 5. HTTP Transformation Plugins">HTTP Transformation Plugins</a>
+ Detailed explanation of the null-transform example; also discusses
+ vconnections, VIOs, and IO buffers.</p>
+</li>
+<li>
+<p><a href="NewProtocolPlugins" title="Chapter 6. New Protocol Plugins">New Protocol Plugins</a>
+ Detailed explanation of a sample protocol plugin that supports a
+ synthetic protocol. Discusses vconnections and mutexes, as well as
+ the the new netconnection, DNS lookup, logging, and cache APIs.</p>
+</li>
+<li>
+<p><a href="ch07#CachePlugin">Cache Plugin</a>
+ (( Cache plugin description here ))</p>
+</li>
+</ul>
+<p>The remaining sections comprise the API function reference and are
+organized by function type:</p>
+<ul>
+<li>
+<p><a href="MiscellaneousInterfaceGuide" title="Chapter 9. Miscellaneous Interface Guide">Miscellaneous Interface Guide</a>
+ Details error-writing and tracing functions, thread functions, and
+ Traffic Server API versions of the <code>malloc</code> and <code>fopen</code> families.
+ The Traffic Server API versions overcome various C library
+ limitations.</p>
+</li>
+<li>
+<p><a href="HTTPHooksAndTransactions" title="Chapter 8. HTTP Hooks and Transactions">HTTP Hooks and Transactions</a>
+ Functions in this chapter hook your plugin to Traffic Server HTTP
+ processes.</p>
+</li>
+<li>
+<p><a href="HTTPHeaders" title="Chapter 10. HTTP Headers">HTTP Headers</a>
+ Contains instructions for implementing performance enhancements for
+ all plugins that manipulate HTTP headers. These functions examine
+ and modify HTTP headers, MIME headers, URLs, and the marshal
+ buffers that contain header information. If you are working with
+ headers, then be sure to read this chapter.</p>
+</li>
+<li>
+<p><a href="MutexGuide" title="Chapter 11. Mutex Guide">Mutex Guide</a></p>
+</li>
+<li>
+<p><a href="Continuations" title="Chapter 12. Continuations">Continuations</a></p>
+<p>Continuations provide the basic callback mechanism and data
+abstractions used in Traffic Server.</p>
+</li>
+<li>
+<p><a href="PluginConfigurations" title="Chapter 13. Plugin Configurations">Plugin Configurations</a></p>
+</li>
+<li>
+<p><a href="ActionsGuide" title="Chapter 14. Actions Guide">Actions Guide</a></p>
+<p>Describes how to use <code>INKActions</code> and the <code>INKDNSLookup</code> API.</p>
+</li>
+<li>
+<p><a href="IOGuide" title="Chapter 15. IO Guide">IO Guide</a></p>
+<p>Describes how to use the Traffic Server IO interfaces:
+<code>INKVConnection</code>, <code>INKVIO</code>, <code>INKIOBuffer</code>, <code>INKNetVConnection</code>, the
+Cache API.</p>
+</li>
+<li>
+<p><a href="PluginManagement" title="Chapter 16. Plugin Management">Plugin Management</a>
+ These functions enable you to set up a configuration interface for
+ plugins, access installed plugin files, and set up plugin
+ licensing.</p>
+</li>
+<li>
+<p><a href="AddingStatistics" title="Chapter 17. Adding Statistics">Adding Statistics</a></p>
+<p>These functions add statistics to your plugin.</p>
+</li>
+<li>
+<p><a href="FunctionReference" title="Chapter 18. Function Reference">Function Reference</a></p>
+<p>A list of all functions in the Traffic Server API, grouped by
+functionality.</p>
+</li>
+</ul>
</div>
<div id="footer">