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 2011/12/19 23:58:08 UTC
svn commit: r800542 [9/23] - in
/websites/staging/trafficserver/trunk/content/docs/v2: ./ admin/
admin/images/ sdk/ sdk/css/ sdk/images/ sdk/images/docbook/ sdk/js/
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/App_SampleSourceCode.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/App_SampleSourceCode.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/App_SampleSourceCode.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,303 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Appendix A. Sample Source Code</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKTextLogObjectWrite.html">Prev</a> - INKTextLogObjectWrire</div>
+<div class="navnext">Appendix B. Deprecated Functions - <a accesskey="n" href="App_DeprecatedFunctions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="appendix" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="App_SampleSourceCode"></a>Appendix A. Sample Source Code</h2></div></div></div>
+
+<p>This appendix provides several source code examples. In the online formats of this book, function calls are linked to their references
+ in the previous chapters. The following sample plugins are
+ provided:</p>
+<div class="itemizedlist"><ul type="disc"><li><p><a href="App_SampleSourceCode.html#Sample_blacklist-1.c" title="blacklist-1.c">blacklist-1.c</a></p></li></ul></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="Sample_blacklist-1.c"></a>blacklist-1.c</h2></div></div></div>
+<p>The sample blacklisting plugin included in the Traffic Server SDK
+ is <code class="filename">blacklist-1.c</code>. This plugin checks every incoming
+ HTTP client request against a list of blacklisted web sites. If the
+ client requests a blacklisted site, then the plugin returns an <code>Access
+ forbidden</code> message to the client.</p>
+<p>This plugin illustrates:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>An HTTP transaction extension</p></li>
+<li><p>How to examine HTTP request headers</p></li>
+<li><p>How to use the logging interface</p></li>
+<li><p>How to use the plugin configuration management
+ interface</p></li>
+</ul></div>
+<pre class="programlisting">
+/* blacklist-1.c: An example program that denies client access
+ * to blacklisted sites. This plugin illustrates
+ * how to use configuration information from the
+ * blacklist.txt configuration file.
+ *
+ * Usage:
+ * (Solaris) : blacklist-1.so
+ *
+ *
+ */
+
+#include <stdio.h>
+#include <string.h>
+#include <ts/ts.h>
+
+#define MAX_NSITES 500
+
+static char* sites[MAX_NSITES];
+static int nsites;
+static INKMutex sites_mutex;
+static INKTextLogObject log;
+
+static void
+handle_dns (INKHttpTxn txnp, INKCont contp)
+{
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKMLoc url_loc;
+ const char *host;
+ int i;
+ int host_length;
+
+ if (!INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ INKError ("couldn't retrieve client request header\n");
+ goto done;
+ }
+
+ url_loc = INKHttpHdrUrlGet (bufp, hdr_loc);
+ if (!url_loc) {
+ INKError ("couldn't retrieve request url\n");
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ host = INKUrlHostGet (bufp, url_loc, &host_length);
+ if (!host) {
+ INKError ("couldn't retrieve request hostname\n");
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ INKMutexLock(sites_mutex);
+
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host, sites[i], host_length) == 0) {
+ if (log) {
+ INKTextLogObjectWrite(log, "blacklisting site: %s", sites[i]);
+ } else {
+ printf ("blacklisting site: %s\n", sites[i]);
+ }
+ INKHttpTxnHookAdd (txnp,
+ INK_HTTP_SEND_RESPONSE_HDR_HOOK,
+ contp);
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_ERROR);
+ INKMutexUnlock(sites_mutex);
+ return;
+ }
+ }
+
+ INKMutexUnlock(sites_mutex);
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+
+ done:
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_CONTINUE);
+}
+
+static void
+handle_response (INKHttpTxn txnp)
+{
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKMLoc url_loc;
+ char *url_str;
+ char *buf;
+ int url_length;
+
+ if (!INKHttpTxnClientRespGet (txnp, &bufp, &hdr_loc)) {
+ INKError ("couldn't retrieve client response header\n");
+ goto done;
+ }
+
+ INKHttpHdrStatusSet (bufp, hdr_loc, INK_HTTP_STATUS_FORBIDDEN);
+ INKHttpHdrReasonSet (bufp, hdr_loc,
+ INKHttpHdrReasonLookup (INK_HTTP_STATUS_FORBIDDEN),
+ strlen (INKHttpHdrReasonLookup (INK_HTTP_STATUS_FORBIDDEN)) );
+
+ if (!INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ INKError ("couldn't retrieve client request header\n");
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ url_loc = INKHttpHdrUrlGet (bufp, hdr_loc);
+ if (!url_loc) {
+ INKError ("couldn't retrieve request url\n");
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ buf = (char *)INKmalloc (4096);
+
+ url_str = INKUrlStringGet (bufp, url_loc, &url_length);
+ sprintf (buf, "You are forbidden from accessing \"%s\"\n", url_str);
+ INKfree (url_str);
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+
+ INKHttpTxnErrorBodySet (txnp, buf, strlen (buf), NULL);
+
+ done:
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_CONTINUE);
+}
+
+static void
+read_blacklist (void)
+{
+ char blacklist_file[1024];
+ INKFile file;
+
+ sprintf (blacklist_file, "%s/blacklist.txt", INKPluginDirGet());
+ file = INKfopen(blacklist_file, "r");
+
+ INKMutexLock (sites_mutex);
+ nsites = 0;
+
+ if (file != NULL) {
+ char buffer[1024];
+
+ while (INKfgets (file, buffer, sizeof(buffer)-1) != NULL &&
+ nsites < MAX_NSITES) {
+ char* eol;
+ if ((eol = strstr(buffer, "\r\n")) != NULL) {
+ /* To handle newlines on Windows */
+ *eol = '\0';
+ } else if ((eol = strchr(buffer, '\n')) != NULL) {
+ *eol = '\0';
+ } else {
+ /* Not a valid line, skip it */
+ continue;
+ }
+ if (sites[nsites] != NULL) {
+ INKfree (sites[nsites]);
+ }
+ sites[nsites] = INKstrdup (buffer);
+ nsites++;
+ }
+
+ INKfclose (file);
+ } else {
+ INKError ("unable to open %s\n", blacklist_file);
+ INKError ("all sites will be allowed\n", blacklist_file);
+ }
+
+ INKMutexUnlock (sites_mutex);
+
+}
+
+static int
+blacklist_plugin (INKCont contp, INKEvent event, void *edata)
+{
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+
+ switch (event) {
+ case INK_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case INK_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ case INK_EVENT_MGMT_UPDATE:
+ read_blacklist ();
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+}
+
+int
+check_ts_version()
+{
+
+ const char *ts_version = INKTrafficServerVersionGet();
+ int result = 0;
+
+ if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;
+
+ if (sscanf(ts_version, "%d.%d.%d", &major_ts_version,
+ &minor_ts_version, &patch_ts_version) != 3) {
+ return 0;
+ }
+
+ /* Need at least TS 2.0 */
+ if (major_ts_version >= 2) {
+ result = 1;
+ }
+
+ }
+
+ return result;
+}
+
+void
+INKPluginInit (int argc, const char *argv[])
+{
+ int i;
+ INKCont contp;
+ INKPluginRegistrationInfo info;
+ int error;
+
+ info.plugin_name = "blacklist-1";
+ info.vendor_name = "DsCompany";
+ info.support_email = "ts-api-support@DsCompany.com";
+
+ if (!INKPluginRegister (INK_SDK_VERSION_2_0 , &info)) {
+ INKError ("Plugin registration failed.\n");
+ }
+
+ if (!check_ts_version()) {
+ INKError ("Plugin requires Traffic Server 2.0 or later\n");
+ return;
+ }
+
+ /* create an INKTextLogObject to log blacklisted requests to */
+ log = INKTextLogObjectCreate("blacklist", INK_LOG_MODE_ADD_TIMESTAMP,<a class="indexterm" name="id429173"></a>
+ NULL, &error);
+ if (!log) {
+ printf("Blacklist plugin: error %d while creating log\n", error);
+ }
+
+ sites_mutex = INKMutexCreate ();
+
+ nsites = 0;
+ for (i = 0; i < MAX_NSITES; i++) {
+ sites[i] = NULL;
+ }
+
+ read_blacklist ();
+
+ contp = INKContCreate (blacklist_plugin, NULL);
+
+ INKHttpHookAdd (INK_HTTP_OS_DNS_HOOK, contp);
+
+ INKMgmtUpdateRegister (contp, "Super Blacklist Plugin", "blacklist.cgi");
+}</pre>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/App_SampleSourceCode.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/App_Troubleshooting.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/App_Troubleshooting.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/App_Troubleshooting.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,65 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Appendix C. Troubleshooting Tips</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="Dep_MutexFunctions.html">Prev</a> - Mutex Function</div>
+<div class="navnext">Unable to Load Plugins - <a accesskey="n" href="Trouble_LoadPlugins.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="appendix" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="App_Troubleshooting"></a>Appendix C. Troubleshooting Tips</h2></div></div></div>
+<p>This appendix lists the following troubleshooting tips.</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="App_Troubleshooting.html#Trouble_CompilePlugins" title="Unable to Compile Plugins">Unable to Compile Plugins</a></p></li>
+<li><p><a href="Trouble_LoadPlugins.html" title="Unable to Load Plugins">Unable to Load Plugins</a></p></li>
+<li><p><a href="Trouble_DebugTags.html" title="Using Debug Tags">Using Debug Tags</a></p></li>
+<li><p><a href="Trouble_UsingDebugger.html" title="Using a Debugger">Using a Debugger</a></p></li>
+<li><p><a href="Trouble_DebugMemLeaks.html" title="Debugging Memory Leaks">Debugging Memory Leaks</a></p></li>
+</ul></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="Trouble_CompilePlugins"></a>Unable to Compile Plugins</h2></div></div></div>
+<p>The process for compiling a shared library varies with
+ the platform used, so the Traffic Server API includes <code>makefile</code> templates you can use to create shared libraries on all supported
+ Traffic Server platforms.</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div>
+ <h3 class="title">
+<a name="CompilePlugins_Unix"></a>UNIX Example</h3></div></div></div>
+<p>Assuming the sample program is stored in the file <code>hello-world.c</code>,
+ you could use the following commands to building a shared library on
+ Solaris using the GNU C compiler.</p>
+<pre class="programlisting">gcc -g -Wall -fPIC -o hello-world.o -c hello-world.c
+gcc -g -Wall -shared -o hello-world.so hello-world.o</pre>
+<p>The first command compiles <code>hello-world.c </code>as Position Independent
+ Code (PIC); the second command links the single<code> hello-world.o</code> object file into the <code>hello-world.so</code> shared library.</p>
+<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>Make sure that your plugin is not statically linked with
+ system libraries.</p></td></tr>
+</table></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="CompilePlugins_HPUX"></a>HPUX Example</h3></div></div></div>
+<p>Assuming the sample program is stored in the file <code>hello_world.c</code>,
+ you could use the following commands to build a shared library on
+ HPUX:</p>
+<pre class="programlisting">cc +z -o hello_world.o -c hello_world.c
+ld -b -o hello_world.so hello_world.o</pre>
+</div>
+<div class="section" lang="en">
+</div></div>
+</div>
+
+
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/App_Troubleshooting.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/AppendTransformPlugin.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/AppendTransformPlugin.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/AppendTransformPlugin.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,142 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>The Append-Transform Plugin</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="SampleNullTransformPlugin.html">Prev</a> - The Sample Null Transform Plugin</div>
+<div class="navnext">The Sample Buffered Null Transform Plugin - <a accesskey="n" href="SampleBufferedNullTransformPlugin.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="AppendTransformPlugin"></a>The Append-Transform Plugin</h2></div></div></div>
+<p>The append-transform plugin appends text to the body of an HTTP
+ response. It obtains this text from a file; the name of the file
+ containing the append text is a parameter you specify in
+ <code class="filename">plugin.config</code>, as follows:</p>
+<pre class="programlisting">append-transform.so path/to/file</pre>
+<p>The append-transform plugin is based on
+ <code class="filename">null-transform.c</code>. The only difference is that after
+ the plugin feeds the document through the transformation, it adds text
+ to the response.</p>
+<p>Below is a list of the functions in
+ <code class="filename">append-transform.c</code>, in the order they appear in the
+ source code. Below each entry is a description of what the function does:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<p><code class="function"><b>my_data_alloc</b></code></p>
+<p>Allocates and initializes a <code>MyData</code> structure. The plugin
+ defines a struct, <code class="code">MyData</code>, as follows:</p>
+<pre class="programlisting"> typedef struct {
+ INKVIO output_vio;
+ INKIOBuffer output_buffer;
+ INKIOBufferReader output_reader;
+ int append_needed;
+ } MyData;</pre>
+<p>The <code class="code">MyData</code> structure is used to represent data
+ that the transformation (vconnection) needs. The transformation's
+ data pointer is set to a <code class="code">MyData</code> pointer using
+ <code class="code">INKContDataSet</code> in the <code class="code">handle_transform</code>
+ routine.</p>
+</li>
+<li>
+<p><code class="function"><b>my_data_destroy</b></code></p>
+<p>Destroys objects of type <code class="code">MyData</code>. To deallocate the transform's data, the
+ <code>append_transform</code> routine (see below) calls <code class="code">my_data_destroy</code> when the transformation is complete.</p>
+</li>
+<li>
+<p><code class="function"><b>handle_transform</b></code></p>
+<p>This function does the actual data transformation. The
+ transformation is created in <code class="code">transform_add</code> (see below).
+ <code>handle_transform</code> is called by <code>append_transform</code>.</p>
+</li>
+<li>
+<p><code class="function"><b>append_transform</b></code></p>
+<p>This is the handler function for the transformation
+ vconnection created in <code>transform_add</code>. It is the implementation of
+ the vconnection.</p>
+<div class="itemizedlist"><ul type="circle">
+<li>
+ <p>If the transformation vconnection has been closed, then
+ <code>append_transform</code> calls <code class="function">my_data_destroy</code> to
+ destroy the vonnection.</p></li>
+<li>
+ <p>If <code class="function">append_transform</code> receives an error
+ event, then it calls back the continuation to let it know it has
+ completed the write operation.</p></li>
+<li>
+ <p>If it receives a <code class="code">WRITE_COMPLETE</code> event, then it
+ shuts down the write portion of its vconnection.</p></li>
+<li>
+ <p>If it receives a <code class="code">WRITE_READY</code> or any other
+ event (such as
+ <code class="code">INK_HTTP_RESPONSE_TRANSFORM_HOOK</code>)<a class="indexterm" name="id304599"></a>, then it calls <code class="function">handle_transform</code>
+ to attempt to transform more data.</p></li>
+</ul></div>
+</li>
+<li>
+<p><code class="function"><b>transformable</b></code></p>
+<p>The plugin transforms only documents that have a content type
+ of <code class="code">text/html</code>. This function examines the
+ <code class="code">Content-Type</code> MIME header field in the response header. If the value of the MIME field is <code class="code">text/html</code>, then the
+ function returns 1; otherwise, it returns zero.</p>
+</li>
+<li>
+<p><code class="function"><b>transform_add</b></code></p>
+<p>Creates the transformation for the current transaction and
+ sets up a transformation hook. The handler function for the
+ transformation is <code class="function">append_transform</code>.</p>
+</li>
+<li>
+<p><code class="function"><b>transform_plugin</b></code></p>
+<p>This is the handler function for the main continuation for the
+ plugin. Traffic Server calls this function whenever it reads an HTTP
+ response header. <code class="function">transform_plugin</code> does the
+ following:</p>
+<div class="itemizedlist"><ul type="circle">
+<li><p>Gets a handle to the HTTP transaction being
+ processed</p></li>
+<li><p>Calls <code class="function">transformable</code> to determine
+ whether the response document content is of type
+ <code class="code">text/html</code></p></li>
+<li>
+ <p>If the content is transformable, then it calls
+ <code class="function">transform_add</code> to create the
+ transformation.</p></li>
+<li><p>Calls <code class="function">INKHttpTxnReenable</code> to continue
+ the transaction</p></li>
+</ul></div>
+</li>
+<li>
+<p><code class="function"><b>load</b></code></p>
+<p>Opens the file containing the text to be appended and loads
+ the contents of the file into an <code class="function">INKIOBuffer</code>
+ called <code class="function">append_buffer</code>.</p>
+</li>
+<li>
+<p><code class="function"><b>INKPluginInit</b></code></p>
+<p>Does the following:</p>
+<div class="itemizedlist"><ul type="circle">
+<li><p>Checks to make sure that the required configuration
+ information (the append text filename) is entered in
+ <code class="filename">plugin.config</code> correctly.</p></li>
+<li>
+ <p>If there is a filename, then <code class="function">INKPluginInit</code>
+ calls load to load the text.</p></li>
+<li><p>Creates a continuation for the plugin. The handler for
+ this continuation is
+ <code class="function">transform_plugin</code>.</p></li>
+<li>
+ <p>Adds the plugin's continuation to
+ <code class="function">INK_HTTP_READ_RESPONSE_HDR_HOOK</code>. In other
+ words, it sets up a callback of the plugin's continuation when
+ Traffic Server reads HTTP response headers.</p></li>
+</ul></div>
+</li>
+</ul></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/AppendTransformPlugin.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/BasicAuthorizatonPlugin.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/BasicAuthorizatonPlugin.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/BasicAuthorizatonPlugin.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,36 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>The Basic Authorization Plugin</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="WorkWHTTPHeaderFunc.html">Prev</a> - Working with HTTP Header Functions</div>
+<div class="navnext">Implementing the Handler and Getting a Handle to the
+ Transaction - <a accesskey="n" href="ImplementHandler_GetTransHandle.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="BasicAuthorizatonPlugin"></a>The Basic Authorization Plugin</h2></div></div></div>
+<p>The sample basic authorization plugin,
+ <code class="filename">basic-auth.c</code>, checks for basic HTTP proxy
+ authorization. In HTTP basic proxy authorization, client user names and
+ passwords are contained in the <code class="code">Proxy-Authorization</code> header.
+ The password is encoded using base64 encoding. The plugin checks all
+ incoming requests for the authorization header, user name, and password.
+ If the plugin does not find all of the these, then it reenables with an error
+ (effectively stopping the transaction) and adds a transaction hook to
+ the send response header event.</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="CreatePluginParentCont_GlHk"></a>Creating the Plugin's Parent Continuation and Global
+ Hook</h3></div></div></div>
+<p>The parent continuation and global hook are created as
+ follows:</p>
+<pre class="programlisting">INKHttpHookAdd (INK_HTTP_OS_DNS_HOOK, INKContCreate (auth_plugin, NULL));</pre>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/BasicAuthorizatonPlugin.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/BlacklistPlugin.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/BlacklistPlugin.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/BlacklistPlugin.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,90 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>The Blacklist Plugin</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="HeaderBasedPluginEx.html">Prev</a> - Chapter 4. Header-Based Plugin Examples</div>
+<div class="navnext">Setting a Global Hook - <a accesskey="n" href="SettingGlobalHook.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="BlacklistPlugin"></a>The Blacklist Plugin</h2></div></div></div>
+<p>The sample blacklisting plugin included in the Traffic Server SDK
+ is <code class="filename">blacklist_1.c</code>. This plugin checks every incoming
+ HTTP client request against a list of blacklisted web sites. If the
+ client requests a blacklisted site, then the plugin returns an
+ <code class="code">Access forbidden</code> message to the client. </p>
+<p>The flow of HTTP
+ processing with the blacklist plugin is illustrated in the figure titled <a href="CreatingTSPlugins.html#Fig_BlacklistPlugin" title="Figure 2.5. Blacklist Plugin"> "Blacklist Plugin"</a>. This example also contains a
+ simple configuration management interface. It can read a list of
+ blacklisted sites from a file (<code class="filename">blacklist.txt</code>) that
+ can be updated by a Traffic Server administrator. When the configuration
+ file is updated, Traffic Server sends an event to the plugin that wakes
+ it up to do some work.</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="CreatingParentContinuation"></a>Creating the Parent Continuation<a class="indexterm" name="id373031"></a></h3></div></div></div>
+<p>You create the static parent continuation in the mandatory
+ <code class="function">INKPluginInit</code> function. This parent continuation
+ effectively <span class="bold"><strong>is</strong></span> the plugin: the plugin
+ does work when this continuation receives an event from Traffic
+ Server. Traffic Server passes the event as an argument to the
+ continuation's handler function. When you create continuations, you
+ must create and specify their handler functions.</p>
+<p>You can specify an optional mutex lock when you create
+ continuations. The mutex lock protects data shared by asynchronous
+ processes. Because Traffic Server has a multi-threaded design, race conditions can occur if
+ several threads try to access the same continuation's data.</p>
+<p>Here is how the static parent continuation is created in
+ <code class="filename">blacklist-1.c</code></p>
+<pre class="programlisting">void
+INKPluginInit (int argc, const char *argv[])
+{ ...
+ INKCont contp;
+
+ contp = INKContCreate (blacklist_plugin, NULL);
+...
+}</pre>
+<p>:</p>
+<p>The handler function for the plugin is <code>blacklist_plugin</code>, and the
+ mutex is null. The continuation handler function's job is to handle
+ the events that are sent to it; accordingly, the <code class="filename">blacklist_plugin</code> routine consists of a switch
+ statement that covers each of the events that might be sent to
+ it:</p>
+<pre class="programlisting">static int
+blacklist_plugin (INKCont contp, INKEvent event, void *edata)
+{
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+ switch (event) {
+ case INK_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case INK_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ case INK_EVENT_MGMT_UPDATE:
+ read_blacklist ();
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+}</pre>
+<p>When you write handler functions, you have to anticipate any
+ events that might be sent to the handler by hooks or by other
+ functions. In the Blacklist plugin, <code class="code">INK_EVENT_OS_DNS</code> is
+ sent because of the global hook established in
+ <code class="code">INKPluginInit</code>,
+ <code class="code">INK_EVENT_HTTP_SEND_RESPONSE_HDR</code> is sent because the
+ plugin contains a transaction hook (see <a href="SettingUpTransacHook.html" title="Setting Up a Transaction Hook">Setting Up a Transaction Hook</a>), and
+ <code class="code">INK_EVENT_MGMT_UPDATE</code> is sent by Traffic Manager whenever
+ there is a configuration change (see <a href="SettingUpUIUpdateCallbacks.html" title="Setting Up UI Update Callbacks">Setting Up UI Update Callbacks</a>). It is good practice to have a
+ default case in your switch statements.</p>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/BlacklistPlugin.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheAPI.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheAPI.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheAPI.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,56 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Guide to the Cache API</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="IOBuffers_IO.html">Prev</a> - IO Buffers</div>
+<div class="navnext">How to Do a Cache Write - <a accesskey="n" href="DoACacheWrite.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="CacheAPI"></a>Guide to the Cache API</h2></div></div></div>
+<p>The cache API enables plugins to read, write, and remove objects in the
+ Traffic Server cache. All cache APIs are keyed by an object called an
+ <code class="function">INKCacheKey</code>; cache keys are created via
+ <code class="function">INKCacheKeyCreate</code>; keys are destroyed via
+ <code class="function">INKCacheKeyDestroy</code>. Use
+ <code class="function">INKCacheKeyDigestSet</code> to set the hash of the cache
+ key.</p>
+<p>Note that the cache APIs differentiate between HTTP data and
+ plugin data. The cache APIs do not allow you to write HTTP docs in the
+ cache; you can only write plugin-specific data (a specific type
+ of data that differs from the HTTP type).</p>
+<p><b>Example:</b></p>
+<pre class="programlisting"> const unsigned char *key_name = "example key name";
+
+ INKCacheKey key;
+ INKCacheKeyCreate (&key);
+ INKCacheKeyDigestSet (key, (unsigned char *) key_name , strlen(key_name));
+ INKCacheKeyDestroy (key);</pre>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="DoACacheRead"></a>How to Do a Cache Read</h3></div></div></div>
+<p><code class="function">INKCacheRead</code> does not really read - it is
+ used for lookups (see the sample Protocol plugin). Possible
+ callback events include:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p><code class="code">INK_EVENT_CACHE_OPEN_READ</code> - indicates the
+ lookup was successful. The data passed back along with this event
+ is a cache vconnection that can be used to initiate a read on this
+ keyed data.</p></li>
+<li>
+ <p><code class="code">INK_EVENT_CACHE_OPEN_READ_FAILED</code> - indicates the lookup was unsuccessful. Reasons for this event could be that
+ another continuation is writing to that cache location, or
+ the cache key doesn't refer to a cached resource. Data payload for
+ this event indicates the possible reason the read failed
+ (<code class="function">INKCacheError</code>).</p></li>
+</ul></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheAPI.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheAPI_Example.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheAPI_Example.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheAPI_Example.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,58 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Example</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="Errors_Cache.html">Prev</a> - Errors</div>
+<div class="navnext">Chapter 16. Plugin Management - <a accesskey="n" href="PluginManagement.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="CacheAPI_Example"></a>Example</h3></div></div></div>
+<p>In the example below, suppose there is a cache hit and the cache
+ returns a vconnection that enables you to read the document from cache. To
+ do this, you need to prepare a buffer (<code class="varname">cache_bufp</code>)
+ to hold the document; meanwhile, use
+ <code class="function">INKVConnCachedObjectSizeGet</code> to find out the actual
+ size of the document (<code class="varname">content_length</code>). Then,
+ issue <code class="function">INKVConnRead</code> to read the document
+ with the total data length required as
+ <code class="varname">content_length</code>. Assume the following data:</p>
+<pre class="programlisting"> INKIOBuffer cache_bufp = INKIOBufferCreate ();
+ INKIOBufferReader cache_readerp = INKIOBufferReaderAlloc (out_bufp);
+ INKVConn cache_vconnp = NULL;
+ INKVIO cache_vio = NULL;
+ int content_length = 0;</pre>
+<p>In the <code class="code">INK_CACHE_OPEN_READ</code> handler:</p>
+<pre class="programlisting">cache_vconnp = (INKVConn) data;
+ INKVConnCachedObjectSizeGet (cache_vconnp, &content_length);
+ cache_vio = INKVConnRead (cache_vconn, contp, cache_bufp, content_length);</pre>
+<p>In the <code class="code">INK_EVENT_VCONN_READ_READY</code> handler:</p>
+<pre class="programlisting">(usual VCONN_READ_READY handler logic)
+int nbytes = INKVIONBytesGet (cache_vio);
+int ntodo = INKVIONTodoGet (cache_vio);
+int ndone = INKVIONDoneGet (cache_vio);
+(consume data in cache_bufp)
+INKVIOReenable (cache_vio);</pre>
+<p>Do not try to get continuations or VIOs from
+ <code class="function">INKVConn</code> objects for cache vconnections. Also
+ note that the following APIs can only be used on transformation
+ vconnections and must not be used on cache vconnections or net vconnections:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><code class="function">INKVConnWriteVIOGet</code></p></li>
+<li><p><code class="function">INKVConnReadVIOGet</code></p></li>
+<li><p><code class="function">INKVConnClosedGet</code></p></li>
+</ul></div>
+<p>APIs such as <code class="function">INKVConnRead</code>,
+ <code class="function">INKVConnWrite</code>,
+ <code class="function">INKVConnClose</code>, <code class="function">INKVConnAbort</code>, and <code class="function">INKVConnShutdown</code> can be used on any kind of
+ vconnections.</p>
+<p>When you are finished:</p>
+<pre class="programlisting">INKCacheKeyDestroy (key);</pre>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheAPI_Example.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheInterfaceFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheInterfaceFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheInterfaceFunctions.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,91 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Cache Interface Functions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+ <div class="navprev"> <a accesskey="p" href="INKNetVConnRemotePortGet.html">Prev</a> - INKNetVConnRemotePortGet</div>
+ <div class="navnext">INKCacheKeyDigestSet - <a accesskey="n" href="INKCacheKeyDigestSet.html">Next</a> </div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+ <div class="titlepage">
+ <h2 class="title" style="clear: both;"> <a name="CacheInterfaceFunctions">Cache Interface Functions</a></h2>
+ </div>
+
+ <ul><b>
+<li><a href="CacheInterfaceFunctions.html#INKCacheKeyCreate">INKCacheKeyCreate</a></li>
+<li><a href="CacheInterfaceFunctions.html#INKSetCacheUrl">INKSetCacheUrl</a></li>
+<li><a href="INKCacheKeyDigestSet.html">INKCacheKeyDigestSet</a></li>
+<li><a href="INKCacheKeyHostNameSet.html">INKCacheKeyHostNameSet</a></li>
+<li><a href="INKCacheKeyDestroy.html">INKCacheKeyDestroy</a></li>
+<li><a href="INKCacheRead.html">INKCacheRead</a></li>
+<li><a href="INKCacheReady.html">INKCacheReady</a></li>
+<li><a href="INKCacheWrite.html">INKCacheWrite</a> </li>
+<li><a href="INKCacheRemove.html">INKCacheRemove</a></li>
+<li><a href="INKCacheKeyPinnedSet.html">INKCacheKeyPinnedSet</a></li>
+<li><a href="INKVConnCacheObjectSizeGet.html">INKVConnCacheObjectSizeGet</a></li>
+</b>
+</ul>
+
+ <div class="section" lang="en">
+ <div class="titlepage">
+ <h3 class="title"> <a name="INKCacheKeyCreate">INKCacheKeyCreate</a></h3>
+ </div>
+ <p>Creates a new cache key that will be assigned to an object to be
+ cached.</p>
+ <div class="variablelist">
+ <dl>
+ <dt><span class="term"><b>Prototype</b></span></dt>
+ <dd>
+ <p><code class="code">INKReturnCode INKCacheKeyCreate (InkCacheKey
+ *<em class="replaceable"><code>new_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>new_key </code></em></code> is
+ set to the allocated key.</p>
+ </dd>
+ <dt><span class="term"><b>Description</b></span></dt>
+ <dd>
+ <p>Creates (allocates memory for) a new cache key. The key
+ can then be generated and assigned to an object using <code class="function">INKCacheKeyDigestSet</code>.</p>
+ </dd>
+ <dt><span class="term"><b>Returns</b></span></dt>
+ <dd>
+ <p><code class="code">INK_SUCCESS</code> if successful.</p>
+ <p><code class="code">INK_ERROR</code> if the cache key could not be
+ allocated.</p>
+ </dd>
+ </dl>
+ </div>
+ <div class="section" lang="en">
+ <div class="titlepage">
+ <h3 class="title"> <a name="INKSetCacheUrl">INKSetCacheUrl</a></h3>
+ </div>
+ <p>This is an API to set the cache URL. This will be the URL for the cached object.</p>
+ <div class="variablelist">
+ <dl>
+ <dt><span class="term"><b>Prototype</b></span></dt>
+ <dd>
+ <p><code class="code">INKReturnCode INKSetCacheUrl (INKHttpTxn <span class="replaceable">txnp</span>, const char *<span class="replaceable">url</span>)</code></p>
+ </dd>
+ <dt><span class="term"><b>Arguments</b></span></dt>
+ <dd>
+ <p>The URL for the cached object will be set to<code class="code"><span class="replaceable"> url</span></code>.</p>
+ </dd>
+ <dt><span class="term"><b>Example</b></span></dt>
+ <dd>
+ <pre class="programlisting">INKHttpTxn txnp = (INKHttpTxn)edata;
+if (INKSetCacheUrl(txnp, "http://www.yahoo.com") != INK_SUCCESS) {
+// ERROR
+}</pre>
+ </dd>
+ </dl>
+ </div>
+ </div>
+ </div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CacheInterfaceFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/ConceptIndex.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/ConceptIndex.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/ConceptIndex.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,201 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Index</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="TypeIndex.html">Prev</a> - Appendix E. Type Index</div>
+<div class="navnext"></div>
+</div>
+<div id="toc"></div>
+<div class="index">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="ConceptIndex"></a>Index</h2></div></div></div>
+<div class="index">
+<div class="indexdiv">
+<h3>C</h3>
+<dl>
+<dt>compiling on HPUX, <a href="ASimplePlugin.html#Compiling_HPUX">HPUX Example</a>
+</dt>
+<dt>compiling on UNIX, <a href="ASimplePlugin.html#Compiling_Unix">UNIX Example</a></dt>
+<dt>compiling plugins, examples, <a href="ASimplePlugin.html#CompilingYourPlugin">Compile Your Plugin</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>D</h3>
+<dl>
+<dt>deprecated functions, <a href="DeprecatedMarshBufFuncs.html">Deprecated Functions</a>
+</dt>
+<dt>duplicate MIME fields, <a href="DuplicateMIMEFlds.html">Duplicate MIME Fields Are Not Coalesced</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>G</h3>
+<dl>
+<dt>global hook, <a href="SettingGlobalHook.html">Setting a Global Hook</a>
+</dt>
+<dt>global HTTP hooks, <a href="AddingHooks.html">Adding Hooks</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>H</h3>
+<dl>
+<dt><code>hello-world</code> example, <a href="ASimplePlugin.html">A Simple Plugin</a>
+</dt>
+<dt>HTTP header, <a href="MIMEHeaders.html">MIME Headers</a>
+</dt>
+<dt>HTTP session, <a href="HTTPSessions.html">HTTP Sessions</a>
+</dt>
+<dt>HTTP transaction, <a href="HTTPSessions.html">HTTP Sessions</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>I</h3>
+<dl>
+<dt><code>INKEventFunc</code>, <a href="AccessingTransactionProc.html">Accessing the Transaction Being Processed</a>
+</dt>
+<dt><code>INKHttpAltInfo</code>, <a href="HTTPAlternateSelection.html">HTTP Alternate Selection</a>
+</dt>
+<dt><code>INKHttpTxn</code>, <a href="AccessingTransactionProc.html">Accessing the Transaction Being Processed</a>, <a href="HTTP_Transactions.html">HTTP Transactions</a>
+</dt>
+<dt><code>INKMBufferCreate</code>, <a href="HTTPHeaders2.html">HTTP Headers</a>
+</dt>
+<dt><code>INKVIO</code>, <a href="HTTPTransformationPlugins.html#VIOs">VIOs</a>
+</dt>
+<dt><code>INK_HTTP_RESPONSE_TRANSFORM_HOOK</code>, <a href="AppendTransformPlugin.html">The Append-Transform Plugin</a>
+</dt>
+<dt><code>INK_HTTP_SSN_CLOSE_HOOK</code>, <a href="HTTPSessions.html">HTTP Sessions</a>
+</dt>
+<dt><code>INK_HTTP_SSN_START_HOOK</code>, <a href="HTTPSessions.html">HTTP Sessions</a>
+</dt>
+<dt><code>INK_LOG_MODE_ADD_TIMESTAMP</code>, <a href="App_SampleSourceCode.html#Sample_blacklist-1.c"><code>blacklist-1.c</code></a>
+</dt>
+<dt><code>INT64_MAX</code>, <a href="IOGuide.html#VconnectionUsersView">The vconnection user's view</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>L</h3>
+<dl><dt>lock, <a href="MutexGuide.html#Mutexes">Mutexes</a>
+</dt></dl>
+</div>
+<div class="indexdiv">
+<h3>M</h3>
+<dl>
+<dt>memory leak</dt>
+<dd><dl><dt>in transformation plugins, <a href="Transformations_IO.html#TransformVconnection">Transformation VConnection</a>
+</dt></dl></dd>
+<dt>method (HTTP), <a href="HTTPHeaders.html#AboutHTTPHeaders">About HTTP Headers</a>
+</dt>
+<dt>MIME field, <a href="HTTPHeaders.html#AboutHTTPHeaders">About HTTP Headers</a>, <a href="MIMEHeaders.html">MIME Headers</a>
+</dt>
+<dt>MIME field name, <a href="MIMEHeaders.html">MIME Headers</a>
+</dt>
+<dt>MIME field value, <a href="MIMEHeaders.html">MIME Headers</a>
+</dt>
+<dt>MIME fields, <a href="MIMEFldsBelongAssocMIMEHdr.html">MIME Fields Always Belong to an Associated MIME
+ Header</a>
+</dt>
+<dt>MIME header, <a href="HTTPHeaders.html#AboutHTTPHeaders">About HTTP Headers</a>, <a href="MIMEHeaders.html">MIME Headers</a>
+</dt>
+<dd><dl><dt>Backus-Naur form, <a href="MIMEHeaders.html">MIME Headers</a>
+</dt></dl></dd>
+<dt>multiple plugins, <a href="Updatingplugin.configFile.html">Update the plugin.config File</a>
+</dt>
+<dt>mutexes, <a href="MutexGuide.html#Mutexes">Mutexes</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>N</h3>
+<dl>
+<dt>new MIME field functions, <a href="MIMEFldsBelongAssocMIMEHdr.html">MIME Fields Always Belong to an Associated MIME
+ Header</a></dt>
+<dt>null-terminated strings, <a href="GuideTSHTTPHdrSyst.html#NoNullTerminatedStrings">No Null-Terminated Strings</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>P</h3>
+<dl>
+<dt>parent continuation, <a href="BlacklistPlugin.html#CreatingParentContinuation">Creating the Parent Continuation</a>
+</dt>
+<dt>parent <code>INKMLoc</code>, <a href="RlsMarshalBufHandles.html">Release Marshal Buffer Handles</a>
+</dt>
+<dt>parent MIME header, <a href="MIMEFldsBelongAssocMIMEHdr.html">MIME Fields Always Belong to an Associated MIME
+ Header</a>
+</dt>
+<dt><code>plugin.config</code>, <a href="GetingStarted.html#PluginConfiguration">Plugin Configuration</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>R</h3>
+<dl>
+<dt>read VIO, <a href="HTTPTransformationPlugins.html#WritingContentTransformPlugins">Writing Content Transform Plugins</a>
+</dt>
+<dt>releasing mbuffer handles, <a href="RlsMarshalBufHandles.html">Release Marshal Buffer Handles</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>S</h3>
+<dl>
+<dt>sample code</dt>
+<dd><dl>
+<dt><code>INKPluginRegister</code>, <a href="PlusingRegisAndVersionCkg.html">Plugin Registration and Version Checking</a>
+</dt>
+<dt>version check, <a href="PlusingRegisAndVersionCkg.html">Plugin Registration and Version Checking</a>
+</dt>
+</dl></dd>
+<dt>statistics</dt>
+<dd><dl><dt>viewing, <a href="ViewStatsUsingTrafLine.html">Viewing Statistics Using Traffic Line</a>
+</dt></dl></dd>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>T</h3>
+<dl>
+<dt>thread locking, <a href="MutexGuide.html#Mutexes">Mutexes</a>
+</dt>
+<dt>Traffic Edge, <a href="PlusingRegisAndVersionCkg.html">Plugin Registration and Version Checking</a>
+</dt>
+<dt>Traffic Line, <a href="ViewStatsUsingTrafLine.html">Viewing Statistics Using Traffic Line</a>
+</dt>
+<dt>Traffic Server, <a href="PlusingRegisAndVersionCkg.html">Plugin Registration and Version Checking</a>
+</dt>
+<dt>transaction, <a href="AccessingTransactionProc.html">Accessing the Transaction Being Processed</a>
+</dt>
+<dd><dl><dt>getting a handle to, <a href="AccessingTransactionProc.html">Accessing the Transaction Being Processed</a>
+</dt></dl></dd>
+<dt>transaction hook, <a href="SettingUpTransacHook.html">Setting Up a Transaction Hook</a>
+</dt>
+<dt>transformation, <a href="HTTPTransformationPlugins.html#WritingContentTransformPlugins">Writing Content Transform Plugins</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>V</h3>
+<dl>
+<dt>vconnection, <a href="HTTPTransformationPlugins.html#WritingContentTransformPlugins">Writing Content Transform Plugins</a>
+</dt>
+<dt>version checking, <a href="PlusingRegisAndVersionCkg.html">Plugin Registration and Version Checking</a>
+</dt>
+<dt>VIO, <a href="HTTPTransformationPlugins.html#WritingContentTransformPlugins">Writing Content Transform Plugins</a>
+</dt>
+</dl>
+</div>
+<div class="indexdiv">
+<h3>W</h3>
+<dl><dt>write VIO, <a href="HTTPTransformationPlugins.html#WritingContentTransformPlugins">Writing Content Transform Plugins</a>
+</dt></dl>
+</div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/ConceptIndex.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/ContinuationFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/ContinuationFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/ContinuationFunctions.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,53 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Continuation Functions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKMutexUnlock.html">Prev</a> - INKMutexUnlock</div>
+<div class="navnext">INKContCreate - <a accesskey="n" href="INKContCreate.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="ContinuationFunctions"></a>Continuation Functions</h2></div></div></div>
+
+
+<ul><b>
+<li><a href="ContinuationFunctions.html#INKContCall">INKContCall</a></li>
+<li><a href="INKContCreate.html">INKContCreate</a></li>
+<li><a href="INKContDataGet.html">INKContDataGet</a></li>
+<li><a href="INKContDataSet.html">INKContDataSet</a></li>
+<li><a href="INKContDestroy.html">INKContDestroy</a></li>
+<li><a href="INKContMutexGet.html">INKContMutexGet</a></li>
+<li><a href="INKContSchedule.html">INKContSchedule</a> </li>
+</b>
+</ul>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKContCall"></a>INKContCall</h3></div></div></div>
+<p>Calls a continuation.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKContCall (INKCont
+ <em class="replaceable"><code>contp</code></em>, INKEvent
+ <em class="replaceable"><code>event</code></em>, void
+ *<em class="replaceable"><code>edata</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Sends <code class="code"><em class="replaceable"><code>event </code></em></code> and
+ <code class="code"><em class="replaceable"><code>edata </code></em></code> to the
+ <code class="code"><em class="replaceable"><code>contp </code></em></code>'s handler
+ function. It is an error to call a continuation without holding
+ the continuation's lock.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd><p>The values returned by the continuation <code>contp</code> event
+ handler.</p></dd>
+</dl></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/ContinuationFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/Continuations.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/Continuations.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/Continuations.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,124 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 12. Continuations</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="MutexGuide.html">Prev</a> - Chapter 11. Mutex Guide</div>
+<div class="navnext">How to Activate Continuations - <a accesskey="n" href="ActivateContinuations.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="Continuations"></a>Chapter 12. Continuations</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"><a href="Continuations.html#MutexesAndData">Mutexes and Data</a></span></dt>
+<dt><span class="section"><a href="ActivateContinuations.html">How to Activate Continuations</a></span></dt>
+<dt><span class="section"><a href="WritingHandlerFunctions.html">Writing Handler Functions</a></span></dt>
+</dl>
+</div>
+<p>The continuation interface is Traffic Server's basic callback
+ mechanism. <b>Continuations</b> are instances of the opaque data type <code>INKCont</code>. In
+ its basic form, a continuation represents a handler function and a mutex. </p>
+<p>This chapter covers the following topics:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="Continuations.html#MutexesAndData" title="Mutexes and Data">Mutexes and Data</a></p></li>
+<li><p><a href="ActivateContinuations.html" title="How to Activate Continuations">How to Activate Continuations</a></p></li>
+<li><a href="WritingHandlerFunctions.html">Writing Handler Functions</a></li>
+</ul></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="MutexesAndData"></a>Mutexes and Data</h2></div></div></div>
+<p>A continuation must be created with a mutex if your continuation
+ does one of the following:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p>is registered globally (<code class="function">INKHttpHookAdd</code> or
+ <code class="function">INKHttpSsnHookAdd</code>) to an HTTP hook and uses
+ <code class="function">INKContDataSet/Get</code></p></li>
+<li>
+ <p>is registered locally (<code class="function">INKHttpTxnHookAdd</code>),
+ but for multiple transactions uses
+ <code class="function">INKContDataSet/Get</code></p></li>
+<li>
+ <p>uses <code class="function">INKCacheXXX</code>,
+ <code class="function">INKNetXXX</code>, <code class="function">INKHostLookup</code>, or <code class="function">INKContSchedule</code> APIs</p></li>
+</ul></div>
+<p>Before being activated, a caller must grab the continuation's
+ mutex. This requirement makes it possible for a continuation's handler
+ function to safely access its data and to prevent multiple callers from running it at the same time (see the <a href="NewProtocolPlugins.html#AboutSampleProtocol" >sample Protocol plugin</a> for
+ usage). The data protected by the mutex is any global or continuation
+ data associated to the continuation by
+ <code class="function">INKContDataSet</code>. This does not include the local
+ data created by the continuation handler function. A typical example of
+ continuations created with associated data structures and mutexes is the
+ transaction state machine created in the sample Protocol plugin (see
+ <a href="NewProtocolPlugins.html#ImplementTransStMachine" title="One Way to Implement a Transaction State Machine">One Way to Implement a Transaction State Machine</a>).</p>
+<p>A reentrant call occurs when the continuation passed as an
+ argument to the API can be called in the same stack trace as the
+ function calling the API. For example, if you call <code>INKCacheRead</code> (<code class="code">contp, mykey</code>), it is possible that <code>contp</code>'s handler will be
+ called directly and then <code class="function">INKCacheRead</code> returns. </p>
+<p>Caveats that could cause issues include the following:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>a continuation has data associated with it
+ (<code class="function">INKContDataGet</code>).</p></li>
+<li>
+ <p>the reentrant call passes itself as a continuation to the
+ reentrant API. In this case, the continuation should not try to
+ access its data after calling the reentrant API. The reason
+ for this is that data may be modified by the section of code in the
+ continuation's handler that handles the event sent by the API. It is
+ recommended that you always return after a reentrant call to avoid
+ accessing something that has been deallocated.</p></li>
+</ul></div>
+<p>Below is an example, followed by an explanation.</p>
+<pre class="programlisting">continuation_handler (INKCont contp, INKEvent event, void *edata) {
+ switch (event) {
+ case event1:
+ INKReentrantCall (contp);
+ /* Return right away after this call */
+ break;
+ case event2:
+ INKContDestroy (contp);
+ break;
+ }
+}</pre>
+<p>The above example first assumes that the continuation is called
+ back with <code class="code">event1</code>; it then does the first reentrant call that
+ schedules the continuation to receive <code class="code">event2</code>. Because the
+ call is reentrant, the processor calls back the continuation right away
+ with <code class="code">event2</code> and the continuation is destroyed. If you try
+ to access the continuation or one of its members after the reentrant
+ call, then you might access something that has been deallocated. To avoid
+ accessing something that has been deallocated, never access the
+ continuation or any of its members after a reentrant call - just exit the
+ handler.</p>
+<p><b>Note:</b> Most HTTP transaction plugin continuations do not need
+ non-null mutexes because they're called within the processing of an
+ HTTP transaction, and therefore have the transaction's mutex.</p>
+<p>It is also possible to specify a continuation's mutex as
+ <code class="code">NULL</code>. This should be done only when registering a
+ continuation to a global hook, by a call to
+ <code class="function">INKHttpHookAdd</code>. In this case, the continuation can
+ be called simultaneously by different instances of HTTP SM running on
+ different threads. Having a mutex here would slow and/or hinder Traffic Server
+ performance, since all the threads will try to lock the same mutex. The
+ drawback of not having a mutex is that such a continuation cannot have
+ data associated with it (i.e., <code class="function">INKContDataGet/Set</code> cannot
+ be used).</p>
+<p>When using a <code class="code">NULL</code> mutex it is dangerous to access
+ the continuation's data, but usually continuations
+ with <code class="code">NULL</code> mutexes have no data associated with them anyway. An
+ example of such a continuation is one that gets called back every
+ time an HTTP request is read, and then determines from the request alone
+ if the request should go through or be rejected. An HTTP
+ transaction gives its continuation data to the
+ <code class="code">contp</code>.</p>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/Continuations.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/Conventions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/Conventions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/Conventions.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,55 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Typographical Conventions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="pr01s02.html">Prev</a> - How to Use This Book</div>
+<div class="navnext">Chapter 1. Getting Started - <a accesskey="n" href="GetingStarted.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="Conventions"></a>Typographical Conventions</h2></div></div></div>
+<p>This document uses the following typographic conventions:</p>
+<div class="table">
+<a name="id305513"></a><p class="title"><b>Table 1. Typographical Conventions</b></p>
+<table summary="Typographical Conventions" border="1">
+<colgroup>
+<col />
+<col />
+</colgroup>
+<thead><tr>
+<th align="center">Convention</th>
+<th align="center">Purpose</th>
+</tr></thead>
+<tbody>
+<tr>
+<td><span class="emphasis"><em>italics </em> or<b> bold</b></span></td>
+<td>Used to introduce terms.</td>
+</tr>
+<tr>
+<td><code class="code">monospaced face</code></td>
+<td>Represents C language statements, commands, file content,
+ and computer output.</td>
+</tr>
+<tr>
+<td><code class="code"><em class="replaceable"><code>monospaced
+ italic</code></em></code></td>
+<td>Represents variables for which you should substitute a
+ value.</td>
+</tr>
+<tr>
+<td><code class="code">...</code>
+ (ellipsis)</td>
+<td>Indicates the omission of irrelevant or unimportant
+ information.</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/Conventions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CoupledStatistics.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/CoupledStatistics.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/CoupledStatistics.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,118 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Coupled Statistics</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="AddingStatistics.html">Prev</a> - Chapter 17. Adding Statistics</div>
+<div class="navnext">Viewing Statistics Using Traffic Line - <a accesskey="n" href="ViewStatsUsingTrafLine.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="CoupledStatistics"></a>Coupled Statistics</h2></div></div></div>
+<p>Use coupled statistics for quantities that are related and therefore must be
+ updated jointly. </p>
+<p>As a very simple example, suppose you have three
+ statistics: <code class="code">sum</code>, <code class="code">part_1</code>, and
+ <code class="code">part_2</code>. They must always preserve the relationship that
+ <code class="code">sum = part_1 + part_2</code>. If you update <code class="code">part_1</code>
+ without updating <code>sum</code> at the same time, then the equation becomes untrue. Therefore, the statistics are said to be <i>coupled</i>. </p>
+<p>The
+ mechanism for updating coupled statistics jointly is to create local
+ copies of global coupled statistics in the routines that modifiy them.
+ When each local copy is updated appropriately, do a global update
+ using <code class="code">INKStatsCoupledUpdate</code>. To specify which statistics
+ are related to one another, establish a coupled statistic category
+ and make sure that each coupled statistic belongs to the appropriate
+ category. When it is time to do the global update, specify the
+ category to be updated.</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>The local statistic copy must have a duplicate set of statistics
+ as that of the master copy. Local statistics must also be added to the
+ local statistic category in the same order as their master copy
+ counterparts were originally added.</p></td></tr>
+</table></div>
+<p>Below are the steps you need to follow, along with a code example taken from the <code class="filename">redirect-1.c</code> sample
+ plugin.</p>
+<h3>
+<a name="AddCoupledStats"></a>To add coupled statistics:</h3>
+<div class="orderedlist"><ol type="1">
+<li><p>Declare the global category for your coupled statistics as a
+ global <code class="code">INKCoupledStat</code> variable in your plugin.</p></li>
+<li><p>Declare your coupled statistics as global <code class="code">INKStat</code>
+ variables in your plugin.</p></li>
+<li><p>In <code class="code">INKPluginInit</code>, create a new global coupled
+ category using
+ <code class="code">INKStatCoupledGlobalCategoryCreate</code>.</p></li>
+<li>
+<p>In <code class="code">INKPluginInit</code>, create new global coupled
+ statistics using <code class="code">INKStatCoupledGlobalAdd</code>.</p>
+<p>When you create a new statistic, you need to give it an
+ "external" name that the Traffic Server command line interface
+ (Traffic Line) uses to access the statistic.</p>
+</li>
+<li>
+ <p>In any routine wherein you want to modify (increment, decrement,
+ or other modification) your coupled statistics, declare local copies
+ of the coupled category and coupled statistics.</p></li>
+<li>
+ <p>Create local copies using
+ <code class="code">INKStatCoupledLocalCopyCreate</code> and
+ <code class="code">INKStatCoupledLocalAdd</code>.</p></li>
+<li>
+ <p>Modify the local copies of your statistics. Then call
+ <code class="code">INKStatsCoupledUpdate</code> to update the
+ global copies jointly.</p></li>
+<li>
+ <p>When you are finished, you must destroy all of the local
+ copies in the category via
+ <code class="code">INKStatCoupledLocalCopyDestroy</code>.</p></li>
+</ol></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="Examp_redirect-1.c"></a>Example Using the redirect-1.c Sample Plugin</h3></div></div></div>
+<pre class="programlisting">static INKCoupledStat request_outcomes;
+
+static INKStat requests_all;
+static INKStat requests_redirects;
+static INKStat requests_unchanged;
+
+request_outcomes = INKStatCoupledGlobalCategoryCreate ("request_outcomes");
+
+requests_all = INKStatCoupledGlobalAdd (request_outcomes, "requests.all", INKSTAT_TYPE_FLOAT);
+requests_redirects = INKStatCoupledGlobalAdd (request_outcomes, "requests.redirects",
+ INKSTAT_TYPE_INT64);
+requests_unchanged = INKStatCoupledGlobalAdd (request_outcomes, "requests.unchanged",
+ INKSTAT_TYPE_INT64);
+
+INKCoupledStat local_request_outcomes;
+INKStat local_requests_all;
+INKStat local_requests_redirects;
+INKStat local_requests_unchanged;
+
+local_request_outcomes = INKStatCoupledLocalCopyCreate("local_request_outcomes",
+ request_outcomes);
+local_requests_all = INKStatCoupledLocalAdd(local_request_outcomes, "requests.all.local",
+ INKSTAT_TYPE_FLOAT);
+local_requests_redirects = INKStatCoupledLocalAdd(local_request_outcomes,
+ "requests.redirects.local", INKSTAT_TYPE_INT64);
+local_requests_unchanged = INKStatCoupledLocalAdd(local_request_outcomes,
+ "requests.unchanged.local", INKSTAT_TYPE_INT64);
+
+INKStatFloatAddTo( local_requests_all, 1.0 ) ;
+...
+INKStatIncrement (local_requests_unchanged);
+INKStatsCoupledUpdate(local_request_outcomes);
+
+INKStatCoupledLocalCopyDestroy(local_request_outcomes); </pre>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CoupledStatistics.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CoupledStatsFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/CoupledStatsFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/CoupledStatsFunctions.html Mon Dec 19 22:58:01 2011
@@ -0,0 +1,191 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Coupled Statistics</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="StatisticsFunctions.html">Prev</a> - Uncoupled Statistics Functions</div>
+<div class="navnext">Logging Functions - <a accesskey="n" href="LoggingFunctions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div>
+ <h3 class="title">
+<a name="CoupledStatsFunctions"></a>Coupled Statistics Functions</h3></div></div></div>
+
+
+<b>
+<ul>
+<li><a href="CoupledStatsFunctions.html#INKStatCoupledGlobalAdd">INKStatCoupledGlobalAdd</a></li>
+<li><a href="CoupledStatsFunctions.html#INKStatCoupledGlobalCategoryCreate">INKStatCoupledGlobalCategoryCreate</a></li>
+<li><a href="CoupledStatsFunctions.html#INKStatCoupledLocalAdd">INKStatCoupledLocalAdd</a></li>
+<li><a href="CoupledStatsFunctions.html#INKStatCoupledLocalCopyCreate">INKStatCoupledLocalCopyCreate</a></li>
+<li><a href="CoupledStatsFunctions.html#INKStatCoupledLocalCopyDestroy">INKStatCoupledLocalCopyDestroy</a></li>
+<li><a href="CoupledStatsFunctions.html#INKStatsCoupledUpdate">INKStatsCoupledUpdate</a></li>
+</ul>
+</b>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKStatCoupledGlobalAdd"></a>INKStatCoupledGlobalAdd</h4></div></div></div>
+<p>.Creates a global coupled statistic.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKStat INKStatCoupledGlobalAdd (INKCoupledStat
+ <em class="replaceable"><code>global_copy</code></em> , const char *
+ <em class="replaceable"><code>the_name</code></em> , INKStatTypes
+ <em class="replaceable"><code>the_type</code></em> )</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p><code class="code"><em class="replaceable"><code>global_copy </code></em></code> is
+ the name of the global coupled statistics category to which your new
+ coupled statistic belongs.</p>
+<p><code class="code"><em class="replaceable"><code>the_name </code></em></code> is the
+ name you use to view the statistic using Traffic Line (see
+ <a href="ViewStatsUsingTrafLine.html" title="Viewing Statistics Using Traffic Line">Viewing Statistics Using Traffic Line)</a>. There are two
+ <code class="function">INKStatTypes</code>:
+ <code class="code">INKSTAT_TYPE_INT64</code> and
+ <code class="code">INKSTAT_TYPE_FLOAT</code> (see <a href="CoupledStatistics.html#AddCoupledStats">How to Add Coupled Statistics</a>).</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A handle to the newly-created global coupled
+ statistic.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKStatCoupledGlobalCategoryCreate"></a>INKStatCoupledGlobalCategoryCreate</h4></div></div></div>
+<p>Creates a global coupled statistics category.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKCoupledStat INKStatCoupledGlobalCategoryCreate
+ ( const char * <em class="replaceable"><code>the_name</code></em>
+ )</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Returns a new global coupled statistics category; use this
+ function in <code class="function">INKPluginInit</code>. The name
+ argument is the name you use to access this statistic in Traffic
+ Line. For more information, see <a href="ViewStatsUsingTrafLine.html" title="Viewing Statistics Using Traffic Line">Viewing Statistics Using Traffic Line</a> and <a href="CoupledStatistics.html#AddCoupledStats">How to Add Coupled Statistics</a>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A handle to a the newly-created global coupled statistics
+ category.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKStatCoupledLocalAdd"></a>INKStatCoupledLocalAdd</h4></div></div></div>
+<p>Creates a local copy of a global coupled statistic.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKStat INKStatCoupledLocalAdd (INKCoupledStat
+ <em class="replaceable"><code>local_copy</code></em>, const char *
+ <em class="replaceable"><code>the_name</code></em>, INKStatTypes
+ <em class="replaceable"><code>the_type</code></em> )</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p><code class="code"><em class="replaceable"><code>local_copy </code></em></code> is
+ the name of the local coupled stat category to which your new
+ coupled stat belongs.</p>
+<p><code class="code"><em class="replaceable"><code>the_name </code></em></code> is the
+ name you use to view the statistic using Traffic Line (see
+ <a href="ViewStatsUsingTrafLine.html" title="Viewing Statistics Using Traffic Line">Viewing Statistics Using Traffic Line</a>). There are two
+ <code class="function">INKStatTypes</code>:
+ <code class="code">INKSTAT_TYPE_INT64</code> and
+ <code class="code">INKSTAT_TYPE_FLOAT</code> (see <a href="CoupledStatistics.html#AddCoupledStats">How to Add Coupled Statistics</a>).</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A handle to a local copy of the global coupled
+ statistic.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKStatCoupledLocalCopyCreate"></a>INKStatCoupledLocalCopyCreate</h4></div></div></div>
+<p>.Creates a local copy of a global coupled statistics
+ category.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd>
+ <p><code class="code">INKCoupledStat INKStatCoupledLocalCopyCreate (const char * <em class="replaceable"><code>the_name</code></em>,
+ INKCoupledStat
+ <em class="replaceable"><code>global_copy</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Returns a new local coupled statistics category; use this
+ function in any routine where you need to modify local copies
+ of global statistics. The name argument is the name you use to
+ access this statistic in Traffic Line. For additional information, see <a href="ViewStatsUsingTrafLine.html" title="Viewing Statistics Using Traffic Line">Viewing Statistics Using Traffic Line</a> and <a href="CoupledStatistics.html#AddCoupledStats">How to Add Coupled Statistics</a>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A handle to the local copy of the global coupled statistics
+ category.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKStatCoupledLocalCopyDestroy"></a>INKStatCoupledLocalCopyDestroy</h4></div></div></div>
+<p>.Destroys a local category of statistics.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKStatCoupledLocalCopyDestroy
+ (INKCoupledStat
+ <em class="replaceable"><code>local_copy</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Destroys a local statistics category. You should always destroy the
+ local category when you are finished with it (see <a href="CoupledStatistics.html#AddCoupledStats">How to Add Coupled Statistics</a>).</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the operation completes
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKStatsCoupledUpdate"></a>INKStatsCoupledUpdate</h4></div></div></div>
+<p>Updates a category of coupled statistics.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKStatsCoupledUpdate
+ (INKCoupledStat
+ <em class="replaceable"><code>local_copy</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Updates all of the coupled statistics belonging to the
+ category <code class="code"><em class="replaceable"><code>local_copy</code></em></code>.
+ For further information, see <a href="CoupledStatistics.html#AddCoupledStats">How to Add Coupled Statistics</a>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the operation completes
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl>
+</div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/CoupledStatsFunctions.html
------------------------------------------------------------------------------
svn:executable = *