You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bu...@apache.org on 2013/12/24 19:32:22 UTC
svn commit: r891679 [14/24] - in /websites/staging/trafficserver/trunk:
cgi-bin/ content/ content/docs/ content/docs/trunk/
content/docs/trunk/admin/ content/docs/trunk/admin/cluster-howto/
content/docs/trunk/admin/configuration-files/ content/docs/tru...
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPTransformationPlugins.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPTransformationPlugins.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPTransformationPlugins.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,137 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 5. HTTP Transformation Plugins</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="SetTransactionHook.html">Prev</a> - Setting a Transaction Hook</div>
+<div class="navnext">The Sample Null Transform Plugin - <a accesskey="n" href="SampleNullTransformPlugin.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HTTPTransformationPlugins"></a>Chapter 5. HTTP Transformation Plugins</h2></div></div></div>
+<p>Transform plugins examine or transform HTTP message body content.
+ For example, transform plugins can:</p>
+<div class="itemizedlist"><ul type="disc">
+<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></div>
+<p>This chapter explains how to write transform plugins. The
+ following examples are discussed in detail:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="SampleNullTransformPlugin.html" title="The Sample Null Transform Plugin">Sample Null Transform Plugin</a></p></li>
+<li><a href="AppendTransformPlugin.html" title="The Append-Transform Plugin">Append-Transform Plugin</a></li>
+<li><p><a href="SampleBufferedNullTransformPlugin.html" title="The Sample Buffered Null Transform Plugin">Sample Buffered Null Transform Plugin</a></p></li>
+</ul></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="WritingContentTransformPlugins"></a>Writing Content Transform Plugins<a class="indexterm" name="id374305"></a></h2></div></div></div>
+<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 <i>and</i> 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 <span class="emphasis"><b>vconnection</b></span> 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
+ <span class="emphasis"><b>transformation</b></span><a class="indexterm" name="id374327"></a> 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 class="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 <b>VIO</b><a class="indexterm" name="id374345"></a> is a description of an IO operation that is in progress. Every
+ vconnection has an associated <i>input VIO</i> and an associated <i>output VIO</i>.
+ 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 <b>write VIO</b><a class="indexterm" name="id374354"></a> because the input VIO refers to a write operation
+ performed on the vconnection itself. Similarly, the outpt VIO is also
+ called the <b>read VIO</b><a class="indexterm" name="id374362"></a>. 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>
+<div class="figure">
+<a name="Fig_TransformationAndVIOs"></a><p class="title"><b>Figure 5.1. A Transformation and its VIOs</b></p>
+<div class="mediaobject"><img src="images/vconnection.jpg" alt="A Transformation and its VIOs" /></div>
+</div>
+<p>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.html#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 <b>nbytes</b> value in the VIO is the total number of bytes to be written.
+ The <b>ndone</b> 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 <i>implementor's side </i>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 <i>user's side </i>refers to how to use a vconnection
+ to read or write data. At the very least, transformations output (write) data.</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="Transformations"></a>Transformations</h3></div></div></div>
+<p></p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="VIOs"></a>VIOs</h3></div></div></div>
+<p>A <b>VIO</b> 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 class="code">INKVIO<a class="indexterm" name="id374498"></a></code> data structure itself is opaque, but it might
+ have been defined as follows:</p>
+<pre class="programlisting">typedef struct {
+ INKCont continuation;
+ INKVConn vconnection;
+ INKIOBufferReader reader;
+ INKMutex mutex;
+ int nbytes;
+ int ndone;
+} *INKVIO;</pre>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="IOBuffers"></a>IO Buffers</h3></div></div></div>
+<p>The <b>IO buffer</b> 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 <i>buffer block</i> (<code class="code">INKIOBufferBlock</code>) and <i>buffer data</i> (<code class="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 class="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 class="code">INKIOBufferReader</code> data structure. Since only a single
+ writer is allowed, there is no corresponding
+ <code class="code">INKIOBufferWriter</code> data structure. The writer simply
+ modifies the IO buffer directly.</p>
+</div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTPTransformationPlugins.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTP_Transactions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTP_Transactions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTP_Transactions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,183 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>HTTP Transactions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="HTTPSessions.html">Prev</a> - HTTP Sessions</div>
+<div class="navnext">Intercepting HTTP Transactions - <a accesskey="n" href="InterceptingHTTPTx.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HTTP_Transactions"></a>HTTP Transactions</h2></div></div></div>
+<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 <b>HTTP transaction</b> is an object defined for the lifetime of a single request from a client
+ and the corresponding response from Traffic Server. The <code class="function"><b>INKHttpTxn</b></code><a class="indexterm" name="id378960"></a> 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>
+<pre class="programlisting">/*
+* Simple plugin that illustrates:
+* - how to register locally to a transaction
+* - how to deal with data that's associated with a tranaction
+*
+* Note: for readability, error checking is omitted
+*/
+
+#include <ts/ts.h>
+
+#define DBG_TAG "txn"
+
+/* Structure to be associated to txns */
+typedef struct {
+ int i;
+ float f;
+ char *s;
+} TxnData;
+
+/* Allocate memory and init a TxnData structure */
+TxnData *
+txn_data_alloc()
+{
+ TxnData *data;
+ data = INKmalloc(sizeof(TxnData));
+
+ data->i = 1;
+ data->f = 0.5;
+ data->s = "Constant String";
+ return data;
+}
+
+/* Free up a TxnData structure */
+void
+txn_data_free(TxnData *data)
+{
+ INKfree(data);
+}
+
+/* Handler for event READ_REQUEST and TXN_CLOSE */
+static int
+local_hook_handler (INKCont contp, INKEvent event, void *edata)
+{
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+ TxnData *txn_data = INKContDataGet(contp);
+ switch (event) {
+ case INK_EVENT_HTTP_READ_REQUEST_HDR:
+ /* Modify values of txn data */
+ txn_data->i = 2;
+ txn_data->f = 3.5;
+ txn_data->s = "Constant String 2";
+ break;
+
+ case INK_EVENT_HTTP_TXN_CLOSE:
+ /* Print txn data values */
+ INKDebug(DBG_TAG, "Txn data i=%d f=%f s=%s", txn_data->i, txn_data->f,
+ txn_data->s);
+
+ /* Then destroy the txn cont and its data */
+ txn_data_free(txn_data);
+ INKContDestroy(contp);
+ break;
+
+ default:
+ INKAssert(!"Unexpected event");
+ break;
+ }
+
+ INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE);
+ return 1;
+}
+
+/* Handler for event TXN_START */
+static int
+global_hook_handler (INKCont contp, INKEvent event, void *edata)
+{
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+ INKCont txn_contp;
+ TxnData *txn_data;
+
+ switch (event) {
+ case INK_EVENT_HTTP_TXN_START:
+ /* Create a new continuation for this txn and associate data to it */
+ txn_contp = INKContCreate(local_hook_handler, INKMutexCreate());
+ txn_data = txn_data_alloc();
+ INKContDataSet(txn_contp, txn_data);
+
+ /* Registers locally to hook READ_REQUEST and TXN_CLOSE */
+ INKHttpTxnHookAdd(txnp, INK_HTTP_READ_REQUEST_HDR_HOOK, txn_contp);
+ INKHttpTxnHookAdd(txnp, INK_HTTP_TXN_CLOSE_HOOK, txn_contp);
+ break;
+
+ default:
+ INKAssert(!"Unexpected event");
+ break;
+ }
+
+ INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE);
+ return 1;
+}
+
+
+void
+INKPluginInit (int argc, const char *argv[])
+{
+ INKCont contp;
+
+ /* Note that we do not need a mutex for this txn since it registers globally
+ and doesn't have any data associated with it */
+ contp = INKContCreate(global_hook_handler, NULL);
+
+ /* Register gloabally */
+ INKHttpHookAdd(INK_HTTP_TXN_START_HOOK, contp);
+}</pre>
+<p>See <a href="AddingHooks.html" title="Adding Hooks">Adding Hooks</a> for background about HTTP
+ transactions and HTTP hooks, as well as <a href="HTTPHooksAndTransactions.html" title="Chapter 8. HTTP Hooks and Transactions">HTTP Hooks and Transactions</a>. Also see the <a href="HTTPHooksAndTransactions.html#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>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnCacheLookupStatusGet" title="INKHttpTxnCacheLookupStatusGet">INKHttpTxnCacheLookupStatusGet</a></p></li>
+<li>
+ <p><a href="HTTPTransactionFunctions.html#INKHttpTxnCachedReqGet" title="INKHttpTxnCachedReqGet">INKHttpTxnCachedReqGet</a> - Note that it is an
+ error to modify cached headers.</p></li>
+<li>
+ <p><a href="HTTPTransactionFunctions.html#INKHttpTxnCachedRespGet" title="INKHttpTxnCachedRespGet">INKHttpTxnCachedRespGet</a> - Note that it is an
+ error to modify cached headers.</p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnClientIncomingPortGet" title="INKHttpTxnClientIncomingPortGet">INKHttpTxnClientIncomingPortGet</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnClientIPGet" title="INKHttpTxnClientIPGet">INKHttpTxnClientIPGet</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnClientRemotePortGet" title="INKHttpTxnClientRemotePortGet">INKHttpTxnClientRemotePortGet</a></p></li>
+<li>
+ <p><a href="HTTPTransactionFunctions.html#INKHttpTxnClientReqGet" title="INKHttpTxnClientReqGet">INKHttpTxnClientReqGet</a> - Plugins that must
+ read client request headers use this call to retrieve the HTTP
+ header.</p></li>
+<li>
+ <p><a href="HTTPTransactionFunctions.html#INKHttpTxnClientRespGet" title="INKHttpTxnClientRespGet">INKHttpTxnClientRespGet</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnErrorBodySet" title="INKHttpTxnErrorBodySet">INKHttpTxnErrorBodySet</a></p></li>
+<li>
+ <p><a href="HTTPTransactionFunctions.html#INKHttpTxnHookAdd" title="INKHttpTxnHookAdd">INKHttpTxnHookAdd</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnNextHopIPGet" title="INKHttpTxnNextHopIPGet">INKHttpTxnNextHopIPGet</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnNextHopIPGet" title="INKHttpTxnNextHopIPGet">INKHttpTxnNextHopIPGet</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnParentProxySet" title="INKHttpTxnParentProxySet">INKHttpTxnParentProxySet</a></p></li>
+<li>
+ <p><a href="HTTPTransactionFunctions.html#INKHttpTxnReenable" title="INKHttpTxnReenable">INKHttpTxnReenable</a></p></li>
+<li>
+ <p><a href="HTTPTransactionFunctions.html#INKHttpTxnServerIPGet" title="INKHttpTxnServerIPGet">INKHttpTxnServerIPGet</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnServerReqGet" title="INKHttpTxnServerReqGet">INKHttpTxnServerReqGet</a></p></li>
+<li>
+ <p><a href="HTTPTransactionFunctions.html#INKHttpTxnServerRespGet" title="INKHttpTxnServerRespGet">INKHttpTxnServerRespGet</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnSsnGet" title="INKHttpTxnSsnGet">INKHttpTxnSsnGet</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnTransformedRespCache" title="INKHttpTxnTransformedRespCache">INKHttpTxnTransformedRespCache</a></p></li>
+<li><p><a href="HTTPTransactionFunctions.html#INKHttpTxnTransformRespGet" title="INKHttpTxnTransformRespGet">INKHttpTxnTransformRespGet</a></p></li>
+<li>
+ <p><a href="HTTPTransactionFunctions.html#INKHttpTxnUntransformedRespCache" title="INKHttpTxnUntransformedRespCache">INKHttpTxnUntransformedRespCache</a></p></li>
+</ul></div>
+</div>
+</body>
+</html>
+
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HTTP_Transactions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HeaderBasedPluginEx.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HeaderBasedPluginEx.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HeaderBasedPluginEx.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,84 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 4. Header-Based Plugin Examples</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="ch03s02.html">Prev</a> - API Function Reference</div>
+<div class="navnext">The Blacklist Plugin - <a accesskey="n" href="BlacklistPlugin.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HeaderBasedPluginEx"></a>Chapter 4. Header-Based Plugin Examples</h2></div></div></div>
+
+<p><b>Table of Contents</b></p>
+<ul><li><span class="section"><a href="BlacklistPlugin.html">The Blacklist Plugin</a></span></li>
+ <ul>
+ <li><span class="section"><a href="BlacklistPlugin.html#CreatingParentContinuation">Creating the Parent Continuation</a></span></li>
+ <li><span class="section"><a href="SettingGlobalHook.html">Setting a Global Hook</a></span></li>
+ <li><span class="section"><a href="SettingUpUIUpdateCallbacks.html">Setting Up UI Update Callbacks</a></span></li>
+ <li><span class="section"><a href="AccessingTransactionProc.html">Accessing the Transaction Being Processed</a></span></li>
+ <li><span class="section"><a href="SettingUpTransacHook.html">Setting Up a Transaction Hook</a></span></li>
+ <li><span class="section"><a href="WorkWHTTPHeaderFunc.html">Working with HTTP Header Functions</a></span></li>
+ </ul>
+</ul>
+
+
+<ul><li><span class="section"><a href="BasicAuthorizatonPlugin.html">The Basic Authorization Plugin</a></span></li>
+<ul>
+<li><span class="section"><a href="BasicAuthorizatonPlugin.html#CreatePluginParentCont_GlHk">Creating the Plugin's Parent Continuation and Global
+ Hook</a></span></li>
+<li><span class="section"><a href="ImplementHandler_GetTransHandle.html">Implementing the Handler and Getting a Handle to the
+ Transaction</a></span></li>
+<li><span class="section"><a href="WorkWithHTTPHeaders.html">Working With HTTP Headers</a></span></li>
+<li><span class="section"><a href="SetTransactionHook.html">Setting a Transaction Hook</a></span></li>
+</ul>
+</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>
+<div class="itemizedlist"><ul type="disc">
+<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 class="filename">blacklist-1.c</code> and
+ <code class="filename">basic-auth.c</code>.</p></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HeaderBasedEx_Overview"></a>Overview</h2></div></div></div>
+<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>
+<div class="itemizedlist">
+ <ul type="disc"><em></em>
+<li><p>The plugin has a static parent continuation that scans all
+ Traffic Server headers (either request headers, response headers, or
+ both).</p></li>
+<li><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></li>
+<li><p>The plugin gets a handle to the transaction being processed
+ through the global hook.</p></li>
+<li><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></li>
+<li>
+ <p>The plugin obtains client header information and does
+ something based on that information.</p></li></ul></div>
+<p>This chapter demonstrates how these components
+ are implemented in SDK sample code.</p>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HeaderBasedPluginEx.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HostLookupFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HostLookupFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HostLookupFunctions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,90 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Host Lookup Functions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKActionDone.html">Prev</a> - INKActionDone</div>
+<div class="navnext">INKHostLookupResultIPGet - <a accesskey="n" href="INKHostLookupResultIPGet.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HostLookupFunctions"></a>Host Lookup Functions</h2></div></div></div>
+
+
+<ul><b>
+<li><a href="HostLookupFunctions.html#INKHostLookup">INKHostLookup</a></li>
+<li><a href="INKHostLookupResultIPGet.html">INKHostLookupResultIPGet</a></li>
+</b>
+</ul>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKHostLookup"></a>INKHostLookup</h3></div></div></div>
+<p>Instructs Traffic Server to do a DNS lookup on a host name.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKAction INKHostLookupResult (INKCont
+ <em class="replaceable"><code>contp</code></em>, char
+ *<em class="replaceable"><code>hostname</code></em>, int
+ <em class="replaceable"><code>namelen</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="function">INKCont</code>
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is the
+ continuation Traffic Server calls back when the DNS lookup
+ occurs.</p>
+<p><code class="code">char
+ *</code><code class="code"><em class="replaceable"><code>hostname </code></em></code> is the
+ name to look up. Null-terminated.</p>
+<p><code class="code">int
+ </code><code class="code"><em class="replaceable"><code>namelen </code></em></code> is the
+ length of <code class="code"><em class="replaceable"><code>hostname </code></em></code> +1
+ (add one to account for null termination).</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Initiates a DNS lookup of
+ <code class="code"><em class="replaceable"><code>hostname</code></em></code>. When the
+ lookup occurs, Traffic Server sends contp
+ <code class="code">INK_EVENT_DNS_LOOKUP</code>. If the lookup is successful
+ (IP address resolved), then the <code class="code">void *
+ </code><code class="code"><em class="replaceable"><code>data </code></em></code> passed to
+ the handler of the continuation
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is a data of type
+ <code class="function">INKHostLookupResult</code>. You can then use
+ <code class="function">INKHostLookupResultIPGet</code> to convert this
+ information to an unsigned <code>int</code> representing the IP
+ address.</p>
+<p>If the lookup fails (IP address not resolved), then the
+ <code class="code">void *</code> <code class="code"><em class="replaceable"><code>data </code></em></code>
+ passed to the handler of continuation
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is a null
+ pointer.</p>
+<p>You have the option to cancel the action returned by
+ <code class="function">INKHostLookup</code> by using
+ <code class="function">INKActionCancel</code>.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>Reentrant calls are possible; i.e., the cache can call
+ back the user (<code class="code">contp</code>) in the same call.</p></td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>An <code class="function">INKAction</code> object if
+ successful.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an argument is incorrect or
+ if the API fails.</p>
+</dd>
+</dl></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HostLookupFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HostsLookupAPI.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/HostsLookupAPI.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/HostsLookupAPI.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,26 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Hosts Lookup API</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="ActionsGuide.html">Prev</a> - Chapter 14. Actions Guide</div>
+<div class="navnext">Chapter 15. IO Guide - <a accesskey="n" href="IOGuide.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="HostsLookupAPI"></a>Hosts Lookup API</h2></div></div></div>
+<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>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="HostLookupFunctions.html#INKHostLookup" title="INKHostLookup"><code>INKHostLookup</code></a></li>
+<li><code><a href="INKHostLookupResultIPGet.html" title="INKHostLookupResultIPGet">INKHostLookupResultIPGet</a></code></li>
+</ul></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/HostsLookupAPI.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKActionDone.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKActionDone.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKActionDone.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,62 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKActionDone</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="ActionFunctions.html">Prev</a> - Action Functions: INKActionCancel</div>
+<div class="navnext">Host Lookup Functions - <a accesskey="n" href="HostLookupFunctions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKActionDone"></a>INKActionDone</h3></div></div></div>
+<p>Indicates whether an action is completed.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKActionDone (INKAction
+ <em class="replaceable"><code> actionp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p><code class="code"><em class="replaceable"><code>actionp </code></em></code>
+ is a completed action. If a <code class="code">NULL</code> argument is passed to
+ <code class="function">INKActionDone</code>, then Traffic Server crashes
+ and does not return <code class="code">INK_ERROR</code>. </p>
+</dd>
+<dd>
+ <p><b>Note:</b> It is the
+ programmer's responsibility to ensure that a non-null value is
+ passed to <code>INKActionDone</code>.</p>
+ <div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important">
+ <tr>
+ <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/docbook/important.png" /></td>
+ <th align="left">Important</th>
+ </tr>
+ <tr><td align="left" valign="top">
+ <p>Always use <code class="function">INKActionDone</code>
+ immediately after the call that assigns the action. <br> For
+ example:</p>
+ <pre class="programlisting">actionp = INKContSchedule(contp, SOME_TIMEOUT_VALUE);
+if (INKActionDone(actionp)){
+ //event has already occurred
+ }</pre>
+ </td></tr>
+ </table></div>
+ <p>If you call
+ <code class="function">INKActionDone</code><code>(<em class="replaceable">actionp</em>)</code>
+ some time later or somewhere else, then it always returns <code>false</code> and
+ therefore does not accurately reflect whether the action has
+ completed.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code>0</code> if the action has not completed.</p>
+<p><code>1</code> if the action has completed.</p>
+<p><code class="code">INK_ERROR</code> if an error has occurred.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKActionDone.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKAssert.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKAssert.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKAssert.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,51 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKAssert</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKError.html">Prev</a> - INKError</div>
+<div class="navnext">INKReleaseAssert - <a accesskey="n" href="INKReleaseAssert.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKAssert"></a>INKAssert</h3></div></div></div>
+<p>Enables the use of assertion in a plugin.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">void
+ INKAssert(<em class="replaceable"><code>expression</code></em>); </code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+ <p>A Boolean expression.</p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>In <code>debug</code> mode, causes the Traffic Server to print the file
+ name, line number, and expression before it aborts.</p>
+<p>In <code>optim</code> mode, the expression is <u>not</u> removed, but the
+ effects of printing an error message and aborting are. This is an
+ artifact of the way the system assert is normally used and
+ permits:</p>
+<pre class="programlisting">ink_assert(!setsockopt(...));
+</pre>
+<p><b>Note:</b> when using the system "assert", you do not need
+ to worry about the condition since the code will be 'dead code
+ eliminated' by the compiler; with <code class="code">INKAssert</code>, you
+ do.</p>
+</dd>
+<dt><span class="term"><b>Example</b></span></dt>
+<dd><pre class="programlisting">switch (event) {
+case EVENT_IMMEDIATE:
+....
+default:
+INKAssert (!setsockopt(...));
+break;
+}</pre>
+ </dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKAssert.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyDestroy.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyDestroy.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyDestroy.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,41 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKCacheKeyDestroy</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKCacheKeyHostNameSet.html">Prev</a> - INKCacheKeyHostNameSet</div>
+<div class="navnext">INKCacheRead - <a accesskey="n" href="INKCacheRead.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKCacheKeyDestroy"></a>INKCacheKeyDestroy</h3></div></div></div>
+<p>Destroys a cache key.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKCacheKeyDestroy(INKCacheKey
+ <em class="replaceable"><code>key</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="function">INKCacheKey</code>
+ <code class="code"><em class="replaceable"><code>key </code></em></code> is the key to be
+ destroyed.</p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>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></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the cache key was successfully
+ destroyed.</p>
+<p><code class="code">INK_ERROR</code> if the cache key could not be deallocated or
+ was not valid.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyDestroy.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyDigestSet.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyDigestSet.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyDigestSet.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,61 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKCacheKeyDigestSet</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="CacheInterfaceFunctions.html">Prev</a> - Cache Interface Fxns: INKCacheKeyCreate, INKSetCacheUrl</div>
+<div class="navnext">INKCacheKeyHostNameSet - <a accesskey="n" href="INKCacheKeyHostNameSet.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKCacheKeyDigestSet"></a>INKCacheKeyDigestSet</h3></div></div></div>
+<p>Generates and assigns a cache key to an object that will be
+ cached.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKCacheKeyDigestSet(INKCacheKey
+ <em class="replaceable"><code>key</code></em>, const unsigned char
+ *<em class="replaceable"><code>input</code></em>, int
+ <em class="replaceable"><code>length</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="function">INKCacheKey</code>
+ <code class="code"><em class="replaceable"><code>key </code></em></code> is the key that will be
+ associated with the cached object. Before calling
+ <code class="function">INKCacheKeyDigestSet</code>, you must create the
+ key with <code class="function">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 class="function">INKCacheKeyCreate</code> generates identical
+ keys.</p>
+<p><code class="code">const unsigned char
+ *</code><code class="code"><em class="replaceable"><code>input </code></em></code> is a
+ character string that uniquely identifies the object. In most
+ cases, it's the URL of the object.</p>
+<p><code class="code">int
+ </code><code class="code"><em class="replaceable"><code>length </code></em></code> is the
+ length of the input string.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Generates and assigns a cache key to the object to be
+ cached.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the cache key is successfully
+ generated.</p>
+<p><code class="code">INK_ERROR</code> if <code class="function">INKCacheKeyDigestSet</code> cannot be set.</p>
+</dd>
+<dt><span class="term"><b>Example</b></span></dt>
+<dd><pre class="programlisting">const char *digest_string = "mydigest"
+INKCacheKey mykey;
+INKCacheKeyCreate(&mykey);
+INKCacheKeyDigestSet(mykey,digest_string, strlen(digest_string);</pre></dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyDigestSet.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyHostNameSet.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyHostNameSet.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyHostNameSet.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,51 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKCacheKeyHostNameSet</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKCacheKeyDigestSet.html">Prev</a> - INKCacheKeyDigestSet</div>
+<div class="navnext">INKCacheKeyDestroy - <a accesskey="n" href="INKCacheKeyDestroy.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKCacheKeyHostNameSet"></a>INKCacheKeyHostNameSet</h3></div></div></div>
+<p>Associates a host name to a cache key. Use if you want to
+ support cache partitioning by host name.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKCacheKeyHostNameSet(INKCacheKey
+ <em class="replaceable"><code>key</code></em>, const unsigned char
+ <em class="replaceable"><code>*hostname</code></em>, int
+ <em class="replaceable"><code>host_len</code></em>;</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code>INKCacheKey</code> <code class="code"><em class="replaceable"><code>key </code></em></code> is
+ the key to the cached object.</p>
+<p><code class="code">const unsigned char <em class="replaceable"><code>*hostname</code></em> <i> </i></code> is
+ the host name you are associating with the cache key.</p>
+<p><code class="code">int <em class="replaceable"><code>host_len </code></em></code> is
+ the length of the string
+ <code class="code"><em class="replaceable"><code>hostname</code></em></code>.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Associates a host name to a cache key. The host name
+ setting is used in conjunction with the Traffic Server configuration files
+ <code class="filename">partition.config</code> and
+ <code class="filename">hosting.config</code> that enable you to specify
+ under which cache partition the object should be stored.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the <code class="code"><em class="replaceable"><code> hostname </code></em></code> is successfully
+ associated with the cache key.</p>
+<p><code class="code">INK_ERROR</code> if <code class="code"><em class="replaceable"><code>hostname</code></em> </code>cannot
+ be set or is invalid.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyHostNameSet.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyPinnedSet.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyPinnedSet.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyPinnedSet.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,74 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKCacheKeyPinnedSet</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKCacheRemove.html">Prev</a> - INKCacheRemove</div>
+<div class="navnext">INKVConnCacheObjectSizeGet - <a accesskey="n" href="INKVConnCacheObjectSizeGet.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKCacheKeyPinnedSet"></a>INKCacheKeyPinnedSet</h3></div></div></div>
+<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>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKCacheKeyPinnedSet (INKCacheKey
+ <em class="replaceable"><code>key</code></em>, time_t
+ <em class="replaceable"><code>pin_in_cache</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code>INKCacheKey</code> <code class="code"><em class="replaceable"><code>key </code></em></code> is
+ the cache key for the document to be pinned.</p>
+<p><code class="code">time_t
+ <em class="replaceable"><code>pin_in_cache </code></em></code> represents the
+ number of seconds the document is to be pinned in the
+ cache.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Pins the document corresponding to the specified
+ <code class="code"><em class="replaceable"><code>key</code></em></code> in the cache for the
+ specified number of seconds specified in
+ <code class="code"><em class="replaceable"><code>pin_in_cache</code></em></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 class="code"><em class="replaceable"><code>pin_in_cache </code></em></code>
+ interval has expired, the cache may delete the document at any
+ time in order to reclaim space.</p>
+<p>To delete this document before the <code class="code"><em class="replaceable"><code>pin_in_cache</code></em> </code>interval expires, call the <code class="function">INKCacheRemove()</code> function with the
+ document's cache key. </p>
+<p><code class="methodname">InkCacheKeyPinnedSet()</code> should be
+ used after a key is created and before writing the document to
+ cache using <code>I</code><code class="methodname">NKCacheWrite()</code>.</p>
+<p>Because a document is not pinned in the cache by default, it
+ can be garbage-collected at anytime.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>It is important that the
+ <code class="filename">records.config</code> variable
+ <code class="varname"><i>proxy.config.cache.permit.pinning </i></code> (in <code class="filename">records.config</code>) is set to
+ 1 to enable
+ pinning.</p></td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the specified object was
+ successfully pinned in the cache.</p>
+<p><code class="code">INK_ERROR</code> if the pin could not be set or is
+ invalid.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheKeyPinnedSet.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheRead.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheRead.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheRead.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,105 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKCacheRead</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKCacheKeyDestroy.html">Prev</a> - INKCacheKeyDestroy</div>
+<div class="navnext">INKCacheReady - <a accesskey="n" href="INKCacheReady.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKCacheRead"></a>INKCacheRead</h3></div></div></div>
+<p>Initiates a cache read or lookup of an object in the Traffic
+ Server cache.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKAction INKCacheRead (INKCont
+ <em class="replaceable"><code>contp</code></em>, INKCacheKey
+ <em class="replaceable"><code>key</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="function">INKCont</code>
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is the
+ continuation the cache calls back (telling it whether the
+ object exists and can be read).</p>
+<p><code class="function">INKCacheKey</code>
+ <code class="code"><em class="replaceable"><code>key </code></em></code> is the cache key
+ corresponding to the object to be read.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Asks the Traffic Server cache if the object corresponding
+ to <code class="code"><em class="replaceable"><code>key </code></em></code> exists in the
+ cache and can be read.</p>
+<p>You can do a cache lookup to determine whether or not an
+ object is in the cache. To do a cache lookup, call
+ <code class="function">INKCacheRead</code> on a continuation
+ <code class="code"><em class="replaceable"><code>contp</code></em></code>. If the object can
+ be read, then the cache calls
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> back with the
+ event <code class="code">INK_EVENT_CACHE_OPEN_READ</code>. In this case, the
+ cache also passes <code class="code"><em class="replaceable"><code>contp </code></em></code>
+ a cache vconnection;
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> can then initiate
+ a read operation on that vconnection using
+ <code class="function">INKVConnRead</code>.
+ <code class="function">INKVConnCacheObjectSizeGet</code> can be used to
+ determine the size of the object in the cache.</p>
+<p>If the object cannot be read (if, for instance, it is not
+ in the cache), then the cache calls
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> back with the
+ event <code class="code">INK_EVENT_CACHE_OPEN_READ_FAILED</code>. An error
+ code is passed in the <code class="code">void *edata</code> argument of
+ <code class="code"><em class="replaceable"><code>contp</code></em></code>. The error code
+ can be:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p><code class="code">INK_CACHE_ERROR_NOT_READY</code>: trying to
+ access to the cache while it's not yet initialized.</p></li>
+<li>
+ <p><code class="code">INK_CACHE_ERROR_NO_DOC</code>: document does not
+ exist in cache.</p></li>
+<li>
+ <p><code class="code">INK_CACHE_ERROR_DOC_BUSY</code>: trying to read
+ a document while another continuation is writing on
+ it.</p></li>
+<li><p>Any other value: unknown read failure</p></li>
+</ul></div>
+<p>Finally, once you have performed a cache lookup, you can
+ write into cache with <code class="function">INKCacheWrite</code>. The
+ user (<code class="code"><em class="replaceable"><code>contp</code></em></code>) also has
+ the option to cancel the action returned by
+ <code class="function">INKCacheRead</code> by using
+ <code class="function">INKActionCancel</code>.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>It is up to the user to read the data from the cache
+ <code class="code">vc iobuffer</code> and consume it. The cache does not
+ bufferize the data and will not call the user back
+ unless all the data from the <code class="code">cache iobuffer</code> is
+ consumed.</p>
+<p>Reentrant calls are possible; in other words, the cache
+ can call back the user (<code class="code"><em class="replaceable"><code>contp</code></em></code>) in the same
+ call.</p>
+</td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>An <code class="function">INKAction</code> object if
+ successful.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an argument is incorrect or
+ if the API failed.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheRead.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheReady.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheReady.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheReady.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKCacheReady</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKCacheRead.html">Prev</a> - INKCacheRead</div>
+<div class="navnext">INKCacheWrite - <a accesskey="n" href="INKCacheWrite.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKCacheReady"></a>INKCacheReady</h3></div></div></div>
+<p>Determines if the Traffic Server cache is initialized and ready
+ to accept requests for the specified data type.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKCacheReady (int
+ *<em class="replaceable"><code>is_ready</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+ <p>If the cache is ready, then the <code class="code">int *<em class="replaceable"><code>is_ready </code></em></code>
+ argument is set to a non-zero value. It is set to 0 if the cache is not
+ ready.</p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>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>
+<p>When a plugin starts (i.e., when its
+ <code class="function">INKPluginInit</code> function is called), there is
+ no guarantee that the cache is already initialized. This API is
+ useful if a plugin needs to access the cache from the
+ <code class="function">INKPluginInit</code> function. If the cache is not
+ ready, then the plugin should retry later.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if this function cannot be set or
+ if it is invalid.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheReady.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheRemove.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheRemove.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheRemove.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,79 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKCacheRemove</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKCacheWrite.html">Prev</a> - INKCacheWrite</div>
+<div class="navnext">INKCacheKeyPinnedSet - <a accesskey="n" href="INKCacheKeyPinnedSet.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKCacheRemove"></a>INKCacheRemove</h3></div></div></div>
+<p>Removes an object from the Traffic Server cache.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKAction INKCacheRemove (INKCont
+ <em class="replaceable"><code>contp</code></em>, INKCacheKey
+ <em class="replaceable"><code>key</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="function">INKCont</code>
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is the
+ continuation the cache calls back when reporting the success or
+ failure of the remove.</p>
+<p><code class="function">INKCacheKey</code>
+ <code class="code"><em class="replaceable"><code>key </code></em></code> is the cache key
+ that corresponds to the object tol be removed.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Removes the object corresponding to
+ <code class="code"><em class="replaceable"><code>key </code></em></code> from the
+ cache.</p>
+<p>If the object was removed successfully, then the cache calls
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> back with the
+ event <code class="code">INK_EVENT_CACHE_REMOVE</code>.</p>
+<p>If the object was not found in the cache, then the cache calls
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> back with the
+ event <code class="code">INK_EVENT_CACHE_REMOVE_FAILED</code>. An error code
+ is passed in the <code class="code">void *edata</code> argument of
+ <code class="code"><em class="replaceable"><code>contp</code></em></code>. The error code
+ can be:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p><code class="code">INK_CACHE_ERROR_NOT_READY</code>: tried to
+ access the cache before it was initialized.</p></li>
+<li>
+ <p><code class="code">INK_CACHE_ERROR_NO_DOC</code>: doc doesn't exist
+ in cache</p></li>
+<li><p>any other value: unknown remove failure</p></li>
+</ul></div>
+<p>In both of these callbacks, the user does not have to do
+ anything. The user does not get a vconnection from the cache,
+ since no data needs to be transferred. When the cache calls the
+ user back with <code class="code">INK_EVENT_CACHE_REMOVE</code>, the remove
+ has already been committed.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>Reentrant calls are possible, i.e. the cache can call
+ back the user (<code>contp</code>) in the same call.</p></td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>An <code class="function">INKAction</code> object if
+ successful.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an argument is incorrect or
+ if the API fails.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheRemove.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheWrite.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheWrite.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheWrite.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,106 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKCacheWrite</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKCacheReady.html">Prev</a> - INKCacheReady</div>
+<div class="navnext">INKCacheRemove - <a accesskey="n" href="INKCacheRemove.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKCacheWrite"></a>INKCacheWrite</h3></div></div></div>
+<p>Initiates writing an object to the Traffic Server cache.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKAction INKCacheWrite (INKCont
+ <em class="replaceable"><code>contp</code></em>, INKCacheKey
+ <em class="replaceable"><code>key</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="function">INKCont</code>
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is the
+ continuation the cache calls back (telling it whether the
+ write operation can proceed).</p>
+<p><code class="function">INKCacheKey</code>
+ <code class="code"><em class="replaceable"><code>key </code></em></code> is the cache key
+ that corresponds to the object to be cached.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Asks the Traffic Server cache if
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> can start writing
+ the object (corresponding to key) to the cache.</p>
+<p>If the object can be written, then the cache calls
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> back with the
+ event <code class="code">INK_EVENT_CACHE_OPEN_WRITE</code>. In this case, the
+ cache also passes <code class="code"><em class="replaceable"><code>contp </code></em></code>
+ a cache vconnection in the <code class="code">void *edata</code> argument;
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> can then initiate
+ a write operation on that vconnection using
+ <code class="function">INKVConnWrite</code>. The object is not committed
+ to cache until the vconnection is closed.</p>
+<p>If the object cannot be written, then the cache calls
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> back with the
+ event <code class="code">INK_EVENT_CACHE_OPEN_WRITE_FAILED</code>. This can
+ happen, for example, if there is another object with the same
+ key being written to the cache. An error code is passed in the
+ <code class="code">void *edata</code> argument of
+ <code class="code"><em class="replaceable"><code>contp</code></em></code>. The error code
+ can be:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p><code class="code">INK_CACHE_ERROR_NOT_READY</code>: trying to
+ access to the cache before it's initialized.</p></li>
+<li>
+ <p><code class="code">INK_CACHE_ERROR_DOC_BUSY</code>: trying to write
+ a document while another continuation is writing or reading
+ it.</p></li>
+<li><p>Any other value: unknown write failure.</p></li>
+</ul></div>
+<p>The user (<code class="code"><em class="replaceable"><code>contp</code></em></code>)
+ has the option to cancel the action returned by
+ <code class="function">INKCacheWrite</code>.</p>
+<p>The actual data is written/read to the cache through the
+ cache vconnection. When the cache calls the user back with
+ <code class="code">OPEN_READ</code> or <code class="code">OPEN_WRITE</code>, it passes a
+ <code class="function">INKVConn</code> to the user. The user uses this
+ vconnection for any data transfer. When all data has been
+ transferred, the user must do a
+ <code class="function">INKVConnClose</code>. In case of any errors, the
+ user must do an <code class="function">INKVConnAbort(contp,
+ 0).</code></p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top">
+<p>Reentrant calls are possible; in other words, the cache
+ can call back the user
+ (<code class="code"><em class="replaceable"><code>contp</code></em></code>) in the same
+ call.</p>
+<p><code class="function">INKCacheWrite</code> does not overwrite
+ content already stored in the cache under the same cache key.
+ If you try to do so, then the cache returns
+ <code class="code">INK_EVENT_CACHE_OPEN_WRITE_FAILED</code>. To overwrite
+ content, first call <code class="function">INKCacheRemove</code> to
+ remove the content and then call
+ <code class="function">INKCacheWrite</code>.</p>
+</td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>An <code class="function">INKAction</code> object if
+ successful.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an argument is incorrect or
+ the API fails.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKCacheWrite.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigGet.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigGet.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigGet.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,47 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKConfigGet</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="PluginConfigurationFunctions.html">Prev</a> - Plugin Configuration Functions: INKConfigDataGet</div>
+<div class="navnext">INKConfigRelease - <a accesskey="n" href="INKConfigRelease.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKConfigGet"></a>INKConfigGet</h3></div></div></div>
+<p>Returns a pointer to the Traffic Server configuration.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKConfig INKConfigGet (unsigned int
+ <em class="replaceable"><code>id</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves the current configuration pointer associated
+ with the configuration identifier
+ <code class="code"><em class="replaceable"><code>id</code></em></code>. The function
+ <code class="function">INKConfigDataGet</code> can then be used to
+ retrieve the data pointer from within the configuration. </p>
+</dd>
+<dd>
+ <p><code class="function">INKConfigGet</code> increments the reference count
+ inside the configuration. It is important to call
+ <code class="function">INKConfigRelease</code> to decrement the reference
+ count when the user is done with the configuration
+ pointer.</p>
+ <p>Before you call <code class="function">INKConfigGet</code>, you
+ must set the identifier
+ <code class="code"><em class="replaceable"><code>id </code></em></code> to some plugin
+ configuration data using <code class="function">INKConfigSet</code> (see
+ the code snippet in the previous section).</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd><p>A pointer to the current Traffic Server
+ configuration.</p></dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigGet.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigRelease.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigRelease.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigRelease.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,38 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKConfigRelease</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKConfigGet.html">Prev</a> - INKConfigGet</div>
+<div class="navnext">INKConfigSet - <a accesskey="n" href="INKConfigSet.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKConfigRelease"></a>INKConfigRelease</h3></div></div></div>
+<p>Releases a configuration pointer.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">void INKConfigRelease (unsigned int
+ <em class="replaceable"><code>id</code></em>, INKConfig
+ <em class="replaceable"><code>configp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Releases the configuration pointer
+ <code class="code"><em class="replaceable"><code>configp </code></em></code> on the
+ configuration associated with the identifier
+ <code class="code"><em class="replaceable"><code>id</code></em></code>. </p></dd>
+<dd>
+ <p>If <code class="code"><em class="replaceable"><code>configp </code></em></code> is no longer the
+ current configuration, then
+ <code class="function">INKConfigRelease</code> may call the
+ configuration's destroy function.</p>
+</dd>
+</dl>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigRelease.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigSet.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigSet.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigSet.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,103 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKConfigSet</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKConfigRelease.html">Prev</a> - INKConfigRelease</div>
+<div class="navnext">Action Functions - <a accesskey="n" href="ActionFunctions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKConfigSet"></a>INKConfigSet</h3></div></div></div>
+<p>Assigns an identifier to plugin configuration data.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">unsigned int INKConfigSet (unsigned int
+ <em class="replaceable"><code>id</code></em>, void
+ *<em class="replaceable"><code>data</code></em>, INKConfigDestroyFunc
+ <em class="replaceable"><code>funcp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code>unsigned int </code><code class="code"><em class="replaceable"><code>id </code></em></code> is
+ the identifier assigned to configuration
+ <code class="code"><em class="replaceable"><code>data</code></em></code>. Do not use <code>1</code> or<code> 2</code> for <code class="code"><em class="replaceable"><code>id </code></em></code> because Traffic Server
+ internally assigns these IDs to parent and HTTP configurations.
+ You can enter <code>0</code> as <code class="code"><em class="replaceable"><code>id</code></em></code>,
+ however, and <code class="function">INKConfigSet</code> will allocate an
+ identifier for you (with a value of <code>3</code> or greater). There is an
+ internal upper limit of <code>100</code> for <code class="code"><em class="replaceable"><code>id</code></em></code>.</p>
+<p><code class="code">void
+ *</code><code class="code"><em class="replaceable"><code>data </code></em></code> points to
+ the data you're associating with
+ <code class="code"><em class="replaceable"><code>id</code></em></code>.</p>
+<p><code class="function">INKConfigDestroyFunc</code>
+ <code class="code"><em class="replaceable"><code>funcp </code></em></code> is a pointer to a
+ destroy function that's called when Traffic Server determines
+ there are no more references to data. The only argument for
+ <code class="code"><em class="replaceable"><code>funcp </code></em></code> is
+ <code class="code"><em class="replaceable"><code> data</code></em></code>.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets the opaque data pointer
+ <code class="code"><em class="replaceable"><code>data </code></em></code> to be associated
+ with the configuration identifier
+ <code class="code"><em class="replaceable"><code>id</code></em></code>. If
+ <code class="code"><em class="replaceable"><code>id </code></em></code> is <code>0</code>, then Traffic
+ Server allocates a new configuration identifier, and <code class="function">INKConfigSet</code> returns this value. If
+ <code class="code"><em class="replaceable"><code>id </code></em></code> is non-zero, then
+ <code class="function">INKConfigSet</code> returns
+ <code class="code"><em class="replaceable"><code>id</code></em></code>. To make sure that
+ the configuration identifier stays within the recommended range
+ of <code>3</code> to <code>100</code>, follow the code example in the previous
+ section.</p>
+<div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="images/docbook/caution.png" /></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>Never pick a configuration identifier yourself. When you
+ need a new config ID, you <b>must</b> always pass <code>0</code> as <code class="code"><em class="replaceable"><code>id </code></em></code> to the
+ <code class="function">INKConfigSet</code> API (which will return a new
+ valid <code class="code"><em class="replaceable"><code> id</code></em></code>). It is not
+ safe to pick up a randomly-selected <code class="code"><em class="replaceable"><code>id </code></em></code> because there might be
+ a conflict with ones
+ already in use by Traffic Server. This can cause severe memory
+ corruption, since the <code class="function">INKConfig</code> mechanism is
+ also used internally by Traffic Server.</p></td></tr>
+</table></div>
+<p>The <code class="code"><em class="replaceable"><code>funcp </code></em></code>
+ parameter is a pointer to a destroy function that's
+ called with <code class="code"><em class="replaceable"><code>data </code></em></code> as its
+ only parameter when Traffic Server determines there are no
+ more references to
+ <code class="code"><em class="replaceable"><code>data</code></em></code>.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>Since the current data always has a reference count of at least <code>1</code>, <code class="code"><em class="replaceable"><code> data </code></em></code> is not
+ destroyed while it is the current piece of configuration data.</p></td></tr>
+</table></div>
+<p>See the code snippet in the previous section for
+ usage.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+ <p>The <code>unsigned int</code> that was assigned to the data. If the
+ input <code class="code"><em class="replaceable"><code>id </code></em></code> is <code>0</code>, then a new
+ configuration identifier is allocated (with value <code>3</code> or larger). If
+ the input <code class="code"><em class="replaceable"><code>id </code></em></code> is <code>0</code>, then the
+ return value is the available identifier allocated by Traffic
+ Server. If <code class="code"><em class="replaceable"><code>id </code></em></code> is
+ non-zero, then the return value is
+ <code class="code"><em class="replaceable"><code>id</code></em></code>.</p></dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKConfigSet.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContCreate.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContCreate.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContCreate.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,50 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKContCreate</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="ContinuationFunctions.html">Prev</a> - Continuation Functions: INKContCall</div>
+<div class="navnext">INKContDataGet - <a accesskey="n" href="INKContDataGet.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKContCreate"></a>INKContCreate</h3></div></div></div>
+<p>Creates a continuation.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKCont INKContCreate (INKEventFunc
+ <em class="replaceable"><code>funcp</code></em>, INKMutex
+ <em class="replaceable"><code>mutexp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Creates a new <code class="function">INKCont </code>object. The
+ continuation's handler function is
+ <code class="code"><em class="replaceable"><code>funcp </code></em></code> and its mutex is
+ <code class="code"><em class="replaceable"><code>mutexp</code></em></code>. As mentioned
+ previously, a continuation's mutex can be <code class="code">NULL</code> -
+ this is accomplished by specifying <code class="code">NULL</code> for
+ <code class="code"><em class="replaceable"><code>mutexp</code></em></code>.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>If you specify a <code>NULL</code> mutex, then a mutex is created for the
+ continuation and this mutex is held when the continuation is
+ called back.</p></td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A handle to the newly-created continuation.</p>
+<p><code class="code">INK_ERROR_PTR</code> if the <code>INKCont</code> object is not
+ successfully created.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContCreate.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContDataGet.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContDataGet.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContDataGet.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,35 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKContDataGet</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKContCreate.html">Prev</a> - INKContCreate</div>
+<div class="navnext">INKContDataSet - <a accesskey="n" href="INKContDataSet.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKContDataGet"></a>INKContDataGet</h3></div></div></div>
+<p>Gets a data pointer from a continuation.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">void* INKContDataGet (INKCont
+ <em class="replaceable"><code>contp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Retrieves the data pointer from
+ <code class="code"><em class="replaceable"><code>contp</code></em></code>. The data pointer
+ can be set with a call to <code class="function">INKContDataSet</code>; it
+ is up to the plugin to allocate/deallocate the pointer.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The pointer on the data for continuation <code class="code"> <em class="replaceable"><code> contp</code></em></code>. </p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContDataGet.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContDataSet.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContDataSet.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContDataSet.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,38 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>INKContDataSet</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKContDataGet.html">Prev</a> - INKContDataGet</div>
+<div class="navnext">INKContDestroy - <a accesskey="n" href="INKContDestroy.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKContDataSet"></a>INKContDataSet</h3></div></div></div>
+<p>Sets a data pointer for the specified continuation.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKContDataSet (INKCont
+ <em class="replaceable"><code>contp</code></em>, void
+ *<em class="replaceable"><code>data</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Sets the data pointer of
+ <code class="code"><em class="replaceable"><code> contp </code></em></code> to
+ <code class="code"><em class="replaceable"><code> data</code></em></code>. The data can later
+ be retrieved by a call to
+ <code class="function">INKContDataGet</code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the pointer is successfully
+ set.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/INKContDataSet.html
------------------------------------------------------------------------------
svn:executable = *