You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by di...@apache.org on 2010/02/26 19:48:35 UTC
svn commit: r916785 - in /incubator/trafficserver/site/trunk/docs/sdk:
MIMEHeaders.html MarshalBuffers.html MarshallBuffersFunctions.html
MiscellaneousInterfaceGuide.html
Author: dianes
Date: Fri Feb 26 18:48:35 2010
New Revision: 916785
URL: http://svn.apache.org/viewvc?rev=916785&view=rev
Log:
edits previously overlooked
Modified:
incubator/trafficserver/site/trunk/docs/sdk/MIMEHeaders.html
incubator/trafficserver/site/trunk/docs/sdk/MarshalBuffers.html
incubator/trafficserver/site/trunk/docs/sdk/MarshallBuffersFunctions.html
incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html
Modified: incubator/trafficserver/site/trunk/docs/sdk/MIMEHeaders.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/MIMEHeaders.html?rev=916785&r1=916784&r2=916785&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/MIMEHeaders.html (original)
+++ incubator/trafficserver/site/trunk/docs/sdk/MIMEHeaders.html Fri Feb 26 18:48:35 2010
@@ -57,58 +57,56 @@
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="MIMEHeaders"></a>MIME Headers</h2></div></div></div>
-<p>The Traffic Server API MIME header functions enable you to
+<p>The Traffic Server API <b class="index">MIME header functions </b> enable you to
retrieve and modify information about HTTP MIME fields.</p>
<p>An HTTP request or response consists of a header, body, and
trailer. The <b>HTTP</b> <b>header</b><a class="indexterm" name="id383429"></a> consists of a request (or response) line and a MIME header<a class="indexterm" name="id383437"></a>. A <b>MIME</b> <b>header</b> is composed of zero or more <a class="indexterm" name="id383447"></a>MIME fields. A <b>MIME</b> <b>field</b> is composed of a field name, a
colon, and zero or more field values (the values in a field are separated
- by commas). In the example below: <code>Foo</code> is the <a class="indexterm" name="id383456"></a>MIME field name, <code>bar</code> is the first <a class="indexterm" name="id383465"></a>MIME field value, and <code>car</code> is the second MIME field
- value.</p>
+ by commas). </p>
+<p>In the example below: <code>Foo</code> is the <a class="indexterm" name="id383456"></a>MIME field name, <code>bar</code> is the first <a class="indexterm" name="id383465"></a>MIME field value, and <code>car</code> is the second MIME field
+ value.</p>
<pre class="programlisting">Foo: bar, car</pre>
-<p>The following is an augmented Backus-Naur Form (BNF) for the form
+<p>The following example is an augmented Backus-Naur Form (BNF) for the form
of a <a class="indexterm" name="id383483"></a>MIME header - it specifies exactly what was described
above. A <b>header</b> consists of zero or more <b>fields</b> that consist of a name,
a separating colon, and zero or more values. A name or <b>value</b> is simply a
string of tokens that is potentially zero length; a <b>token</b> is any
character except certain control characters and separators (such as
- colons).</p>
+ colons). For the purpose of retrieving a field, field names are not case-sensitive; therefore, the field names <code class="code">Foo</code>, <code class="code">foo</code> and <code class="code">fOO</code> are all equivalent.</p>
<pre class="programlisting">MIME-header = *MIME-field
MIME-field = field-name ":" #field-value
field-name = *token
-field-value = *token</pre>
-<p>For the purposes of retrieving a field, field names are not case-sensitive; ergo, the field names <code class="code">Foo</code>, <code class="code">foo</code> and
- <code class="code">fOO</code> are all equivalent.</p>
+field-value = *token
+</pre>
<p>The MIME header data structure is a parsed version of a standard
Internet MIME header. The MIME header data structure is similar to the
URL data structure (see <a href="URLs.html" title="URLs">URLs</a>). The actual data is
- stored in a marshal buffer and the MIME header functions operate on a
+ stored in a marshal buffer; the MIME header functions operate on a
marshal buffer and a location (<code>INKMLoc</code>) within the buffer.</p>
<p>After a call to <code class="function">INKMimeHdrFieldDestroy</code>,
<code class="function">INKMimeHdrFieldRemove</code>, or
<code class="function">INKUrlDestroy</code> is made, you must deallocate the
<code class="function">INKMLoc</code> handle with a call to
<code class="function">INKHandleMLocRelease</code>. You do not need to deallocate
- a <code class="code">NULL</code> handles. For example: if you called
+ a <code class="code">NULL</code> handles. For example: if you call
<code class="function">INKMimeHdrFieldValueStringGet</code> to get the value of
the content type field and the field does not exist, then it returns
<code class="code">INK_NULL_MLOC</code>. In such a case, you wouldn't need to
deallocate the handle with a call to
<code class="function">INKHandleMLocRelease</code>.</p>
-<p>The location (<code class="function">INKMLoc</code>) in the following MIME
- header functions can be either a HTTP header location or a MIME header
- location. If an HTTP header location is passed to these function, then the
- system locates the MIME header associated with this HTTP header and
- then executes the corresponding MIME header operations specified by the
+<p>The location (<code class="function">INKMLoc</code>) in the <a href="MIMEHeaders.html#MimeHeaderFxns"> MIME header functions</a> can be either an HTTP header location or a MIME header
+ location. If an HTTP header location is passed to these functions, then the
+ system locates the MIME header associated with that HTTP header and
+ executes the corresponding MIME header operations specified by the
functions (see the example in the description of <a href="MimeHeadersFunctions.html#INKMimeHdrCopy" title="INKMimeHdrCopy"><code class="code">INKMimeHdrCopy</code></a>).</p>
-<p>MIME headers may contain more than one MIME field with the same
- name. While previous versions of Traffic Server joined multiple fields with the same name into one field
- with composite values, this behavior comes at a performance cost and
- causes compatability issues with older clients and servers.
- Future versions of Traffic Server will cease coalescing duplicate
+<p><b>Note: </b>MIME headers may contain more than one MIME field with the same
+ name. Previous versions of Traffic Server joined multiple fields with the same name into one field
+ with composite values, but this behavior came at a performance cost and
+ caused compatability issues with older clients and servers.
+ Future versions of Traffic Server have ceased coalescing duplicate
fields. Correctly-behaving plugins should check for the presence of
- duplicate fields, and iterate over the duplicate fields, by using
- <code class="function">INKMimeHdrFieldNextDup</code>.</p>
-<p>To facilitate fast comparisons and to reduce storage size, Traffic
+ duplicate fields and iterate over the duplicate fields by using <code class="function">INKMimeHdrFieldNextDup</code>.</p>
+<p>To facilitate fast comparisons and reduce storage size, Traffic
Server defines several pre-allocated field names. These field names
correspond to field names found in HTTP and NNTP headers.</p>
<div class="informaltable"><table border="1">
@@ -120,11 +118,11 @@
<tbody>
<tr>
<td align="center"><span class="bold"><strong>Traffic Server
- pre-allocated field names </strong></span></td>
-<td align="center"><span class="bold"><strong>HTTP and NNTP header
- field names</strong></span></td>
-<td align="center"><span class="bold"><strong>Associated string
- lengths</strong></span></td>
+ Pre-allocated Field Names </strong></span></td>
+<td align="center"><span class="bold"><strong>HTTP and NNTP Header
+ Field Names</strong></span></td>
+<td align="center"><span class="bold"><strong>Associated String
+ Lengths</strong></span></td>
</tr>
<tr>
<td><code>INK_MIME_FIELD_ACCEPT</code></td>
@@ -481,10 +479,10 @@
<p>The header field names above are defined in
<code class="filename">InkAPI.h</code> as <code class="code">const char*</code> strings. When
Traffic Server sets the name portion of a header field (or any portion
- for that matter), it makes a quick check to see if the new value is one
+ for that matter), it quickly checks to see if the new value is one
of the known values. If it is, then it stores a pointer into a global table instead of storing the known value in the
marshal buffer. The header field
- names listed above are also pointers into this table, which allows simple
+ names listed above are also pointers into this table, which enables simple
pointer comparison of the value returned from
<code class="function">INKMimeHdrFieldNameGet</code> with one of the values
listed above. It is also recommended that you use the above values when
@@ -496,10 +494,10 @@
the field "<code class="code">@My-Field</code>" to a header. Even though Traffic
Server never sends that field out in a request to an origin server or in
a response to a client, it can be printed in Traffic Server logs by defining a
- custom log config file that explicitly logs such fields. This provides
+ custom log configuration file that explicitly logs such fields. This provides
a useful mechanism for plugins to store information about an object in
one of the MIME headers associated with the object.</p>
-<p>The MIME header functions are listed below:</p>
+<p><a name="MimeHeaderFxns"></a>The MIME header functions are listed below:</p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="function">INKMimeHdrFieldClone</code></p></li>
<li><p><code class="function">INKMimeHdrFieldCopy</code></p></li>
Modified: incubator/trafficserver/site/trunk/docs/sdk/MarshalBuffers.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/MarshalBuffers.html?rev=916785&r1=916784&r2=916785&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/MarshalBuffers.html (original)
+++ incubator/trafficserver/site/trunk/docs/sdk/MarshalBuffers.html Fri Feb 26 18:48:35 2010
@@ -57,7 +57,7 @@
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="MarshalBuffers"></a>Marshal Buffers</h2></div></div></div>
-<p>The marshal buffer, or <code class="function">INKMBuffer</code>, is a heap
+<p>A <b>marshal buffer</b>, or <code class="function">INKMBuffer</code>, is a heap
data structure that stores parsed URLs, MIME headers, and HTTP headers.
You can allocate new objects out of marshal buffers and change the
values within the marshal buffer. Whenever you manipulate an object, you
@@ -65,7 +65,7 @@
marshal buffer containing the object
(<code class="function">INKMBuffer</code>).</p>
<p>Routines exist for manipulating the object based on these two
- pieces of information. See, for example, one of the following:</p>
+ pieces of information. For example, see one of the following:</p>
<div class="itemizedlist"><ul type="disc">
<li><p><a href="HTTPHeaders2.html" title="HTTP Headers">HTTP Headers</a></p></li>
<li><p><a href="URLs.html" title="URLs">URLs</a></p></li>
Modified: incubator/trafficserver/site/trunk/docs/sdk/MarshallBuffersFunctions.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/MarshallBuffersFunctions.html?rev=916785&r1=916784&r2=916785&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/MarshallBuffersFunctions.html (original)
+++ incubator/trafficserver/site/trunk/docs/sdk/MarshallBuffersFunctions.html Fri Feb 26 18:48:35 2010
@@ -62,15 +62,15 @@
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="MarshallBuffersFunctions"></a>Marshal Buffers</h2></div></div></div>
-<p>The marshal buffer, or <code class="function">INKMBuffer</code>, is a heap
+<p>A <b>marshal buffer</b>, or <code class="function">INKMBuffer</code>, is a heap
data structure that stores parsed URLs, MIME headers, and HTTP headers.
- You can allocate new objects out of marshal buffers as well as change the
+ You can allocate new objects out of marshal buffers, as well as change the
values within a marshal buffer. Whenever you manipulate an object, you
require the handle to the object (<code class="function">INKMLoc</code>) and the
marshal buffer containing the object
(<code class="function">INKMBuffer</code>).</p>
<p>Routines exist for manipulating the object based on these two
- pieces of information. For example, see the following:</p>
+ pieces of information. See, for example, the following:</p>
<div class="itemizedlist"><ul type="disc">
<li>
<p><a href="HTTPHeaderFunctions.html" title="HTTP Header Functions">HTTP Header Functions</a></p></li>
@@ -88,7 +88,7 @@
</tr>
<tr><td align="left" valign="top"><p>Any marshal buffer fetched by <code>INKHttpTxn*Get</code> (for example, <code class="function">INKHttpTxnClientReqGet</code> or
<code class="function">INKHttpTxnServerRespGet</code>) will be used by other
- parts of the system. Be careful not to destroy these shared,
+ parts of the system. Be careful not to destroy these shared
transaction marshal buffers.</p></td></tr>
</table></div>
<div class="section" lang="en">
Modified: incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html?rev=916785&r1=916784&r2=916785&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html (original)
+++ incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html Fri Feb 26 18:48:35 2010
@@ -73,7 +73,7 @@
<p>Most of the functions in the Traffic Server API provide an interface
to specific code modules within Traffic Server. The miscellaneous
functions described in this chapter provide some useful general
- capabilities. They are as follows:</p>
+ capabilities. They are categorized as follows:</p>
<div class="itemizedlist"><ul type="disc">
<li><p><a href="DebuggingFunctions.html" title="Debugging Functions">Debugging Functions</a></p></li>
<li>
@@ -81,10 +81,10 @@
<li><p><a href="MemoryAllocation.html" title="Memory Allocation">Memory Allocation</a></p></li>
<li><p><a href="ThreadFunctions.html" title="Thread Functions">Thread Functions</a></p></li>
</ul></div>
-<p>While the C library already provides functions such as
+<p>The C library already provides functions such as
<code class="function">printf</code>, <code class="function">malloc</code>, and
- <code class="function">fopen</code> to perform these tasks, the Traffic Server
- API versions overcome various C library limitations (such as portability
+ <code class="function">fopen</code> to perform these tasks. The Traffic Server
+ API versions, however, overcome various C library limitations (such as portability
to all Traffic Server-supported platforms).</p>
<div class="section" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -95,7 +95,7 @@
if you are running Traffic Server in debug mode.</p></li>
<li>
<p><a href="INKIsDebugTagSet.html" title="INKIsDebugTagSet">INKIsDebugTagSet</a> checks to see if a debug tag
- is set. If the debug tag is set, then Traffic Server prints out any debug
+ is set. If the debug tag is set, then Traffic Server prints out all debug
statements associated with the tag.</p></li>
<li>
<p><a href="INKError.html" title="INKError">INKError</a> prints error messages to Traffic