You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bu...@apache.org on 2013/12/24 19:32:22 UTC
svn commit: r891679 [19/24] - in /websites/staging/trafficserver/trunk:
cgi-bin/ content/ content/docs/ content/docs/trunk/
content/docs/trunk/admin/ content/docs/trunk/admin/cluster-howto/
content/docs/trunk/admin/configuration-files/ content/docs/tru...
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/MimeHeadersFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/MimeHeadersFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/MimeHeadersFunctions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,1639 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>MIIME Headers</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="URLFunctions.html">Prev</a> - URL Functions</div>
+<div class="navnext">Mutex Functions - <a accesskey="n" href="MutexFunctions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="MimeHeadersFunctions"></a>MIIME Headers</h3></div></div></div>
+<p>MIME headers and fields can be components of request headers,
+ response headers, or standalone headers created within your plugin.
+ Make sure you call the MIME header functions appropriately. For
+ example: if you want to clone a MIME header field within a request
+ header, then call <code class="function">INKMimeHdrFieldClone</code> after
+ <code class="code">READ_REQUEST_HDR_HOOK</code>.</p>
+<p>The Traffic Server MIME header functions are listed below:</p>
+<ul><b>
+<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>
+</b></ul>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldAppend"></a>INKMimeHdrFieldAppend</h4></div></div></div>
+<p>Appends a field in a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldAppend (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>)</code></p></dd>
+<dt><b><span class="term">Description</span></b></dt>
+<dd>
+ <p>Appends the MIME field located at field within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code>
+ into the MIME header located at
+ <code class="code"><em class="replaceable"><code>url_loc </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldClone"></a>INKMimeHdrFieldClone</h4></div></div></div>
+<p>Copies a MIME field to a marshal buffer and returns the
+ <code class="function">INKMLoc</code> location of the copied field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKMimeHdrFieldClone (INKMBuffer
+ <em class="replaceable"><code>dest_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>dest_hdr</code></em>, INKMBuffer
+ <em class="replaceable"><code>src_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>src_hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>src_field</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Copies the contents of the MIME field located at
+ <code class="code"><em class="replaceable"><code>src_field </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> to a MIME
+ header located at
+ <code class="code"><em class="replaceable"><code>dest_hdr </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>dest_bufp</code></em></code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The <code class="function">INKMLoc</code> location of the copied
+ field. Release the returned handle with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldCopy"></a>INKMimeHdrFieldCopy</h4></div></div></div>
+<p>Copies a MIME field from one specified location to another
+ specified location.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldCopy (INKMBuffer
+ <em class="replaceable"><code>dest_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>dest_hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>dest_field</code></em>, INKMBuffer
+ <em class="replaceable"><code>src_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>src_hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>src_field</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Copies the contents of the MIME field located at
+ <code class="code"><em class="replaceable"><code>src_field </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> to the MIME
+ field located at
+ <code class="code"><em class="replaceable"><code>dest_field </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>dest_bufp</code></em></code>. </p>
+</dd>
+<dd>
+ <p><code class="function">INKMimeHdrFieldCopy</code> works correctly even
+ if <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> and
+ <code class="code"><em class="replaceable"><code>dest_bufp </code></em></code> point to
+ different marshal buffers.</p>
+ <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+ <tr>
+ <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+ <th align="left">Note</th>
+ </tr>
+ <tr><td align="left" valign="top"><p>You must first create the destination MIME field
+ before you can copy into it.</p></td></tr>
+ </table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldCopyValues"></a>INKMimeHdrFieldCopyValues</h4></div></div></div>
+<p>Copies MIME field values from one location to another.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldCopyValues
+ (INKMBuffer <em class="replaceable"><code>dest_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>dest_hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>dest_field</code></em>, INKMBuffer
+ <em class="replaceable"><code>src_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>src_hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>src_field</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Copies the values contained within the MIME field
+ located at <code class="code"><em class="replaceable"><code>src_field </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> to the MIME
+ field located at
+ <code class="code"><em class="replaceable"><code>dest_field </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>dest_bufp</code></em></code>. </p></dd>
+<dd>
+ <p><code class="function">INKMimeHdrFieldCopyValues</code> works correctly
+ even if <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> and
+ <code class="code"><em class="replaceable"><code>dest_bufp </code></em></code> point to
+ different marshal buffers. </p>
+</dd>
+<dd>
+ <p><code class="function">INKMimeHdrFieldCopyValues</code> does not copy
+ the field's name.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldCreate"></a>INKMimeHdrFieldCreate</h4></div></div></div>
+<p>Creates a new MIME field within a specified marshal
+ buffer.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKMimeHdrFieldCreate (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd><p>Creates a new MIME field with the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd><p>The location of the new MIME field. Release with a call
+ to <code class="function">INKHandleMLocRelease</code>.</p></dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldDestroy"></a>INKMimeHdrFieldDestroy</h4></div></div></div>
+<p>Deletes a specified MIME field from a marshal buffer.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">void INKMimeHdrFieldDestroy (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Destroys the MIME field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the MIME
+ header located at <code class="code"><em class="replaceable"><code>hdr </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>.</p>
+<p>After the call to
+ <code class="function">INKMimeHdrFieldDestroy</code>, you must release
+ the <code class="function">INKMLoc</code> handle
+ <code class="code"><em class="replaceable"><code>field </code></em></code> with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldLengthGet"></a>INKMimeHdrFieldLengthGet</h4></div></div></div>
+<p>Calculates the length of a string representation in a
+ specified MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKMimeHdrFieldLengthGet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Calculates the length of the MIME field located at
+ <code class="code"><code class="code"><em class="replaceable"><code>field </code></em></code></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp </code></em></code> if it was
+ returned as a string. This is the length of the MIME field in
+ its unparsed form.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The calculated length of a string representation of the
+ specified MIME field.</p>
+<p><code class="code">INK_ERROR</code> if there is an error.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldNameGet"></a>INKMimeHdrFieldNameGet</h4></div></div></div>
+<p>Gets the name and name length of a specified MIME
+ field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">const char* INKMimeHdrFieldNameGet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ *<em class="replaceable"><code>length</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Returns the name of the field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p><code class="function">INKMimeHdrFieldNameGet</code> places the length
+ of the returned string in the
+ <code class="code"><em class="replaceable"><code>length </code></em></code>
+ argument.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A pointer to the name of the specified field within the
+ specified MIME header.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>The returned string is not guaranteed to be
+ null-terminated.</p></td></tr>
+</table></div>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldNameSet"></a>INKMimeHdrFieldNameSet</h4></div></div></div>
+<p>Sets the name for a specified MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldNameSet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, const char
+ *<em class="replaceable"><code>name</code></em>, int
+ <em class="replaceable"><code>length</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets the name of the field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code> to
+ the string <code class="code"><em class="replaceable"><code>name</code></em></code>. </p>
+</dd>
+<dd>
+ <p>If <code class="code"><em class="replaceable"><code>length </code></em></code> is <code>-1</code>, then <code class="function">INKMimeHdrFieldNameSet</code> assumes the name
+ is null-terminated. Otherwise, the length of the string
+ <code class="code"><em class="replaceable"><code>name </code></em></code> is taken to be
+ <code class="code"><em class="replaceable"><code>length</code></em></code>. </p>
+</dd>
+<dd>
+ <p><code class="function">INKMimeHdrFieldNameSet</code> copies the string
+ to within <code class="code"><em class="replaceable"><code>bufp</code></em></code>, so it
+ is okay to modify or delete
+ <code class="code"><em class="replaceable"><code>name </code></em></code> after calling
+ <code class="function">INKMimeHdrFieldNameSet</code>. When possible, use the <code class="code">INK_MIME_FIELD_XXX</code> tokens
+ for <code class="code"><em class="replaceable"><code> name </code></em></code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldNext"></a>INKMimeHdrFieldNext</h4></div></div></div>
+<p>Returns the next MIME field after a specified MIME field in a
+ MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKMimeHdrFieldNext (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Conceptually, MIME fields are listed in a MIME
+ header (see the <a href="GuideTSHTTPHdrSyst.html" title="Guide to Traffic Server HTTP Header System">Guide to Traffic Server's HTTP Header System</a>).
+ <code class="function">INKMimeHdrFieldNext</code> returns the location
+ of the next <code class="code"><em class="replaceable"><code>field </code></em></code> in
+ the list, after the field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ If the next field is not found, then a <code class="code">NULL</code> pointer is
+ returned.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The location of the MIME field following the specified
+ MIME field within the specified MIME header. Release the
+ returned <code class="function">INKMLoc</code> with a call to
+ <code class="function">INKHandleMLocRelease</code> (see the code
+ example below).</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+<dt><span class="term"><b>Example</b></span></dt>
+<dd>
+<p>An example of a loop through each MIME field of an HTTP
+ header is featured below:</p>
+<pre class="programlisting">field_loc = INKMimeHdrFieldGet (hdr_bufp, hdr_loc, 0);
+ while (field_loc) {
+ /* Temp variable used only for the loop */
+ INKMLoc next_field_loc;
+
+ /* Do your job with the field here */
+
+ /* Get the next field and release the current one */
+ next_field_loc = INKMimeHdrFieldNext (hdr_bufp, hdr_loc, field_loc);
+ INKHandleMLocRelease(hdr_bufp, hdr_loc, field_loc);
+ field_loc = next_field_loc;
+ }</pre>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldNextDup"></a>INKMimeHdrFieldNextDup</h4></div></div></div>
+<p>Returns the next duplicate MIME field after a specified MIME
+ field in a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKMimeHdrFieldNextDup (INKMBuffer <span class="replaceable">bufp</span>,
+ INKMLoc <span class="replaceable">hdr</span>, INKMLoc <span class="replaceable">field</span>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>MIME headers <u>can</u> 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. The current version of Traffic Server does not
+ coalesce duplicate fields.</p>
+<p>Your plugins should check for the presence of duplicate
+ fields and iterate over duplicate fields via
+ <code class="function">INKMimeHdrFieldNextDup. INKMimeHdrFieldNextDup</code>
+ returns the location of the next duplicate field in the list
+ after the field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ If the next field is not found, then a <code class="code">NULL</code> pointer is
+ returned.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The location of the next duplicate MIME field that
+ follows the specified field within the specified MIME header.
+ Release with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueAppend"></a>INKMimeHdrFieldValueAppend</h4></div></div></div>
+<p>Appends a string to a specified value in a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueAppend
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>idx</code></em>, const char
+ *<em class="replaceable"><code>value</code></em>, int
+ <em class="replaceable"><code>length</code></em>)</code></p></dd>
+<dt><span class="term"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="code"><em class="replaceable"><code>bufp </code></em></code> is the
+ marshal buffer containing the MIME field.</p>
+<p><code class="code"><em class="replaceable"><code>hdr </code></em></code> is the
+ location of the parent object within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp </code></em></code> from which
+ <code class="code"><em class="replaceable"><code>field </code></em></code> was
+ retrieved.</p>
+<p><code class="code"><em class="replaceable"><code>field </code></em></code> is the
+ location of the MIME field to be appended.</p>
+<p><code class="code"><em class="replaceable"><code>idx </code></em></code> is the index
+ of the field value to be appended. For example: in the MIME
+ field <code class="code">Foo: bar</code><code>, car</code> the index of the value <code>bar</code> is
+ <code>0</code> and the index of <code>car</code> is <code>1</code>.</p>
+<p><code class="code"><em class="replaceable"><code>value </code></em></code> is the
+ string that will be appended to the MIME field <code class="replaceable">value </code> at
+ <code class="code"><em class="replaceable"><code>idx</code></em></code>.</p>
+<p><code class="code"><em class="replaceable"><code>length </code></em></code> is the
+ length of the string <em class="replaceable"><code>value </code></em>to be appended.</p>
+</dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Appends the string stored in
+ <code class="code"><em class="replaceable"><code>value </code></em></code> to a specific
+ value in the MIME field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>The effect of <code class="function">INKMimeHdrFieldValueAppend</code>
+ is as if the previous value was retrieved, the string
+ <code class="code"><em class="replaceable"><code>value </code></em></code> was appended to
+ it, and this new string was stored back in the MIME field at
+ the same position. </p>
+</dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies which value in the field to append to. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is not between <code>0</code> and <code class="function">INKMimeHdrFieldValuesCount
+ (</code><code class="code"><em class="replaceable"><code>bufp, hdr, field</code></em></code><code>) - 1</code>,
+ then no operation is performed.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the string is successfully
+ appended.</p>
+<p><code class="code">INK_ERROR</code> if the hook is not added.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueDateGet"></a>INKMimeHdrFieldValueDateGet</h4></div></div></div>
+<p>Gets the date value from a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueDateGet
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, time_t
+ *<em class="replaceable"><code>value</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Retrieves a date
+ <code class="code"><em class="replaceable"><code>value </code></em></code> from within the
+ MIME field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>All values are stored as strings within the MIME field. <code class="function">INKMimeHdrFieldValueDateGet</code> parses the
+ string <code class="code"><em class="replaceable"><code>value </code></em></code> to return
+ an integer date representation.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The date <code class="code"><em class="replaceable"><code>value </code></em></code>
+ from the specified MIME header.</p>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueDateInsert"></a>INKMimeHdrFieldValueDateInsert</h4></div></div></div>
+<p>Inserts a date value into a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueDateInsert
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, time_t
+ <em class="replaceable"><code>value</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Inserts the date
+ <code class="code"><em class="replaceable"><code>value </code></em></code> into the MIME
+ field located at <code class="code"><em class="replaceable"><code>field </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>All values are
+ stored as strings within the MIME field. <code class="function">INKMimeHdrFieldValueDateInsert</code> simply
+ formats the date into a string and then calls
+ <code class="function">INKMimeHdrFieldValueInsert</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueDateSet"></a>INKMimeHdrFieldValueDateSet</h4></div></div></div>
+<p>Sets a date value in a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueDateSet
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, time_t
+ <em class="replaceable"><code>value</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets a value in the MIME field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code> to
+ the date <code class="code"><em class="replaceable"><code>value</code></em></code>. All
+ values are stored as strings within the MIME field.
+ <code class="function">INKMimeHdrFieldValueDateSet</code> simply
+ formats the date into a string and then calls
+ <code class="function">INKMimeHdrFieldValueStringSet</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueDelete"></a>INKMimeHdrFieldValueDelete</h4></div></div></div>
+<p>Deletes a specified value from a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldVcoalueDelete
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>idx</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Removes and deletes a value from the MIME field located
+ at <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies which value should be deleted. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is not between <code>0</code> and <code class="function">INKMimeHdrFieldValuesCount</code><code>
+ (</code><code class="code"><em class="replaceable"><code>bufp, hdr, field</code></em></code><code>) - 1</code>,
+ then no operation is performed.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueIntGet"></a>INKMimeHdrFieldValueIntGet</h4></div></div></div>
+<p>Gets an integer field value in a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueIntGet
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>idx</code></em>, int
+ *<em class="replaceable"><code>value</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Retrieves an integer value from within the MIME field
+ located at <code class="code"><em class="replaceable"><code>field </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp </code></em></code>. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies which value within the field to retrieve. The fields
+ are numbered from <code>0</code> to <code class="function">INKMimeHdrFieldValuesCount</code><code>
+ (</code><code class="code"><em class="replaceable"><code>bufp, hdr, field</code></em></code><code>) -
+ 1</code>. If <code class="code"><em class="replaceable"><code>idx </code></em></code> does not lie
+ within that range, then <code>INKMimeHdrFieldValueIntGet</code> returns <code>(int) 0</code>. </p>
+</dd>
+<dd>
+ <p>All values are stored as strings within the MIME field; <code class="function">INKMimeHdrFieldValueIntGet</code> parses the
+ string <code class="code"><em class="replaceable"><code>value </code></em></code> to return
+ an integer.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The integer value from the specified MIME field.</p>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueIntInsert"></a>INKMimeHdrFieldValueIntInsert</h4></div></div></div>
+<p>Inserts an integer value into a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueIntInsert
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>value</code></em>, int
+ <em class="replaceable"><code>idx</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Inserts the integer
+ <code class="code"><em class="replaceable"><code>value </code></em></code> into the MIME
+ field located at <code class="code"><em class="replaceable"><code>field </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies where the inserted value should be placed with respect
+ to the other values already in the MIME field. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is <code>0</code>, then the
+ value is prepended to the list of values in the field.
+ Increasing values of <code class="code"><em class="replaceable"><code>idx </code></em></code> places the value
+ farther down the list of values. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is <code>-1</code>, then the <code class="code"><em class="replaceable"><code>value </code></em></code> is appended to
+ the list of values. Normal usage is to specify <code>-1</code> for <code class="code"><em class="replaceable"><code>idx </code></em></code> so that the value
+ is appended to the list of values. </p>
+</dd>
+<dd>
+ <p>All values are stored as
+ strings within the MIME field. <code class="function">INKMimeHdrFieldValueIntInsert</code> simply
+ formats the integer into a string and then calls
+ <code class="function">INKMimeHdrFieldValueInsert</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueIntSet"></a>INKMimeHdrFieldValueIntSet</h4></div></div></div>
+<p>Sets an integer value within a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueIntSet
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>idx</code></em>, int
+ <em class="replaceable"><code>value</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Sets a value in the MIME field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies which value in the field to change. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is not between <code>0</code> and <code>INKMimeHdrFieldValuesCount (</code><code class="code"><em class="replaceable"><code>bufp, hdr,
+ field</code></em></code><code>) - 1</code>, then no operation is
+ performed. </p>
+</dd>
+<dd>
+ <p>All values are stored as strings within the MIME
+ field. <code class="function">INKMimeHdrFieldValueIntSet</code> simply
+ formats the integer into a string and then calls
+ <code class="function">INKMimeHdrFieldValueSet</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="function">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="function">INK_ERROR</code> if an error occurs while
+ calling the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueStringGet"></a>INKMimeHdrFieldValueStringGet</h4></div></div></div>
+<p>Gets a specified field value from a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueStringGet
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>idx</code></em>, const char
+ **<em class="replaceable"><code>value</code></em>, int
+ *<em class="replaceable"><code>value_len</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Retrieves a string
+ <code class="code"><em class="replaceable"><code>value </code></em></code> from within the
+ MIME <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies which field to retrieve. The fields are numbered
+ from <code>0</code> to <code class="function">INKMimeHdrFieldValuesCount</code><code>
+ (</code><code class="code"><em class="replaceable"><code>bufp, hdr, field</code></em></code><code>) -
+ 1</code>. If <code class="code"><em class="replaceable"><code>idx </code></em></code> does not lie
+ within that range, then <code class="code">NULL</code> is returned. </p>
+</dd>
+<dd>
+ <p>The
+ length of the returned string is placed in
+ the <code class="code"><em class="replaceable"><code>value_len </code></em></code>
+ argument. The string returned is not guaranteed to be NULL terminated.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A pointer to the specified field
+ <code class="code"><em class="replaceable"><code>value </code></em></code> in the MIME
+ header.</p>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueStringInsert"></a>INKMimeHdrFieldValueStringInsert</h4></div></div></div>
+<p>Inserts a value into a specified location within a MIME
+ field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueStringInsert
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>idx</code></em>, const char
+ *<em class="replaceable"><code>value</code></em>, int
+ <em class="replaceable"><code>length</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Inserts the string
+ <code class="code"><em class="replaceable"><code>value </code></em></code> into the MIME
+ field located at <code class="code"><em class="replaceable"><code>field </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>If <code class="code"><em class="replaceable"><code>len </code></em></code> is <code>-1</code>, then <code class="function">INKMimeHdrFieldValueStringInsert</code> assumes
+ that <code class="code"><em class="replaceable"><code>value </code></em></code> is
+ null-terminated. Otherwise, the length of the string
+ <code class="code"><em class="replaceable"><code>value </code></em></code> is taken to be
+ <code class="code"><em class="replaceable"><code>length</code></em></code>. </p>
+</dd>
+<dd>
+ <p><code class="function">INKMimeHdrFieldValueStringInsert</code> copies
+ the string to within
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>, so it is okay to
+ modify or delete <code class="code"><em class="replaceable"><code>value </code></em></code>
+ after calling
+ <code class="function">INKMimeHdrFieldValueStringSet</code>. </p>
+</dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies where the inserted value should be placed with respect
+ to the other values already in the MIME field. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is <code>0</code>, then <code class="function">INKMimeHdrFieldValueStringInsert</code> prepends
+ the value to the list of values in the field. Increasing
+ values of <code class="code"><em class="replaceable"><code>idx </code></em></code> place
+ the value farther down the list of values. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is<code> -1</code>,
+ then <code class="function">INKMimeHdrFieldValueStringInsert</code> appends
+ the value to the list of values. Normal usage is to specify<code> -1</code> for <code class="replaceable">idx </code> so that the value is appended to the list
+ of values.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueStringSet"></a>INKMimeHdrFieldValueStringSet</h4></div></div></div>
+<p>Sets a value in a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueStringSet
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>idx</code></em>, const char
+ *<em class="replaceable"><code>value</code></em>, int
+ <em class="replaceable"><code>len</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Sets a value in the MIME field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code> to
+ the string <code class="code"><em class="replaceable"><code>value</code></em></code>. </p>
+</dd>
+<dd>
+ <p>If <code class="code"><em class="replaceable"><code>len </code></em></code> is <code>-1</code>, then it is
+ assumed that <code class="code"><em class="replaceable"><code>value </code></em></code> is
+ null-terminated. Otherwise, the length of the string
+ <code class="code"><em class="replaceable"><code>value </code></em></code> is taken to be
+ <code class="code"><em class="replaceable"><code>len</code></em></code>. </p>
+</dd>
+<dd>
+ <p>The string is
+ copied to within <code class="code"><em class="replaceable"><code>bufp</code></em></code>,
+ so it is okay to modify or delete
+ <code class="code"><em class="replaceable"><code>value </code></em></code> after calling
+ <code class="function">INKMimeHdrFieldValueStringSet</code>. </p>
+</dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies which value in the field to change. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is not between <code>0</code> and <code class="function">INKMimeHdrFieldValuesCount</code>
+ <code>(</code><code class="code"><em class="replaceable"><code>bufp, hdr, field</code></em></code><code>) - 1</code>,
+ then no operation will be performed. If <code class="code"><em class="replaceable"><code>idx </code></em></code> is set to <code>-1</code>, then
+ all the MIME field values are returned. </p>
+</dd>
+<dt><b>Example</b></dt>
+<dd>
+ <p>Suppose
+ the MIME field is <code class="code">MyField: value1</code>,<code class="code">
+ value2</code>, <code class="code">value3</code>. If
+ <code class="function">INKMimeHdrFieldGet</code> is called with
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> set to <code>-1</code>, then it will
+ return a pointer to "<code class="code">value1</code>, <code class="code">value2</code>,
+ <code class="code">value3</code>".</p>
+ <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+ <tr>
+ <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+ <th align="left">Note</th>
+ </tr>
+ <tr><td align="left" valign="top"><p>As with other MIME header manipulation APIs, the string
+ is not null-terminated.</p></td></tr>
+ </table></div>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueUintGet"></a>INKMimeHdrFieldValueUintGet</h4></div></div></div>
+<p>Gets an unsigned integer field value in a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueUintGet
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>idx</code></em>, unsigned int
+ *<em class="replaceable"><code>value</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Retrieves an unsigned integer
+ <code class="code"><em class="replaceable"><code>value </code></em></code> from within the
+ MIME field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p>
+</dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies which field to retrieve. The fields are numbered
+ from <code>0</code> to <code class="function">INKMimeHdrFieldValuesCount</code>
+ <code>(</code><code class="code"><em class="replaceable"><code>bufp, hdr, field</code></em></code><code>) -
+ 1</code>. If <code class="code"><em class="replaceable"><code>idx </code></em></code> does not lie
+ within that range, then
+ <code class="function">INKMimeHdrFieldValueGetUnit</code> returns
+ <code>(unsigned int) 0</code>. </p>
+</dd>
+<dd>
+ <p>All values are stored as strings within the
+ MIME field. <code class="function">INKMimeHdrFieldValueUintGet</code>
+ parses the string
+ <code class="code"><em class="replaceable"><code>value </code></em></code> to return an
+ unsigned integer.</p>
+ <p>It is not possible to determine if
+ <code class="function">INKMimeHdrFieldValueUintGet</code> is returning
+ an unsigned <code>int</code> value in error. If you need to check for
+ errors in MIME header field values, then you can fetch the header
+ as a string and examine it (see the example below). </p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The unsigned integer <code class="replaceable">value </code> from the
+ specified MIME field.</p>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+<dt><span class="term"><b>Example</b></span></dt>
+<dd> <p>The example below contains sample code that fetches MIME headers from marshal buffers into strings using <code>INKMimeHdrFieldValueGet</code> instead. The context of this example is that the plugin is processing an HTTP transaction and has access to a transaction.</p></dd>
+<dd>
+ <pre class="programlisting">static void
+handle_string (INKHttpTxn txnp, INKCont contp) {
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKMLoc field;
+ int len;
+ char* output_string;
+ const char* value;
+/* Fetch the transaction's client request header into a marshal buffer. */
+ if (!INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ INKError ("couldn't retrieve client request header\n");
+ goto done;
+ }
+ field=INKMimeHdrFieldFind(bufp, hdr_loc,
+ INK_MIME_FIELD_CONTENT_LENGTH);
+
+ if (!field) {
+ INKError ("Content-Length field not found.\n");
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+ /* Obtain the value of the content length (normally an
+ * unsigned int) as a string. */
+ value=INKMimeHdrFieldValueGet (bufp, hdr_loc, field, 0, &len);
+
+ if ((!value) || (len<=0))}
+ INKHandleMLocRelease (bufp, hdr_loc, field);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+ /* Allocate the string with an extra byte for the string terminator. */
+ output_string = (char*) INKmalloc(len + 1);
+
+ /* Copy the value. */
+ strncpy (output_string, value, len);
+
+ /* Terminate the string */
+ output_string[len] = '\0';
+/* Now that you have the MIME fields as a string, you can do
+ whatever you want with it. For example: you can print it or
+ make sure it's an unsigned integer, either by using the
+ atol C function or by scanning each ASCII character. */
+ INKDebug("my-plugin", "%s", output_string);
+
+</pre></dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueUintInsert"></a>INKMimeHdrFieldValueUintInsert</h4></div></div></div>
+<p>Inserts an unsigned integer value into a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueUintInsert
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, unsigned int
+ <em class="replaceable"><code>value</code></em>, int
+ <em class="replaceable"><code>idx</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Inserts the unsigned integer
+ <code class="code"><em class="replaceable"><code>value </code></em></code> into the MIME
+ field located at <code class="code"><em class="replaceable"><code>field </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies where the inserted value should be placed with respect
+ to other values already in the MIME field. If<code class="code"><em class="replaceable"><code> idx</code></em> </code>is <code>0</code>, then the value is prepended to the
+ list of values in the field. Increasing values of <code class="code"><em class="replaceable"><code>idx </code></em></code> simply places the
+ value farther down on the list of values. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is <code>-1</code>, then the
+ value is appended to the list of values. Normal usage is
+ to specify <code>-1</code> for <code class="code"><em class="replaceable"><code>idx </code></em></code>
+ so that the value will be appended to the existing list of values. </p>
+</dd>
+<dd>
+ <p>All
+ values are stored as strings within the MIME field. <code class="function">INKMimeHdrFieldValueUintInsert</code> simply
+ formats the unsigned integer into a string and then calls
+ <code class="function">INKMimeHdrFieldValueStringInsert</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValueUintSet"></a>INKMimeHdrFieldValueUintSet</h4></div></div></div>
+<p>Sets a value in a MIME field to a specified unsigned
+ integer.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValueUintSet
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>, int
+ <em class="replaceable"><code>idx</code></em>, unsigned int
+ <em class="replaceable"><code>value</code></em>) </code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Sets a value in the MIME field located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code> to
+ the unsigned integer
+ <code class="code"><em class="replaceable"><code>value</code></em></code>. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies which value in the field to change. If
+ <code class="code"><em class="replaceable"><code>idx </code></em></code> is not between <code> 0</code> and <code class="function">INKMimeHdrFieldValuesCount</code>
+ <code>(</code><code class="code"><em class="replaceable"><code>bufp, hdr, field</code></em></code><code>) - 1</code>,
+ then no operation is performed. </p>
+</dd>
+<dd>
+ <p>All values are stored as
+ strings within the MIME field. <code class="function">INKMimeHdrFieldValueUintSet</code> simply
+ formats the unsigned integer into a string and then calls
+ <code class="function">INKMimeHdrFieldValueStringSet</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the API is called
+ successfully.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs while calling
+ the API or if an argument is invalid.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValuesClear"></a>INKMimeHdrFieldValuesClear</h4></div></div></div>
+<p>Clears all values in a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldValuesClear
+ (INKMBuffer <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Removes and destroys all values within the MIME
+ field located at <code class="code"><em class="replaceable"><code>field </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>.</p>
+<p>Make sure you release any corresponding
+ <code class="function">INKMLoc</code> via
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldValuesCount"></a>INKMimeHdrFieldValuesCount</h4></div></div></div>
+<p>Counts the values in a MIME field.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKMimeHdrFieldValuesCount (INKMBuffer <span class="replaceable">bufp</span>,
+ INKMLoc <span class="replaceable">hdr</span>, INKMLoc <span class="replaceable">field</span>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Retrieves a count of the number of values in the MIME
+ field located at <code class="code"><em class="replaceable"><code>field </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The number of values in the specified MIME field.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrClone"></a>INKMimeHdrClone</h4></div></div></div>
+<p>Copies a MIME header and returns the location of the
+ copied header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKMimeHdrClone(INKMBuffer
+ <em class="replaceable"><code>dest_bufp</code></em>, INKMBuffer
+ <em class="replaceable"><code>src_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>src_hdr_loc</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Copies the contents of the MIME header located at
+ <code class="code"><em class="replaceable"><code> src_hdr_loc </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> to the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>dest_bufp</code></em></code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The <code class="function">INKMLoc</code> location of the copied
+ header. Release the returned handle with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrCopy"></a>INKMimeHdrCopy</h4></div></div></div>
+<p>Copies a MIME header to a specified MIME header
+ location.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrCopy (INKMBuffer
+ <em class="replaceable"><code>dest_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>dest_hdr_loc</code></em>, INKMBuffer
+ <em class="replaceable"><code>src_bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>src_hdr_loc</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Copies the contents of the MIME header located at
+ <code class="code"><em class="replaceable"><code> src_hdr_loc </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> to the MIME
+ header located at
+ <code class="code"><em class="replaceable"><code>dest_hdr_loc </code></em></code> within
+ the marshal buffer
+ <code class="code"><em class="replaceable"><code>dest_bufp</code></em></code>. </p>
+</dd>
+<dd>
+ <p><code class="function">INKMimeHdrCopy</code> works correctly even if
+ <code class="code"><em class="replaceable"><code>src_bufp </code></em></code> and
+ <code class="code"><em class="replaceable"><code>dest_bufp </code></em></code> point to
+ different marshal buffers.</p>
+ <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+ <tr>
+ <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+ <th align="left">Note</th>
+ </tr>
+ <tr><td align="left" valign="top"><p>Make sure the destination marshal buffer and
+ the destination MIME header location have been created before
+ copying (see the example below).</p></td></tr>
+ </table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+<dt><span class="term"><b>Example</b></span></dt>
+<dd><pre class="programlisting">static void
+copyResponseMimeHdr (INKCont pCont, INKHttpTxn pTxn)
+{
+ INKMBuffer respHdrBuf, tmpBuf;
+ INKMLoc respHttpHdrLoc, tmpMimeHdrLoc;
+
+ if ( !INKHttpTxnClientRespGet (pTxn, &respHdrBuf, &respHttpHdrLoc) ) {
+ INKError ("couldn't retrieve client response header\n");
+ INKHandleMLocRelease (respHdrBuf, INK_NULL_MLOC,
+ respHttpHdrLoc);
+ goto done;
+ }
+ tmpBuf = INKMBufferCreate ();
+ tmpMimeHdrLoc = INKMimeHdrCreate(tmpBuf);
+
+ INKMimeHdrCopy(tmpBuf, tmpMimeHdrLoc, respHdrBuf, respHttpHdrLoc);
+
+ INKHandleMLocRelease (tmpBuf, INK_NULL_MLOC, tmpMimeHdrLoc);
+ INKHandleMLocRelease (respHdrBuf, INK_NULL_MLOC, respHttpHdrLoc);
+
+ INKMBufferDestroy(tmpBuf);
+
+ done:
+ INKHttpTxnReenable(pTxn, INK_EVENT_HTTP_CONTINUE); }</pre></dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrCreate"></a>INKMimeHdrCreate</h4></div></div></div>
+<p>Creates a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKMimeHdrCreate (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd><p>Creates a new MIME header within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>Location of the newly-created MIME header. Release with
+ a call to <code class="function">INKHandleMLocRelease</code>.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrDestroy"></a>INKMimeHdrDestroy</h4></div></div></div>
+<p>Destroys a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrDestroy (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Destroys the MIME header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>.</p>
+<p>Release the <code class="function">INKMLoc</code> handle
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldFind"></a>INKMimeHdrFieldFind</h4></div></div></div>
+<p>Finds specific fields in a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKMimeHdrFieldFind (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>loc</code></em>, const char*
+ <em class="replaceable"><code>name</code></em>, int
+ <em class="replaceable"><code>length</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Retrieves a MIME field from within the MIME header
+ located at <code class="code"><em class="replaceable"><code>loc </code></em></code> within
+ the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>name </code></em></code> and
+ <code class="code"><em class="replaceable"><code>length </code></em></code> parameters
+ specify which field to retrieve. For each MIME field in the
+ MIME header, a case-insensitive string comparison is done
+ between the field name and
+ <code class="code"><em class="replaceable"><code>name</code></em></code>. The
+ <code class="code"><em class="replaceable"><code>length </code></em></code> parameter
+ specifies the length of the string that
+ <code class="code"><em class="replaceable"><code>name </code></em></code> points to. If
+ <code class="code"><em class="replaceable"><code>length </code></em></code> is <code>-1</code>, then <code class="code"><em class="replaceable"><code> name </code></em></code> is assumed to be
+ null-terminated. If the requested field cannot be found, then <code>0</code> is returned.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The location of the retrieved MIME header. Release with
+ a call to <code class="function">INKHandleMLocRelease</code>.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldGet"></a>INKMimeHdrFieldGet</h4></div></div></div>
+<p>Gets a field in a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMLoc INKMimeHdrFieldGet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, int
+ <em class="replaceable"><code>idx</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Retrieves a MIME field from within the MIME header
+ located at <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code>
+ within the marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>idx </code></em></code> parameter
+ specifies which field to retrieve. The fields are numbered
+ from <code>0</code> to <code class="function">INKMimeHdrFieldsCount</code>
+ <code>(</code><code class="code"><em class="replaceable"><code>bufp, hdr_loc</code></em></code><code>) - 1</code>.
+ If <code class="code"><em class="replaceable"><code>idx </code></em></code> does not lie
+ within that range, then <code>0</code> is returned.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The location of the MIME field from within the MIME
+ header. Release with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldRemove"></a>INKMimeHdrFieldRemove</h4></div></div></div>
+<p>Removes a field in a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldRemove (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, INKMLoc
+ <em class="replaceable"><code>field</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Removes the MIME header located at
+ <code class="code"><em class="replaceable"><code>field </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code>
+ from the MIME header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp</code></em></code>.
+ If the specified field cannot be found in the list of fields
+ associated with the header, then nothing is done.</p>
+<p>After the call to
+ <code class="function">INKMimeHdrFieldDestroy</code>, you must release
+ the <code class="function">INKMLoc</code> handle field with a call to
+ <code class="function">INKHandleMLocRelease</code>.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/docbook/note.png" /></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>Removing the MIME field doesn't destroy the field - it
+ only detaches it and hides it from the printed output.The
+ field can be reattached by calling
+ <code class="function">INKMimeHdrFieldAppend</code>.</p></td></tr>
+</table></div>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldsClear"></a>INKMimeHdrFieldsClear</h4></div></div></div>
+<p>Clears all the fields in a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeHdrFieldsClear (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+<p>Removes and destroys all MIME fields in the MIME
+ header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>.</p>
+<p>Make sure that you release any corresponding
+ <code class="function">INKMLoc</code> using
+ <code class="function">INKHandleMLocRelease</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrFieldsCount"></a>INKMimeHdrFieldsCount</h4></div></div></div>
+<p>Counts the fields in a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKMimeHdrFieldsCount (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Obtains a count of the number of MIME fields within the
+ MIME header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer
+ <code class="code"><em class="replaceable"><code>bufp</code></em></code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The number of fields within the specified MIME
+ header.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrLengthGet"></a>INKMimeHdrLengthGet</h4></div></div></div>
+<p>Gets the length of a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKMimeHdrLengthGet (INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Calculates the length of the MIME header located at
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> within the
+ marshal buffer <code class="code"><em class="replaceable"><code>bufp </code></em></code> if
+ it was returned as a string. This is the length of the MIME
+ header in its unparsed form.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>The length of the specified MIME header.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrParse"></a>INKMimeHdrParse</h4></div></div></div>
+<p>Parses a MIME header.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">int INKMimeHdrParse (INKMimeParser
+ <em class="replaceable"><code>parser</code></em>, INKMBuffer
+ <em class="replaceable"><code>bufp</code></em>, INKMLoc
+ <em class="replaceable"><code>hdr_loc</code></em>, const char
+ **<em class="replaceable"><code>start</code></em>, const char
+ *<em class="replaceable"><code>end</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Parses a MIME header. The MIME header must have already
+ been allocated, and both
+ <code class="code"><em class="replaceable"><code>bufp </code></em></code> and
+ <code class="code"><em class="replaceable"><code>hdr_loc </code></em></code> must point
+ within that header. </p></dd>
+<dd>
+ <p>The <code class="code"><em class="replaceable"><code>start </code></em></code> argument points
+ to the current position of the buffer being parsed and the
+ <code class="code"><em class="replaceable"><code>end </code></em></code> argument points to
+ one byte after the end of the buffer. Upon return,
+ <code class="code"><em class="replaceable"><code>start </code></em></code> is modified to
+ point past the last character parsed. </p>
+</dd>
+<dd>
+ <p>It is possible to parse
+ a MIME header a single byte at a time using repeated calls to <code class="function">INKMimeHdrParse</code>. As long as an error does
+ not occur, the <code>INKMimeHdrParse</code> function consumes that
+ single byte and asks for more.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_PARSE_ERROR</code> if an error occurs.</p>
+<p><code class="code">INK_PARSE_DONE</code> when a
+ <code class="code">\r\n\r\n</code> pattern is encountered, indicating the
+ end of the header. </p>
+</dd>
+<dd>
+ <p><code class="code">INK_PARSE_CONT</code> if
+ parsing of the header stopped because the end of the buffer
+ was reached.</p>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeParserClear"></a>INKMimeParserClear</h4></div></div></div>
+<p>Clears a MIME header parser so it can be reused.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeParserClear (INKMimeParser
+ <em class="replaceable"><code>parser</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Clears the specified MIME
+ <code class="code"><em class="replaceable"><code>parser </code></em></code> so it can be
+ used again.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if successful.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeParserCreate"></a>INKMimeParserCreate</h4></div></div></div>
+<p>Creates a parser for MIME headers.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMimeParser INKMimeParserCreate
+ (void)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Creates a MIME parser. The parser's data structure
+ contains information about the header being parsed. A single
+ MIME parser can be used multiple times, but not
+ simultaneously. Before being used again, the parser must be
+ cleared by calling <code>INKMimeParserClear</code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A pointer to the newly-created MIME parser.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeParserDestroy"></a>INKMimeParserDestroy</h4></div></div></div>
+<p>Destroys a MIME header parser.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKReturnCode INKMimeParserDestroy (INKMimeParser
+ <em class="replaceable"><code>parser</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Destroys the specified MIME
+ <code class="code"><em class="replaceable"><code> parser </code></em></code> and frees the
+ associated memory.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p><code class="code">INK_SUCCESS</code> if the parser is successfully
+ destroyed.</p>
+<p><code class="code">INK_ERROR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKMimeHdrPrint"></a>INKMimeHdrPrint</h4></div></div></div>
+<p>Prints a MIME header to an IO buffer.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
[... 23 lines stripped ...]