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 [9/21] - in
/websites/staging/trafficserver/trunk/content/docs/trunk: admin/ sdk/
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HTTPTransformationPlugins.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HTTPTransformationPlugins.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HTTPTransformationPlugins.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HTTPTransformationPlugins.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,148 @@
<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="SetTransactionHook">Prev</a> - Setting a Transaction Hook
+The Sample Null Transform Plugin -
+<a href="SampleNullTransformPlugin">Next</a></p>
+<h2 id="chapter_5_http_transformation_plugins">Chapter 5. HTTP Transformation Plugins</h2>
+<p>Transform plugins examine or transform HTTP message body content.
+For example, transform plugins can:</p>
+<ul>
+<li>
+<p>Append text to HTML documents</p>
+</li>
+<li>
+<p>Compress images</p>
+</li>
+<li>
+<p>Do virus checking (on client <code>POST</code> data or server response
+ data)</p>
+</li>
+<li>
+<p>Do content-based filtering (filter out HTML documents that
+ contain certain terms or expressions)</p>
+</li>
+</ul>
+<p>This chapter explains how to write transform plugins. The following
+examples are discussed in detail:</p>
+<ul>
+<li>
+<p><a href="SampleNullTransformPlugin" title="The Sample Null Transform Plugin">Sample Null Transform Plugin</a></p>
+</li>
+<li>
+<p><a href="AppendTransformPlugin" title="The Append-Transform Plugin">Append-Transform Plugin</a></p>
+</li>
+<li><a href="SampleBufferedNullTransformPlugin" title="The Sample Buffered Null Transform Plugin">Sample Buffered Null Transform Plugin</a></li>
+</ul>
+<h2 id="writing_content_transform_plugins">Writing Content Transform Plugins</h2>
+<p>Content transformation plugins transform HTTP response content
+(such as images or HTML documents) and HTTP request content (such
+as client <code>POST</code> data). Because the data stream to be transformed
+is of variable length, these plugins must use a mechanism that
+passes data from buffer to buffer <em>and</em> checks to see if the end of
+the data stream is reached. This mechanism is provided by virtual
+connections (vconnections) and virtual IO descriptors (VIOs).</p>
+<p>A <strong>vconnection</strong> is an abstraction for a data pipe that allows its
+users to perform asynchronous reads and writes without knowing the
+underlying implementation. A transformation is a specific type of
+vconnection. A <strong>transformation</strong> connects an input data source and
+an output data sink; this feature enables it to view and modify all
+the data passing through it.</p>
+<p>Transformations can be chained together, one after the other, so
+that multiple transformations can be performed on the same content.
+The vconnection type, <code>INKVConn</code>, is actually a subclass of
+<code>INKCont</code>, which means that vconnections (and transformations) are
+continuations. Vconnections and transformations can thus exchange
+events, informing one another that data is available for reading or
+writing, or that the end of a data stream is reached.</p>
+<p>A <strong>VIO</strong> is a description of an IO operation that is in progress.
+Every vconnection has an associated <em>input VIO</em> and an associated
+<em>output VIO</em>. When vconnections are transferring data to one
+another, one vconnection's input VIO is another vconnection's
+output VIO. A vconnection's input VIO is also called its
+<strong>write VIO</strong> because the input VIO refers to a write operation
+performed on the vconnection itself. Similarly, the outpt VIO is
+also called the <strong>read VIO</strong>. For transformations, which are
+designed to pass data in one direction, you can picture the
+relationship between the transformation vconnection and its VIOs as
+follows:</p>
+<p><strong>Figure 5.1. A Transformation and its VIOs</strong></p>
+<p><img alt="A Transformation and its VIOs" src="images/vconnection.jpg" />
+Because the Traffic Server API places transformations directly in
+the response or request data stream, the transformation vconnection
+is responsible only for reading the data from the input buffer,
+transforming it, and then writing it to the output buffer. The
+upstream vconnection writes the incoming data to the
+transformation's input buffer. In the figure above,
+<a href="HTTPTransformationPlugins#Fig_TransformationAndVIOs" title="Figure 5.1. A Transformation and its VIOs">A Transformation and its VIOs</a>,
+the input VIO describes the progress of the upstream vconnection's
+write operation on the transformation, while the output VIO
+describes the progress of the transformation's write operation on
+the output (downstream) vconnection. The <strong>nbytes</strong> value in the
+VIO is the total number of bytes to be written. The <strong>ndone</strong> value
+is the current progress, or the number of bytes that have been
+written at a specific point in time.</p>
+<p>When writing a transformation plugin, you must understand
+implementation as well as the use of vconnections. The
+<em>implementor's side</em>refers to how to implement a vconnection that
+others can use. At minimum, a transform plugin creates a
+transformation that sits in the data stream and must be able to
+handle the events that the upstream and downstream vconnections
+send to it. The <em>user's side</em>refers to how to use a vconnection to
+read or write data. At the very least, transformations output
+(write) data.</p>
+<h3 id="transformations">Transformations</h3>
+<h3 id="vios">VIOs</h3>
+<p>A <strong>VIO</strong> or virtual IO is a description of an in progress IO
+operation. The VIO data structure is used by vconnection users to
+determine how much progress has been made on a particular IO
+operation, and to reenable an IO operation when it stalls due to
+buffer space. Vconnection implementors use VIOs to determine the
+buffer for an IO operation, how much work to do on the IO
+operation, and which continuation to call back when progress on the
+IO operation is made.</p>
+<p>The <code>INKVIO<a class="indexterm" name="id374498"></a></code> data
+structure itself is opaque, but it might have been defined as
+follows:</p>
+<div class="codehilite"><pre><span class="n">typedef</span> <span class="n">struct</span> <span class="p">{</span>
+ <span class="n">INKCont</span> <span class="n">continuation</span><span class="p">;</span>
+ <span class="n">INKVConn</span> <span class="n">vconnection</span><span class="p">;</span>
+ <span class="n">INKIOBufferReader</span> <span class="n">reader</span><span class="p">;</span>
+ <span class="n">INKMutex</span> <span class="n">mutex</span><span class="p">;</span>
+ <span class="nb">int</span> <span class="n">nbytes</span><span class="p">;</span>
+ <span class="nb">int</span> <span class="n">ndone</span><span class="p">;</span>
+<span class="p">}</span> <span class="o">*</span><span class="n">INKVIO</span><span class="p">;</span>
+</pre></div>
+
+
+<h3 id="io_buffers">IO Buffers</h3>
+<p>The <strong>IO buffer</strong> data structure is the building block of the
+vconnection abstraction. An IO buffer is composed of a list of
+buffer blocks which, in turn, point to buffer data. Both the
+<em>buffer block</em> (<code>INKIOBufferBlock</code>) and <em>buffer data</em>
+(<code>INKIOBufferData</code>) data structures are reference counted so they
+can reside in multiple buffers at the same time. This makes it
+extremely efficient to copy data from one IO buffer to another
+using <code>INKIOBufferCopy</code>, since Traffic Server only needs to copy
+pointers and adjust reference counts appropriately (instead of
+actually copying any data).</p>
+<p>The IO buffer abstraction provides for a single writer and multiple
+readers. In order for the readers to have no knowledge of each
+other, they manipulate IO buffers through the<code>INKIOBufferReader</code>
+data structure. Since only a single writer is allowed, there is no
+corresponding <code>INKIOBufferWriter</code> data structure. The writer simply
+modifies the IO buffer directly.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HTTP_Transactions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HTTP_Transactions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HTTP_Transactions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HTTP_Transactions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,231 @@
<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="HTTPSessions">Prev</a> - HTTP Sessions
+Intercepting HTTP Transactions - <a href="InterceptingHTTPTx">Next</a></p>
+<h2 id="http_transactions">HTTP Transactions</h2>
+<p>The HTTP transaction functions enable you to set up plugin
+callbacks to HTTP transactions and obtain/modify information about
+particular HTTP transactions.</p>
+<p>As described in the section on HTTP sessions, an
+<strong>HTTP transaction</strong> is an object defined for the lifetime of a
+single request from a client and the corresponding response from
+Traffic Server. The <code><b>INKHttpTxn</b></code> structure is the main
+handle given to a plugin for manipulating a transaction's internal
+state. Additionally, an HTTP transaction has a reference back to
+the HTTP session that created it.</p>
+<p>The sample code below illustrates how to register locally to a
+transaction and associate data to the transaction.</p>
+<div class="codehilite"><pre><span class="o">/*</span>
+<span class="o">*</span> <span class="n">Simple</span> <span class="n">plugin</span> <span class="n">that</span> <span class="n">illustrates:</span>
+<span class="o">*</span> <span class="o">-</span> <span class="n">how</span> <span class="n">to</span> <span class="n">register</span> <span class="n">locally</span> <span class="n">to</span> <span class="n">a</span> <span class="n">transaction</span>
+<span class="o">*</span> <span class="o">-</span> <span class="n">how</span> <span class="n">to</span> <span class="n">deal</span> <span class="n">with</span> <span class="n">data</span> <span class="n">that</span><span class="s">'s associated with a tranaction</span>
+<span class="s">*</span>
+<span class="s">* Note: for readability, error checking is omitted</span>
+<span class="s">*/</span>
+
+<span class="s">#include <ts/ts.h></span>
+
+<span class="s">#define DBG_TAG "txn"</span>
+
+<span class="s">/* Structure to be associated to txns */</span>
+<span class="s">typedef struct {</span>
+<span class="s"> int i;</span>
+<span class="s"> float f;</span>
+<span class="s"> char *s;</span>
+<span class="s">} TxnData;</span>
+
+<span class="s">/* Allocate memory and init a TxnData structure */</span>
+<span class="s">TxnData *</span>
+<span class="s">txn_data_alloc()</span>
+<span class="s">{</span>
+<span class="s"> TxnData *data;</span>
+<span class="s"> data = INKmalloc(sizeof(TxnData));</span>
+
+<span class="s"> data->i = 1;</span>
+<span class="s"> data->f = 0.5;</span>
+<span class="s"> data->s = "Constant String";</span>
+<span class="s"> return data;</span>
+<span class="s">}</span>
+
+<span class="s">/* Free up a TxnData structure */</span>
+<span class="s">void</span>
+<span class="s">txn_data_free(TxnData *data)</span>
+<span class="s">{</span>
+<span class="s"> INKfree(data);</span>
+<span class="s">}</span>
+
+<span class="s">/* Handler for event READ_REQUEST and TXN_CLOSE */</span>
+<span class="s">static int</span>
+<span class="s">local_hook_handler (INKCont contp, INKEvent event, void *edata)</span>
+<span class="s">{</span>
+<span class="s"> INKHttpTxn txnp = (INKHttpTxn) edata;</span>
+<span class="s"> TxnData *txn_data = INKContDataGet(contp);</span>
+<span class="s"> switch (event) {</span>
+<span class="s"> case INK_EVENT_HTTP_READ_REQUEST_HDR:</span>
+<span class="s"> /* Modify values of txn data */</span>
+<span class="s"> txn_data->i = 2;</span>
+<span class="s"> txn_data->f = 3.5;</span>
+<span class="s"> txn_data->s = "Constant String 2";</span>
+<span class="s"> break;</span>
+
+<span class="s"> case INK_EVENT_HTTP_TXN_CLOSE:</span>
+<span class="s"> /* Print txn data values */</span>
+<span class="s"> INKDebug(DBG_TAG, "Txn data i=%d f=%f s=%s", txn_data->i, txn_data->f,</span>
+<span class="s"> txn_data->s);</span>
+
+<span class="s"> /* Then destroy the txn cont and its data */</span>
+<span class="s"> txn_data_free(txn_data);</span>
+<span class="s"> INKContDestroy(contp);</span>
+<span class="s"> break;</span>
+
+<span class="s"> default:</span>
+<span class="s"> INKAssert(!"Unexpected event");</span>
+<span class="s"> break;</span>
+<span class="s"> }</span>
+
+<span class="s"> INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE);</span>
+<span class="s"> return 1;</span>
+<span class="s">}</span>
+
+<span class="s">/* Handler for event TXN_START */</span>
+<span class="s">static int</span>
+<span class="s">global_hook_handler (INKCont contp, INKEvent event, void *edata)</span>
+<span class="s">{</span>
+<span class="s"> INKHttpTxn txnp = (INKHttpTxn) edata;</span>
+<span class="s"> INKCont txn_contp;</span>
+<span class="s"> TxnData *txn_data;</span>
+
+<span class="s"> switch (event) {</span>
+<span class="s"> case INK_EVENT_HTTP_TXN_START:</span>
+<span class="s"> /* Create a new continuation for this txn and associate data to it */</span>
+<span class="s"> txn_contp = INKContCreate(local_hook_handler, INKMutexCreate());</span>
+<span class="s"> txn_data = txn_data_alloc();</span>
+<span class="s"> INKContDataSet(txn_contp, txn_data);</span>
+
+<span class="s"> /* Registers locally to hook READ_REQUEST and TXN_CLOSE */</span>
+<span class="s"> INKHttpTxnHookAdd(txnp, INK_HTTP_READ_REQUEST_HDR_HOOK, txn_contp);</span>
+<span class="s"> INKHttpTxnHookAdd(txnp, INK_HTTP_TXN_CLOSE_HOOK, txn_contp);</span>
+<span class="s"> break;</span>
+
+<span class="s"> default:</span>
+<span class="s"> INKAssert(!"Unexpected event");</span>
+<span class="s"> break;</span>
+<span class="s"> }</span>
+
+<span class="s"> INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE);</span>
+<span class="s"> return 1;</span>
+<span class="s">}</span>
+
+<span class="s">void</span>
+<span class="s">INKPluginInit (int argc, const char *argv[])</span>
+<span class="s">{</span>
+<span class="s"> INKCont contp;</span>
+
+<span class="s"> /* Note that we do not need a mutex for this txn since it registers globally</span>
+<span class="s"> and doesn'</span><span class="n">t</span> <span class="n">have</span> <span class="n">any</span> <span class="n">data</span> <span class="n">associated</span> <span class="n">with</span> <span class="n">it</span> <span class="o">*/</span>
+ <span class="n">contp</span> <span class="o">=</span> <span class="n">INKContCreate</span><span class="p">(</span><span class="n">global_hook_handler</span><span class="p">,</span> <span class="n">NULL</span><span class="p">);</span>
+
+ <span class="sr">/* Register gloabally */</span>
+ <span class="n">INKHttpHookAdd</span><span class="p">(</span><span class="n">INK_HTTP_TXN_START_HOOK</span><span class="p">,</span> <span class="n">contp</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>See <a href="AddingHooks" title="Adding Hooks">Adding Hooks</a> for background
+about HTTP transactions and HTTP hooks, as well as
+<a href="HTTPHooksAndTransactions" title="Chapter 8. HTTP Hooks and Transactions">HTTP Hooks and Transactions</a>.
+Also see the
+<a href="HTTPHooksAndTransactions#Fig_HHTTPTxStateDiag" title="Figure 8.1. HTTP Transaction State Diagram">HTTP Transaction State Diagram</a>
+for an illustration of the steps involved in a typical HTTP
+transaction.</p>
+<p>The HTTP transaction functions are:</p>
+<ul>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnCacheLookupStatusGet" title="INKHttpTxnCacheLookupStatusGet">INKHttpTxnCacheLookupStatusGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnCachedReqGet" title="INKHttpTxnCachedReqGet">INKHttpTxnCachedReqGet</a></p>
+<ul>
+<li>Note that it is an error to modify cached headers.</li>
+</ul>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnCachedRespGet" title="INKHttpTxnCachedRespGet">INKHttpTxnCachedRespGet</a></p>
+<ul>
+<li>Note that it is an error to modify cached headers.</li>
+</ul>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnClientIncomingPortGet" title="INKHttpTxnClientIncomingPortGet">INKHttpTxnClientIncomingPortGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnClientIPGet" title="INKHttpTxnClientIPGet">INKHttpTxnClientIPGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnClientRemotePortGet" title="INKHttpTxnClientRemotePortGet">INKHttpTxnClientRemotePortGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnClientReqGet" title="INKHttpTxnClientReqGet">INKHttpTxnClientReqGet</a></p>
+<ul>
+<li>Plugins that must read client request headers use this call to
+retrieve the HTTP header.</li>
+</ul>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnClientRespGet" title="INKHttpTxnClientRespGet">INKHttpTxnClientRespGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnErrorBodySet" title="INKHttpTxnErrorBodySet">INKHttpTxnErrorBodySet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnHookAdd" title="INKHttpTxnHookAdd">INKHttpTxnHookAdd</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnNextHopIPGet" title="INKHttpTxnNextHopIPGet">INKHttpTxnNextHopIPGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnNextHopIPGet" title="INKHttpTxnNextHopIPGet">INKHttpTxnNextHopIPGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnParentProxySet" title="INKHttpTxnParentProxySet">INKHttpTxnParentProxySet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnReenable" title="INKHttpTxnReenable">INKHttpTxnReenable</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnServerIPGet" title="INKHttpTxnServerIPGet">INKHttpTxnServerIPGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnServerReqGet" title="INKHttpTxnServerReqGet">INKHttpTxnServerReqGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnServerRespGet" title="INKHttpTxnServerRespGet">INKHttpTxnServerRespGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnSsnGet" title="INKHttpTxnSsnGet">INKHttpTxnSsnGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnTransformedRespCache" title="INKHttpTxnTransformedRespCache">INKHttpTxnTransformedRespCache</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnTransformRespGet" title="INKHttpTxnTransformRespGet">INKHttpTxnTransformRespGet</a></p>
+</li>
+<li>
+<p><a href="HTTPTransactionFunctions#INKHttpTxnUntransformedRespCache" title="INKHttpTxnUntransformedRespCache">INKHttpTxnUntransformedRespCache</a></p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HeaderBasedPluginEx.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HeaderBasedPluginEx.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HeaderBasedPluginEx.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HeaderBasedPluginEx.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,92 @@
<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> - API Function Reference
+The Blacklist Plugin - <a href="BlacklistPlugin">Next</a></p>
+<h2 id="chapter_4_header-based_plugin_examples">Chapter 4. Header-Based Plugin Examples</h2>
+<p><strong>Table of Contents</strong></p>
+<ul>
+<li><a href="BlacklistPlugin">The Blacklist Plugin</a></li>
+<li>
+<ul>
+<li>
+<p><a href="BlacklistPlugin#CreatingParentContinuation">Creating the Parent Continuation</a></p>
+</li>
+<li>
+<p><a href="SettingGlobalHook">Setting a Global Hook</a></p>
+</li>
+<li><a href="SettingUpUIUpdateCallbacks">Setting Up UI Update Callbacks</a></li>
+<li><a href="AccessingTransactionProc">Accessing the Transaction Being Processed</a></li>
+<li><a href="SettingUpTransacHook">Setting Up a Transaction Hook</a></li>
+<li><a href="WorkWHTTPHeaderFunc">Working with HTTP Header Functions</a></li>
+</ul>
+</li>
+<li>
+<p><a href="BasicAuthorizatonPlugin">The Basic Authorization Plugin</a></p>
+</li>
+<li>
+<ul>
+<li>
+<p><a href="BasicAuthorizatonPlugin#CreatePluginParentCont_GlHk">Creating the Plugin's Parent Continuation and Global Hook</a></p>
+</li>
+<li>
+<p><a href="ImplementHandler_GetTransHandle">Implementing the Handler and Getting a Handle to the Transaction</a></p>
+</li>
+<li><a href="WorkWithHTTPHeaders">Working With HTTP Headers</a></li>
+<li><a href="SetTransactionHook">Setting a Transaction Hook</a></li>
+</ul>
+</li>
+</ul>
+<p>Header-based plugins read or modify the headers of HTTP messages
+that Traffic Server sends and receives. Reading this chapter will
+help you to understand the following topics:</p>
+<ul>
+<li>
+<p>Creating continuations for your plugins</p>
+</li>
+<li>
+<p>Adding global hooks</p>
+</li>
+<li>
+<p>Adding transaction hooks</p>
+</li>
+<li>
+<p>Working with HTTP header functions</p>
+</li>
+</ul>
+<p>The two sample plugins discussed in this chapter are
+<code>blacklist-1.c</code> and <code>basic-auth.c</code>.</p>
+<h2 id="overview">Overview</h2>
+<p>Header-based plugins take actions based on the contents of HTTP
+request or response headers. Examples include filtering (on the
+basis of requested URL, source IP address, or other request
+header), user authentication, or user redirection. Header-based
+plugins have the following common elements:</p>
+<p>**
+The plugin has a static parent continuation that scans all Traffic
+Server headers (either request headers, response headers, or
+both).</p>
+<p>The plugin has a global hook. This enables the plugin to check all
+transactions to determine if the plugin needs to do something.</p>
+<p>The plugin gets a handle to the transaction being processed through
+the global hook.</p>
+<p>If the plugin needs to do something to transactions in specific
+cases, then it sets up a transaction hook for a particular event.</p>
+<p>The plugin obtains client header information and does something
+based on that information.</p>
+<p>This chapter demonstrates how these components are implemented in
+SDK sample code.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HostLookupFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HostLookupFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HostLookupFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HostLookupFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,69 @@
<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="INKActionDone">Prev</a> - INKActionDone
+INKHostLookupResultIPGet - <a href="INKHostLookupResultIPGet">Next</a></p>
+<h2 id="host_lookup_functions">Host Lookup Functions</h2>
+<hr />
+<p><a href="HostLookupFunctions#INKHostLookup">INKHostLookup</a>
+<a href="INKHostLookupResultIPGet">INKHostLookupResultIPGet</a></p>
+<h3 id="inkhostlookup">INKHostLookup</h3>
+<p>Instructs Traffic Server to do a DNS lookup on a host name.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKAction INKHostLookupResult (INKCont <em class="replaceable"><code>contp</code>,
+ char *<em><code>hostname</code></em>, int <em><code>namelen</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCont</code> <code><em class="replaceable"><code>contp</code> is the
+ continuation Traffic Server calls back when the DNS lookup occurs.</p>
+<div class="codehilite"><pre><span class="sb">`char *``<em class="replaceable"><code>hostname`</span> <span class="n">is</span>
+<span class="n">the</span> <span class="n">name</span> <span class="n">to</span> <span class="n">look</span> <span class="n">up</span><span class="o">.</span> <span class="n">Null</span><span class="o">-</span><span class="n">terminated</span><span class="o">.</span>
+
+<span class="sb">`int``<em class="replaceable"><code>namelen`</span> <span class="n">is</span> <span class="n">the</span> <span class="nb">length</span> <span class="n">of</span>
+<span class="sb">`<em class="replaceable"><code>hostname`</span> <span class="o">+</span><span class="mi">1</span> <span class="p">(</span><span class="n">add</span> <span class="n">one</span> <span class="n">to</span> <span class="n">account</span> <span class="k">for</span>
+<span class="n">null</span> <span class="n">termination</span><span class="p">)</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Initiates a DNS lookup of
+ <code><em class="replaceable"><code>hostname</code>. When the lookup occurs,
+ Traffic Server sends contp <code>INK_EVENT_DNS_LOOKUP</code>. If the lookup is
+ successful (IP address resolved), then the
+ <code>void *``<em class="replaceable"><code>data</code> passed to the handler
+ of the continuation <code><em class="replaceable"><code>contp</code> is a data
+ of type <code>INKHostLookupResult</code>. You can then use
+ <code>INKHostLookupResultIPGet</code> to convert this information to an
+ unsigned <code>int</code> representing the IP address.</p>
+<div class="codehilite"><pre><span class="n">If</span> <span class="n">the</span> <span class="n">lookup</span> <span class="n">fails</span> <span class="p">(</span><span class="n">IP</span> <span class="n">address</span> <span class="ow">not</span> <span class="n">resolved</span><span class="p">),</span> <span class="k">then</span> <span class="n">the</span> <span class="sb">`void *`</span>
+<span class="sb">`<em class="replaceable"><code>data`</span> <span class="n">passed</span> <span class="n">to</span> <span class="n">the</span> <span class="n">handler</span> <span class="n">of</span>
+<span class="n">continuation</span> <span class="sb">`<em class="replaceable"><code>contp`</span> <span class="n">is</span> <span class="n">a</span> <span class="n">null</span>
+<span class="n">pointer</span><span class="o">.</span>
+
+<span class="n">You</span> <span class="n">have</span> <span class="n">the</span> <span class="n">option</span> <span class="n">to</span> <span class="n">cancel</span> <span class="n">the</span> <span class="n">action</span> <span class="n">returned</span> <span class="n">by</span>
+<span class="sb">`INKHostLookup`</span> <span class="n">by</span> <span class="n">using</span> <span class="sb">`INKActionCancel`</span><span class="o">.</span>
+
+<span class="o">!</span><span class="p">[[</span><span class="n">Note</span><span class="p">]](</span><span class="n">images</span><span class="sr">/docbook/</span><span class="n">note</span><span class="o">.</span><span class="n">png</span><span class="p">)</span>
+<span class="n">Note</span>
+<span class="n">Reentrant</span> <span class="n">calls</span> <span class="n">are</span> <span class="n">possible</span><span class="p">;</span> <span class="n">i</span><span class="o">.</span><span class="n">e</span><span class="o">.</span><span class="p">,</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">can</span> <span class="n">call</span> <span class="n">back</span> <span class="n">the</span>
+<span class="n">user</span> <span class="p">(</span><span class="sb">`contp`</span><span class="p">)</span> <span class="n">in</span> <span class="n">the</span> <span class="n">same</span> <span class="n">call</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ An <code>INKAction</code> object if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">argument</span> <span class="n">is</span> <span class="n">incorrect</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">the</span> <span class="n">API</span> <span class="n">fails</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HostsLookupAPI.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HostsLookupAPI.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HostsLookupAPI.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/HostsLookupAPI.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,27 @@
<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="ActionsGuide">Prev</a> - Chapter 14. Actions Guide
+Chapter 15. IO Guide - <a href="IOGuide">Next</a></p>
+<h2 id="hosts_lookup_api">Hosts Lookup API</h2>
+<p>The hosts lookup enables plugins to ask Traffic Server to do a host
+lookup of a host name, much like a DNS lookup.</p>
+<p>The hosts lookup functions are as follows:</p>
+<ul>
+<li><a href="HostLookupFunctions#INKHostLookup" title="INKHostLookup"><code>INKHostLookup</code></a></li>
+<li><code><a href="INKHostLookupResultIPGet.html" title="INKHostLookupResultIPGet">INKHostLookupResultIPGet</a></code></li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKActionDone.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKActionDone.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKActionDone.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKActionDone.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,53 @@
<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="ActionFunctions">Prev</a> - Action Functions: INKActionCancel
+Host Lookup Functions - <a href="HostLookupFunctions">Next</a></p>
+<h3 id="inkactiondone">INKActionDone</h3>
+<p>Indicates whether an action is completed.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int INKActionDone (INKAction <em class="replaceable"><code> actionp</code>)</p>
+<p><strong>Description</strong>
+ ~ <code><em class="replaceable"><code>actionp</code> is a completed action.
+ If a <code>NULL</code> argument is passed to <code>INKActionDone</code>, then Traffic
+ Server crashes and does not return <code>INK_ERROR</code>.</p>
+<p>~ <strong>Note:</strong> It is the programmer's responsibility to ensure that
+ a non-null value is passed to <code>INKActionDone</code>.</p>
+<div class="codehilite"><pre>![[Important]](images/docbook/important.png)
+Important
+Always use `INKActionDone` immediately after the call that assigns
+the action.
+For example:
+
+ actionp = INKContSchedule(contp, SOME_TIMEOUT_VALUE);
+ if (INKActionDone(actionp)){
+ //event has already occurred
+ }
+
+If you call `INKActionDone``(<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>actionp<span class="nt"></em></span>)`
+some time later or somewhere else, then it always returns `false`
+and therefore does not accurately reflect whether the action has
+completed.
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>0</code> if the action has not completed.</p>
+<div class="codehilite"><pre><span class="sb">`1`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">action</span> <span class="n">has</span> <span class="n">completed</span><span class="o">.</span>
+
+<span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">has</span> <span class="n">occurred</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKAssert.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKAssert.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKAssert.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKAssert.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,48 @@
<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="INKError">Prev</a> - INKError
+INKReleaseAssert - <a href="INKReleaseAssert">Next</a></p>
+<h3 id="inkassert">INKAssert</h3>
+<p>Enables the use of assertion in a plugin.</p>
+<p><strong>Prototype</strong>
+ ~ <code>void INKAssert(<em class="replaceable"><code>expression</code>);</p>
+<p><strong>Arguments</strong>
+ ~ A Boolean expression.</p>
+<p><strong>Description</strong>
+ ~ In <code>debug</code> mode, causes the Traffic Server to print the file
+ name, line number, and expression before it aborts.</p>
+<div class="codehilite"><pre><span class="n">In</span> <span class="sb">`optim`</span> <span class="n">mode</span><span class="p">,</span> <span class="n">the</span> <span class="n">expression</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">removed</span><span class="p">,</span> <span class="n">but</span> <span class="n">the</span> <span class="n">effects</span> <span class="n">of</span>
+<span class="n">printing</span> <span class="n">an</span> <span class="n">error</span> <span class="n">message</span> <span class="ow">and</span> <span class="n">aborting</span> <span class="n">are</span><span class="o">.</span> <span class="n">This</span> <span class="n">is</span> <span class="n">an</span> <span class="n">artifact</span> <span class="n">of</span>
+<span class="n">the</span> <span class="n">way</span> <span class="n">the</span> <span class="nb">system</span> <span class="n">assert</span> <span class="n">is</span> <span class="n">normally</span> <span class="n">used</span> <span class="ow">and</span> <span class="n">permits:</span>
+
+ <span class="n">ink_assert</span><span class="p">(</span><span class="o">!</span><span class="nb">setsockopt</span><span class="p">(</span><span class="o">...</span><span class="p">));</span>
+
+<span class="o">**</span><span class="n">Note:</span><span class="o">**</span> <span class="n">when</span> <span class="n">using</span> <span class="n">the</span> <span class="nb">system</span> <span class="s">"assert"</span><span class="p">,</span> <span class="n">you</span> <span class="k">do</span> <span class="ow">not</span> <span class="n">need</span> <span class="n">to</span> <span class="n">worry</span>
+<span class="n">about</span> <span class="n">the</span> <span class="n">condition</span> <span class="n">since</span> <span class="n">the</span> <span class="n">code</span> <span class="n">will</span> <span class="n">be</span> <span class="s">'dead code eliminated'</span>
+<span class="n">by</span> <span class="n">the</span> <span class="n">compiler</span><span class="p">;</span> <span class="n">with</span> <span class="sb">`INKAssert`</span><span class="p">,</span> <span class="n">you</span> <span class="k">do</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Example</strong>
+ ~ switch (event) {
+ case EVENT_IMMEDIATE:
+ ....
+ default:
+ INKAssert (!setsockopt(...));
+ break;
+ }</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyDestroy.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyDestroy.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyDestroy.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyDestroy.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="INKCacheKeyHostNameSet">Prev</a> - INKCacheKeyHostNameSet
+INKCacheRead - <a href="INKCacheRead">Next</a></p>
+<h3 id="inkcachekeydestroy">INKCacheKeyDestroy</h3>
+<p>Destroys a cache key.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKCacheKeyDestroy(INKCacheKey <em class="replaceable"><code>key</code>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCacheKey</code> <code><em class="replaceable"><code>key</code> is the key to
+ be destroyed.</p>
+<p><strong>Description</strong>
+ ~ Destroys a cache key (deallocates memory). You must destroy
+ cache keys when you are finished with them (i.e., after all reads
+ and writes are completed).</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the cache key was successfully destroyed.</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">deallocated</span> <span class="ow">or</span> <span class="n">was</span> <span class="ow">not</span>
+<span class="n">valid</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyDigestSet.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyDigestSet.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyDigestSet.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyDigestSet.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,56 @@
<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="CacheInterfaceFunctions">Prev</a> - Cache Interface Fxns:
+INKCacheKeyCreate, INKSetCacheUrl
+INKCacheKeyHostNameSet - <a href="INKCacheKeyHostNameSet">Next</a></p>
+<h3 id="inkcachekeydigestset">INKCacheKeyDigestSet</h3>
+<p>Generates and assigns a cache key to an object that will be
+cached.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKCacheKeyDigestSet(INKCacheKey <em class="replaceable"><code>key</code>,
+ const unsigned char *<em><code>input</code></em>, int <em><code>length</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCacheKey</code> <code><em class="replaceable"><code>key</code> is the key
+ that will be associated with the cached object. Before calling
+ <code>INKCacheKeyDigestSet</code>, you must create the key with
+ <code>INKCacheKeyCreate</code>. Note that in order to generate unique keys,
+ you must use unique input strings. This means that if the input
+ strings are identical, then <code>INKCacheKeyCreate</code> generates identical
+ keys.</p>
+<div class="codehilite"><pre><span class="sb">`const unsigned char *``<em class="replaceable"><code>input`</span>
+<span class="n">is</span> <span class="n">a</span> <span class="n">character</span> <span class="n">string</span> <span class="n">that</span> <span class="n">uniquely</span> <span class="n">identifies</span> <span class="n">the</span> <span class="n">object</span><span class="o">.</span> <span class="n">In</span> <span class="n">most</span>
+<span class="n">cases</span><span class="p">,</span> <span class="n">it</span><span class="err">'</span><span class="n">s</span> <span class="n">the</span> <span class="n">URL</span> <span class="n">of</span> <span class="n">the</span> <span class="n">object</span><span class="o">.</span>
+
+<span class="sb">`int``<em class="replaceable"><code>length`</span> <span class="n">is</span> <span class="n">the</span> <span class="nb">length</span> <span class="n">of</span> <span class="n">the</span>
+<span class="n">input</span> <span class="n">string</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Generates and assigns a cache key to the object to be cached.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the cache key is successfully generated.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="sb">`INKCacheKeyDigestSet`</span> <span class="n">cannot</span> <span class="n">be</span> <span class="n">set</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Example</strong>
+ ~ const char *digest_string = "mydigest"
+ INKCacheKey mykey;
+ INKCacheKeyCreate(&mykey);
+ INKCacheKeyDigestSet(mykey,digest_string, strlen(digest_string);</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyHostNameSet.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyHostNameSet.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyHostNameSet.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyHostNameSet.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,47 @@
<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="INKCacheKeyDigestSet">Prev</a> - INKCacheKeyDigestSet
+INKCacheKeyDestroy - <a href="INKCacheKeyDestroy">Next</a></p>
+<h3 id="inkcachekeyhostnameset">INKCacheKeyHostNameSet</h3>
+<p>Associates a host name to a cache key. Use if you want to support
+cache partitioning by host name.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKCacheKeyHostNameSet(INKCacheKey <em class="replaceable"><code>key</code>,
+ const unsigned char <em><code>*hostname</code></em>, int <em><code>host_len</code></em>;</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCacheKey</code> <code><em class="replaceable"><code>key</code> is the key to
+ the cached object.</p>
+<div class="codehilite"><pre><span class="sb">`const unsigned char <em class="replaceable"><code>*hostname`</span> <span class="o">**</span> <span class="n">is</span>
+<span class="n">the</span> <span class="n">host</span> <span class="n">name</span> <span class="n">you</span> <span class="n">are</span> <span class="n">associating</span> <span class="n">with</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">key</span><span class="o">.</span>
+
+<span class="sb">`int <em class="replaceable"><code>host_len`</span> <span class="n">is</span> <span class="n">the</span> <span class="nb">length</span> <span class="n">of</span> <span class="n">the</span>
+<span class="n">string</span> <span class="sb">`<em class="replaceable"><code>hostname`</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Associates a host name to a cache key. The host name setting is
+ used in conjunction with the Traffic Server configuration files
+ <code>partition.config</code> and <code>hosting.config</code> that enable you to specify
+ under which cache partition the object should be stored.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the <code><em class="replaceable"><code> hostname</code>
+ is successfully associated with the cache key.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="sb">`<em class="replaceable"><code>hostname`</span> <span class="n">cannot</span> <span class="n">be</span>
+<span class="n">set</span> <span class="ow">or</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyPinnedSet.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyPinnedSet.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyPinnedSet.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheKeyPinnedSet.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,70 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "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="INKCacheRemove">Prev</a> - INKCacheRemove
+INKVConnCacheObjectSizeGet -
+<a href="INKVConnCacheObjectSizeGet">Next</a></p>
+<h3 id="inkcachekeypinnedset">INKCacheKeyPinnedSet</h3>
+<p>Pins the document corresponding to the specified key in the cache
+so that the garbage collection process does not delete the document
+from the cache for the specified number of seconds.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKCacheKeyPinnedSet (INKCacheKey <em class="replaceable"><code>key</code>,
+ time_t <em><code>pin_in_cache</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCacheKey</code> <code><em class="replaceable"><code>key</code> is the cache
+ key for the document to be pinned.</p>
+<div class="codehilite"><pre><span class="sb">`time_t <em class="replaceable"><code>pin_in_cache`</span>
+<span class="n">represents</span> <span class="n">the</span> <span class="n">number</span> <span class="n">of</span> <span class="n">seconds</span> <span class="n">the</span> <span class="n">document</span> <span class="n">is</span> <span class="n">to</span> <span class="n">be</span> <span class="n">pinned</span> <span class="n">in</span>
+<span class="n">the</span> <span class="n">cache</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Pins the document corresponding to the specified
+ <code><em class="replaceable"><code>key</code> in the cache for the specified
+ number of seconds specified in
+ <code><em class="replaceable"><code>pin_in_cache</code>. Once the document is
+ pinned, the garbage collection will not delete this document from
+ the specifed number of seconds and the document can even persist
+ across Traffic Server re-runs. However, after the
+ <code><em class="replaceable"><code>pin_in_cache</code> interval has expired,
+ the cache may delete the document at any time in order to reclaim
+ space.</p>
+<div class="codehilite"><pre>To delete this document before the
+`<span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">><code></span>pin_in_cache` interval expires, call
+the `INKCacheRemove()` function with the document's cache key.
+
+`InkCacheKeyPinnedSet()` should be used after a key is created and
+before writing the document to cache using `I``NKCacheWrite()`.
+
+Because a document is not pinned in the cache by default, it can be
+garbage-collected at anytime.
+
+![[Note]](images/docbook/note.png)
+Note
+It is important that the `records.config` variable
+`<span class="nt"><i></span>proxy.config.cache.permit.pinning <span class="nt"></i></span>` (in `records.config`)
+is set to 1 to enable pinning.
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the specified object was successfully pinned
+ in the cache.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">pin</span> <span class="n">could</span> <span class="ow">not</span> <span class="n">be</span> <span class="n">set</span> <span class="ow">or</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheRead.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheRead.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheRead.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheRead.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,89 @@
<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="INKCacheKeyDestroy">Prev</a> - INKCacheKeyDestroy
+INKCacheReady - <a href="INKCacheReady">Next</a></p>
+<h3 id="inkcacheread">INKCacheRead</h3>
+<p>Initiates a cache read or lookup of an object in the Traffic Server
+cache.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKAction INKCacheRead (INKCont <em class="replaceable"><code>contp</code>,
+ INKCacheKey <em><code>key</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCont</code> <code><em class="replaceable"><code>contp</code> is the
+ continuation the cache calls back (telling it whether the object
+ exists and can be read).</p>
+<div class="codehilite"><pre><span class="sb">`INKCacheKey`</span> <span class="sb">`<em class="replaceable"><code>key`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">key</span>
+<span class="n">corresponding</span> <span class="n">to</span> <span class="n">the</span> <span class="n">object</span> <span class="n">to</span> <span class="n">be</span> <span class="nb">read</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Asks the Traffic Server cache if the object corresponding to
+ <code><em class="replaceable"><code>key</code> exists in the cache and can be
+ read.</p>
+<div class="codehilite"><pre><span class="n">You</span> <span class="n">can</span> <span class="k">do</span> <span class="n">a</span> <span class="n">cache</span> <span class="n">lookup</span> <span class="n">to</span> <span class="n">determine</span> <span class="n">whether</span> <span class="ow">or</span> <span class="ow">not</span> <span class="n">an</span> <span class="n">object</span> <span class="n">is</span>
+<span class="n">in</span> <span class="n">the</span> <span class="n">cache</span><span class="o">.</span> <span class="n">To</span> <span class="k">do</span> <span class="n">a</span> <span class="n">cache</span> <span class="n">lookup</span><span class="p">,</span> <span class="n">call</span> <span class="sb">`INKCacheRead`</span> <span class="n">on</span> <span class="n">a</span>
+<span class="n">continuation</span> <span class="sb">`<em class="replaceable"><code>contp`</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="n">object</span>
+<span class="n">can</span> <span class="n">be</span> <span class="nb">read</span><span class="p">,</span> <span class="k">then</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">calls</span>
+<span class="sb">`<em class="replaceable"><code>contp`</span> <span class="n">back</span> <span class="n">with</span> <span class="n">the</span> <span class="n">event</span>
+<span class="sb">`INK_EVENT_CACHE_OPEN_READ`</span><span class="o">.</span> <span class="n">In</span> <span class="n">this</span> <span class="k">case</span><span class="p">,</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">also</span> <span class="n">passes</span>
+<span class="sb">`<em class="replaceable"><code>contp`</span> <span class="n">a</span> <span class="n">cache</span> <span class="n">vconnection</span><span class="p">;</span>
+<span class="sb">`<em class="replaceable"><code>contp`</span> <span class="n">can</span> <span class="k">then</span> <span class="n">initiate</span> <span class="n">a</span> <span class="nb">read</span>
+<span class="n">operation</span> <span class="n">on</span> <span class="n">that</span> <span class="n">vconnection</span> <span class="n">using</span> <span class="sb">`INKVConnRead`</span><span class="o">.</span>
+<span class="sb">`INKVConnCacheObjectSizeGet`</span> <span class="n">can</span> <span class="n">be</span> <span class="n">used</span> <span class="n">to</span> <span class="n">determine</span> <span class="n">the</span> <span class="n">size</span> <span class="n">of</span>
+<span class="n">the</span> <span class="n">object</span> <span class="n">in</span> <span class="n">the</span> <span class="n">cache</span><span class="o">.</span>
+
+<span class="n">If</span> <span class="n">the</span> <span class="n">object</span> <span class="n">cannot</span> <span class="n">be</span> <span class="nb">read</span> <span class="p">(</span><span class="k">if</span><span class="p">,</span> <span class="k">for</span> <span class="n">instance</span><span class="p">,</span> <span class="n">it</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">in</span> <span class="n">the</span>
+<span class="n">cache</span><span class="p">),</span> <span class="k">then</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">calls</span> <span class="sb">`<em class="replaceable"><code>contp`</span>
+<span class="n">back</span> <span class="n">with</span> <span class="n">the</span> <span class="n">event</span> <span class="sb">`INK_EVENT_CACHE_OPEN_READ_FAILED`</span><span class="o">.</span> <span class="n">An</span> <span class="n">error</span>
+<span class="n">code</span> <span class="n">is</span> <span class="n">passed</span> <span class="n">in</span> <span class="n">the</span> <span class="sb">`void *edata`</span> <span class="n">argument</span> <span class="n">of</span>
+<span class="sb">`<em class="replaceable"><code>contp`</span><span class="o">.</span> <span class="n">The</span> <span class="n">error</span> <span class="n">code</span> <span class="n">can</span> <span class="n">be:</span>
+
+<span class="o">-</span> <span class="sb">`INK_CACHE_ERROR_NOT_READY`</span><span class="p">:</span> <span class="n">trying</span> <span class="n">to</span> <span class="n">access</span> <span class="n">to</span> <span class="n">the</span> <span class="n">cache</span>
+ <span class="k">while</span> <span class="n">it</span><span class="err">'</span><span class="n">s</span> <span class="ow">not</span> <span class="n">yet</span> <span class="n">initialized</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="sb">`INK_CACHE_ERROR_NO_DOC`</span><span class="p">:</span> <span class="n">document</span> <span class="n">does</span> <span class="ow">not</span> <span class="n">exist</span> <span class="n">in</span> <span class="n">cache</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="sb">`INK_CACHE_ERROR_DOC_BUSY`</span><span class="p">:</span> <span class="n">trying</span> <span class="n">to</span> <span class="nb">read</span> <span class="n">a</span> <span class="n">document</span> <span class="k">while</span>
+ <span class="n">another</span> <span class="n">continuation</span> <span class="n">is</span> <span class="n">writing</span> <span class="n">on</span> <span class="n">it</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="n">Any</span> <span class="n">other</span> <span class="n">value:</span> <span class="n">unknown</span> <span class="nb">read</span> <span class="n">failure</span>
+
+<span class="n">Finally</span><span class="p">,</span> <span class="n">once</span> <span class="n">you</span> <span class="n">have</span> <span class="n">performed</span> <span class="n">a</span> <span class="n">cache</span> <span class="n">lookup</span><span class="p">,</span> <span class="n">you</span> <span class="n">can</span> <span class="nb">write</span> <span class="n">into</span>
+<span class="n">cache</span> <span class="n">with</span> <span class="sb">`INKCacheWrite`</span><span class="o">.</span> <span class="n">The</span> <span class="n">user</span>
+<span class="p">(</span><span class="sb">`<em class="replaceable"><code>contp`</span><span class="p">)</span> <span class="n">also</span> <span class="n">has</span> <span class="n">the</span> <span class="n">option</span> <span class="n">to</span>
+<span class="n">cancel</span> <span class="n">the</span> <span class="n">action</span> <span class="n">returned</span> <span class="n">by</span> <span class="sb">`INKCacheRead`</span> <span class="n">by</span> <span class="n">using</span>
+<span class="sb">`INKActionCancel`</span><span class="o">.</span>
+
+<span class="o">!</span><span class="p">[[</span><span class="n">Note</span><span class="p">]](</span><span class="n">images</span><span class="sr">/docbook/</span><span class="n">note</span><span class="o">.</span><span class="n">png</span><span class="p">)</span>
+<span class="n">Note</span>
+<span class="n">It</span> <span class="n">is</span> <span class="n">up</span> <span class="n">to</span> <span class="n">the</span> <span class="n">user</span> <span class="n">to</span> <span class="nb">read</span> <span class="n">the</span> <span class="n">data</span> <span class="n">from</span> <span class="n">the</span> <span class="n">cache</span> <span class="sb">`vc iobuffer`</span>
+<span class="ow">and</span> <span class="n">consume</span> <span class="n">it</span><span class="o">.</span> <span class="n">The</span> <span class="n">cache</span> <span class="n">does</span> <span class="ow">not</span> <span class="n">bufferize</span> <span class="n">the</span> <span class="n">data</span> <span class="ow">and</span> <span class="n">will</span> <span class="ow">not</span>
+<span class="n">call</span> <span class="n">the</span> <span class="n">user</span> <span class="n">back</span> <span class="k">unless</span> <span class="n">all</span> <span class="n">the</span> <span class="n">data</span> <span class="n">from</span> <span class="n">the</span> <span class="sb">`cache iobuffer`</span> <span class="n">is</span>
+<span class="n">consumed</span><span class="o">.</span>
+
+<span class="n">Reentrant</span> <span class="n">calls</span> <span class="n">are</span> <span class="n">possible</span><span class="p">;</span> <span class="n">in</span> <span class="n">other</span> <span class="n">words</span><span class="p">,</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">can</span> <span class="n">call</span>
+<span class="n">back</span> <span class="n">the</span> <span class="n">user</span> <span class="p">(</span><span class="sb">`<em class="replaceable"><code>contp`</span><span class="p">)</span> <span class="n">in</span> <span class="n">the</span> <span class="n">same</span>
+<span class="n">call</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ An <code>INKAction</code> object if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">argument</span> <span class="n">is</span> <span class="n">incorrect</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">the</span> <span class="n">API</span> <span class="n">failed</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheReady.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheReady.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheReady.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheReady.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,44 @@
<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="INKCacheRead">Prev</a> - INKCacheRead
+INKCacheWrite - <a href="INKCacheWrite">Next</a></p>
+<h3 id="inkcacheready">INKCacheReady</h3>
+<p>Determines if the Traffic Server cache is initialized and ready to
+accept requests for the specified data type.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKCacheReady (int *<em class="replaceable"><code>is_ready</code>)</p>
+<p><strong>Arguments</strong>
+ ~ If the cache is ready, then the
+ <code>int *<em class="replaceable"><code>is_ready</code> argument is set to a
+ non-zero value. It is set to 0 if the cache is not ready.</p>
+<p><strong>Description</strong>
+ ~ Asks the Traffic Server cache if it is initialized and ready to
+ accept requests. If the cache is not initialized, then any attempts
+ to read, write, or remove documents will fail.</p>
+<div class="codehilite"><pre><span class="n">When</span> <span class="n">a</span> <span class="n">plugin</span> <span class="n">starts</span> <span class="p">(</span><span class="n">i</span><span class="o">.</span><span class="n">e</span><span class="o">.</span><span class="p">,</span> <span class="n">when</span> <span class="n">its</span> <span class="sb">`INKPluginInit`</span> <span class="n">function</span> <span class="n">is</span>
+<span class="n">called</span><span class="p">),</span> <span class="n">there</span> <span class="n">is</span> <span class="nb">no</span> <span class="n">guarantee</span> <span class="n">that</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">is</span> <span class="n">already</span>
+<span class="n">initialized</span><span class="o">.</span> <span class="n">This</span> <span class="n">API</span> <span class="n">is</span> <span class="n">useful</span> <span class="k">if</span> <span class="n">a</span> <span class="n">plugin</span> <span class="n">needs</span> <span class="n">to</span> <span class="n">access</span> <span class="n">the</span>
+<span class="n">cache</span> <span class="n">from</span> <span class="n">the</span> <span class="sb">`INKPluginInit`</span> <span class="n">function</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">ready</span><span class="p">,</span>
+<span class="k">then</span> <span class="n">the</span> <span class="n">plugin</span> <span class="n">should</span> <span class="n">retry</span> <span class="n">later</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">this</span> <span class="n">function</span> <span class="n">cannot</span> <span class="n">be</span> <span class="n">set</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">it</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheRemove.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheRemove.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheRemove.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/INKCacheRemove.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,69 @@
<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="INKCacheWrite">Prev</a> - INKCacheWrite
+INKCacheKeyPinnedSet - <a href="INKCacheKeyPinnedSet">Next</a></p>
+<h3 id="inkcacheremove">INKCacheRemove</h3>
+<p>Removes an object from the Traffic Server cache.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKAction INKCacheRemove (INKCont <em class="replaceable"><code>contp</code>,
+ INKCacheKey <em><code>key</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCont</code> <code><em class="replaceable"><code>contp</code> is the
+ continuation the cache calls back when reporting the success or
+ failure of the remove.</p>
+<div class="codehilite"><pre><span class="sb">`INKCacheKey`</span> <span class="sb">`<em class="replaceable"><code>key`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">key</span>
+<span class="n">that</span> <span class="n">corresponds</span> <span class="n">to</span> <span class="n">the</span> <span class="n">object</span> <span class="n">tol</span> <span class="n">be</span> <span class="n">removed</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Removes the object corresponding to
+ <code><em class="replaceable"><code>key</code> from the cache.</p>
+<div class="codehilite"><pre><span class="n">If</span> <span class="n">the</span> <span class="n">object</span> <span class="n">was</span> <span class="n">removed</span> <span class="n">successfully</span><span class="p">,</span> <span class="k">then</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">calls</span>
+<span class="sb">`<em class="replaceable"><code>contp`</span> <span class="n">back</span> <span class="n">with</span> <span class="n">the</span> <span class="n">event</span>
+<span class="sb">`INK_EVENT_CACHE_REMOVE`</span><span class="o">.</span>
+
+<span class="n">If</span> <span class="n">the</span> <span class="n">object</span> <span class="n">was</span> <span class="ow">not</span> <span class="n">found</span> <span class="n">in</span> <span class="n">the</span> <span class="n">cache</span><span class="p">,</span> <span class="k">then</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">calls</span>
+<span class="sb">`<em class="replaceable"><code>contp`</span> <span class="n">back</span> <span class="n">with</span> <span class="n">the</span> <span class="n">event</span>
+<span class="sb">`INK_EVENT_CACHE_REMOVE_FAILED`</span><span class="o">.</span> <span class="n">An</span> <span class="n">error</span> <span class="n">code</span> <span class="n">is</span> <span class="n">passed</span> <span class="n">in</span> <span class="n">the</span>
+<span class="sb">`void *edata`</span> <span class="n">argument</span> <span class="n">of</span> <span class="sb">`<em class="replaceable"><code>contp`</span><span class="o">.</span>
+<span class="n">The</span> <span class="n">error</span> <span class="n">code</span> <span class="n">can</span> <span class="n">be:</span>
+
+<span class="o">-</span> <span class="sb">`INK_CACHE_ERROR_NOT_READY`</span><span class="p">:</span> <span class="n">tried</span> <span class="n">to</span> <span class="n">access</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">before</span>
+ <span class="n">it</span> <span class="n">was</span> <span class="n">initialized</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="sb">`INK_CACHE_ERROR_NO_DOC`</span><span class="p">:</span> <span class="n">doc</span> <span class="n">doesn</span><span class="err">'</span><span class="n">t</span> <span class="n">exist</span> <span class="n">in</span> <span class="n">cache</span>
+
+<span class="o">-</span> <span class="n">any</span> <span class="n">other</span> <span class="n">value:</span> <span class="n">unknown</span> <span class="n">remove</span> <span class="n">failure</span>
+
+<span class="n">In</span> <span class="n">both</span> <span class="n">of</span> <span class="n">these</span> <span class="n">callbacks</span><span class="p">,</span> <span class="n">the</span> <span class="n">user</span> <span class="n">does</span> <span class="ow">not</span> <span class="n">have</span> <span class="n">to</span> <span class="k">do</span> <span class="n">anything</span><span class="o">.</span>
+<span class="n">The</span> <span class="n">user</span> <span class="n">does</span> <span class="ow">not</span> <span class="n">get</span> <span class="n">a</span> <span class="n">vconnection</span> <span class="n">from</span> <span class="n">the</span> <span class="n">cache</span><span class="p">,</span> <span class="n">since</span> <span class="nb">no</span> <span class="n">data</span>
+<span class="n">needs</span> <span class="n">to</span> <span class="n">be</span> <span class="n">transferred</span><span class="o">.</span> <span class="n">When</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">calls</span> <span class="n">the</span> <span class="n">user</span> <span class="n">back</span> <span class="n">with</span>
+<span class="sb">`INK_EVENT_CACHE_REMOVE`</span><span class="p">,</span> <span class="n">the</span> <span class="n">remove</span> <span class="n">has</span> <span class="n">already</span> <span class="n">been</span> <span class="n">committed</span><span class="o">.</span>
+
+<span class="o">!</span><span class="p">[[</span><span class="n">Note</span><span class="p">]](</span><span class="n">images</span><span class="sr">/docbook/</span><span class="n">note</span><span class="o">.</span><span class="n">png</span><span class="p">)</span>
+<span class="n">Note</span>
+<span class="n">Reentrant</span> <span class="n">calls</span> <span class="n">are</span> <span class="n">possible</span><span class="p">,</span> <span class="n">i</span><span class="o">.</span><span class="n">e</span><span class="o">.</span> <span class="n">the</span> <span class="n">cache</span> <span class="n">can</span> <span class="n">call</span> <span class="n">back</span> <span class="n">the</span> <span class="n">user</span>
+<span class="p">(</span><span class="sb">`contp`</span><span class="p">)</span> <span class="n">in</span> <span class="n">the</span> <span class="n">same</span> <span class="n">call</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ An <code>INKAction</code> object if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">argument</span> <span class="n">is</span> <span class="n">incorrect</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">the</span> <span class="n">API</span> <span class="n">fails</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">