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 [5/21] - in
/websites/staging/trafficserver/trunk/content/docs/trunk: admin/ sdk/
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/App_SampleSourceCode.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/App_SampleSourceCode.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/App_SampleSourceCode.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/App_SampleSourceCode.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,315 @@
<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="INKTextLogObjectWrite">Prev</a> - INKTextLogObjectWrire
+Appendix B. Deprecated Functions -
+<a href="App_DeprecatedFunctions">Next</a></p>
+<h2 id="appendix_a_sample_source_code">Appendix A. Sample Source Code</h2>
+<p>This appendix provides several source code examples. In the online
+formats of this book, function calls are linked to their references
+in the previous chapters. The following sample plugins are
+provided:</p>
+<ul>
+<li><a href="App_SampleSourceCode#Sample_blacklist-1.c" title="blacklist-1.c">blacklist-1.c</a></li>
+</ul>
+<h2 id="blacklist-1c">blacklist-1.c</h2>
+<p>The sample blacklisting plugin included in the Traffic Server SDK
+is <code>blacklist-1.c</code>. This plugin checks every incoming HTTP client
+request against a list of blacklisted web sites. If the client
+requests a blacklisted site, then the plugin returns an
+<code>Access forbidden</code> message to the client.</p>
+<p>This plugin illustrates:</p>
+<ul>
+<li>
+<p>An HTTP transaction extension</p>
+</li>
+<li>
+<p>How to examine HTTP request headers</p>
+</li>
+<li>
+<p>How to use the logging interface</p>
+</li>
+<li>
+<p>How to use the plugin configuration management interface</p>
+<p>/<em> blacklist-1.c: An example program that denies client access <br />
+ * to blacklisted sites. This plugin illustrates
+ * how to use configuration information from the<br />
+ * blacklist.txt configuration file.
+ </em>
+ * Usage: <br />
+ * (Solaris) : blacklist-1.so
+ <em>
+ </em>
+ */</p>
+<h1 id="include_stdioh">include <stdio.h></h1>
+<h1 id="include_stringh">include <string.h></h1>
+<h1 id="include_tstsh">include <ts/ts.h></h1>
+<h1 id="define_max_nsites_500">define MAX_NSITES 500</h1>
+<p>static char* sites[MAX_NSITES];
+static int nsites;
+static INKMutex sites_mutex;
+static INKTextLogObject log;</p>
+<p>static void
+handle_dns (INKHttpTxn txnp, INKCont contp)
+{
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKMLoc url_loc;
+ const char *host;
+ int i;
+ int host_length;</p>
+<div class="codehilite"><pre><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">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="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">url_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 request url\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">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">host</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">&</span><span class="n">host_length</span><span class="p">);</span>
+<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">host</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKError</span> <span class="p">(</span><span class="s">"couldn't retrieve request hostname\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">url_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">INKMutexLock</span><span class="p">(</span><span class="n">sites_mutex</span><span class="p">);</span>
+
+<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">nsites</span><span class="p">;</span> <span class="n">i</span><span class="o">++</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">host</span><span class="p">,</span> <span class="n">sites</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">host_length</span><span class="p">)</span> <span class="o">==</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="nb">log</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKTextLogObjectWrite</span><span class="p">(</span><span class="nb">log</span><span class="p">,</span> <span class="s">"blacklisting site: %s"</span><span class="p">,</span> <span class="n">sites</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="nb">printf</span> <span class="p">(</span><span class="s">"blacklisting site: %s\n"</span><span class="p">,</span> <span class="n">sites</span><span class="p">[</span><span class="n">i</span><span class="p">]);</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_SEND_RESPONSE_HDR_HOOK</span><span class="p">,</span>
+ <span class="n">contp</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">url_loc</span><span class="p">,</span> <span class="n">host</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>
+ <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_ERROR</span><span class="p">);</span>
+ <span class="n">INKMutexUnlock</span><span class="p">(</span><span class="n">sites_mutex</span><span class="p">);</span>
+ <span class="k">return</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">INKMutexUnlock</span><span class="p">(</span><span class="n">sites_mutex</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">url_loc</span><span class="p">,</span> <span class="n">host</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>
+<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>done:
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_CONTINUE);
+}</p>
+<p>static void
+handle_response (INKHttpTxn txnp)
+{
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKMLoc url_loc;
+ char <em>url_str;
+ char </em>buf;
+ int url_length;</p>
+<div class="codehilite"><pre><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">INKHttpTxnClientRespGet</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 response 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">INKHttpHdrStatusSet</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_HTTP_STATUS_FORBIDDEN</span><span class="p">);</span>
+<span class="n">INKHttpHdrReasonSet</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">INKHttpHdrReasonLookup</span> <span class="p">(</span><span class="n">INK_HTTP_STATUS_FORBIDDEN</span><span class="p">),</span>
+ <span class="n">strlen</span> <span class="p">(</span><span class="n">INKHttpHdrReasonLookup</span> <span class="p">(</span><span class="n">INK_HTTP_STATUS_FORBIDDEN</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">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="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">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="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">url_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 request url\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">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">buf</span> <span class="o">=</span> <span class="p">(</span><span class="n">char</span> <span class="o">*</span><span class="p">)</span><span class="n">INKmalloc</span> <span class="p">(</span><span class="mi">4096</span><span class="p">);</span>
+
+<span class="n">url_str</span> <span class="o">=</span> <span class="n">INKUrlStringGet</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">&</span><span class="n">url_length</span><span class="p">);</span>
+<span class="nb">sprintf</span> <span class="p">(</span><span class="n">buf</span><span class="p">,</span> <span class="s">"You are forbidden from accessing \"%s\"\n"</span><span class="p">,</span> <span class="n">url_str</span><span class="p">);</span>
+<span class="n">INKfree</span> <span class="p">(</span><span class="n">url_str</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>
+<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">INKHttpTxnErrorBodySet</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">buf</span><span class="p">,</span> <span class="n">strlen</span> <span class="p">(</span><span class="n">buf</span><span class="p">),</span> <span class="n">NULL</span><span class="p">);</span>
+</pre></div>
+
+
+<p>done:
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_CONTINUE);
+}</p>
+<p>static void
+read_blacklist (void)
+{
+ char blacklist_file[1024];
+ INKFile file;</p>
+<div class="codehilite"><pre><span class="nb">sprintf</span> <span class="p">(</span><span class="n">blacklist_file</span><span class="p">,</span> <span class="s">"%s/blacklist.txt"</span><span class="p">,</span> <span class="n">INKPluginDirGet</span><span class="p">());</span>
+<span class="n">file</span> <span class="o">=</span> <span class="n">INKfopen</span><span class="p">(</span><span class="n">blacklist_file</span><span class="p">,</span> <span class="s">"r"</span><span class="p">);</span>
+
+<span class="n">INKMutexLock</span> <span class="p">(</span><span class="n">sites_mutex</span><span class="p">);</span>
+<span class="n">nsites</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">file</span> <span class="o">!=</span> <span class="n">NULL</span><span class="p">)</span> <span class="p">{</span>
+</pre></div>
+
+
+<p>char buffer[1024];</p>
+<p>while (INKfgets (file, buffer, sizeof(buffer)-1) != NULL &&
+ nsites < MAX_NSITES) {
+ char<em> eol;
+ if ((eol = strstr(buffer, "rn")) != NULL) {
+ /</em> To handle newlines on Windows <em>/
+ </em>eol = '0';
+ } else if ((eol = strchr(buffer, 'n')) != NULL) {
+ <em>eol = '0';
+ } else {
+ /</em> Not a valid line, skip it */
+ continue;
+ }
+ if (sites[nsites] != NULL) {
+ INKfree (sites[nsites]);
+ }
+ sites[nsites] = INKstrdup (buffer);
+ nsites++;
+ }</p>
+<p>INKfclose (file);
+ } else {
+ INKError ("unable to open %sn", blacklist_file);
+ INKError ("all sites will be allowedn", blacklist_file);
+ }</p>
+<div class="codehilite"><pre><span class="n">INKMutexUnlock</span> <span class="p">(</span><span class="n">sites_mutex</span><span class="p">);</span>
+</pre></div>
+
+
+<p>}</p>
+<p>static int
+blacklist_plugin (INKCont contp, INKEvent event, void *edata)
+{
+ INKHttpTxn txnp = (INKHttpTxn) edata;</p>
+<div class="codehilite"><pre><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_OS_DNS:</span>
+ <span class="n">handle_dns</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">contp</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">INK_EVENT_HTTP_SEND_RESPONSE_HDR:</span>
+ <span class="n">handle_response</span> <span class="p">(</span><span class="n">txnp</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">INK_EVENT_MGMT_UPDATE:</span>
+</pre></div>
+
+
+<p>read_blacklist ();
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+}</p>
+<p>int
+check_ts_version()
+{</p>
+<p>const char *ts_version = INKTrafficServerVersionGet();
+ int result = 0;</p>
+<p>if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;</p>
+<div class="codehilite"><pre> <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">"%d.%d.%d"</span><span class="p">,</span> <span class="o">&</span><span class="n">major_ts_version</span><span class="p">,</span>
+ <span class="o">&</span><span class="n">minor_ts_version</span><span class="p">,</span> <span class="o">&</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">/* Need at least TS 2.0 */</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">major_ts_version</span> <span class="o">>=</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>
+</pre></div>
+
+
+<p>}</p>
+<p>return result;
+}</p>
+<p>void
+INKPluginInit (int argc, const char *argv[])
+{
+ int i;
+ INKCont contp;
+ INKPluginRegistrationInfo info;
+ int error;</p>
+<div class="codehilite"><pre><span class="n">info</span><span class="o">.</span><span class="n">plugin_name</span> <span class="o">=</span> <span class="s">"blacklist-1"</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">"DsCompany"</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">"ts-api-support@DsCompany.com"</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">&</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">"Plugin registration failed.\n"</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>
+</pre></div>
+
+
+<p>INKError ("Plugin requires Traffic Server 2.0 or latern");
+ return;
+ }</p>
+<div class="codehilite"><pre><span class="sr">/* create an INKTextLogObject to log blacklisted requests to */</span>
+<span class="nb">log</span> <span class="o">=</span> <span class="n">INKTextLogObjectCreate</span><span class="p">(</span><span class="s">"blacklist"</span><span class="p">,</span> <span class="n">INK_LOG_MODE_ADD_TIMESTAMP</span><span class="p">,</span>
+ <span class="n">NULL</span><span class="p">,</span> <span class="o">&</span><span class="n">error</span><span class="p">);</span>
+<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nb">log</span><span class="p">)</span> <span class="p">{</span>
+</pre></div>
+
+
+<p>printf("Blacklist plugin: error %d while creating logn", error);
+ }</p>
+<div class="codehilite"><pre><span class="n">sites_mutex</span> <span class="o">=</span> <span class="n">INKMutexCreate</span> <span class="p">();</span>
+
+<span class="n">nsites</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">MAX_NSITES</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
+</pre></div>
+
+
+<p>sites[i] = NULL;
+ }</p>
+<div class="codehilite"><pre><span class="n">read_blacklist</span> <span class="p">();</span>
+
+<span class="n">contp</span> <span class="o">=</span> <span class="n">INKContCreate</span> <span class="p">(</span><span class="n">blacklist_plugin</span><span class="p">,</span> <span class="n">NULL</span><span class="p">);</span>
+
+<span class="n">INKHttpHookAdd</span> <span class="p">(</span><span class="n">INK_HTTP_OS_DNS_HOOK</span><span class="p">,</span> <span class="n">contp</span><span class="p">);</span>
+
+<span class="n">INKMgmtUpdateRegister</span> <span class="p">(</span><span class="n">contp</span><span class="p">,</span> <span class="s">"Super Blacklist Plugin"</span><span class="p">,</span> <span class="s">"blacklist.cgi"</span><span class="p">);</span>
+</pre></div>
+
+
+<p>}</p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/App_Troubleshooting.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/App_Troubleshooting.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/App_Troubleshooting.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/App_Troubleshooting.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,66 @@
<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="Dep_MutexFunctions">Prev</a> - Mutex Function
+Unable to Load Plugins - <a href="Trouble_LoadPlugins">Next</a></p>
+<h2 id="appendix_c_troubleshooting_tips">Appendix C. Troubleshooting Tips</h2>
+<p>This appendix lists the following troubleshooting tips.</p>
+<ul>
+<li>
+<p><a href="App_Troubleshooting#Trouble_CompilePlugins" title="Unable to Compile Plugins">Unable to Compile Plugins</a></p>
+</li>
+<li>
+<p><a href="Trouble_LoadPlugins" title="Unable to Load Plugins">Unable to Load Plugins</a></p>
+</li>
+<li>
+<p><a href="Trouble_DebugTags" title="Using Debug Tags">Using Debug Tags</a></p>
+</li>
+<li>
+<p><a href="Trouble_UsingDebugger" title="Using a Debugger">Using a Debugger</a></p>
+</li>
+<li>
+<p><a href="Trouble_DebugMemLeaks" title="Debugging Memory Leaks">Debugging Memory Leaks</a></p>
+</li>
+</ul>
+<h2 id="unable_to_compile_plugins">Unable to Compile Plugins</h2>
+<p>The process for compiling a shared library varies with the platform
+used, so the Traffic Server API includes <code>makefile</code> templates you
+can use to create shared libraries on all supported Traffic Server
+platforms.</p>
+<h3 id="unix_example">UNIX Example</h3>
+<p>Assuming the sample program is stored in the file <code>hello-world.c</code>,
+you could use the following commands to building a shared library
+on Solaris using the GNU C compiler.</p>
+<div class="codehilite"><pre><span class="n">gcc</span> <span class="o">-</span><span class="n">g</span> <span class="o">-</span><span class="n">Wall</span> <span class="o">-</span><span class="n">fPIC</span> <span class="o">-</span><span class="n">o</span> <span class="n">hello</span><span class="o">-</span><span class="n">world</span><span class="o">.</span><span class="n">o</span> <span class="o">-</span><span class="n">c</span> <span class="n">hello</span><span class="o">-</span><span class="n">world</span><span class="o">.</span><span class="n">c</span>
+<span class="n">gcc</span> <span class="o">-</span><span class="n">g</span> <span class="o">-</span><span class="n">Wall</span> <span class="o">-</span><span class="n">shared</span> <span class="o">-</span><span class="n">o</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="n">hello</span><span class="o">-</span><span class="n">world</span><span class="o">.</span><span class="n">o</span>
+</pre></div>
+
+
+<p>The first command compiles <code>hello-world.c</code>as Position Independent
+Code (PIC); the second command links the single<code>hello-world.o</code>
+object file into the <code>hello-world.so</code> shared library.</p>
+<p><img alt="[Caution]" src="images/docbook/caution.png" />
+Caution
+Make sure that your plugin is not statically linked with system
+libraries.</p>
+<h3 id="hpux_example">HPUX Example</h3>
+<p>Assuming the sample program is stored in the file <code>hello_world.c</code>,
+you could use the following commands to build a shared library on
+HPUX:</p>
+<div class="codehilite"><pre><span class="n">cc</span> <span class="o">+</span><span class="n">z</span> <span class="o">-</span><span class="n">o</span> <span class="n">hello_world</span><span class="o">.</span><span class="n">o</span> <span class="o">-</span><span class="n">c</span> <span class="n">hello_world</span><span class="o">.</span><span class="n">c</span>
+<span class="n">ld</span> <span class="o">-</span><span class="n">b</span> <span class="o">-</span><span class="n">o</span> <span class="n">hello_world</span><span class="o">.</span><span class="n">so</span> <span class="n">hello_world</span><span class="o">.</span><span class="n">o</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/AppendTransformPlugin.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/AppendTransformPlugin.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/AppendTransformPlugin.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/AppendTransformPlugin.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,161 @@
<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="SampleNullTransformPlugin">Prev</a> - The Sample Null Transform
+Plugin
+The Sample Buffered Null Transform Plugin -
+<a href="SampleBufferedNullTransformPlugin">Next</a></p>
+<h2 id="the_append-transform_plugin">The Append-Transform Plugin</h2>
+<p>The append-transform plugin appends text to the body of an HTTP
+response. It obtains this text from a file; the name of the file
+containing the append text is a parameter you specify in
+<code>plugin.config</code>, as follows:</p>
+<div class="codehilite"><pre><span class="n">append</span><span class="o">-</span><span class="n">transform</span><span class="o">.</span><span class="n">so</span> <span class="n">path</span><span class="sr">/to/</span><span class="n">file</span>
+</pre></div>
+
+
+<p>The append-transform plugin is based on <code>null-transform.c</code>. The
+only difference is that after the plugin feeds the document through
+the transformation, it adds text to the response.</p>
+<p>Below is a list of the functions in <code>append-transform.c</code>, in the
+order they appear in the source code. Below each entry is a
+description of what the function does:</p>
+<ul>
+<li>
+<p><code><b>my_data_alloc</b></code></p>
+<p>Allocates and initializes a <code>MyData</code> structure. The plugin defines
+a struct, <code>MyData</code>, as follows:</p>
+<div class="codehilite"><pre> <span class="n">typedef</span> <span class="n">struct</span> <span class="p">{</span>
+ <span class="n">INKVIO</span> <span class="n">output_vio</span><span class="p">;</span>
+ <span class="n">INKIOBuffer</span> <span class="n">output_buffer</span><span class="p">;</span>
+ <span class="n">INKIOBufferReader</span> <span class="n">output_reader</span><span class="p">;</span>
+ <span class="nb">int</span> <span class="n">append_needed</span><span class="p">;</span>
+ <span class="p">}</span> <span class="n">MyData</span><span class="p">;</span>
+</pre></div>
+
+
+<p>The <code>MyData</code> structure is used to represent data that the
+transformation (vconnection) needs. The transformation's data
+pointer is set to a <code>MyData</code> pointer using <code>INKContDataSet</code> in the
+<code>handle_transform</code> routine.</p>
+</li>
+<li>
+<p><code><b>my_data_destroy</b></code></p>
+<p>Destroys objects of type <code>MyData</code>. To deallocate the transform's
+data, the <code>append_transform</code> routine (see below) calls
+<code>my_data_destroy</code> when the transformation is complete.</p>
+</li>
+<li>
+<p><code><b>handle_transform</b></code></p>
+<p>This function does the actual data transformation. The
+transformation is created in <code>transform_add</code> (see below).
+<code>handle_transform</code> is called by <code>append_transform</code>.</p>
+</li>
+<li>
+<p><code><b>append_transform</b></code></p>
+<p>This is the handler function for the transformation vconnection
+created in <code>transform_add</code>. It is the implementation of the
+vconnection.</p>
+<ul>
+<li>
+<p>If the transformation vconnection has been closed, then
+ <code>append_transform</code> calls <code>my_data_destroy</code> to destroy the
+ vonnection.</p>
+</li>
+<li>
+<p>If <code>append_transform</code> receives an error event, then it calls
+ back the continuation to let it know it has completed the write
+ operation.</p>
+</li>
+<li>
+<p>If it receives a <code>WRITE_COMPLETE</code> event, then it shuts down the
+ write portion of its vconnection.</p>
+</li>
+<li>
+<p>If it receives a <code>WRITE_READY</code> or any other event (such as
+ <code>INK_HTTP_RESPONSE_TRANSFORM_HOOK</code>), then it calls
+ <code>handle_transform</code> to attempt to transform more data.</p>
+</li>
+</ul>
+</li>
+<li>
+<p><code><b>transformable</b></code></p>
+<p>The plugin transforms only documents that have a content type of
+<code>text/html</code>. This function examines the <code>Content-Type</code> MIME header
+field in the response header. If the value of the MIME field is
+<code>text/html</code>, then the function returns 1; otherwise, it returns
+zero.</p>
+</li>
+<li>
+<p><code><b>transform_add</b></code></p>
+<p>Creates the transformation for the current transaction and sets up
+a transformation hook. The handler function for the transformation
+is <code>append_transform</code>.</p>
+</li>
+<li>
+<p><code><b>transform_plugin</b></code></p>
+<p>This is the handler function for the main continuation for the
+plugin. Traffic Server calls this function whenever it reads an
+HTTP response header. <code>transform_plugin</code> does the following:</p>
+<ul>
+<li>
+<p>Gets a handle to the HTTP transaction being processed</p>
+</li>
+<li>
+<p>Calls <code>transformable</code> to determine whether the response
+ document content is of type <code>text/html</code></p>
+</li>
+<li>
+<p>If the content is transformable, then it calls <code>transform_add</code>
+ to create the transformation.</p>
+</li>
+<li>
+<p>Calls <code>INKHttpTxnReenable</code> to continue the transaction</p>
+</li>
+</ul>
+</li>
+<li>
+<p><code><b>load</b></code></p>
+<p>Opens the file containing the text to be appended and loads the
+contents of the file into an <code>INKIOBuffer</code> called <code>append_buffer</code>.</p>
+</li>
+<li>
+<p><code><b>INKPluginInit</b></code></p>
+<p>Does the following:</p>
+<ul>
+<li>
+<p>Checks to make sure that the required configuration information
+ (the append text filename) is entered in <code>plugin.config</code>
+ correctly.</p>
+</li>
+<li>
+<p>If there is a filename, then <code>INKPluginInit</code> calls load to load
+ the text.</p>
+</li>
+<li>
+<p>Creates a continuation for the plugin. The handler for this
+ continuation is <code>transform_plugin</code>.</p>
+</li>
+<li>
+<p>Adds the plugin's continuation to
+ <code>INK_HTTP_READ_RESPONSE_HDR_HOOK</code>. In other words, it sets up a
+ callback of the plugin's continuation when Traffic Server reads
+ HTTP response headers.</p>
+</li>
+</ul>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/BasicAuthorizatonPlugin.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/BasicAuthorizatonPlugin.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/BasicAuthorizatonPlugin.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/BasicAuthorizatonPlugin.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="WorkWHTTPHeaderFunc">Prev</a> - Working with HTTP Header
+Functions
+Implementing the Handler and Getting a Handle to the Transaction -
+<a href="ImplementHandler_GetTransHandle">Next</a></p>
+<h2 id="the_basic_authorization_plugin">The Basic Authorization Plugin</h2>
+<p>The sample basic authorization plugin, <code>basic-auth.c</code>, checks for
+basic HTTP proxy authorization. In HTTP basic proxy authorization,
+client user names and passwords are contained in the
+<code>Proxy-Authorization</code> header. The password is encoded using base64
+encoding. The plugin checks all incoming requests for the
+authorization header, user name, and password. If the plugin does
+not find all of the these, then it reenables with an error
+(effectively stopping the transaction) and adds a transaction hook
+to the send response header event.</p>
+<h3 id="creating_the_plugins_parent_continuation_and_global_hook">Creating the Plugin's Parent Continuation and Global Hook</h3>
+<p>The parent continuation and global hook are created as follows:</p>
+<div class="codehilite"><pre><span class="n">INKHttpHookAdd</span> <span class="p">(</span><span class="n">INK_HTTP_OS_DNS_HOOK</span><span class="p">,</span> <span class="n">INKContCreate</span> <span class="p">(</span><span class="n">auth_plugin</span><span class="p">,</span> <span class="n">NULL</span><span class="p">));</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/BlacklistPlugin.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/BlacklistPlugin.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/BlacklistPlugin.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/BlacklistPlugin.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,101 @@
<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="HeaderBasedPluginEx">Prev</a> - Chapter 4. Header-Based Plugin
+Examples
+Setting a Global Hook - <a href="SettingGlobalHook">Next</a></p>
+<h2 id="the_blacklist_plugin">The Blacklist Plugin</h2>
+<p>The sample blacklisting plugin included in the Traffic Server SDK
+is <code>blacklist_1.c</code>. This plugin checks every incoming HTTP client
+request against a list of blacklisted web sites. If the client
+requests a blacklisted site, then the plugin returns an
+<code>Access forbidden</code> message to the client.</p>
+<p>The flow of HTTP processing with the blacklist plugin is
+illustrated in the figure titled
+<a href="CreatingTSPlugins#Fig_BlacklistPlugin" title="Figure 2.5. Blacklist Plugin">"Blacklist Plugin"</a>.
+This example also contains a simple configuration management
+interface. It can read a list of blacklisted sites from a file
+(<code>blacklist.txt</code>) that can be updated by a Traffic Server
+administrator. When the configuration file is updated, Traffic
+Server sends an event to the plugin that wakes it up to do some
+work.</p>
+<h3 id="creating_the_parent_continuation">Creating the Parent Continuation</h3>
+<p>You create the static parent continuation in the mandatory
+<code>INKPluginInit</code> function. This parent continuation effectively
+<strong>is</strong> the plugin: the plugin does work when this continuation
+receives an event from Traffic Server. Traffic Server passes the
+event as an argument to the continuation's handler function. When
+you create continuations, you must create and specify their handler
+functions.</p>
+<p>You can specify an optional mutex lock when you create
+continuations. The mutex lock protects data shared by asynchronous
+processes. Because Traffic Server has a multi-threaded design, race
+conditions can occur if several threads try to access the same
+continuation's data.</p>
+<p>Here is how the static parent continuation is created in
+<code>blacklist-1.c</code></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="o">...</span>
+ <span class="n">INKCont</span> <span class="n">contp</span><span class="p">;</span>
+
+ <span class="n">contp</span> <span class="o">=</span> <span class="n">INKContCreate</span> <span class="p">(</span><span class="n">blacklist_plugin</span><span class="p">,</span> <span class="n">NULL</span><span class="p">);</span>
+<span class="o">...</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>:</p>
+<p>The handler function for the plugin is <code>blacklist_plugin</code>, and the
+mutex is null. The continuation handler function's job is to handle
+the events that are sent to it; accordingly, the <code>blacklist_plugin</code>
+routine consists of a switch statement that covers each of the
+events that might be sent to it:</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="nb">int</span>
+<span class="n">blacklist_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_OS_DNS:</span>
+ <span class="n">handle_dns</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">contp</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_HTTP_SEND_RESPONSE_HDR:</span>
+ <span class="n">handle_response</span> <span class="p">(</span><span class="n">txnp</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_MGMT_UPDATE:</span>
+ <span class="n">read_blacklist</span> <span class="p">();</span>
+ <span class="k">return</span> <span class="mi">0</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>When you write handler functions, you have to anticipate any events
+that might be sent to the handler by hooks or by other functions.
+In the Blacklist plugin, <code>INK_EVENT_OS_DNS</code> is sent because of the
+global hook established in <code>INKPluginInit</code>,
+<code>INK_EVENT_HTTP_SEND_RESPONSE_HDR</code> is sent because the plugin
+contains a transaction hook (see
+<a href="SettingUpTransacHook" title="Setting Up a Transaction Hook">Setting Up a Transaction Hook</a>),
+and <code>INK_EVENT_MGMT_UPDATE</code> is sent by Traffic Manager whenever
+there is a configuration change (see
+<a href="SettingUpUIUpdateCallbacks" title="Setting Up UI Update Callbacks">Setting Up UI Update Callbacks</a>).
+It is good practice to have a default case in your switch
+statements.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheAPI.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheAPI.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheAPI.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheAPI.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,57 @@
<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="IOBuffers_IO">Prev</a> - IO Buffers
+How to Do a Cache Write - <a href="DoACacheWrite">Next</a></p>
+<h2 id="guide_to_the_cache_api">Guide to the Cache API</h2>
+<p>The cache API enables plugins to read, write, and remove objects in
+the Traffic Server cache. All cache APIs are keyed by an object
+called an <code>INKCacheKey</code>; cache keys are created via
+<code>INKCacheKeyCreate</code>; keys are destroyed via <code>INKCacheKeyDestroy</code>.
+Use <code>INKCacheKeyDigestSet</code> to set the hash of the cache key.</p>
+<p>Note that the cache APIs differentiate between HTTP data and plugin
+data. The cache APIs do not allow you to write HTTP docs in the
+cache; you can only write plugin-specific data (a specific type of
+data that differs from the HTTP type).</p>
+<p><strong>Example:</strong></p>
+<div class="codehilite"><pre> <span class="n">const</span> <span class="n">unsigned</span> <span class="n">char</span> <span class="o">*</span><span class="n">key_name</span> <span class="o">=</span> <span class="s">"example key name"</span><span class="p">;</span>
+
+ <span class="n">INKCacheKey</span> <span class="n">key</span><span class="p">;</span>
+ <span class="n">INKCacheKeyCreate</span> <span class="p">(</span><span class="o">&</span><span class="n">key</span><span class="p">);</span>
+ <span class="n">INKCacheKeyDigestSet</span> <span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="p">(</span><span class="n">unsigned</span> <span class="n">char</span> <span class="o">*</span><span class="p">)</span> <span class="n">key_name</span> <span class="p">,</span> <span class="n">strlen</span><span class="p">(</span><span class="n">key_name</span><span class="p">));</span>
+ <span class="n">INKCacheKeyDestroy</span> <span class="p">(</span><span class="n">key</span><span class="p">);</span>
+</pre></div>
+
+
+<h3 id="how_to_do_a_cache_read">How to Do a Cache Read</h3>
+<p><code>INKCacheRead</code> does not really read - it is used for lookups (see
+the sample Protocol plugin). Possible callback events include:</p>
+<ul>
+<li>
+<p><code>INK_EVENT_CACHE_OPEN_READ</code> - indicates the lookup was
+ successful. The data passed back along with this event is a cache
+ vconnection that can be used to initiate a read on this keyed
+ data.</p>
+</li>
+<li>
+<p><code>INK_EVENT_CACHE_OPEN_READ_FAILED</code> - indicates the lookup was
+ unsuccessful. Reasons for this event could be that another
+ continuation is writing to that cache location, or the cache key
+ doesn't refer to a cached resource. Data payload for this event
+ indicates the possible reason the read failed (<code>INKCacheError</code>).</p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheAPI_Example.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheAPI_Example.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheAPI_Example.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheAPI_Example.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,73 @@
<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="Errors_Cache">Prev</a> - Errors
+Chapter 16. Plugin Management - <a href="PluginManagement">Next</a></p>
+<h3 id="example">Example</h3>
+<p>In the example below, suppose there is a cache hit and the cache
+returns a vconnection that enables you to read the document from
+cache. To do this, you need to prepare a buffer (<code>cache_bufp</code>) to
+hold the document; meanwhile, use <code>INKVConnCachedObjectSizeGet</code> to
+find out the actual size of the document (<code>content_length</code>). Then,
+issue <code>INKVConnRead</code> to read the document with the total data
+length required as <code>content_length</code>. Assume the following data:</p>
+<div class="codehilite"><pre> <span class="n">INKIOBuffer</span> <span class="n">cache_bufp</span> <span class="o">=</span> <span class="n">INKIOBufferCreate</span> <span class="p">();</span>
+ <span class="n">INKIOBufferReader</span> <span class="n">cache_readerp</span> <span class="o">=</span> <span class="n">INKIOBufferReaderAlloc</span> <span class="p">(</span><span class="n">out_bufp</span><span class="p">);</span>
+ <span class="n">INKVConn</span> <span class="n">cache_vconnp</span> <span class="o">=</span> <span class="n">NULL</span><span class="p">;</span>
+ <span class="n">INKVIO</span> <span class="n">cache_vio</span> <span class="o">=</span> <span class="n">NULL</span><span class="p">;</span>
+ <span class="nb">int</span> <span class="n">content_length</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+
+
+<p>In the <code>INK_CACHE_OPEN_READ</code> handler:</p>
+<div class="codehilite"><pre><span class="n">cache_vconnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">INKVConn</span><span class="p">)</span> <span class="n">data</span><span class="p">;</span>
+ <span class="n">INKVConnCachedObjectSizeGet</span> <span class="p">(</span><span class="n">cache_vconnp</span><span class="p">,</span> <span class="o">&</span><span class="n">content_length</span><span class="p">);</span>
+ <span class="n">cache_vio</span> <span class="o">=</span> <span class="n">INKVConnRead</span> <span class="p">(</span><span class="n">cache_vconn</span><span class="p">,</span> <span class="n">contp</span><span class="p">,</span> <span class="n">cache_bufp</span><span class="p">,</span> <span class="n">content_length</span><span class="p">);</span>
+</pre></div>
+
+
+<p>In the <code>INK_EVENT_VCONN_READ_READY</code> handler:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">usual</span> <span class="n">VCONN_READ_READY</span> <span class="n">handler</span> <span class="n">logic</span><span class="p">)</span>
+<span class="nb">int</span> <span class="n">nbytes</span> <span class="o">=</span> <span class="n">INKVIONBytesGet</span> <span class="p">(</span><span class="n">cache_vio</span><span class="p">);</span>
+<span class="nb">int</span> <span class="n">ntodo</span> <span class="o">=</span> <span class="n">INKVIONTodoGet</span> <span class="p">(</span><span class="n">cache_vio</span><span class="p">);</span>
+<span class="nb">int</span> <span class="n">ndone</span> <span class="o">=</span> <span class="n">INKVIONDoneGet</span> <span class="p">(</span><span class="n">cache_vio</span><span class="p">);</span>
+<span class="p">(</span><span class="n">consume</span> <span class="n">data</span> <span class="n">in</span> <span class="n">cache_bufp</span><span class="p">)</span>
+<span class="n">INKVIOReenable</span> <span class="p">(</span><span class="n">cache_vio</span><span class="p">);</span>
+</pre></div>
+
+
+<p>Do not try to get continuations or VIOs from <code>INKVConn</code> objects for
+cache vconnections. Also note that the following APIs can only be
+used on transformation vconnections and must not be used on cache
+vconnections or net vconnections:</p>
+<ul>
+<li>
+<p><code>INKVConnWriteVIOGet</code></p>
+</li>
+<li>
+<p><code>INKVConnReadVIOGet</code></p>
+</li>
+<li>
+<p><code>INKVConnClosedGet</code></p>
+</li>
+</ul>
+<p>APIs such as <code>INKVConnRead</code>, <code>INKVConnWrite</code>, <code>INKVConnClose</code>,
+<code>INKVConnAbort</code>, and <code>INKVConnShutdown</code> can be used on any kind of
+vconnections.</p>
+<p>When you are finished:</p>
+<div class="codehilite"><pre><span class="n">INKCacheKeyDestroy</span> <span class="p">(</span><span class="n">key</span><span class="p">);</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheInterfaceFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheInterfaceFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheInterfaceFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/CacheInterfaceFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,63 @@
<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="INKNetVConnRemotePortGet">Prev</a> - INKNetVConnRemotePortGet
+INKCacheKeyDigestSet - <a href="INKCacheKeyDigestSet">Next</a></p>
+<h2 id="cache_interface_functions">Cache Interface Functions</h2>
+<hr />
+<p><a href="CacheInterfaceFunctions#INKCacheKeyCreate">INKCacheKeyCreate</a>
+<a href="CacheInterfaceFunctions#INKSetCacheUrl">INKSetCacheUrl</a>
+<a href="INKCacheKeyDigestSet">INKCacheKeyDigestSet</a>
+<a href="INKCacheKeyHostNameSet">INKCacheKeyHostNameSet</a>
+<a href="INKCacheKeyDestroy">INKCacheKeyDestroy</a>
+<a href="INKCacheRead">INKCacheRead</a>
+<a href="INKCacheReady">INKCacheReady</a>
+<a href="INKCacheWrite">INKCacheWrite</a>
+<a href="INKCacheRemove">INKCacheRemove</a>
+<a href="INKCacheKeyPinnedSet">INKCacheKeyPinnedSet</a>
+<a href="INKVConnCacheObjectSizeGet">INKVConnCacheObjectSizeGet</a></p>
+<h3 id="inkcachekeycreate">INKCacheKeyCreate</h3>
+<p>Creates a new cache key that will be assigned to an object to be
+cached.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKCacheKeyCreate (InkCacheKey *<em class="replaceable"><code>new_key</code>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCacheKey *``<em class="replaceable"><code>new_key</code>
+ is set to the allocated key.</p>
+<p><strong>Description</strong>
+ ~ Creates (allocates memory for) a new cache key. The key can
+ then be generated and assigned to an object using
+ <code>INKCacheKeyDigestSet</code>.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">key</span> <span class="n">could</span> <span class="ow">not</span> <span class="n">be</span> <span class="n">allocated</span><span class="o">.</span>
+</pre></div>
+
+
+<h3 id="inksetcacheurl">INKSetCacheUrl</h3>
+<p>This is an API to set the cache URL. This will be the URL for the
+cached object.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKSetCacheUrl (INKHttpTxn <span class="replaceable">txnp</span>, const char *<span class="replaceable">url</span>)</code></p>
+<p><strong>Arguments</strong>
+ ~ The URL for the cached object will be set
+ to<code><span class="replaceable"> url</span></code>.</p>
+<p><strong>Example</strong>
+ ~ INKHttpTxn txnp = (INKHttpTxn)edata;
+ if (INKSetCacheUrl(txnp, "http://www.yahoo.com") != INK_SUCCESS) {
+ // ERROR
+ }</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ConceptIndex.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ConceptIndex.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ConceptIndex.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ConceptIndex.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,133 @@
<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="TypeIndex">Prev</a> - Appendix E. Type Index</p>
+<h2 id="index">Index</h2>
+<h3 id="c">C</h3>
+<p>compiling on HPUX,
+<a href="ASimplePlugin#Compiling_HPUX">HPUX Example</a>
+compiling on UNIX,
+<a href="ASimplePlugin#Compiling_Unix">UNIX Example</a>
+compiling plugins, examples,
+<a href="ASimplePlugin#CompilingYourPlugin">Compile Your Plugin</a></p>
+<h3 id="d">D</h3>
+<p>deprecated functions,
+<a href="DeprecatedMarshBufFuncs">Deprecated Functions</a>
+duplicate MIME fields,
+<a href="DuplicateMIMEFlds">Duplicate MIME Fields Are Not Coalesced</a></p>
+<h3 id="g">G</h3>
+<p>global hook, <a href="SettingGlobalHook">Setting a Global Hook</a>
+global HTTP hooks, <a href="AddingHooks">Adding Hooks</a></p>
+<h3 id="h">H</h3>
+<p><code>hello-world</code> example, <a href="ASimplePlugin">A Simple Plugin</a>
+HTTP header, <a href="MIMEHeaders">MIME Headers</a>
+HTTP session, <a href="HTTPSessions">HTTP Sessions</a>
+HTTP transaction, <a href="HTTPSessions">HTTP Sessions</a></p>
+<h3 id="i">I</h3>
+<p><code>INKEventFunc</code>,
+<a href="AccessingTransactionProc">Accessing the Transaction Being Processed</a>
+<code>INKHttpAltInfo</code>,
+<a href="HTTPAlternateSelection">HTTP Alternate Selection</a>
+<code>INKHttpTxn</code>,
+<a href="AccessingTransactionProc">Accessing the Transaction Being Processed</a>,
+<a href="HTTP_Transactions">HTTP Transactions</a>
+<code>INKMBufferCreate</code>, <a href="HTTPHeaders2">HTTP Headers</a>
+<code>INKVIO</code>, <a href="HTTPTransformationPlugins#VIOs">VIOs</a>
+<code>INK_HTTP_RESPONSE_TRANSFORM_HOOK</code>,
+<a href="AppendTransformPlugin">The Append-Transform Plugin</a>
+<code>INK_HTTP_SSN_CLOSE_HOOK</code>, <a href="HTTPSessions">HTTP Sessions</a>
+<code>INK_HTTP_SSN_START_HOOK</code>, <a href="HTTPSessions">HTTP Sessions</a>
+<code>INK_LOG_MODE_ADD_TIMESTAMP</code>,
+<a href="App_SampleSourceCode#Sample_blacklist-1.c"><code>blacklist-1.c</code></a>
+<code>INT_MAX</code>,
+<a href="IOGuide#VconnectionUsersView">The vconnection user's view</a></p>
+<h3 id="l">L</h3>
+<p>lock, <a href="MutexGuide#Mutexes">Mutexes</a></p>
+<h3 id="m">M</h3>
+<p>memory leak
+in transformation plugins,
+<a href="Transformations_IO#TransformVconnection">Transformation VConnection</a>
+method (HTTP),
+<a href="HTTPHeaders#AboutHTTPHeaders">About HTTP Headers</a>
+MIME field,
+<a href="HTTPHeaders#AboutHTTPHeaders">About HTTP Headers</a>,
+<a href="MIMEHeaders">MIME Headers</a>
+MIME field name, <a href="MIMEHeaders">MIME Headers</a>
+MIME field value, <a href="MIMEHeaders">MIME Headers</a>
+MIME fields,
+<a href="MIMEFldsBelongAssocMIMEHdr">MIME Fields Always Belong to an Associated MIME Header</a>
+MIME header,
+<a href="HTTPHeaders#AboutHTTPHeaders">About HTTP Headers</a>,
+<a href="MIMEHeaders">MIME Headers</a>
+Backus-Naur form, <a href="MIMEHeaders">MIME Headers</a>
+multiple plugins,
+<a href="Updatingplugin.configFile">Update the plugin.config File</a>
+mutexes, <a href="MutexGuide#Mutexes">Mutexes</a></p>
+<h3 id="n">N</h3>
+<p>new MIME field functions,
+<a href="MIMEFldsBelongAssocMIMEHdr">MIME Fields Always Belong to an Associated MIME Header</a>
+null-terminated strings,
+<a href="GuideTSHTTPHdrSyst#NoNullTerminatedStrings">No Null-Terminated Strings</a></p>
+<h3 id="p">P</h3>
+<p>parent continuation,
+<a href="BlacklistPlugin#CreatingParentContinuation">Creating the Parent Continuation</a>
+parent <code>INKMLoc</code>,
+<a href="RlsMarshalBufHandles">Release Marshal Buffer Handles</a>
+parent MIME header,
+<a href="MIMEFldsBelongAssocMIMEHdr">MIME Fields Always Belong to an Associated MIME Header</a>
+<code>plugin.config</code>,
+<a href="GetingStarted#PluginConfiguration">Plugin Configuration</a></p>
+<h3 id="r">R</h3>
+<p>read VIO,
+<a href="HTTPTransformationPlugins#WritingContentTransformPlugins">Writing Content Transform Plugins</a>
+releasing mbuffer handles,
+<a href="RlsMarshalBufHandles">Release Marshal Buffer Handles</a></p>
+<h3 id="s">S</h3>
+<p>sample code
+<code>INKPluginRegister</code>,
+<a href="PlusingRegisAndVersionCkg">Plugin Registration and Version Checking</a>
+version check,
+<a href="PlusingRegisAndVersionCkg">Plugin Registration and Version Checking</a>
+statistics
+viewing,
+<a href="ViewStatsUsingTrafLine">Viewing Statistics Using Traffic Line</a></p>
+<h3 id="t">T</h3>
+<p>thread locking, <a href="MutexGuide#Mutexes">Mutexes</a>
+Traffic Edge,
+<a href="PlusingRegisAndVersionCkg">Plugin Registration and Version Checking</a>
+Traffic Line,
+<a href="ViewStatsUsingTrafLine">Viewing Statistics Using Traffic Line</a>
+Traffic Server,
+<a href="PlusingRegisAndVersionCkg">Plugin Registration and Version Checking</a>
+transaction,
+<a href="AccessingTransactionProc">Accessing the Transaction Being Processed</a>
+getting a handle to,
+<a href="AccessingTransactionProc">Accessing the Transaction Being Processed</a>
+transaction hook,
+<a href="SettingUpTransacHook">Setting Up a Transaction Hook</a>
+transformation,
+<a href="HTTPTransformationPlugins#WritingContentTransformPlugins">Writing Content Transform Plugins</a></p>
+<h3 id="v">V</h3>
+<p>vconnection,
+<a href="HTTPTransformationPlugins#WritingContentTransformPlugins">Writing Content Transform Plugins</a>
+version checking,
+<a href="PlusingRegisAndVersionCkg">Plugin Registration and Version Checking</a>
+VIO,
+<a href="HTTPTransformationPlugins#WritingContentTransformPlugins">Writing Content Transform Plugins</a></p>
+<h3 id="w">W</h3>
+<p>write VIO,
+<a href="HTTPTransformationPlugins#WritingContentTransformPlugins">Writing Content Transform Plugins</a></p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ContinuationFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ContinuationFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ContinuationFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ContinuationFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,42 @@
<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="INKMutexUnlock">Prev</a> - INKMutexUnlock
+INKContCreate - <a href="INKContCreate">Next</a></p>
+<h2 id="continuation_functions">Continuation Functions</h2>
+<hr />
+<p><a href="ContinuationFunctions#INKContCall">INKContCall</a>
+<a href="INKContCreate">INKContCreate</a>
+<a href="INKContDataGet">INKContDataGet</a>
+<a href="INKContDataSet">INKContDataSet</a>
+<a href="INKContDestroy">INKContDestroy</a>
+<a href="INKContMutexGet">INKContMutexGet</a>
+<a href="INKContSchedule">INKContSchedule</a></p>
+<h3 id="inkcontcall">INKContCall</h3>
+<p>Calls a continuation.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int INKContCall (INKCont <em class="replaceable"><code>contp</code>,
+ INKEvent <em><code>event</code></em>, void *<em><code>edata</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Sends <code><em class="replaceable"><code>event</code> and
+ <code><em class="replaceable"><code>edata</code> to the
+ <code><em class="replaceable"><code>contp</code>'s handler function. It is an
+ error to call a continuation without holding the continuation's
+ lock.</p>
+<p><strong>Returns</strong>
+ ~ The values returned by the continuation <code>contp</code> event
+ handler.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Continuations.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Continuations.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Continuations.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Continuations.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,134 @@
<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="MutexGuide">Prev</a> - Chapter 11. Mutex Guide
+How to Activate Continuations - <a href="ActivateContinuations">Next</a></p>
+<h2 id="chapter_12_continuations">Chapter 12. Continuations</h2>
+<p><strong>Table of Contents</strong></p>
+<p><a href="Continuations#MutexesAndData">Mutexes and Data</a>
+<a href="ActivateContinuations">How to Activate Continuations</a>
+<a href="WritingHandlerFunctions">Writing Handler Functions</a>
+The continuation interface is Traffic Server's basic callback
+mechanism. <strong>Continuations</strong> are instances of the opaque data type
+<code>INKCont</code>. In its basic form, a continuation represents a handler
+function and a mutex.</p>
+<p>This chapter covers the following topics:</p>
+<ul>
+<li>
+<p><a href="Continuations#MutexesAndData" title="Mutexes and Data">Mutexes and Data</a></p>
+</li>
+<li>
+<p><a href="ActivateContinuations" title="How to Activate Continuations">How to Activate Continuations</a></p>
+</li>
+<li>
+<p><a href="WritingHandlerFunctions">Writing Handler Functions</a></p>
+</li>
+</ul>
+<h2 id="mutexes_and_data">Mutexes and Data</h2>
+<p>A continuation must be created with a mutex if your continuation
+does one of the following:</p>
+<ul>
+<li>
+<p>is registered globally (<code>INKHttpHookAdd</code> or
+ <code>INKHttpSsnHookAdd</code>) to an HTTP hook and uses <code>INKContDataSet/Get</code></p>
+</li>
+<li>
+<p>is registered locally (<code>INKHttpTxnHookAdd</code>), but for multiple
+ transactions uses <code>INKContDataSet/Get</code></p>
+</li>
+<li>
+<p>uses <code>INKCacheXXX</code>, <code>INKNetXXX</code>, <code>INKHostLookup</code>, or
+ <code>INKContSchedule</code> APIs</p>
+</li>
+</ul>
+<p>Before being activated, a caller must grab the continuation's
+mutex. This requirement makes it possible for a continuation's
+handler function to safely access its data and to prevent multiple
+callers from running it at the same time (see the
+<a href="NewProtocolPlugins#AboutSampleProtocol">sample Protocol plugin</a>
+for usage). The data protected by the mutex is any global or
+continuation data associated to the continuation by
+<code>INKContDataSet</code>. This does not include the local data created by
+the continuation handler function. A typical example of
+continuations created with associated data structures and mutexes
+is the transaction state machine created in the sample Protocol
+plugin (see
+<a href="NewProtocolPlugins#ImplementTransStMachine" title="One Way to Implement a Transaction State Machine">One Way to Implement a Transaction State Machine</a>).</p>
+<p>A reentrant call occurs when the continuation passed as an argument
+to the API can be called in the same stack trace as the function
+calling the API. For example, if you call <code>INKCacheRead</code>
+(<code>contp, mykey</code>), it is possible that <code>contp</code>'s handler will be
+called directly and then <code>INKCacheRead</code> returns.</p>
+<p>Caveats that could cause issues include the following:</p>
+<ul>
+<li>
+<p>a continuation has data associated with it (<code>INKContDataGet</code>).</p>
+</li>
+<li>
+<p>the reentrant call passes itself as a continuation to the
+ reentrant API. In this case, the continuation should not try to
+ access its data after calling the reentrant API. The reason for
+ this is that data may be modified by the section of code in the
+ continuation's handler that handles the event sent by the API. It
+ is recommended that you always return after a reentrant call to
+ avoid accessing something that has been deallocated.</p>
+</li>
+</ul>
+<p>Below is an example, followed by an explanation.</p>
+<div class="codehilite"><pre><span class="n">continuation_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="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">event1:</span>
+ <span class="n">INKReentrantCall</span> <span class="p">(</span><span class="n">contp</span><span class="p">);</span>
+ <span class="sr">/* Return right away after this call */</span>
+ <span class="n">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="n">event2:</span>
+ <span class="n">INKContDestroy</span> <span class="p">(</span><span class="n">contp</span><span class="p">);</span>
+ <span class="n">break</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The above example first assumes that the continuation is called
+back with <code>event1</code>; it then does the first reentrant call that
+schedules the continuation to receive <code>event2</code>. Because the call is
+reentrant, the processor calls back the continuation right away
+with <code>event2</code> and the continuation is destroyed. If you try to
+access the continuation or one of its members after the reentrant
+call, then you might access something that has been deallocated. To
+avoid accessing something that has been deallocated, never access
+the continuation or any of its members after a reentrant call -
+just exit the handler.</p>
+<p><strong>Note:</strong> Most HTTP transaction plugin continuations do not need
+non-null mutexes because they're called within the processing of an
+HTTP transaction, and therefore have the transaction's mutex.</p>
+<p>It is also possible to specify a continuation's mutex as <code>NULL</code>.
+This should be done only when registering a continuation to a
+global hook, by a call to <code>INKHttpHookAdd</code>. In this case, the
+continuation can be called simultaneously by different instances of
+HTTP SM running on different threads. Having a mutex here would
+slow and/or hinder Traffic Server performance, since all the
+threads will try to lock the same mutex. The drawback of not having
+a mutex is that such a continuation cannot have data associated
+with it (i.e., <code>INKContDataGet/Set</code> cannot be used).</p>
+<p>When using a <code>NULL</code> mutex it is dangerous to access the
+continuation's data, but usually continuations with <code>NULL</code> mutexes
+have no data associated with them anyway. An example of such a
+continuation is one that gets called back every time an HTTP
+request is read, and then determines from the request alone if the
+request should go through or be rejected. An HTTP transaction gives
+its continuation data to the <code>contp</code>.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Conventions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Conventions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Conventions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Conventions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,33 @@
<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="pr01s02">Prev</a> - How to Use This Book
+Chapter 1. Getting Started - <a href="GetingStarted">Next</a></p>
+<h2 id="typographical_conventions">Typographical Conventions</h2>
+<p>This document uses the following typographic conventions:</p>
+<p><strong>Table 1. Typographical Conventions</strong></p>
+<p>Convention
+Purpose
+<em>italics</em> or<strong>bold</strong>
+Used to introduce terms.
+<code>monospaced face</code>
+Represents C language statements, commands, file content, and
+computer output.
+<code><em class="replaceable"><code>monospaced italic</code>
+Represents variables for which you should substitute a value.
+<code>...</code> (ellipsis)
+Indicates the omission of irrelevant or unimportant information.</p>
</div>
<div id="footer">