You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bu...@apache.org on 2010/11/06 07:31:10 UTC
svn commit: r778776 [14/21] - in
/websites/staging/trafficserver/trunk/content/docs/trunk: admin/ sdk/
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOBufferInterfaceFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOBufferInterfaceFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOBufferInterfaceFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOBufferInterfaceFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,51 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="INKVIOReenable">Prev</a> - INKVIOReenable
+INKIOBufferBlockReadAvail - <a href="INKIOBufferBlockReadAvail">Next</a></p>
+<h2 id="io_buffer_interface">IO Buffer Interface</h2>
+<hr />
+<p><a href="IOBufferInterfaceFunctions#INKIOBufferBlockNext">INKIOBufferBlockNext</a>
+<a href="INKIOBufferBlockReadAvail">INKIOBufferBlockReadAvail</a>
+<a href="INKIOBufferBlockReadStart">INKIOBufferBlockReadStart</a>
+<a href="INKIOBufferBlockWriteAvail">INKIOBufferBlockWriteAvail</a>
+<a href="INKIOBufferBlockWriteStart">INKIOBufferBlockWriteStart</a>
+<a href="INKIOBufferCopy">INKIOBufferCopy</a>
+<a href="INKIOBufferCreate">INKIOBufferCreate</a>
+<a href="INKIOBufferDestroy">INKIOBufferDestroy</a>
+<a href="INKIOBufferProduce">INKIOBufferProduce</a>
+<a href="INKIOBufferReaderAlloc">INKIOBufferReaderAlloc</a>
+<a href="INKIOBufferReaderAvail">INKIOBufferReaderAvail</a>
+<a href="INKIOBufferReaderClone">INKIOBufferReaderClone</a>
+<a href="INKIOBufferReaderConsume">INKIOBufferReaderConsume</a>
+<a href="INKIOBufferReaderFree">INKIOBufferReaderFree</a>
+<a href="INKIOBufferReaderStart">INKIOBufferReaderStart</a>
+<a href="INKIOBufferSizedCreate">INKIOBufferSizedCreate</a>
+<a href="INKIOBufferStart">INKIOBufferStart</a>
+<a href="INKIOBufferWaterMarkGet">INKIOBufferWaterMarkGet</a>
+<a href="INKIOBufferWaterMarkSet">INKIOBufferWaterMarkSet</a>
+<a href="INKIOBufferWrite">INKIOBufferWrite</a></p>
+<h3 id="inkiobufferblocknext">INKIOBufferBlockNext</h3>
+<p>Gets the next IO buffer block.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKIOBufferBlock INKIOBufferBlockNext (INKIOBufferBlock <em class="replaceable"><code>blockp</code>)</p>
+<p><strong>Description</strong>
+ ~ Gets the next block in the buffer block chain.</p>
+<p><strong>Returns</strong>
+ ~ The next IO buffer block.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOBuffers_IO.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOBuffers_IO.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOBuffers_IO.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOBuffers_IO.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,54 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="VIOs_IO">Prev</a> - VIOs
+Guide to the Cache API - <a href="CacheAPI">Next</a></p>
+<h2 id="io_buffers">IO Buffers</h2>
+<p>The IO buffer data structure is the building block of the
+vconnection abstraction. An <strong>IO buffer</strong> (<code>INKIOBuffer</code>) is
+composed of a list of buffer blocks that point to buffer data. Both
+the buffer block (<code>INKIOBufferBlock</code>) and buffer data
+(<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 via
+<code>INKIOBufferCopy</code>, since Traffic Server must only copy pointers and
+adjust reference counts appropriately (and doesn't actually copy
+any data).</p>
+<p>The IO buffer abstraction provides for a single writer and multiple
+readers. In order for the readers to have no knowledge of each
+other, they manipulate IO buffers through the <code>INKIOBufferReader</code>
+data structure. Since only a single writer is allowed, there is no
+corresponding <code>INKIOBufferWriter</code> data structure. The writer simply
+modifies the IO buffer directly. To see an example that illustrates
+how to use IOBuffers, refer to the sample code in the description
+of
+<a href="INKIOBufferBlockReadStart" title="INKIOBufferBlockReadStart"><code>INKIOBufferBlockReadStart</code></a>.</p>
+<p>Additional information about IO buffer functions:</p>
+<ul>
+<li>
+<p>The <code>INKIOBufferReader</code> data structure tracks how much data in
+ <code>INKIOBuffer</code> has been read. It has an offset number of bytes that
+ is the current start point of a particular buffer reader (for every
+ read operation on an <code>INKIOBuffer</code>, you must allocate an
+ <code>INKIOBufferReader</code>).</p>
+</li>
+<li>
+<p>Bytes that have already been read may not necessarily be freed
+ within the <code>INKIOBuffer</code>. To consume bytes that have been read, you
+ must call <code>INKIOBufferConsume</code>.</p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOGuide.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOGuide.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOGuide.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/IOGuide.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,174 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="HostsLookupAPI">Prev</a> - Hosts Lookup API
+Net Vconnections - <a href="NetVconnections">Next</a></p>
+<h2 id="chapter_15_io_guide">Chapter 15. IO Guide</h2>
+<p>This chapter contains the following sections:</p>
+<hr />
+<p><a href="IOGuide#Vconnections" title="Vconnections">Vconnections</a>
+<a href="NetVconnections" title="Net Vconnections">Net Vconnections</a>
+<a href="Transformations_IO" title="Transformations">Transformations</a>
+<a href="HTTPTransformationPlugins#VIOs" title="VIOs">VIOs</a>
+<a href="HTTPTransformationPlugins#IOBuffers" title="IO Buffers">IO Buffers</a>
+<a href="CacheAPI" title="Guide to the Cache API">Guide to the Cache API</a>
+- <a href="CacheAPI#DoACacheRead">How to Do a Cache Read</a>
+- <a href="DoACacheWrite">How to Do a Cache Write</a>
+- <a href="DoACacheRemove">How to Do a Cache Remove</a>
+- <a href="Errors_Cache">Errors</a>
+- <a href="CacheAPI_Example">Example</a></p>
+<h2 id="vconnections">Vconnections</h2>
+<h3 id="vconnections_a_users_perspective">Vconnections: a User's Perspective</h3>
+<p>To use a vconnection, a user must first get a handle to one. This
+is usually accomplished by having it handed to the user; the user
+may also simply issue a call that creates a vconnection (such as
+<code>INKNetConnect)</code>. In the case of transform plugins, the plugin
+creates a transformation vconnection viav <code>INKTransformCreate</code> and
+then accesses the output vconnection using
+<code>INKTransformOutputVConnGet</code>.</p>
+<p>After getting a handle to a vconnection, the user can then issue a
+read or write call. It's important to note that not all
+vconnections support both reading and writing - as of yet, there
+has not been a need to query a vconnection about whether it can
+perform a read or write operation. That ability should be obvious
+from context.</p>
+<p>To issue a read or write operation, a user calls <code>INKVConnRead</code> or
+<code>INKVConnWrite</code>. These two operations both return <code>VIO (INKVIO)</code>.
+The VIO describes the operation being performed and how much
+progress has been made. Transform plugins initiate output to the
+downstream vconnection by calling <code>INKVConnWrite</code>.</p>
+<p>A vconnection read or write operation is different from a normal
+UNIX <code>read(2)</code> or <code>write(2)</code> operation. Specifically, the
+vconnection operation can specify more data to be read or written
+than exists in the buffer handed to the operation. For example,
+it's typical to issue a read for <code>INT_MAX</code> (4 billion) bytes from a
+network vconnection in order to read all the data from the network
+connection until the end of stream is reached. This contrasts with
+the usual UNIX fashion of issuing repeated calls to <code>read(2)</code> until
+one of the calls finally returns <code>0</code> to indicate the end of stream
+was reached (indeed, the underlying implementation of vconnections
+on UNIX still does issue those calls to <code>read(2)</code>, but the
+interface does not expose that detail).</p>
+<p>At most, a given vconnection can have one read operation and one
+write operation being performed on it. This is restricted both by
+design and common sense: if two write operations were performed on
+a single vconnection, then the user would not be able to specify
+which should occur first and the output would occur in an
+intermingled fashion. Note that both a read operation and a write
+operation can happen on a single vconnection at the same time; the
+restriction is for more than one operation of the same type.</p>
+<p>One obvious issue is that the buffer passed to <code>INKVConnRead</code> and
+<code>INKVConnWrite</code> won't be large enough - there is no reasonable way
+to make a buffer that can hold <code>INT_MAX</code> (4 billion) bytes! The
+secret is that vconnections engage in a protocol whereby they
+signal to the user (via the continuation passed to <code>INKVConnRead</code>
+and <code>INKVConnWrite</code>) that they have emptied the buffers passed to
+them and are ready for more data. When this occurs, it is up to the
+user to add more data to the buffers (or wait for more data to be
+added) and then wake up the vconnection by calling <code>INKVIOReenable</code>
+on the VIO describing the operation. <code>INKVIOReenable</code> specifies
+that the buffer for the operation has been modified and that the
+vconnection should reexamine it to see if it can make further
+progress.</p>
+<p>The null transform plugin provides an example of how this is done.
+Below is a prototype for <code>INKVConnWrite</code>:</p>
+<div class="codehilite"><pre><span class="n">INKVIO</span> <span class="n">INKVConnWrite</span> <span class="p">(</span><span class="n">INKVConn</span> <span class="n">connp</span><span class="p">,</span> <span class="n">INKCont</span> <span class="n">contp</span><span class="p">,</span> <span class="n">INKIOBufferReader</span> <span class="n">readerp</span><span class="p">,</span> <span class="nb">int</span> <span class="n">nbytes</span><span class="p">)</span>
+</pre></div>
+
+
+<p>The <code>connp</code> is the vconnection the user is writing to and <code>contp</code>
+is the "user" â i.e., the continuation that <code>connp</code> calls back when
+it has emptied its buffer and is ready for more data.</p>
+<p>The call made in the null transform plugin is:</p>
+<div class="codehilite"><pre><span class="n">INKVConnWrite</span> <span class="p">(</span><span class="n">output_conn</span><span class="p">,</span> <span class="n">contp</span><span class="p">,</span> <span class="n">data</span><span class="o">-></span><span class="n">output_reader</span><span class="p">,</span> <span class="n">INKVIONBytesGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">));</span>
+</pre></div>
+
+
+<p>In the example above, <code>contp</code> is the transformation vconnection
+that is writing to the output vconnection. The number of bytes to
+be written is obtained from <code>input_vio</code> by <code>INKVIONBytesGet</code>.</p>
+<p>When a vconnection calls back its user to indicate that it wants
+more data (or when some other condition has occurred), it issues a
+call to <code>INKContCall</code>. It passes the <code>INKVIO</code> describing the
+operation as the data parameter, and one of the values below as the
+event parameter.</p>
+<p><strong>Event Parameter Value</strong>
+<strong>Description</strong>
+<code>INK_EVENT_ERROR</code>
+Indicates an error has occurred on the vconnection. This will
+happen for network IO if the underlying <code>read(2)</code> or <code>write(2)</code>
+call returns an error.
+<code>INK_EVENT_VCONN_READ_READY</code>
+The vconnection has placed data in the buffer passed to an
+<code>INKVConnRead</code> operation and it would like to do more IO, but the
+buffer is now full. When the user consumes the data from the
+buffer, this should re-enable the VIO so it indicates to the
+vconnection that the buffer has been modified.
+<code>INK_EVENT_VCONN_WRITE_READY</code>
+The vconnection has removed data from the buffer passed to an
+<code>INKVConnWrite</code> operation and it would like to do more IO, but the
+buffer does not have enough data in it. When placing more data in
+the buffer, the user should re-enable the VIO so it indicates to
+the vconnection that the buffer has been modified.
+<code>INK_EVENT_VCONN_READ_COMPLETE</code>
+The vconnection has read all the bytes specified by an
+<code>INKVConnRead</code> operation. The vconnection can now be used to
+initiate a new IO operation.
+<code>INK_EVENT_VCONN_WRITE_COMPLETE</code>
+The vconnection has written all the bytes specified by an
+<code>INKVConnWrite</code> operation and can now be used to initiate a new IO
+operation.
+<code>INK_EVENT_VCONN_EOS</code>
+An attempt was made to read past the end of the stream of bytes
+during the handling of an <code>INKVConnRead</code> operation. This event
+occurs when the number of bytes available for reading from a
+vconnection is less than the number of bytes the user specifies
+should be read from the vconnection in a call to <code>INKVConnRead</code>. A
+common case where this occurs is when the user specifies that
+<code>INT_MAX</code> bytes are to be read from a network connection.
+For example: the null transform plugin's transformation receives
+<code>INK_EVENT_VCONN_WRITE_READY</code> and <code>INK_EVENT_VCONN_WRITE_COMPLETE</code>
+events from the downstream vconnection as a result of the call to
+<code>INKVConnWrite</code>.</p>
+<p>After using a vconnection, the user must call <code>INKVConnClose</code> or
+<code>INKVConnAbort</code>. While both calls indicate that the vconnection can
+destroy itself, <code>INKVConnAbort</code> should be used when the connection
+is being closed abnormally. After a call to <code>INKVConnClose</code> or
+<code>INKVConnAbort</code>, the user will not be called back by the
+vconnection again.</p>
+<p>Sometimes it's desirable to simply close down the write portion of
+a connection while keeping the read portion open. This can be
+accomplished via the <code>INKVConnShutdown</code> function, which shuts down
+either the read or write portion of a vconnection. <em>Shutdown</em> means
+that the vconnection will no longer call back the user with events
+for the portion of the connection that was shut down. For example:
+if the user shuts down the write portion of a connection, then the
+<code>INK_EVENT_VCONN_WRITE_READY</code> or <code>INK_EVENT_VCONN_WRITE_COMPLETE</code>
+events will not be produced. In the null transform plugin, the
+write operation is shut down with a call to <code>INKVConnShutdown</code>. To
+learn how vconnections are used in transformation plugins, see
+<a href="HTTPTransformationPlugins#WritingContentTransformPlugins" title="Writing Content Transform Plugins">Writing Content Transform Plugins</a>.</p>
+<p>The vconnection functions are listed below:</p>
+<hr />
+<p><a href="VconnectionFunctions#INKVConnAbort">INKVConnAbort</a>
+<a href="INKVConnClose">INKVConnClose</a>
+<a href="INKVConnClosedGet">INKVConnClosedGet</a>
+<a href="INKVConnRead">INKVConnRead</a>
+<a href="INKVConnReadVIOGet">INKVConnReadVIOGet</a>
+<a href="INKVConnShutdown">INKVConnShutdown</a>
+<a href="INKVConnWrite">INKVConnWrite</a>
+<a href="INKVConnWriteVIOGet">INKVConnWriteVIOGet</a></p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ImplementHandler_GetTransHandle.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ImplementHandler_GetTransHandle.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ImplementHandler_GetTransHandle.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ImplementHandler_GetTransHandle.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,42 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="BasicAuthorizatonPlugin">Prev</a> - The Basic Authorization
+Plugin
+Working With HTTP Headers - <a href="WorkWithHTTPHeaders">Next</a></p>
+<h3 id="implementing_the_handler_and_getting_a_handle_to_the_transaction">Implementing the Handler and Getting a Handle to the Transaction</h3>
+<p>The handler function for the plugin's parent continuation is
+implemented as follows:</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="nb">int</span>
+<span class="n">auth_plugin</span> <span class="p">(</span><span class="n">INKCont</span> <span class="n">contp</span><span class="p">,</span> <span class="n">INKEvent</span> <span class="n">event</span><span class="p">,</span> <span class="n">void</span> <span class="o">*</span><span class="n">edata</span><span class="p">)</span>
+<span class="p">{</span>
+
+ <span class="n">INKHttpTxn</span> <span class="n">txnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">INKHttpTxn</span><span class="p">)</span> <span class="n">edata</span><span class="p">;</span>
+ <span class="n">switch</span> <span class="p">(</span><span class="n">event</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_HTTP_OS_DNS:</span>
+ <span class="n">handle_dns</span> <span class="p">(</span><span class="n">txnp</span><span class="p">,</span> <span class="n">contp</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">case</span> <span class="n">INK_EVENT_HTTP_SEND_RESPONSE_HDR:</span>
+ <span class="n">handle_response</span> <span class="p">(</span><span class="n">txnp</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="n">default:</span>
+ <span class="n">break</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitializationFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitializationFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitializationFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitializationFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,47 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="FunctionReference">Prev</a> - Chapter 18. Function Reference
+INKPluginRegister - <a href="INKPluginRegister">Next</a></p>
+<h2 id="initialization_functions">Initialization Functions</h2>
+<ul>
+<li><a href="InitializationFunctions#INKPluginInit"><strong>INKPluginInit</strong></a></li>
+<li><strong><a href="INKPluginRegister">INKPluginRegister</a></strong></li>
+<li><strong><a href="INKTrafficServerVersionGet">INKTrafficServerVersionGet</a></strong><a href="INKTrafficServerVersionGet" /></li>
+</ul>
+<h3 id="inkplugininit">INKPluginInit</h3>
+<p><strong>Prototype</strong>
+ ~ <code>void INKPluginInit (int <code class="replaceable">argc</code>, const
+ char <code>*<span class="replaceable">argv</span> []</code>)</p>
+<p><strong>Arguments</strong>
+ ~ <code><code class="replaceable">argc</code> is a count of the number of
+ arguments in the argument vector,
+ <code><code class="varname"><span class="replaceable"> argv</span></code>. The
+ count has a value of at least one because the first argument in the
+ argument vector is the plugin's name, which must exist in order for
+ the plugin to be loaded.</p>
+<div class="codehilite"><pre>`<span class="nt"><code</span> <span class="na">class=</span><span class="s">"varname"</span><span class="nt">><span</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>argv<span class="nt"></span></span>` is
+the vector of arguments. The number of arguments in the vector is
+`<span class="nt"><code</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>argc`; `argv[0]` always contains the
+name of the plugin shared library.
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ This function must be defined by all plugins. Traffic Server
+ calls this initialization routine when it loads the plugin and sets
+ <code>argc</code> and <code>argv</code> based on the values in <code>plugin.config</code>.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitiateConnectionFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitiateConnectionFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitiateConnectionFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitiateConnectionFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,71 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="HTTPTransactionFunctions">Prev</a> - HTTP Transaction Functions
+Intercepting HTTP Transaction Functions -
+<a href="InterceptingHTTPTransactionFuncs">Next</a></p>
+<h2 id="initiate_connection">Initiate Connection</h2>
+<h3 id="inkhttpconnect">INKHttpConnect</h3>
+<p>Sends an HTTP request through the Traffic Server HTTP SM.</p>
+<p><strong>Prototype</strong>
+ ~ <code>InkReturnCode INKHttpConnect (unsigned int <em class="replaceable"><code>ip</code>,
+ int <em><code>port</code></em>, INKVConn *<em><code>vc</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>unsigned int``<em class="replaceable"><code>ip</code> is the IP
+ address used to set the value of the vconnection remote IP address.
+ This is equivalent to a client IP address, or the IP from which the
+ connection originated. Value is in host byte order.</p>
+<div class="codehilite"><pre><span class="sb">`int``<em class="replaceable"><code>port`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">port</span> <span class="n">used</span> <span class="n">to</span> <span class="n">set</span>
+<span class="n">the</span> <span class="n">value</span> <span class="n">of</span> <span class="n">the</span> <span class="n">vconnection</span> <span class="n">remote</span> <span class="n">port</span><span class="o">.</span> <span class="n">This</span> <span class="n">is</span> <span class="n">equivalent</span> <span class="n">to</span> <span class="n">a</span>
+<span class="n">client</span> <span class="n">port</span><span class="p">,</span> <span class="ow">or</span> <span class="n">the</span> <span class="n">port</span> <span class="n">from</span> <span class="n">which</span> <span class="n">the</span> <span class="n">connection</span> <span class="n">originated</span><span class="o">.</span> <span class="n">The</span>
+<span class="n">value</span> <span class="n">is</span> <span class="n">in</span> <span class="n">host</span> <span class="n">byte</span> <span class="n">order</span><span class="o">.</span>
+
+<span class="sb">`INKVConn *``<em class="replaceable"><code>vc`</span> <span class="n">is</span> <span class="n">the</span>
+<span class="n">vconnection</span> <span class="n">returned</span><span class="o">.</span>
+
+<span class="n">Once</span> <span class="n">the</span> <span class="n">vconnection</span> <span class="n">is</span> <span class="n">established</span><span class="p">,</span> <span class="n">you</span> <span class="n">can</span> <span class="k">use</span> <span class="n">regular</span>
+<span class="n">vconnection</span> <span class="n">operations</span> <span class="p">(</span><span class="sb">`INKVConnRead`</span><span class="p">,</span> <span class="sb">`INKVConnWrite`</span><span class="p">,</span> <span class="n">etc</span><span class="p">)</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Sends an HTTP request through the Traffic Server HTTP SM. The
+ HTTP request goes through the Traffic Server the same way a request
+ from a client (such as a browser) does. A typical usage scenario is
+ as follows:</p>
+<div class="codehilite"><pre><span class="o">-</span> <span class="n">Call</span> <span class="sb">`INKHttpConnect`</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="n">Use</span> <span class="sb">`INKVConnWrite`</span> <span class="n">to</span> <span class="nb">send</span> <span class="n">an</span> <span class="n">HTTP</span> <span class="n">request</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="n">Use</span> <span class="sb">`INKVConnRead`</span> <span class="n">to</span> <span class="n">get</span> <span class="n">the</span> <span class="n">HTTP</span> <span class="n">response</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="n">Use</span> <span class="sb">`INKHttpParser`</span> <span class="n">to</span> <span class="n">parse</span> <span class="n">the</span> <span class="n">response</span> <span class="p">(</span><span class="k">if</span> <span class="n">needed</span><span class="p">)</span><span class="o">.</span>
+
+<span class="o">**</span><span class="n">Note:</span><span class="o">**</span> <span class="n">the</span> <span class="n">request</span> <span class="ow">and</span> <span class="n">response</span> <span class="n">go</span> <span class="n">through</span> <span class="n">the</span> <span class="n">Traffic</span> <span class="n">Server</span>
+<span class="n">HTTP</span> <span class="n">SM</span><span class="o">.</span> <span class="n">The</span> <span class="n">request</span> <span class="ow">and</span> <span class="n">the</span> <span class="n">response</span> <span class="n">can</span> <span class="n">be</span> <span class="n">cached</span> <span class="ow">and</span> <span class="n">the</span>
+<span class="n">transaction</span> <span class="n">will</span> <span class="n">be</span> <span class="n">logged</span> <span class="n">in</span> <span class="sb">`squid.log`</span><span class="o">.</span>
+
+<span class="n">Also</span> <span class="n">note</span> <span class="n">that</span> <span class="n">the</span> <span class="n">IP</span> <span class="n">address</span> <span class="n">passed</span> <span class="n">to</span> <span class="sb">`INKHttpConnect`</span> <span class="n">will</span> <span class="n">be</span>
+<span class="n">used</span> <span class="n">as</span> <span class="n">the</span> <span class="n">client</span> <span class="n">IP</span> <span class="n">address</span> <span class="n">in</span> <span class="sb">`squid.log`</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitiateHTTPConnection.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitiateHTTPConnection.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitiateHTTPConnection.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InitiateHTTPConnection.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,25 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="InterceptingHTTPTx">Prev</a> - Intercepting HTTP Transactions
+HTTP Alternate Selection - <a href="HTTPAlternateSelection">Next</a></p>
+<h2 id="initiate_http_connection">Initiate HTTP Connection</h2>
+<p>This function enables plugins to initiate HTTP transactions. The
+initiate HTTP connection function is:</p>
+<ul>
+<li><a href="InitiateConnectionFunctions#INKHttpConnect" title="INKHttpConnect">INKHttpConnect</a></li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InterceptingHTTPTransactionFuncs.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InterceptingHTTPTransactionFuncs.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InterceptingHTTPTransactionFuncs.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InterceptingHTTPTransactionFuncs.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,91 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="InitiateConnectionFunctions">Prev</a> - Initiate Connection
+INKHttpTxnServerIntercept - <a href="INKHttpTxnServerIntercept">Next</a></p>
+<h2 id="intercepting_http_transaction_functions">Intercepting HTTP Transaction Functions</h2>
+<hr />
+<p><a href="InterceptingHTATPTAransactionFuncts#INKHttpTxnIntercept">INKHttpTxnIntercept</a>
+<a href="INKHttpTxnServerIntercept">INKHttpTxnServerIntercept</a></p>
+<h3 id="inkhttptxnintercept">INKHttpTxnIntercept</h3>
+<p>Enables a plugin to intercept an HTTP client's request and serve
+content in place of the origin server.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKHttpTxnIntercept (INKCont <em class="replaceable"><code>contp</code>,
+ INKHttpTxn <em><code>txnp</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>INKCont``<em class="replaceable"><code>contp</code> is the
+ continuation called to accept the connection.</p>
+<div class="codehilite"><pre><span class="sb">`INKHttpTxn``<em class="replaceable"><code>txnp`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">current</span>
+<span class="n">HTTP</span> <span class="n">transaction</span> <span class="n">the</span> <span class="n">plugin</span> <span class="n">wants</span> <span class="n">to</span> <span class="n">intercept</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Enables a plugin to intercept an HTTP client's request and
+ serve content in place of the origin server. The request is
+ intercepted immediately after it is read by Traffic Server; the
+ origin server is not contacted. This API should be used in the
+ <code>INK_HTTP_READ_REQUEST_HDR_HOOK</code> hook.</p>
+<div class="codehilite"><pre><span class="n">Once</span> <span class="sb">`INKHttpTxnIntercept`</span> <span class="n">is</span> <span class="n">called</span><span class="p">,</span> <span class="n">the</span> <span class="n">handler</span> <span class="n">of</span> <span class="n">the</span>
+<span class="n">continuation</span> <span class="sb">`<em class="replaceable"><code>contp`</span> <span class="n">receives</span> <span class="n">an</span>
+<span class="n">event</span> <span class="sb">`INK_EVENT_NET_ACCEPT`</span><span class="o">.</span> <span class="n">Note</span> <span class="n">that</span> <span class="n">the</span> <span class="n">continuation</span> <span class="n">passed</span>
+<span class="n">should</span> <span class="ow">not</span> <span class="n">have</span> <span class="n">a</span> <span class="sb">`NULL`</span> <span class="n">mutex</span><span class="p">;</span> <span class="k">if</span> <span class="n">it</span> <span class="n">does</span><span class="p">,</span> <span class="k">then</span> <span class="n">an</span> <span class="n">error</span> <span class="n">is</span>
+<span class="n">returned</span><span class="o">.</span> <span class="n">The</span> <span class="sb">`void``<em class="replaceable"><code>*data`</span> <span class="n">passed</span> <span class="n">to</span>
+<span class="n">the</span> <span class="n">handler</span> <span class="n">of</span> <span class="n">the</span> <span class="n">continuation</span>
+<span class="sb">`<em class="replaceable"><code>contp`</span> <span class="n">is</span> <span class="n">a</span> <span class="n">data</span> <span class="n">of</span> <span class="n">type</span>
+<span class="sb">`netvconnection`</span> <span class="n">that</span> <span class="n">represents</span> <span class="n">the</span> <span class="n">connection</span><span class="o">.</span> <span class="n">Once</span> <span class="n">a</span> <span class="n">vconnection</span>
+<span class="n">is</span> <span class="n">established</span><span class="p">,</span> <span class="n">the</span> <span class="n">user</span> <span class="n">can</span> <span class="k">use</span> <span class="n">regular</span> <span class="n">vconnection</span> <span class="n">operations</span>
+<span class="p">(</span><span class="sb">`INKVConnRead`</span><span class="p">,</span> <span class="sb">`INKVConnWrite`</span><span class="p">,</span> <span class="n">etc</span><span class="o">...</span><span class="p">)</span><span class="o">.</span>
+
+<span class="n">A</span> <span class="n">typical</span> <span class="n">scenario</span> <span class="k">for</span> <span class="n">using</span> <span class="sb">`INKHttpTxnIntercept`</span> <span class="n">is</span> <span class="n">as</span> <span class="n">follows:</span>
+
+<span class="o">-</span> <span class="n">Call</span> <span class="sb">`INKHttpTxnIntercept`</span> <span class="n">from</span> <span class="n">hook</span>
+ <span class="sb">`INK_HTTP_READ_REQUEST_HDR_HOOK`</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="n">Get</span> <span class="n">called</span> <span class="n">back</span> <span class="n">on</span> <span class="n">the</span> <span class="n">continuation</span><span class="s">'s handler that'</span><span class="n">s</span> <span class="n">passed</span> <span class="n">as</span>
+ <span class="n">an</span> <span class="n">argument</span> <span class="n">to</span> <span class="sb">`INKHttpTxnIntercept`</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="n">Get</span> <span class="n">the</span> <span class="n">vconnection</span> <span class="n">from</span> <span class="n">the</span> <span class="n">argument</span>
+ <span class="sb">`void *``<em class="replaceable"><code>data`</span> <span class="o">.</span>
+
+<span class="o">-</span> <span class="n">Use</span> <span class="sb">`INKVConnRead`</span> <span class="n">to</span> <span class="n">get</span> <span class="n">the</span> <span class="n">HTTP</span> <span class="n">request</span><span class="o">.</span> <span class="n">Note</span> <span class="n">that</span> <span class="n">you</span> <span class="n">will</span>
+ <span class="ow">not</span> <span class="n">receive</span> <span class="n">the</span> <span class="n">event</span> <span class="sb">`INK_VCONN_READ_COMPLETE`</span> <span class="o">-</span> <span class="n">you</span> <span class="n">will</span> <span class="n">only</span>
+ <span class="n">receive</span> <span class="n">the</span> <span class="sb">`INK_VCONN_READ_READY`</span> <span class="n">event</span> <span class="n">because</span> <span class="n">the</span> <span class="n">number</span> <span class="n">of</span>
+ <span class="n">characters</span> <span class="n">to</span> <span class="n">be</span> <span class="nb">read</span> <span class="n">is</span> <span class="n">unknown</span><span class="o">.</span> <span class="n">You</span> <span class="n">should</span> <span class="n">rely</span> <span class="n">on</span>
+ <span class="sb">`INKTHttpParser`</span> <span class="n">to</span> <span class="n">parse</span> <span class="n">the</span> <span class="n">request</span> <span class="ow">and</span> <span class="k">return</span> <span class="n">a</span> <span class="n">status</span>
+ <span class="sb">`INK_PARSE_DONE`</span> <span class="n">when</span> <span class="n">the</span> <span class="n">request</span> <span class="n">is</span> <span class="n">fully</span> <span class="n">received</span> <span class="p">(</span><span class="n">escape</span>
+ <span class="n">sequence</span> <span class="sb">`\r\n\r\n read`</span><span class="p">)</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="n">Use</span> <span class="sb">`INKHttpParser`</span> <span class="n">to</span> <span class="n">parse</span> <span class="n">the</span> <span class="n">request</span><span class="o">.</span>
+
+<span class="o">-</span> <span class="n">Use</span> <span class="sb">`INKVConnWrite`</span> <span class="n">to</span> <span class="nb">write</span> <span class="n">the</span> <span class="n">HTTP</span> <span class="n">response</span><span class="o">.</span>
+
+<span class="o">!</span><span class="p">[[</span><span class="n">Note</span><span class="p">]](</span><span class="n">images</span><span class="sr">/docbook/</span><span class="n">note</span><span class="o">.</span><span class="n">png</span><span class="p">)</span>
+<span class="n">Note</span>
+<span class="n">Because</span> <span class="n">the</span> <span class="n">request</span> <span class="ow">and</span> <span class="n">response</span> <span class="k">do</span> <span class="ow">not</span> <span class="n">go</span> <span class="n">through</span> <span class="n">the</span> <span class="n">Traffic</span>
+<span class="n">Server</span> <span class="n">HTTP</span> <span class="n">state</span> <span class="n">machine</span><span class="p">,</span> <span class="n">neither</span> <span class="n">is</span> <span class="n">cached</span> <span class="n">by</span> <span class="n">Traffic</span> <span class="n">Server</span><span class="o">.</span> <span class="n">The</span>
+<span class="n">request</span> <span class="n">is</span> <span class="n">logged</span> <span class="n">in</span> <span class="sb">`squid.log`</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span> <span class="n">This</span> <span class="n">error</span> <span class="n">is</span> <span class="n">also</span> <span class="n">returned</span> <span class="k">if</span> <span class="n">the</span>
+<span class="n">continuation</span> <span class="n">passed</span> <span class="n">has</span> <span class="n">a</span> <span class="sb">`NULL`</span> <span class="n">mutex</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InterceptingHTTPTx.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InterceptingHTTPTx.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InterceptingHTTPTx.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/InterceptingHTTPTx.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,30 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="HTTP_Transactions">Prev</a> - HTTP Transactions
+Initiate HTTP Connection - <a href="InitiateHTTPConnection">Next</a></p>
+<h2 id="intercepting_http_transactions">Intercepting HTTP Transactions</h2>
+<p>The intercepting HTTP transaction functions enable plugins to
+intercept transactions either after the request is received or upon
+contact with the origin server. The plugin then acts as the origin
+server using the <code>INKVConn</code> interface. The intercepting HTTP
+transaction function allow for reading <code>POST</code> bodies in plugins as
+well as using alternative transports to the origin server.The
+intercepting HTTP transaction functions are:</p>
+<ul>
+<li><a href="InterceptingHTTPTransactionFuncs#INKHttpTxnIntercept" title="INKHttpTxnIntercept">INKHttpTxnIntercept</a></li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Interface_ThreadFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Interface_ThreadFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Interface_ThreadFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/Interface_ThreadFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,33 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="MemoryAllocation">Prev</a> - Memory Allocation
+Chapter 10. HTTP Headers - <a href="HTTPHeaders">Next</a></p>
+<h2 id="thread_functions">Thread Functions</h2>
+<p>The Traffic Server API thread functions enable you to create,
+destroy, and identify threads within Traffic Server. Multithreading
+enables a single program to have more than one stream of execution
+and to process more than one transaction at a time. Threads
+serialize their access to shared resources and data using the
+<code>INKMutex</code> type, as described in
+<a href="MutexGuide#Mutexes" title="Mutexes">Mutexes</a>.</p>
+<p>The thread functions are listed below:</p>
+<hr />
+<p><a href="ThreadFunctions#INKThreadCreate" title="INKThreadCreate">INKThreadCreate</a>
+<a href="INKThreadDestroy" title="INKThreadDestroy">INKThreadDestroy</a>
+<a href="INKThreadInit" title="INKThreadInit">INKThreadInit</a>
+<a href="INKThreadSelf" title="INKThreadSelf">INKThreadSelf</a></p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LicensingPlugin.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LicensingPlugin.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LicensingPlugin.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LicensingPlugin.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,52 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="AccessPluginFiles">Prev</a> - Accessing Installed Plugin Files
+Setting Up Licensing - <a href="SetUpLicensing">Next</a></p>
+<h2 id="licensing_your_plugin">Licensing Your Plugin</h2>
+<p>When installing a plugin that requires a license, <code>plugin.db</code> must
+be updated. This file contains the license keys for the plugins. At
+load time, Traffic Server reads the keys in the <code>plugin.db</code> file
+and checks the validity of each. If a key is not valid, then the
+plugin is not executed.</p>
+<h3 id="format_of_plugindb">Format of plugin.db</h3>
+<p># comments start with a <code>#</code> character</p>
+<div class="codehilite"><pre><span class="k">[plugin_name]</span>
+<span class="na">Object</span><span class="o">=</span><span class="s">plugin.so</span>
+<span class="na">License</span><span class="o">=</span><span class="s">Key</span>
+</pre></div>
+
+
+<p>Be careful with the syntax:</p>
+<ul>
+<li>
+<p>Object is with an uppercase 'O'</p>
+<p>Example: <code>object=plugin.so is bad</code></p>
+</li>
+<li>
+<p>License is with an uppercase 'L'</p>
+<p>Example: <code>license=key is bad</code></p>
+</li>
+<li>
+<p>No blank between '=' and value.</p>
+<p>Example: <code>Object = plugin.so is bad</code></p>
+</li>
+<li>
+<p>No blank after the value, either.</p>
+<p>Example: <code>License=Key is bad</code></p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LoggingAPI.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LoggingAPI.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LoggingAPI.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LoggingAPI.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,121 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="GenerateLicenseKey">Prev</a> - Generating a License Key
+Chapter 17. Adding Statistics - <a href="AddingStatistics">Next</a></p>
+<h2 id="guide_to_the_logging_api">Guide to the Logging API</h2>
+<p>The logging API enables your plugin to log entries in a custom text
+log file that you create with the call <code>INKTextLogObjectCreate</code>.
+This log file is part of Traffic Server's logging system; by
+default, it is stored in the logging directory. Once you have
+created the log object, you can set log properties.</p>
+<p>The logging API enables you to:</p>
+<ul>
+<li>
+<p>Establish a custom text log for your plugin: see
+ <a href="LoggingFunctions#INKTextLogObjectCreate" title="INKTextLogObjectCreate">INKTextLogObjectCreate</a></p>
+</li>
+<li>
+<p>Set the log header for your custom text log: see
+ <a href="INKTextLogObjectHeaderSet" title="INKTextLogObjectHeaderSet">INKTextLogObjectHeaderSet</a></p>
+</li>
+<li>
+<p>Enable or disable rolling your custom text log: see
+ <a href="INKTextLogObjectRollingEnabledSet" title="INKTextLogObjectRollingEnabledSet">INKTextLogObjectRollingEnabledSet</a></p>
+</li>
+<li>
+<p>Set the rolling interval (in seconds) for your custom text log:
+ see
+ <a href="INKTextLogObjectRollingIntervalSecSet" title="INKTextLogObjectRollingIntervalSecSet">INKTextLogObjectRollingIntervalSecSet</a></p>
+</li>
+<li>
+<p>Set the rolling offset for your custom text log: see
+ <a href="INKTextLogObjectRollingOffsetHrSet" title="INKTextLogObjectRollingOffsetHrSet">INKTextLogObjectRollingOffsetHrSet</a></p>
+</li>
+<li>
+<p>Write text entries to the custom text log: see
+ <a href="INKTextLogObjectWrite" title="INKTextLogObjectWrite">INKTextLogObjectWrite</a></p>
+</li>
+<li>
+<p>Flush the contents of the custom text log's write buffer to
+ disk: see
+ <a href="INKTextLogObjectFlush" title="INKTextLogObjectFlush">INKTextLogObjectFlush</a></p>
+</li>
+<li>
+<p>Destroy custom text logs when you are done with them: see
+ <a href="INKTextLogObjectDestroy" title="INKTextLogObjectDestroy">INKTextLogObjectDestroy</a></p>
+</li>
+</ul>
+<p>The steps below show how the logging API is used in the
+<code>blacklist-1.c</code> sample plugin. For the complete source code, see
+the
+<a href="App_SampleSourceCode" title="Appendix A. Sample Source Code"><em>Sample Source Code</em></a>
+appendix.</p>
+<ol>
+<li>
+<p>A new log file is defined as a global variable.</p>
+<div class="codehilite"><pre><span class="n">static</span> <span class="n">INKTextLogObject</span> <span class="nb">log</span><span class="p">;</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>In <code>INKPluginInit</code>, a new log object is allocated:</p>
+<div class="codehilite"><pre><span class="nb">log</span> <span class="o">=</span> <span class="n">INKTextLogObjectCreate</span><span class="p">(</span><span class="s">"blacklist"</span><span class="p">,</span> <span class="n">INK_LOG_MODE_ADD_TIMESTAMP</span><span class="p">,</span>
+ <span class="n">NULL</span><span class="p">,</span> <span class="o">&</span><span class="n">error</span><span class="p">);</span>
+</pre></div>
+
+
+<p>The new log is named <code>blacklist.log</code>. Each entry written to the log
+will have a timestamp. The <code>NULL</code> argument specifies that the new
+log does not have a log header. The error argument stores the
+result of the log creation; if the log is created successfully,
+then an error will be equal to <code>INK_LOG_ERROR_NO_ERROR</code>.</p>
+</li>
+<li>
+<p>After creating the log, the plugin makes sure that the log was
+ created successfully:</p>
+<div class="codehilite"><pre><span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="nb">log</span><span class="p">)</span> <span class="p">{</span>
+ <span class="nb">printf</span><span class="p">(</span><span class="s">"Blacklist plugin: error %d while creating log\n"</span><span class="p">,</span> <span class="n">error</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>The <code>blacklist-1</code> plugin matches the host portion of the URL
+ (in each client request) with a list of blacklisted sites (stored
+ in the array <code>sites[</code>]):</p>
+<div class="codehilite"><pre><span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">nsites</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">strncmp</span> <span class="p">(</span><span class="n">host</span><span class="p">,</span> <span class="n">sites</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">host_length</span><span class="p">)</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+</pre></div>
+
+
+<p>If the host matches one of the blacklisted sites (such as
+<code>sites[i]</code>), then the plugin writes a blacklist entry to
+<code>blacklist.log</code>:</p>
+<div class="codehilite"><pre> <span class="k">if</span> <span class="p">(</span><span class="nb">log</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKTextLogObjectWrite</span><span class="p">(</span><span class="nb">log</span><span class="p">,</span> <span class="s">"blacklisting site: %s"</span><span class="p">,</span> <span class="n">sites</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+</pre></div>
+
+
+<p>The format of the log entry is as follows:</p>
+<p><code><timestamp>``blacklisting site:``sites[i]</code></p>
+<p>The log is not flushed or destroyed in the <code>blacklist-1</code> plugin -
+it lives for the life of the plugin.</p>
+</li>
+</ol>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LoggingFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LoggingFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LoggingFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/LoggingFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,115 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="CoupledStatsFunctions">Prev</a> - Coupled Statistics Functions
+INKTextLogObjectDestroy - <a href="INKTextLogObjectDestroy">Next</a></p>
+<h2 id="logging_functions">Logging Functions</h2>
+<hr />
+<p><a href="LoggingFunctions#INKTextLogObjectCreate">INKTextLogObjectCreate</a>
+<a href="INKTextLogObjectDestroy">INKTextLogObjectDestroy</a>
+<a href="INKTextLogObjectFlush">INKTextLogObjectFlush</a>
+<a href="INKTextLogObjectHeaderSet">INKTextLogObjectHeaderSet</a>
+<a href="INKTextLogObjectRollingEnabledSet">INKTextLogObjectRollingEnabledSet</a>
+<a href="INKTextLogObjectRollingIntervalSecSet">INKTextLogObjectRollingIntervalSecSet</a>
+<a href="INKTextLogObjectRollingOffsetHrSet">INKTextLogObjectRollingOffsetHrSet</a>
+<a href="INKTextLogObjectWrite">INKTextLogObjectWrite</a></p>
+<h3 id="inktextlogobjectcreate">INKTextLogObjectCreate</h3>
+<p>Creates a new custom log for your plugin.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKTextLogObjectCreate (const char *<em class="replaceable"><code>filename</code>,
+ int <em><code>mode</code></em>, INKTextLogObject *<em><code>new_logobj</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code>const char *<em class="replaceable"><code>filename</code>
+ is the name of the new log file created in the <code>log</code> directory. You
+ can specify a path to a subdirectory within the <code>log</code> directory
+ (e.g. <code>subdir/filename</code>), but make sure you create the subdirectory
+ first. If you do not specify a file name extension, then the
+ extension <code>.log</code> is automatically added.</p>
+<div class="codehilite"><pre>The logs you create are treated like ordinary logs - that is, they
+are rolled if log rolling is enabled. Log collation, however, is
+not supported.
+
+`int <span class="nt"><em</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">><code></span>mode` can be `0` and/or the
+following:
+
+ INK_LOG_MODE_ADD_TIMESTAMP
+
+Whenever the plugin makes a log entry using `INKTextLogObjectWrite`
+(see below), it prepends the entry with a timestamp.
+
+ INK_LOG_MODE_DO_NOT_RENAME
+
+This means that if there is a filename conflict, then Traffic
+Server should not attempt to rename the custom log. As a
+consequence of the name conflict, the custom log is not created.
+
+`INKTextLogObject *<span class="nt"><i</span> <span class="na">class=</span><span class="s">"replaceable"</span><span class="nt">></span>new_logobj <span class="nt"></i></span>` is set
+to the newly-created log object.
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Creates a custom log for your plugin. Once the log object is
+ created, use the APIs below to set properties.</p>
+<div class="codehilite"><pre><span class="o">-</span> <span class="p">[</span><span class="n">INKTextLogObjectRollingEnabledSet</span><span class="p">](</span><span class="n">INKTextLogObjectRollingEnabledSet</span><span class="p">)</span>
+<span class="o">-</span> <span class="p">[</span><span class="n">INKTextLogObjectRollingIntervalSecSet</span><span class="p">](</span><span class="n">INKTextLogObjectRollingIntervalSecSet</span><span class="p">)</span>
+<span class="o">-</span> <span class="p">[</span><span class="n">INKTextLogObjectRollingOffsetHrSet</span><span class="p">](</span><span class="n">INKTextLogObjectRollingOffsetHrSet</span><span class="p">)</span>
+
+<span class="n">If</span> <span class="n">the</span> <span class="n">value</span> <span class="n">of</span> <span class="sb">`<em class="replaceable"><code> mode`</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">valid</span><span class="p">,</span>
+<span class="k">then</span> <span class="n">the</span> <span class="n">behavior</span> <span class="n">of</span> <span class="n">the</span> <span class="n">API</span> <span class="n">cannot</span> <span class="n">be</span> <span class="n">predicted</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Example</strong>
+ ~ Suppose you call:</p>
+<div class="codehilite"><pre> <span class="n">INKTextLogObjectCreate</span> <span class="p">(</span><span class="s">"squid"</span> <span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">NULL</span><span class="p">,</span> <span class="o">&</span><span class="nb">log</span><span class="p">);</span>
+
+<span class="n">If</span> <span class="sb">`<em class="replaceable"><code> mode`</span> <span class="n">is</span>
+<span class="sb">`INK_LOG_MODE_DO_NOT_RENAME`</span><span class="p">,</span> <span class="k">then</span> <span class="n">you</span> <span class="n">will</span> <span class="ow">not</span> <span class="n">get</span> <span class="n">a</span> <span class="k">new</span> <span class="nb">log</span> <span class="k">if</span>
+<span class="sb">`squid.log`</span> <span class="n">already</span> <span class="nb">exists</span> <span class="p">(</span><span class="n">you</span><span class="err">'</span><span class="n">ll</span> <span class="n">get</span> <span class="n">an</span> <span class="n">error</span> <span class="n">instead</span><span class="p">)</span><span class="o">.</span>
+
+<span class="n">If</span> <span class="sb">`<em class="replaceable"><code> mode`</span> <span class="n">is</span> <span class="ow">not</span>
+<span class="sb">`INK_LOG_MODE_DO_NOT_RENAME`</span><span class="p">,</span> <span class="k">then</span> <span class="n">Traffic</span> <span class="n">Server</span> <span class="n">tries</span> <span class="n">to</span> <span class="nb">rename</span>
+<span class="n">the</span> <span class="nb">log</span> <span class="n">to</span> <span class="n">a</span> <span class="k">new</span> <span class="n">name</span> <span class="p">(</span><span class="n">it</span> <span class="n">will</span> <span class="n">try</span> <span class="sb">`squid_1.log`</span><span class="p">)</span><span class="o">.</span>
+
+<span class="n">If</span> <span class="n">a</span> <span class="nb">log</span> <span class="n">object</span> <span class="n">is</span> <span class="n">created</span> <span class="n">with</span> <span class="sb">`INK_LOG_MODE_DO_NOT_RENAME`</span> <span class="sb">`mode`</span>
+<span class="ow">and</span> <span class="n">a</span> <span class="nb">log</span> <span class="n">with</span> <span class="n">the</span> <span class="n">same</span> <span class="n">file</span> <span class="n">name</span> <span class="n">already</span> <span class="nb">exists</span><span class="p">,</span> <span class="k">then</span> <span class="n">the</span>
+<span class="n">signature</span> <span class="p">(</span><span class="n">i</span><span class="o">.</span><span class="n">e</span><span class="o">.</span><span class="p">,</span> <span class="n">the</span> <span class="n">type</span> <span class="n">of</span> <span class="nb">log</span> <span class="n">file</span><span class="p">)</span> <span class="n">is</span> <span class="n">compared</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span>
+<span class="n">signatures</span> <span class="n">of</span> <span class="n">the</span> <span class="nb">log</span> <span class="n">files</span> <span class="n">match</span><span class="p">,</span> <span class="k">then</span> <span class="n">the</span> <span class="n">pre</span><span class="o">-</span><span class="n">existing</span> <span class="n">file</span> <span class="n">is</span>
+<span class="n">opened</span> <span class="ow">and</span> <span class="n">logging</span> <span class="n">is</span> <span class="n">resumed</span> <span class="n">at</span> <span class="n">the</span> <span class="n">end</span> <span class="n">of</span> <span class="n">the</span> <span class="n">file</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span>
+<span class="n">signatures</span> <span class="k">do</span> <span class="ow">not</span> <span class="n">match</span><span class="p">,</span> <span class="k">then</span> <span class="n">an</span> <span class="n">error</span> <span class="n">is</span> <span class="n">returned</span><span class="o">.</span>
+
+<span class="n">If</span> <span class="n">a</span> <span class="nb">log</span> <span class="n">object</span> <span class="n">is</span> <span class="n">created</span> <span class="n">without</span> <span class="sb">`INK_LOG_MODE_DO_NOT_RENAME`</span>
+<span class="sb">`mode`</span> <span class="ow">and</span> <span class="n">a</span> <span class="nb">log</span> <span class="n">with</span> <span class="n">the</span> <span class="n">same</span> <span class="n">file</span> <span class="n">name</span> <span class="n">already</span> <span class="nb">exists</span><span class="p">,</span> <span class="k">then</span> <span class="n">the</span>
+<span class="n">signatures</span> <span class="n">are</span> <span class="n">compared</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="n">signatures</span> <span class="n">of</span> <span class="n">the</span> <span class="nb">log</span> <span class="n">files</span> <span class="n">match</span><span class="p">,</span>
+<span class="k">then</span> <span class="n">the</span> <span class="n">pre</span><span class="o">-</span><span class="n">existing</span> <span class="n">file</span> <span class="n">is</span> <span class="n">opened</span> <span class="ow">and</span> <span class="n">logging</span> <span class="n">is</span> <span class="n">resumed</span> <span class="n">at</span> <span class="n">the</span>
+<span class="n">end</span> <span class="n">of</span> <span class="n">the</span> <span class="n">file</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="n">signatures</span> <span class="k">do</span> <span class="ow">not</span> <span class="n">match</span><span class="p">,</span> <span class="k">then</span> <span class="n">another</span> <span class="n">file</span>
+<span class="n">with</span> <span class="sb">`filename_1.log`</span> <span class="n">is</span> <span class="n">tried</span> <span class="ow">and</span> <span class="n">so</span> <span class="n">on</span><span class="o">.</span>
+
+<span class="o">**</span><span class="n">Note:</span><span class="o">**</span> <span class="n">The</span> <span class="nb">log</span> <span class="n">file</span> <span class="n">signature</span> <span class="n">indicates</span> <span class="nb">log</span> <span class="n">file</span> <span class="n">type</span><span class="o">.</span> <span class="n">Log</span> <span class="n">files</span>
+<span class="n">can</span> <span class="n">be</span> <span class="n">structured</span> <span class="p">(</span><span class="n">fixed</span> <span class="nb">format</span><span class="p">)</span> <span class="nb">log</span> <span class="n">files</span> <span class="ow">or</span> <span class="n">unstructured</span> <span class="p">(</span><span class="n">free</span>
+<span class="nb">format</span><span class="p">)</span> <span class="nb">log</span> <span class="n">files</span><span class="o">.</span> <span class="n">All</span> <span class="n">free</span> <span class="nb">format</span> <span class="nb">log</span> <span class="n">files</span> <span class="n">have</span> <span class="n">the</span> <span class="n">same</span>
+<span class="n">signature</span><span class="p">,</span> <span class="k">while</span> <span class="n">fixed</span> <span class="nb">format</span> <span class="nb">log</span> <span class="n">files</span> <span class="n">have</span> <span class="n">the</span> <span class="n">same</span> <span class="n">structured</span>
+<span class="p">(</span><span class="n">fixed</span><span class="p">)</span> <span class="nb">format</span> <span class="n">as</span> <span class="n">the</span> <span class="n">signature</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MIMEFldsBelongAssocMIMEHdr.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MIMEFldsBelongAssocMIMEHdr.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MIMEFldsBelongAssocMIMEHdr.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MIMEFldsBelongAssocMIMEHdr.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,63 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="DuplicateMIMEFlds">Prev</a> - Duplicate MIME Fields Are Not
+Coalesced
+Release Marshal Buffer Handles - <a href="RlsMarshalBufHandles">Next</a></p>
+<h3 id="mime_fields_always_belong_to_an_associated_mime_header">MIME Fields Always Belong to an Associated MIME Header</h3>
+<p>When using Traffic Server, you cannot create a new MIME field
+without an associated MIME header or HTTP header; MIME fields are
+always seen as part of a MIME header or HTTP header.</p>
+<p>To use a MIME field, you must specify the MIME header or HTTP
+header to which it belongs - this is called the field's
+<strong>parent header</strong>. The <code>INKMimeField*</code> functions in older versions
+of the SDK have been deprecated, as they do not require the parent
+header as inputs. The current version of Traffic Server uses new
+functions, the <code><b>INKMimeHdrField*</b></code> series, which require you
+to specify the location of the parent header along with the
+location of the MIME field. For every deprecated <code>INKMimeField*</code>
+function, there is a new, preferred <code>INKMimeHdrField*</code> function.
+Therefore, you should use the <code><b>INKMimeHdrField*</b></code> functions
+instead of the deprecated <code>INKMimeField*</code> series. Examples are
+provided below.</p>
+<p>Instead of:</p>
+<div class="codehilite"><pre><span class="n">INKMLoc</span> <span class="n">INKMimeFieldCreate</span> <span class="p">(</span><span class="n">INKMBuffer</span> <span class="n">bufp</span><span class="p">)</span>
+</pre></div>
+
+
+<p>You should use:</p>
+<div class="codehilite"><pre><span class="n">INKMLoc</span> <span class="n">INKMimeHdrFieldCreate</span> <span class="p">(</span><span class="n">INKMBuffer</span> <span class="n">bufp</span><span class="p">,</span> <span class="n">INKMLoc</span> <span class="n">hdr</span><span class="p">)</span>
+</pre></div>
+
+
+<p>Instead of:</p>
+<div class="codehilite"><pre><span class="n">void</span> <span class="n">INKMimeFieldCopyValues</span> <span class="p">(</span><span class="n">INKMBuffer</span> <span class="n">dest_bufp</span><span class="p">,</span> <span class="n">INKMLoc</span> <span class="n">dest_offset</span><span class="p">,</span>
+ <span class="n">INKMBuffer</span> <span class="n">src_bufp</span><span class="p">,</span> <span class="n">INKMLoc</span> <span class="n">src_offset</span><span class="p">)</span>
+</pre></div>
+
+
+<p>You should use:</p>
+<div class="codehilite"><pre><span class="n">void</span> <span class="n">INKMimeHdrFieldCopyValues</span> <span class="p">(</span><span class="n">INKMBuffer</span> <span class="n">dest_bufp</span><span class="p">,</span> <span class="n">INKMLoc</span> <span class="n">dest_hdr</span><span class="p">,</span>
+ <span class="n">INKMLoc</span> <span class="n">dest_field</span><span class="p">,</span> <span class="n">INKMBuffer</span> <span class="n">src_bufp</span><span class="p">,</span> <span class="n">INKMLoc</span> <span class="n">src_hdr</span><span class="p">,</span> <span class="n">INKMLoc</span>
+ <span class="n">src_field</span><span class="p">)</span>
+</pre></div>
+
+
+<p>In the <code>INKMimeHdrField*</code> function prototypes, the <code>INKMLoc</code> field
+corresponds to the <code>INKMLoc</code> offset used the deprecated
+<code>INKMimeField*</code> functions (see the discussion of parent <code>INKMLoc</code>
+in the following section).</p>
</div>
<div id="footer">