You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ml...@apache.org on 2010/05/25 23:58:39 UTC
svn commit: r948218 [2/2] - /trafficserver/site/trunk/docs/v2/sdk/
Modified: trafficserver/site/trunk/docs/v2/sdk/MIMEHeaders.html
URL: http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/sdk/MIMEHeaders.html?rev=948218&r1=948217&r2=948218&view=diff
==============================================================================
--- trafficserver/site/trunk/docs/v2/sdk/MIMEHeaders.html (original)
+++ trafficserver/site/trunk/docs/v2/sdk/MIMEHeaders.html Tue May 25 21:58:39 2010
@@ -1,505 +1,506 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>MIME Headers</title>
-<!--#include file="top.html" -->
-<div class="navheader">
-<div class="navprev">
-<a accesskey="p" href="URLs.html">Prev</a> - URLs</div>
-<div class="navnext">Chapter 11. Mutex Guide - <a accesskey="n" href="MutexGuide.html">Next</a>
-</div>
-</div>
-<div id="toc"></div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="MIMEHeaders"></a>MIME Headers</h2></div></div></div>
-<p>The Traffic Server <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> contains 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 (values in a field are separated
- 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 example is an augmented <b>Backus-Naur Form</b> (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 contain a name,
- separating colon, and zero or more values. A <b>name</b> 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). 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>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; 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 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 <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><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.
- Hence, the current version of Traffic Server does not coalesce 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 reduce storage size, Traffic
- Server defines several pre-allocated field names. These field names
- correspond to the field names in HTTP and NNTP headers.</p>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col />
-<col />
-<col />
-</colgroup>
-<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>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_ACCEPT</code></td>
-<td>"Accept"</td>
-<td><code>INK_MIME_LEN_ACCEPT</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_ACCEPT_CHARSET</code></td>
-<td>"Accept-Charset"</td>
-<td><code>INK_MIME_LEN_ACCEPT_CHARSET</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_ACCEPT_ENCODING</code></td>
-<td>"Accept-Encoding"</td>
-<td><code>INK_MIME_LEN_ACCEPT_ENCODING</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_ACCEPT_LANGUAGE</code></td>
-<td>"Accept-Language"</td>
-<td><code>INK_MIME_LEN_ACCEPT_LANGUAGE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_ACCEPT_RANGES</code></td>
-<td>"Accept-Ranges"</td>
-<td><code>INK_MIME_LEN_ACCEPT_RANGES</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_AGE</code></td>
-<td>"Age"</td>
-<td><code>INK_MIME_LEN_AGE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_ALLOW</code></td>
-<td>"Allow"</td>
-<td><code>INK_MIME_LEN_ALLOW</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_APPROVED</code></td>
-<td>"Approved"</td>
-<td><code>INK_MIME_LEN_APPROVED</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_AUTHORIZATION</code></td>
-<td>"Authorization"</td>
-<td><code>INK_MIME_LEN_AUTHORIZATION</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_BYTES</code></td>
-<td>"Bytes"</td>
-<td><code>INK_MIME_LEN_BYTES</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CACHE_CONTROL</code></td>
-<td>"Cache-Control"</td>
-<td><code>INK_MIME_LEN_CACHE_CONTROL</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CLIENT_IP</code></td>
-<td>"Client-ip"</td>
-<td><code>INK_MIME_LEN_CLIENT_IP</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONNECTION</code></td>
-<td>"Connection"</td>
-<td><code>INK_MIME_LEN_CONNECTION</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONTENT_BASE</code></td>
-<td>"Content-Base"</td>
-<td><code>INK_MIME_LEN_CONTENT_BASE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONTENT_ENCODING</code></td>
-<td>"Content-Encoding"</td>
-<td><code>INK_MIME_LEN_CONTENT_ENCODING</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONTENT_LANGUAGE</code></td>
-<td>"Content-Language"</td>
-<td><code>INK_MIME_LEN_CONTENT_LANGUAGE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONTENT_LENGTH</code></td>
-<td>"Content-Length"</td>
-<td><code>INK_MIME_LEN_CONTENT_LENGTH</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONTENT_LOCATION</code></td>
-<td>"Content-Location"</td>
-<td><code>INK_MIME_LEN_CONTENT_LOCATION</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONTENT_MD5</code></td>
-<td>"Content-MD5"</td>
-<td><code>INK_MIME_LEN_CONTENT_MD5</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONTENT_RANGE</code></td>
-<td>"Content-Range"</td>
-<td><code>INK_MIME_LEN_CONTENT_RANGE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONTENT_TYPE</code></td>
-<td>"Content-Type"</td>
-<td><code>INK_MIME_LEN_CONTENT_TYPE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_CONTROL</code></td>
-<td>"Control"</td>
-<td><code>INK_MIME_LEN_CONTROL</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_COOKIE</code></td>
-<td>"Cookie"</td>
-<td><code>INK_MIME_LEN_COOKIE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_DATE</code></td>
-<td>"Date"</td>
-<td><code>INK_MIME_LEN_DATE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_DISTRIBUTION</code></td>
-<td>"Distribution"</td>
-<td><code>INK_MIME_LEN_DISTRIBUTION</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_ETAG</code></td>
-<td>"Etag"</td>
-<td><code>INK_MIME_LEN_ETAG</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_EXPECT</code></td>
-<td>"Expect"</td>
-<td><code>INK_MIME_LEN_EXPECT</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_EXPIRES</code></td>
-<td>"Expires"</td>
-<td><code>INK_MIME_LEN_EXPIRES</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_FOLLOWUP_TO</code></td>
-<td>"Followup-To"</td>
-<td><code>INK_MIME_LEN_FOLLOWUP_TO</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_FROM</code></td>
-<td>"From"</td>
-<td><code>INK_MIME_LEN_FROM</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_HOST</code></td>
-<td>"Host"</td>
-<td><code>INK_MIME_LEN_HOST</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_IF_MATCH</code></td>
-<td>"If-Match"</td>
-<td><code>INK_MIME_LEN_IF_MATCH</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_IF_MODIFIED_SINCE</code></td>
-<td>"If-Modified-Since''</td>
-<td><code>INK_MIME_LEN_IF_MODIFIED_SINCE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_IF_NONE_MATCH</code></td>
-<td>"If-None-Match''</td>
-<td><code>INK_MIME_LEN_IF_NONE_MATCH</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_IF_RANGE</code></td>
-<td>"If-Range''</td>
-<td><code>INK_MIME_LEN_IF_RANGE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_IF_UNMODIFIED_SINCE</code></td>
-<td>"If-Unmodified-Since''</td>
-<td><code>INK_MIME_LEN_IF_UNMODIFIED_SINCE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_KEEP_ALIVE</code></td>
-<td>"Keep-Alive''</td>
-<td><code>INK_MIME_LEN_KEEP_ALIVE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_KEYWORDS</code></td>
-<td>"Keywords''</td>
-<td><code>INK_MIME_LEN_KEYWORDS</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_LAST_MODIFIED</code></td>
-<td>"Last-Modified''</td>
-<td><code>INK_MIME_LEN_LAST_MODIFIED</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_LINES</code></td>
-<td>"Lines''</td>
-<td><code>INK_MIME_LEN_LINES</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_LOCATION</code></td>
-<td>"Location''</td>
-<td><code>INK_MIME_LEN_LOCATION</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_MAX_FORWARDS</code></td>
-<td>"Max-Forwards''</td>
-<td><code>INK_MIME_LEN_MAX_FORWARDS</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_MESSAGE_ID</code></td>
-<td>"Message-ID''</td>
-<td><code>INK_MIME_LEN_MESSAGE_ID</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_NEWSGROUPS</code></td>
-<td>"Newsgroups''</td>
-<td><code>INK_MIME_LEN_NEWSGROUPS</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_ORGANIZATION</code></td>
-<td>"Organization''</td>
-<td><code>INK_MIME_LEN_ORGANIZATION</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_PATH</code></td>
-<td>"Path''</td>
-<td><code>INK_MIME_LEN_PATH</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_PRAGMA</code></td>
-<td>"Pragma''</td>
-<td><code>INK_MIME_LEN_PRAGMA</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_PROXY_AUTHENTICATE</code></td>
-<td>"Proxy-Authenticate''</td>
-<td><code>INK_MIME_LEN_PROXY_AUTHENTICATE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_PROXY_AUTHORIZATION</code></td>
-<td>"Proxy-Authorization''</td>
-<td><code>INK_MIME_LEN_PROXY_AUTHORIZATION</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_PROXY_CONNECTION</code></td>
-<td>"Proxy-Connection''</td>
-<td><code>INK_MIME_LEN_PROXY_CONNECTION</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_PUBLIC</code></td>
-<td>"Public''</td>
-<td><code>INK_MIME_LEN_PUBLIC</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_RANGE</code></td>
-<td>"Range''</td>
-<td><code>INK_MIME_LEN_RANGE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_REFERENCES</code></td>
-<td>"References''</td>
-<td><code>INK_MIME_LEN_REFERENCES</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_REFERER</code></td>
-<td>"Referer''</td>
-<td><code>INK_MIME_LEN_REFERER</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_REPLY_TO</code></td>
-<td>"Reply-To''</td>
-<td><code>INK_MIME_LEN_REPLY_TO</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_RETRY_AFTER</code></td>
-<td>"Retry-After''</td>
-<td><code>INK_MIME_LEN_RETRY_AFTER</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_SENDER</code></td>
-<td>"Sender''</td>
-<td><code>INK_MIME_LEN_SENDER</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_SERVER</code></td>
-<td>"Server''</td>
-<td><code>INK_MIME_LEN_SERVER</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_SET_COOKIE</code></td>
-<td>"Set-Cookie''</td>
-<td><code>INK_MIME_LEN_SET_COOKIE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_SUBJECT</code></td>
-<td>"Subject''</td>
-<td><code>INK_MIME_LEN_SUBJECTINK_MIME_LEN_SUBJECT</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_SUMMARY</code></td>
-<td>"Summary''</td>
-<td><code>INK_MIME_LEN_SUMMARY</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_TE</code></td>
-<td>"TE''</td>
-<td><code>INK_MIME_LEN_TE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_TRANSFER_ENCODING</code></td>
-<td>"Transfer-Encoding''</td>
-<td><code>INK_MIME_LEN_TRANSFER_ENCODING</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_UPGRADE</code></td>
-<td>"Upgrade''</td>
-<td><code>INK_MIME_LEN_UPGRADE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_USER_AGENT</code></td>
-<td>"User-Agent''</td>
-<td><code>INK_MIME_LEN_USER_AGENT</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_VARY</code></td>
-<td>"Vary''</td>
-<td><code>INK_MIME_LEN_VARY</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_VIA</code></td>
-<td>"Via''</td>
-<td><code>INK_MIME_LEN_VIA</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_WARNING</code></td>
-<td>"Warning''</td>
-<td><code>INK_MIME_LEN_WARNING</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_WWW_AUTHENTICATE</code></td>
-<td>"Www-Authenticate''</td>
-<td><code>INK_MIME_LEN_WWW_AUTHENTICATE</code></td>
-</tr>
-<tr>
-<td><code>INK_MIME_FIELD_XREF</code></td>
-<td>"Xref''</td>
-<td><code>INK_MIME_LEN_XREF</code></td>
-</tr>
-</tbody>
-</table></div>
-<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 quickly checks to see if the new value is one
- of the known values. If it is, then Traffic Server 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 enables simple
- pointer comparison of the value returned from
- <code class="function">INKMimeHdrFieldNameGet</code> with one of the values
- listed above. It is recommended that you use the above values when
- referring to one of the known header field names to avoid the
- possibility of a spelling error.</p>
-<p>Traffic Server adds one important feature to MIME fields that
- you may not know about: Traffic Server does not print a MIME field if the field name
- begins with the '<code class="code">@</code>' symbol. For example: a plugin can add
- 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 to Traffic Server logs by defining a
- 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><a name="MimeHeaderFxns"></a>The MIME header functions are listed below:</p>
-<div class="itemizedlist"><ul type="disc">
-<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldAppend"><code>INKMimeHdrFieldAppend</code></a></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldClone">INKMimeHdrFieldClone</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldCopy">INKMimeHdrFieldCopy</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldCopyValues">INKMimeHdrFieldCopyValues</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldCreate">INKMimeHdrFieldCreate</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldDestroy">INKMimeHdrFieldDestroy</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldLengthGet">INKMimeHdrFieldLengthGet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldNameGet">INKMimeHdrFieldNameGet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldNameSet">INKMimeHdrFieldNameSet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldNext">INKMimeHdrFieldNext</a></code></li>
-
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldNextDup">INKMimeHdrFieldNextDup</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueAppend">INKMimeHdrFieldValueAppend</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueAppend">INKMimeHdrFieldValueAppend</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueDateGet">INKMimeHdrFieldValueDateGet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueDateInsert">INKMimeHdrFieldValueDateInsert</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueDateSet">INKMimeHdrFieldValueDateSet</a></code></li>
-
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueInsert">INKMimeHdrFieldValueInsert</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueIntGet">INKMimeHdrFieldValueIntGet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueIntSet">INKMimeHdrFieldValueIntSet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueStringGet">INKMimeHdrFieldValueStringGet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueStringInsert">INKMimeHdrFieldValueStringInsert</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueStringSet">INKMimeHdrFieldValueStringSet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueUintGet">INKMimeHdrFieldValueUintGet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueUintInsert">INKMimeHdrFieldValueUintInsert</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueUintSet">INKMimeHdrFieldValueUintSet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValuesClear">INKMimeHdrFieldValuesClear</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValuesCount">INKMimeHdrFieldValuesCount</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrClone">INKMimeHdrClone</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrCopy">INKMimeHdrCopy</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrCreate">INKMimeHdrCreate</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrDestroy">INKMimeHdrDestroy</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldFind">INKMimeHdrFieldFind</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldGet">INKMimeHdrFieldGet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldRemove">INKMimeHdrFieldRemove</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldsClear">INKMimeHdrFieldsClear</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrFieldsCount">INKMimeHdrFieldsCount</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrLengthGet">INKMimeHdrLengthGet</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrParse">INKMimeHdrParse</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeParserClear">INKMimeParserClear</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeParserCreate">INKMimeParserCreate</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeParserDestroy">INKMimeParserDestroy</a></code></li>
-<li><code><a href="MimeHeadersFunctions.html#INKMimeHdrPrint">INKMimeHdrPrint</a></code></li>
-</ul></div>
-</div>
-</body>
-</html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>MIME Headers</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="URLs.html">Prev</a> - URLs</div>
+<div class="navnext">Chapter 11. Mutex Guide - <a accesskey="n" href="MutexGuide.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="MIMEHeaders"></a>MIME Headers</h2></div></div></div>
+<p>The Traffic Server <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> contains 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 (values in a field are separated
+ 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 example is an augmented <b>Backus-Naur Form</b> (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 contain a name,
+ separating colon, and zero or more values. A <b>name</b> 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). 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>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; 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 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 <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><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.
+ Hence, the current version of Traffic Server does not coalesce 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 reduce storage size, Traffic
+ Server defines several pre-allocated field names. These field names
+ correspond to the field names in HTTP and NNTP headers.</p>
+<div class="informaltable"><table border="1">
+<colgroup>
+<col />
+<col />
+<col />
+</colgroup>
+<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>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_ACCEPT</code></td>
+<td>"Accept"</td>
+<td><code>INK_MIME_LEN_ACCEPT</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_ACCEPT_CHARSET</code></td>
+<td>"Accept-Charset"</td>
+<td><code>INK_MIME_LEN_ACCEPT_CHARSET</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_ACCEPT_ENCODING</code></td>
+<td>"Accept-Encoding"</td>
+<td><code>INK_MIME_LEN_ACCEPT_ENCODING</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_ACCEPT_LANGUAGE</code></td>
+<td>"Accept-Language"</td>
+<td><code>INK_MIME_LEN_ACCEPT_LANGUAGE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_ACCEPT_RANGES</code></td>
+<td>"Accept-Ranges"</td>
+<td><code>INK_MIME_LEN_ACCEPT_RANGES</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_AGE</code></td>
+<td>"Age"</td>
+<td><code>INK_MIME_LEN_AGE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_ALLOW</code></td>
+<td>"Allow"</td>
+<td><code>INK_MIME_LEN_ALLOW</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_APPROVED</code></td>
+<td>"Approved"</td>
+<td><code>INK_MIME_LEN_APPROVED</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_AUTHORIZATION</code></td>
+<td>"Authorization"</td>
+<td><code>INK_MIME_LEN_AUTHORIZATION</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_BYTES</code></td>
+<td>"Bytes"</td>
+<td><code>INK_MIME_LEN_BYTES</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CACHE_CONTROL</code></td>
+<td>"Cache-Control"</td>
+<td><code>INK_MIME_LEN_CACHE_CONTROL</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CLIENT_IP</code></td>
+<td>"Client-ip"</td>
+<td><code>INK_MIME_LEN_CLIENT_IP</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONNECTION</code></td>
+<td>"Connection"</td>
+<td><code>INK_MIME_LEN_CONNECTION</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONTENT_BASE</code></td>
+<td>"Content-Base"</td>
+<td><code>INK_MIME_LEN_CONTENT_BASE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONTENT_ENCODING</code></td>
+<td>"Content-Encoding"</td>
+<td><code>INK_MIME_LEN_CONTENT_ENCODING</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONTENT_LANGUAGE</code></td>
+<td>"Content-Language"</td>
+<td><code>INK_MIME_LEN_CONTENT_LANGUAGE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONTENT_LENGTH</code></td>
+<td>"Content-Length"</td>
+<td><code>INK_MIME_LEN_CONTENT_LENGTH</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONTENT_LOCATION</code></td>
+<td>"Content-Location"</td>
+<td><code>INK_MIME_LEN_CONTENT_LOCATION</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONTENT_MD5</code></td>
+<td>"Content-MD5"</td>
+<td><code>INK_MIME_LEN_CONTENT_MD5</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONTENT_RANGE</code></td>
+<td>"Content-Range"</td>
+<td><code>INK_MIME_LEN_CONTENT_RANGE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONTENT_TYPE</code></td>
+<td>"Content-Type"</td>
+<td><code>INK_MIME_LEN_CONTENT_TYPE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_CONTROL</code></td>
+<td>"Control"</td>
+<td><code>INK_MIME_LEN_CONTROL</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_COOKIE</code></td>
+<td>"Cookie"</td>
+<td><code>INK_MIME_LEN_COOKIE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_DATE</code></td>
+<td>"Date"</td>
+<td><code>INK_MIME_LEN_DATE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_DISTRIBUTION</code></td>
+<td>"Distribution"</td>
+<td><code>INK_MIME_LEN_DISTRIBUTION</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_ETAG</code></td>
+<td>"Etag"</td>
+<td><code>INK_MIME_LEN_ETAG</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_EXPECT</code></td>
+<td>"Expect"</td>
+<td><code>INK_MIME_LEN_EXPECT</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_EXPIRES</code></td>
+<td>"Expires"</td>
+<td><code>INK_MIME_LEN_EXPIRES</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_FOLLOWUP_TO</code></td>
+<td>"Followup-To"</td>
+<td><code>INK_MIME_LEN_FOLLOWUP_TO</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_FROM</code></td>
+<td>"From"</td>
+<td><code>INK_MIME_LEN_FROM</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_HOST</code></td>
+<td>"Host"</td>
+<td><code>INK_MIME_LEN_HOST</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_IF_MATCH</code></td>
+<td>"If-Match"</td>
+<td><code>INK_MIME_LEN_IF_MATCH</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_IF_MODIFIED_SINCE</code></td>
+<td>"If-Modified-Since''</td>
+<td><code>INK_MIME_LEN_IF_MODIFIED_SINCE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_IF_NONE_MATCH</code></td>
+<td>"If-None-Match''</td>
+<td><code>INK_MIME_LEN_IF_NONE_MATCH</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_IF_RANGE</code></td>
+<td>"If-Range''</td>
+<td><code>INK_MIME_LEN_IF_RANGE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_IF_UNMODIFIED_SINCE</code></td>
+<td>"If-Unmodified-Since''</td>
+<td><code>INK_MIME_LEN_IF_UNMODIFIED_SINCE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_KEEP_ALIVE</code></td>
+<td>"Keep-Alive''</td>
+<td><code>INK_MIME_LEN_KEEP_ALIVE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_KEYWORDS</code></td>
+<td>"Keywords''</td>
+<td><code>INK_MIME_LEN_KEYWORDS</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_LAST_MODIFIED</code></td>
+<td>"Last-Modified''</td>
+<td><code>INK_MIME_LEN_LAST_MODIFIED</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_LINES</code></td>
+<td>"Lines''</td>
+<td><code>INK_MIME_LEN_LINES</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_LOCATION</code></td>
+<td>"Location''</td>
+<td><code>INK_MIME_LEN_LOCATION</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_MAX_FORWARDS</code></td>
+<td>"Max-Forwards''</td>
+<td><code>INK_MIME_LEN_MAX_FORWARDS</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_MESSAGE_ID</code></td>
+<td>"Message-ID''</td>
+<td><code>INK_MIME_LEN_MESSAGE_ID</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_NEWSGROUPS</code></td>
+<td>"Newsgroups''</td>
+<td><code>INK_MIME_LEN_NEWSGROUPS</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_ORGANIZATION</code></td>
+<td>"Organization''</td>
+<td><code>INK_MIME_LEN_ORGANIZATION</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_PATH</code></td>
+<td>"Path''</td>
+<td><code>INK_MIME_LEN_PATH</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_PRAGMA</code></td>
+<td>"Pragma''</td>
+<td><code>INK_MIME_LEN_PRAGMA</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_PROXY_AUTHENTICATE</code></td>
+<td>"Proxy-Authenticate''</td>
+<td><code>INK_MIME_LEN_PROXY_AUTHENTICATE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_PROXY_AUTHORIZATION</code></td>
+<td>"Proxy-Authorization''</td>
+<td><code>INK_MIME_LEN_PROXY_AUTHORIZATION</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_PROXY_CONNECTION</code></td>
+<td>"Proxy-Connection''</td>
+<td><code>INK_MIME_LEN_PROXY_CONNECTION</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_PUBLIC</code></td>
+<td>"Public''</td>
+<td><code>INK_MIME_LEN_PUBLIC</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_RANGE</code></td>
+<td>"Range''</td>
+<td><code>INK_MIME_LEN_RANGE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_REFERENCES</code></td>
+<td>"References''</td>
+<td><code>INK_MIME_LEN_REFERENCES</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_REFERER</code></td>
+<td>"Referer''</td>
+<td><code>INK_MIME_LEN_REFERER</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_REPLY_TO</code></td>
+<td>"Reply-To''</td>
+<td><code>INK_MIME_LEN_REPLY_TO</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_RETRY_AFTER</code></td>
+<td>"Retry-After''</td>
+<td><code>INK_MIME_LEN_RETRY_AFTER</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_SENDER</code></td>
+<td>"Sender''</td>
+<td><code>INK_MIME_LEN_SENDER</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_SERVER</code></td>
+<td>"Server''</td>
+<td><code>INK_MIME_LEN_SERVER</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_SET_COOKIE</code></td>
+<td>"Set-Cookie''</td>
+<td><code>INK_MIME_LEN_SET_COOKIE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_SUBJECT</code></td>
+<td>"Subject''</td>
+<td><code>INK_MIME_LEN_SUBJECTINK_MIME_LEN_SUBJECT</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_SUMMARY</code></td>
+<td>"Summary''</td>
+<td><code>INK_MIME_LEN_SUMMARY</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_TE</code></td>
+<td>"TE''</td>
+<td><code>INK_MIME_LEN_TE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_TRANSFER_ENCODING</code></td>
+<td>"Transfer-Encoding''</td>
+<td><code>INK_MIME_LEN_TRANSFER_ENCODING</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_UPGRADE</code></td>
+<td>"Upgrade''</td>
+<td><code>INK_MIME_LEN_UPGRADE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_USER_AGENT</code></td>
+<td>"User-Agent''</td>
+<td><code>INK_MIME_LEN_USER_AGENT</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_VARY</code></td>
+<td>"Vary''</td>
+<td><code>INK_MIME_LEN_VARY</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_VIA</code></td>
+<td>"Via''</td>
+<td><code>INK_MIME_LEN_VIA</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_WARNING</code></td>
+<td>"Warning''</td>
+<td><code>INK_MIME_LEN_WARNING</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_WWW_AUTHENTICATE</code></td>
+<td>"Www-Authenticate''</td>
+<td><code>INK_MIME_LEN_WWW_AUTHENTICATE</code></td>
+</tr>
+<tr>
+<td><code>INK_MIME_FIELD_XREF</code></td>
+<td>"Xref''</td>
+<td><code>INK_MIME_LEN_XREF</code></td>
+</tr>
+</tbody>
+</table></div>
+<p>The header field names above are defined in
+ <code class="filename">ts.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 quickly checks to see if the new value is one
+ of the known values. If it is, then Traffic Server 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 enables simple
+ pointer comparison of the value returned from
+ <code class="function">INKMimeHdrFieldNameGet</code> with one of the values
+ listed above. It is recommended that you use the above values when
+ referring to one of the known header field names to avoid the
+ possibility of a spelling error.</p>
+<p>Traffic Server adds one important feature to MIME fields that
+ you may not know about: Traffic Server does not print a MIME field if the field name
+ begins with the '<code class="code">@</code>' symbol. For example: a plugin can add
+ 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 to Traffic Server logs by defining a
+ 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><a name="MimeHeaderFxns"></a>The MIME header functions are listed below:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldAppend">INKMimeHdrFieldAppend</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldClone">INKMimeHdrFieldClone</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldCopy">INKMimeHdrFieldCopy</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldCopyValues">INKMimeHdrFieldCopyValues</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldCreate">INKMimeHdrFieldCreate</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldDestroy">INKMimeHdrFieldDestroy</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldLengthGet">INKMimeHdrFieldLengthGet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldNameGet">INKMimeHdrFieldNameGet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldNameSet">INKMimeHdrFieldNameSet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldNext">INKMimeHdrFieldNext</a></li>
+
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldNextDup">INKMimeHdrFieldNextDup</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueAppend">INKMimeHdrFieldValueAppend</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueAppend">INKMimeHdrFieldValueAppend</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueDateGet">INKMimeHdrFieldValueDateGet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueDateInsert">INKMimeHdrFieldValueDateInsert</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueDateSet">INKMimeHdrFieldValueDateSet</a></li>
+
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueInsert">INKMimeHdrFieldValueInsert</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueIntGet">INKMimeHdrFieldValueIntGet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueIntSet">INKMimeHdrFieldValueIntSet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueStringGet">INKMimeHdrFieldValueStringGet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueStringInsert">INKMimeHdrFieldValueStringInsert</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueStringSet">INKMimeHdrFieldValueStringSet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueUintGet">INKMimeHdrFieldValueUintGet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueUintInsert">INKMimeHdrFieldValueUintInsert</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValueUintSet">INKMimeHdrFieldValueUintSet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValuesClear">INKMimeHdrFieldValuesClear</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldValuesCount">INKMimeHdrFieldValuesCount</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrClone">INKMimeHdrClone</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrCopy">INKMimeHdrCopy</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrCreate">INKMimeHdrCreate</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrDestroy">INKMimeHdrDestroy</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldFind">INKMimeHdrFieldFind</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldGet">INKMimeHdrFieldGet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldRemove">INKMimeHdrFieldRemove</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldsClear">INKMimeHdrFieldsClear</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrFieldsCount">INKMimeHdrFieldsCount</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrLengthGet">INKMimeHdrLengthGet</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrParse">INKMimeHdrParse</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeParserClear">INKMimeParserClear</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeParserCreate">INKMimeParserCreate</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeParserDestroy">INKMimeParserDestroy</a></li>
+<li><a href="MimeHeadersFunctions.html#INKMimeHdrPrint">INKMimeHdrPrint</a></li>
+</ul></div>
+</div>
+</body>
+</html>
+
Modified: trafficserver/site/trunk/docs/v2/sdk/PlusingRegisAndVersionCkg.html
URL: http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/sdk/PlusingRegisAndVersionCkg.html?rev=948218&r1=948217&r2=948218&view=diff
==============================================================================
--- trafficserver/site/trunk/docs/v2/sdk/PlusingRegisAndVersionCkg.html (original)
+++ trafficserver/site/trunk/docs/v2/sdk/PlusingRegisAndVersionCkg.html Tue May 25 21:58:39 2010
@@ -1,94 +1,81 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>Plugin Registration and Version Checking</title>
-<!--#include file="top.html" -->
-<div class="navheader">
-<div class="navprev">
-<a accesskey="p" href="RestartingTS.html">Prev</a> - Restart Traffic Server</div>
-<div class="navnext">Naming Conventions - <a accesskey="n" href="NamingConventions.html">Next</a>
-</div>
-</div>
-<div id="toc"></div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="PlusingRegisAndVersionCkg"></a>Plugin Registration and Version Checking<a class="indexterm" name="id307848"></a></h2></div></div></div>
-<p>You need to make sure that the functions in your plugin are
- supported in your version of Traffic Server.</p>
-<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Important">
-<tr>
-<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="images/docbook/important.png" /></td>
-<th align="left">Important</th>
-</tr>
-<tr><td align="left" valign="top"><p>Throughout this manual, previous versions of Traffic
- Server may be referred to as: Traffic Server, Traffic Server 3.0, Traffic
- Server 3.5, and Traffic Server 5.2. For version checking purposes,
- Traffic Server 1.5 is equivalent to Traffic Server 5.5.</p></td></tr>
-</table></div>
-<p>Use the following interfaces:</p>
-<div class="itemizedlist"><ul type="disc">
-<li><p><a href="INKPluginRegister.html" title="INKPluginRegister">INKPluginRegister</a></p></li>
-<li><p><a href="INKTrafficServerVersionGet.html" title="INKTrafficServerVersionGet">INKTrafficServerVersionGet</a></p></li>
-</ul></div>
-<p>The following version of <code class="filename">hello-world</code>
- registers the plugin and ensures it's running with a compatible version
- of Traffic Server.<a class="indexterm" name="id324299"></a></p>
-<pre class="programlisting">#include <stdio.h>
-#include "InkAPI.h"
-int
-check_ts_version() {
- const char* ts_version = INKTrafficServerVersionGet();
- int result = 0;
-
- if (ts_version) {
- int major_ts_version = 0;
- int minor_ts_version = 0;
- int patch_ts_version = 0;
-
- if (sscanf(ts_version, "%d.%d.%d", &major_ts_version,
- &minor_ts_version, &patch_ts_version) != 3) {
- return 0;
- }
-
- /* Since this is an TS-SDK 2.0 plugin, we need at
- least Traffic Server 3.5.2 to run */
-
- if (major_ts_version > 3) {
- result = 1;
- } else if (major_ts_version == 3) {
- if (minor_ts_version > 5) {
- result = 1;
- } else if (minor_ts_version == 5) {
- if (patch_ts_version >= 2) {
- result = 1;
- }
- }
- }
- }
- return result;
-}
-
-void
-INKPluginInit (int argc, const char *argv[])<a class="indexterm" name="id324315"></a>
-{
-
- INKPluginRegistrationInfo info;
-
- info.plugin_name = "hello-world";
- info.vendor_name = "MyCompany";
- info.support_email = "ts-api-support@MyCompany.com";
-
- if (!INKPluginRegister (INK_SDK_VERSION_2_0 , &info)) {
- INKError ("Plugin registration failed. \n");
- }
-
- if (!check_ts_version()) {
- INKError ("Plugin requires Traffic Server 3.5.2 or later\n");
- return;
- }
-
- INKDebug ("debug-hello", "Hello World!\n");
-}</pre>
-</div>
-</body>
-</html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Plugin Registration and Version Checking</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="RestartingTS.html">Prev</a> - Restart Traffic Server</div>
+<div class="navnext">Naming Conventions - <a accesskey="n" href="NamingConventions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="PlusingRegisAndVersionCkg"></a>Plugin Registration and Version Checking<a class="indexterm" name="id307848"></a></h2></div></div></div>
+<p>Make sure that the functions in your plugin are
+ supported in your version of Traffic Server.</p>
+
+<p>Use the following interfaces:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="INKPluginRegister.html" title="INKPluginRegister">INKPluginRegister</a></li>
+<li><a href="INKTrafficServerVersionGet.html" title="INKTrafficServerVersionGet">INKTrafficServerVersionGet</a></li>
+</ul></div>
+<p>The following version of <code class="filename">hello-world</code>
+ registers the plugin and ensures it's running with a compatible version
+ of Traffic Server.<a class="indexterm" name="id324299"></a></p>
+<pre class="programlisting">#include <stdio.h>
+#include <ts/ts.h>
+int
+check_ts_version()
+{
+
+ const char *ts_version = INKTrafficServerVersionGet();
+ int result = 0;
+
+ if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;
+
+ if (sscanf(ts_version, "%d.%d.%d", &major_ts_version,
+ &minor_ts_version, &patch_ts_version) != 3) {
+ return 0;
+ }
+
+ /* We need at least Traffic Server 2.0 */
+
+ if (major_ts_version >= 2) {
+ result = 1;
+ }
+
+ }
+
+ return result;
+}
+
+void
+INKPluginInit (int argc, const char *argv[])<a class="indexterm" name="id324315"></a>
+{
+
+ INKPluginRegistrationInfo info;
+
+ info.plugin_name = "hello-world";
+ info.vendor_name = "MyCompany";
+ info.support_email = "ts-api-support@MyCompany.com";
+
+ if (!INKPluginRegister (INK_SDK_VERSION_2_0 , &info)) {
+ INKError ("Plugin registration failed. \n");
+ }
+
+ if (!check_ts_version()) {
+ INKError ("Plugin requires Traffic Server 2.0 or later\n");
+ return;
+ }
+
+ INKDebug ("debug-hello", "Hello World!\n");
+}</pre>
+</div>
+</body>
+</html>
+
Modified: trafficserver/site/trunk/docs/v2/sdk/SpecifyingPluginLocation.html
URL: http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/sdk/SpecifyingPluginLocation.html?rev=948218&r1=948217&r2=948218&view=diff
==============================================================================
--- trafficserver/site/trunk/docs/v2/sdk/SpecifyingPluginLocation.html (original)
+++ trafficserver/site/trunk/docs/v2/sdk/SpecifyingPluginLocation.html Tue May 25 21:58:39 2010
@@ -1,32 +1,33 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>Specify the Plugin's Location</title>
-<!--#include file="top.html" -->
-<div class="navheader">
-<div class="navprev">
-<a accesskey="p" href="Updatingplugin.configFile.html">Prev</a> - Update the <code class="filename">plugin.config</code> File</div>
-<div class="navnext">Restart Traffic Server - <a accesskey="n" href="RestartingTS.html">Next</a>
-</div>
-</div>
-<div id="toc"></div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="SpecifyingPluginLocation"></a>Specify the Plugin's Location</h3></div></div></div>
-<p>All plugins must be located in the directory specified by the
- configuration variable
- <code class="replaceable">proxy.config.plugin.plugin_dir</code>, which is located in
- the <code class="filename">records.config</code> file. The directory can be
- specified as an absolute or relative path.</p>
-<p>If a relative path is used, then the starting directory will be
- the Traffic Server installation directory as specified in
- <code class="filename">/etc/traffic_server</code>. The default value is
- <code class="code">config/plugins</code>, which tells Traffic Server to use the
- directory plugins located in the same configuration directory as
- <code class="filename">records.config</code>. It is common to use the default
- directory. Be sure to place the shared library
- <code class="filename">hello-world.so</code> inside the directory you have
- configured.</p>
-</div>
-</body>
-</html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Specify the Plugin's Location</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="Updatingplugin.configFile.html">Prev</a> - Update the <code class="filename">plugin.config</code> File</div>
+<div class="navnext">Restart Traffic Server - <a accesskey="n" href="RestartingTS.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="SpecifyingPluginLocation"></a>Specify the Plugin's Location</h3></div></div></div>
+<p>All plugins must be located in the directory specified by the
+ configuration variable
+ <code class="replaceable"> proxy.config.plugin.plugin_dir</code>, which is located in
+ the <code class="filename">records.config</code> file. The directory can be
+ specified as an absolute or relative path.</p>
+<p>If a relative path is used, then the starting directory will be
+ the Traffic Server installation directory as specified in
+ <code class="filename">/etc/traffic_server</code>. The default value is
+ <code class="code">config/plugins</code>, which tells Traffic Server to use the
+ directory plugins located in the same configuration directory as
+ <code class="filename">records.config</code>. It is common to use the default
+ directory. Be sure to place the shared library
+ <code class="filename">hello-world.so</code> inside the directory you've
+ configured.</p>
+</div>
+</body>
+</html>
+
Modified: trafficserver/site/trunk/docs/v2/sdk/URLs.html
URL: http://svn.apache.org/viewvc/trafficserver/site/trunk/docs/v2/sdk/URLs.html?rev=948218&r1=948217&r2=948218&view=diff
==============================================================================
--- trafficserver/site/trunk/docs/v2/sdk/URLs.html (original)
+++ trafficserver/site/trunk/docs/v2/sdk/URLs.html Tue May 25 21:58:39 2010
@@ -1,147 +1,151 @@
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<title>URLs</title>
-<!--#include file="top.html" -->
-<div class="navheader">
-<div class="navprev">
-<a accesskey="p" href="HTTPHeaders2.html">Prev</a> - HTTP Headers</div>
-<div class="navnext">MIME Headers - <a accesskey="n" href="MIMEHeaders.html">Next</a>
-</div>
-</div>
-<div id="toc"></div>
-<div class="section" lang="en">
-<div class="titlepage"><div><div><h2 class="title">
-<a name="URLs"></a>URLs</h2></div></div></div>
-<p>API URL functions provide access to URL data stored in marshal
- buffers. The URL functions can create, copy, retrieve or delete entire
- URLs; they can also etrieve or modify parts of URLs, such as port or scheme
- information.</p>
-<p>The general form of an Internet URL is:</p>
-<pre class="programlisting">scheme://user:password@host:port/stuff</pre>
-<p>The URL data structure includes support for two specific types of
- internet URLs. HTTP URLs have the form:</p>
-<pre class="programlisting">http://user:password@host:port/path;params?query#fragment</pre>
-<p>FTP URLs have the form:</p>
-<pre class="programlisting">ftp://user:password@host:port/path;type=val</pre>
-<p>The URL port and FTP type are stored as integers. All remaining
- parts of the URL (scheme, user, etc.) are stored as strings. Traffic Server URL functions are named according to the portion of the URL on
- which they operate. For instance, the function that retrieves the host
- portion of a URL is named <code class="function">INKUrlHostGet</code>.</p>
-<p>To facilitate fast comparisons and reduce storage size, Traffic
- Server defines several preallocated scheme names.</p>
-<div class="informaltable"><table border="1">
-<colgroup>
-<col />
-<col />
-<col />
-</colgroup>
-<tbody>
-<tr>
-<td align="center"><span class="bold"><strong>Traffic Server
- Definition</strong></span></td>
-<td align="center"><span class="bold"><strong>Pre-Allocated Scheme
- Name</strong></span></td>
-<td align="center"><span class="bold"><strong>URL Scheme String
- Lengths</strong></span></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_FILE</code></td>
-<td>"file"</td>
-<td><code>INK_URL_LEN_FILE</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_FTP</code></td>
-<td>"ftp"</td>
-<td><code>INK_URL_LEN_FTP</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_GOPHER</code></td>
-<td>"gopher"</td>
-<td><code>INK_URL_LEN_GOPHER</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_HTTP</code></td>
-<td>"http"</td>
-<td><code>INK_URL_LEN_HTTP</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_HTTPS</code></td>
-<td>"https"</td>
-<td><code>INK_URL_LEN_HTTPS</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_MAILTO</code></td>
-<td>"mailto"</td>
-<td><code>INK_URL_LEN_MAILTO</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_NEWS</code></td>
-<td>"news"</td>
-<td><code>INK_URL_LEN_NEWS</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_NNTP</code></td>
-<td>"nntp"</td>
-<td><code>INK_URL_LEN_NNTP</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_PROSPERO</code></td>
-<td>"prospero"</td>
-<td><code>INK_URL_LEN_PROSPERO</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_TELNET</code></td>
-<td>"telnet"</td>
-<td><code>INK_URL_LEN_TELNET</code></td>
-</tr>
-<tr>
-<td><code>INK_URL_SCHEME_WAIS</code></td>
-<td>"wais"</td>
-<td><code>INK_URL_LEN_WAIS</code></td>
-</tr>
-</tbody>
-</table></div>
-<p>The scheme names above are defined in <code>InkAPI.h</code> as <code>const</code> <code>char*</code> strings. When Traffic Server sets the scheme portion of the URL (or any
- portion 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
- scheme values listed above are also pointers into this table. This
- allows simple pointer comparison of the value returned from
- <code>INKUrlSchemeGet</code> with one of the values listed above. You should
- use the Traffic Server-defined values when referring to one of
- the known schemes, since it prevents possible spelling errors.</p>
-<p>The URL functions are listed below:</p>
-<div class="itemizedlist"><ul type="disc">
-<li><p><code class="function">INKUrlClone</code></p></li>
-<li><p><code class="function">INKUrlCopy</code></p></li>
-<li><p><code class="function">INKUrlCreate</code></p></li>
-<li><p><code class="function">INKUrlDestroy</code></p></li>
-<li><p><code class="function">INKUrlPrint</code></p></li>
-<li><p><code class="function">INKUrlFtpTypeGet</code></p></li>
-<li><p><code class="function">INKUrlFtpTypeSet</code></p></li>
-<li><p><code class="function">INKUrlHostGet</code></p></li>
-<li><p><code class="function">INKUrlHostSet</code></p></li>
-<li><p><code class="function">INKUrlHttpFragmentGet</code></p></li>
-<li><p><code class="function">INKUrlHttpFragmentSet</code></p></li>
-<li><p><code class="function">INKUrlHttpParamsGet</code></p></li>
-<li><p><code class="function">INKUrlHttpParamsSet</code></p></li>
-<li><p><code class="function">INKUrlHttpQueryGet</code></p></li>
-<li><p><code class="function">INKUrlHttpQuerySet</code></p></li>
-<li><p><code class="function">INKUrlLengthGet</code></p></li>
-<li><p><code class="function">INKUrlParse</code></p></li>
-<li><p><code class="function">INKUrlPasswordGet</code></p></li>
-<li><p><code class="function">INKUrlPasswordSet</code></p></li>
-<li><p><code class="function">INKUrlPathGet</code></p></li>
-<li><p><code class="function">INKU<code class="function">r</code>lPathSet</code></p></li>
-<li><p><code class="function">INKUrlPortGet</code></p></li>
-<li><p><code class="function">INKUrlPortSet</code></p></li>
-<li><p><code class="function">INKUrlSchemeGet</code></p></li>
-<li><p><code class="function">INKUrlSchemeSet</code></p></li>
-<li><p><code class="function">INKUrlStringGet</code></p></li>
-<li><p><code class="function">INKUrlUserGet</code></p></li>
-<li><p><code class="function">INKUrlUserSet</code></p></li>
-</ul></div>
-</div>
-</body>
-</html>
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>URLs</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="HTTPHeaders2.html">Prev</a> - HTTP Headers</div>
+<div class="navnext">MIME Headers - <a accesskey="n" href="MIMEHeaders.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="URLs"></a>URLs</h2></div></div></div>
+<p>API URL functions provide access to URL data stored in marshal
+ buffers. The URL functions can create, copy, retrieve or delete entire
+ URLs; they can also retrieve or modify parts of URLs, such as port or scheme
+ information.</p>
+<p>The general form of an Internet URL is:</p>
+<pre class="programlisting">scheme://user:password@host:port/stuff</pre>
+<p>The URL data structure includes support for two specific types of
+ internet URLs. HTTP URLs have the form:</p>
+<pre class="programlisting">http://user:password@host:port/path;params?query#fragment</pre>
+<p>FTP URLs have the form:</p>
+<pre class="programlisting">ftp://user:password@host:port/path;type=val</pre>
+<p>The URL port and FTP type are stored as integers. All remaining
+ parts of the URL (scheme, user, etc.) are stored as strings. Traffic Server URL functions are named according to the portion of the URL on
+ which they operate. For instance, the function that retrieves the host
+ portion of a URL is named <code class="function">INKUrlHostGet</code>.</p>
+<p>To facilitate fast comparisons and reduce storage size, Traffic
+ Server defines several preallocated scheme names.</p>
+<div class="informaltable"><table border="1">
+<colgroup>
+<col />
+<col />
+<col />
+</colgroup>
+<tbody>
+<tr>
+<td align="center"><span class="bold"><strong>Traffic Server
+ Definition</strong></span></td>
+<td align="center"><span class="bold"><strong>Pre-Allocated Scheme
+ Name</strong></span></td>
+<td align="center"><span class="bold"><strong>URL Scheme String
+ Lengths</strong></span></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_FILE</code></td>
+<td>"file"</td>
+<td><code>INK_URL_LEN_FILE</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_FTP</code></td>
+<td>"ftp"</td>
+<td><code>INK_URL_LEN_FTP</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_GOPHER</code></td>
+<td>"gopher"</td>
+<td><code>INK_URL_LEN_GOPHER</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_HTTP</code></td>
+<td>"http"</td>
+<td><code>INK_URL_LEN_HTTP</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_HTTPS</code></td>
+<td>"https"</td>
+<td><code>INK_URL_LEN_HTTPS</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_MAILTO</code></td>
+<td>"mailto"</td>
+<td><code>INK_URL_LEN_MAILTO</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_NEWS</code></td>
+<td>"news"</td>
+<td><code>INK_URL_LEN_NEWS</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_NNTP</code></td>
+<td>"nntp"</td>
+<td><code>INK_URL_LEN_NNTP</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_PROSPERO</code></td>
+<td>"prospero"</td>
+<td><code>INK_URL_LEN_PROSPERO</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_TELNET</code></td>
+<td>"telnet"</td>
+<td><code>INK_URL_LEN_TELNET</code></td>
+</tr>
+<tr>
+<td><code>INK_URL_SCHEME_WAIS</code></td>
+<td>"wais"</td>
+<td><code>INK_URL_LEN_WAIS</code></td>
+</tr>
+</tbody>
+</table></div>
+<p>The scheme names above are defined in <code>ts.h</code> as <code>const</code> <code>char*</code> strings. When Traffic Server sets the scheme portion of the URL (or any
+ portion 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
+ scheme values listed above are also pointers into this table. This
+ allows simple pointer comparison of the value returned from
+ <code>INKUrlSchemeGet</code> with one of the values listed above. You should
+ use the Traffic Server-defined values when referring to one of
+ the known schemes, since doing so can prevent the possibility of spelling errors.</p>
+<p>Traffic Server <b>URL functions</b> are listed below:</p>
+<div class="itemizedlist"><ul type="disc">
+<b>
+<li><a href="URLFunctions.html#INKUrlClone">INKUrlClone</a></li>
+<li><a href="URLFunctions.html#INKUrlCopy">INKUrlCopy</a></li>
+<li><a href="URLFunctions.html#INKUrlCreate">INKUrlCreate</a></li>
+<li><a href="URLFunctions.html#INKUrlDestroy">INKUrlDestroy</a></li>
+<li><a href="URLFunctions.html#INKUrlPrint">INKUrlPrint</a></li>
+<li><a href="URLFunctions.html#INKUrlFtpTypeGet">INKUrlFtpTypeGet</a></li>
+<li><a href="URLFunctions.html#INKUrlFtpTypeSet">INKUrlFtpTypeSet</a></li>
+<li><a href="URLFunctions.html#INKUrlHostGet">INKUrlHostGet</a></li>
+<li><a href="URLFunctions.html#INKUrlHostSet">INKUrlHostSet</a></li>
+<li><a href="URLFunctions.html#INKUrlHttpFragmentGet">INKUrlHttpFragmentGet</a></li>
+<li><a href="URLFunctions.html#INKUrlHttpFragmentSet">INKUrlHttpFragmentSet</a></li>
+<li><a href="URLFunctions.html#INKUrlHttpParamsGet">INKUrlHttpParamsGet</a></li>
+<li><a href="URLFunctions.html#INKUrlHttpParamsSet">INKUrlHttpParamsSet</a></li>
+<li><a href="URLFunctions.html#INKUrlHttpQueryGet">INKUrlHttpQueryGet</a></li>
+<li><a href="URLFunctions.html#INKUrlHttpQuerySet">INKUrlHttpQuerySet</a></li>
+<li><a href="URLFunctions.html#INKUrlLengthGet">INKUrlLengthGet</a></li>
+<li><a href="URLFunctions.html#INKUrlParse">INKUrlParse</a></li>
+<li><a href="URLFunctions.html#INKUrlPasswordGet">INKUrlPasswordGet</a></li>
+<li><a href="URLFunctions.html#INKUrlPasswordSet">INKUrlPasswordSet</a></li>
+<li><a href="URLFunctions.html#INKUrlPathGet">INKUrlPathGet</a></li>
+<li><a href="URLFunctions.html#INKUrlPathSet">INKUrlPathSet</a></li>
+<li><a href="URLFunctions.html#INKUrlPortGet">INKUrlPortGet</a></li>
+<li><a href="URLFunctions.html#INKUrlPortSet">INKUrlPortSet</a></li>
+<li><a href="URLFunctions.html#INKUrlSchemeGet">INKUrlSchemeGet</a></li>
+<li><a href="URLFunctions.html#INKUrlSchemeSet">INKUrlSchemeSet</a></li>
+<li><a href="URLFunctions.html#INKUrlStringGet">INKUrlStringGet</a></li>
+<li><a href="URLFunctions.html#INKUrlUserGet">INKUrlUserGet</a></li>
+<li><a href="URLFunctions.html#INKUrlUserSet">INKUrlUserSet</a></li>
+
+</b>
+</ul></div>
+</div>
+</body>
+</html>
+