You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bu...@apache.org on 2010/11/06 07:31:10 UTC
svn commit: r778776 [16/21] - in
/websites/staging/trafficserver/trunk/content/docs/trunk: admin/ sdk/
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MimeHeadersFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MimeHeadersFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MimeHeadersFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MimeHeadersFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,1167 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="URLFunctions">Prev</a> - URL Functions
+Mutex Functions - <a href="MutexFunctions">Next</a></p>
+<h3 id="miime_headers">MIIME Headers</h3>
+<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>INKMimeHdrFieldClone</code> after
+<code>READ_REQUEST_HDR_HOOK</code>.</p>
+<p>The Traffic Server MIME header functions are listed below:</p>
+<hr />
+<p><a href="MimeHeadersFunctions#INKMimeHdrFieldAppend">INKMimeHdrFieldAppend</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldClone">INKMimeHdrFieldClone</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldCopy">INKMimeHdrFieldCopy</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldCopyValues">INKMimeHdrFieldCopyValues</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldCreate">INKMimeHdrFieldCreate</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldDestroy">INKMimeHdrFieldDestroy</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldLengthGet">INKMimeHdrFieldLengthGet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldNameGet">INKMimeHdrFieldNameGet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldNameSet">INKMimeHdrFieldNameSet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldNext">INKMimeHdrFieldNext</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldNextDup">INKMimeHdrFieldNextDup</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueAppend">INKMimeHdrFieldValueAppend</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueAppend">INKMimeHdrFieldValueAppend</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueDateGet">INKMimeHdrFieldValueDateGet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueDateInsert">INKMimeHdrFieldValueDateInsert</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueDateSet">INKMimeHdrFieldValueDateSet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueInsert">INKMimeHdrFieldValueInsert</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueIntGet">INKMimeHdrFieldValueIntGet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueIntSet">INKMimeHdrFieldValueIntSet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueStringGet">INKMimeHdrFieldValueStringGet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueStringInsert">INKMimeHdrFieldValueStringInsert</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueStringSet">INKMimeHdrFieldValueStringSet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueUintGet">INKMimeHdrFieldValueUintGet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueUintInsert">INKMimeHdrFieldValueUintInsert</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValueUintSet">INKMimeHdrFieldValueUintSet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValuesClear">INKMimeHdrFieldValuesClear</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldValuesCount">INKMimeHdrFieldValuesCount</a>
+<a href="MimeHeadersFunctions#INKMimeHdrClone">INKMimeHdrClone</a>
+<a href="MimeHeadersFunctions#INKMimeHdrCopy">INKMimeHdrCopy</a>
+<a href="MimeHeadersFunctions#INKMimeHdrCreate">INKMimeHdrCreate</a>
+<a href="MimeHeadersFunctions#INKMimeHdrDestroy">INKMimeHdrDestroy</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldFind">INKMimeHdrFieldFind</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldGet">INKMimeHdrFieldGet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldRemove">INKMimeHdrFieldRemove</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldsClear">INKMimeHdrFieldsClear</a>
+<a href="MimeHeadersFunctions#INKMimeHdrFieldsCount">INKMimeHdrFieldsCount</a>
+<a href="MimeHeadersFunctions#INKMimeHdrLengthGet">INKMimeHdrLengthGet</a>
+<a href="MimeHeadersFunctions#INKMimeHdrParse">INKMimeHdrParse</a>
+<a href="MimeHeadersFunctions#INKMimeParserClear">INKMimeParserClear</a>
+<a href="MimeHeadersFunctions#INKMimeParserCreate">INKMimeParserCreate</a>
+<a href="MimeHeadersFunctions#INKMimeParserDestroy">INKMimeParserDestroy</a>
+<a href="MimeHeadersFunctions#INKMimeHdrPrint">INKMimeHdrPrint</a></p>
+<h4 id="inkmimehdrfieldappend">INKMimeHdrFieldAppend</h4>
+<p>Appends a field in a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldAppend (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Appends the MIME field located at field within the marshal
+ buffer <code><em class="replaceable"><code>bufp</code> into the MIME header
+ located at <code><em class="replaceable"><code>url_loc</code> within the
+ marshal buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldclone">INKMimeHdrFieldClone</h4>
+<p>Copies a MIME field to a marshal buffer and returns the <code>INKMLoc</code>
+location of the copied field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMLoc INKMimeHdrFieldClone (INKMBuffer <em class="replaceable"><code>dest_bufp</code>,
+ INKMLoc <em><code>dest_hdr</code></em>, INKMBuffer <em><code>src_bufp</code></em>, INKMLoc <em><code>src_hdr</code></em>,
+ INKMLoc <em><code>src_field</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Copies the contents of the MIME field located at
+ <code><em class="replaceable"><code>src_field</code> within the marshal buffer
+ <code><em class="replaceable"><code>src_bufp</code> to a MIME header located
+ at <code><em class="replaceable"><code>dest_hdr</code> within the marshal
+ buffer <code><em class="replaceable"><code>dest_bufp</code>.</p>
+<p><strong>Returns</strong>
+ ~ The <code>INKMLoc</code> location of the copied field. Release the
+ returned handle with a call to <code>INKHandleMLocRelease</code>.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldcopy">INKMimeHdrFieldCopy</h4>
+<p>Copies a MIME field from one specified location to another
+specified location.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldCopy (INKMBuffer <em class="replaceable"><code>dest_bufp</code>,
+ INKMLoc <em><code>dest_hdr</code></em>, INKMLoc <em><code>dest_field</code></em>, INKMBuffer
+ <em><code>src_bufp</code></em>, INKMLoc <em><code>src_hdr</code></em>, INKMLoc <em><code>src_field</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Copies the contents of the MIME field located at
+ <code><em class="replaceable"><code>src_field</code> within the marshal buffer
+ <code><em class="replaceable"><code>src_bufp</code> to the MIME field located
+ at <code><em class="replaceable"><code>dest_field</code> within the marshal
+ buffer <code><em class="replaceable"><code>dest_bufp</code>.</p>
+<p>~ <code>INKMimeHdrFieldCopy</code> works correctly even if
+ <code><em class="replaceable"><code>src_bufp</code> and
+ <code><em class="replaceable"><code>dest_bufp</code> point to different
+ marshal buffers.</p>
+<div class="codehilite"><pre><span class="o">!</span><span class="p">[[</span><span class="n">Note</span><span class="p">]](</span><span class="n">images</span><span class="sr">/docbook/</span><span class="n">note</span><span class="o">.</span><span class="n">png</span><span class="p">)</span>
+<span class="n">Note</span>
+<span class="n">You</span> <span class="n">must</span> <span class="n">first</span> <span class="n">create</span> <span class="n">the</span> <span class="n">destination</span> <span class="n">MIME</span> <span class="n">field</span> <span class="n">before</span> <span class="n">you</span> <span class="n">can</span>
+<span class="n">copy</span> <span class="n">into</span> <span class="n">it</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldcopyvalues">INKMimeHdrFieldCopyValues</h4>
+<p>Copies MIME field values from one location to another.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldCopyValues (INKMBuffer <em class="replaceable"><code>dest_bufp</code>,
+ INKMLoc <em><code>dest_hdr</code></em>, INKMLoc <em><code>dest_field</code></em>, INKMBuffer
+ <em><code>src_bufp</code></em>, INKMLoc <em><code>src_hdr</code></em>, INKMLoc <em><code>src_field</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Copies the values contained within the MIME field located at
+ <code><em class="replaceable"><code>src_field</code> within the marshal buffer
+ <code><em class="replaceable"><code>src_bufp</code> to the MIME field located
+ at <code><em class="replaceable"><code>dest_field</code> within the marshal
+ buffer <code><em class="replaceable"><code>dest_bufp</code>.</p>
+<p>~ <code>INKMimeHdrFieldCopyValues</code> works correctly even if
+ <code><em class="replaceable"><code>src_bufp</code> and
+ <code><em class="replaceable"><code>dest_bufp</code> point to different
+ marshal buffers.</p>
+<p>~ <code>INKMimeHdrFieldCopyValues</code> does not copy the field's name.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldcreate">INKMimeHdrFieldCreate</h4>
+<p>Creates a new MIME field within a specified marshal buffer.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMLoc INKMimeHdrFieldCreate (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Creates a new MIME field with the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p><strong>Returns</strong>
+ ~ The location of the new MIME field. Release with a call to
+ <code>INKHandleMLocRelease</code>.</p>
+<h4 id="inkmimehdrfielddestroy">INKMimeHdrFieldDestroy</h4>
+<p>Deletes a specified MIME field from a marshal buffer.</p>
+<p><strong>Prototype</strong>
+ ~ <code>void INKMimeHdrFieldDestroy (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>, INKMLoc <em><code>field</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Destroys the MIME field located at
+ <code><em class="replaceable"><code>field</code> within the MIME header
+ located at <code><em class="replaceable"><code>hdr</code> within the marshal
+ buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<div class="codehilite"><pre><span class="n">After</span> <span class="n">the</span> <span class="n">call</span> <span class="n">to</span> <span class="sb">`INKMimeHdrFieldDestroy`</span><span class="p">,</span> <span class="n">you</span> <span class="n">must</span> <span class="n">release</span> <span class="n">the</span>
+<span class="sb">`INKMLoc`</span> <span class="n">handle</span> <span class="sb">`<em class="replaceable"><code>field`</span> <span class="n">with</span> <span class="n">a</span> <span class="n">call</span>
+<span class="n">to</span> <span class="sb">`INKHandleMLocRelease`</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldlengthget">INKMimeHdrFieldLengthGet</h4>
+<p>Calculates the length of a string representation in a specified
+MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int INKMimeHdrFieldLengthGet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>, INKMLoc <em><code>field</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Calculates the length of the MIME field located at
+ <code><code class="code"><em class="replaceable"><code>field</code> within the
+ marshal buffer <code><em class="replaceable"><code>bufp</code> if it was
+ returned as a string. This is the length of the MIME field in its
+ unparsed form.</p>
+<p><strong>Returns</strong>
+ ~ The calculated length of a string representation of the
+ specified MIME field.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">there</span> <span class="n">is</span> <span class="n">an</span> <span class="n">error</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldnameget">INKMimeHdrFieldNameGet</h4>
+<p>Gets the name and name length of a specified MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>const char* INKMimeHdrFieldNameGet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>, INKMLoc <em><code>field</code></em>, int *<em><code>length</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Returns the name of the field located at
+ <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ <code>INKMimeHdrFieldNameGet</code> places the length of the returned
+ string in the <code><em class="replaceable"><code>length</code> argument.</p>
+<p><strong>Returns</strong>
+ ~ A pointer to the name of the specified field within the
+ specified MIME header. Release the returned string with a call to
+ <code>INKHandleStringRelease</code>.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+
+<span class="o">!</span><span class="p">[[</span><span class="n">Note</span><span class="p">]](</span><span class="n">images</span><span class="sr">/docbook/</span><span class="n">note</span><span class="o">.</span><span class="n">png</span><span class="p">)</span>
+<span class="n">Note</span>
+<span class="n">The</span> <span class="n">returned</span> <span class="n">string</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">guaranteed</span> <span class="n">to</span> <span class="n">be</span> <span class="n">null</span><span class="o">-</span><span class="n">terminated</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldnameset">INKMimeHdrFieldNameSet</h4>
+<p>Sets the name for a specified MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldNameSet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>, INKMLoc <em><code>field</code></em>, const char *<em><code>name</code></em>, int
+ <em><code>length</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Sets the name of the field located at
+ <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code> to the string
+ <code><em class="replaceable"><code>name</code>.</p>
+<p>~ If <code><em class="replaceable"><code>length</code> is <code>-1</code>, then
+ <code>INKMimeHdrFieldNameSet</code> assumes the name is null-terminated.
+ Otherwise, the length of the string
+ <code><em class="replaceable"><code>name</code> is taken to be
+ <code><em class="replaceable"><code>length</code>.</p>
+<p>~ <code>INKMimeHdrFieldNameSet</code> copies the string to within
+ <code><em class="replaceable"><code>bufp</code>, so it is okay to modify or
+ delete <code><em class="replaceable"><code>name</code> after calling
+ <code>INKMimeHdrFieldNameSet</code>. When possible, use the
+ <code>INK_MIME_FIELD_XXX</code> tokens for
+ <code><em class="replaceable"><code> name</code>.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldnext">INKMimeHdrFieldNext</h4>
+<p>Returns the next MIME field after a specified MIME field in a MIME
+header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMLoc INKMimeHdrFieldNext (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>, INKMLoc <em><code>field</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Conceptually, MIME fields are listed in a MIME header (see the
+ <a href="GuideTSHTTPHdrSyst" title="Guide to Traffic Server HTTP Header System">Guide to Traffic Server's HTTP Header System</a>).
+ <code>INKMimeHdrFieldNext</code> returns the location of the next
+ <code><em class="replaceable"><code>field</code> in the list, after the field
+ located at <code><em class="replaceable"><code>field</code> within the marshal
+ buffer <code><em class="replaceable"><code>bufp</code>. If the next field is
+ not found, then a <code>NULL</code> pointer is returned.</p>
+<p><strong>Returns</strong>
+ ~ The location of the MIME field following the specified MIME
+ field within the specified MIME header. Release the returned
+ <code>INKMLoc</code> with a call to <code>INKHandleMLocRelease</code> (see the code
+ example below).</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Example</strong>
+ ~ An example of a loop through each MIME field of an HTTP header
+ is featured below:</p>
+<div class="codehilite"><pre> <span class="n">field_loc</span> <span class="o">=</span> <span class="n">INKMimeHdrFieldGet</span> <span class="p">(</span><span class="n">hdr_bufp</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+ <span class="k">while</span> <span class="p">(</span><span class="n">field_loc</span><span class="p">)</span> <span class="p">{</span>
+ <span class="sr">/* Temp variable used only for the loop */</span>
+ <span class="n">INKMLoc</span> <span class="n">next_field_loc</span><span class="p">;</span>
+
+ <span class="sr">/* Do your job with the field here */</span>
+
+ <span class="sr">/* Get the next field and release the current one */</span>
+ <span class="n">next_field_loc</span> <span class="o">=</span> <span class="n">INKMimeHdrFieldNext</span> <span class="p">(</span><span class="n">hdr_bufp</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">,</span> <span class="n">field_loc</span><span class="p">);</span>
+ <span class="n">INKHandleMLocRelease</span><span class="p">(</span><span class="n">hdr_bufp</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">,</span> <span class="n">field_loc</span><span class="p">);</span>
+ <span class="n">field_loc</span> <span class="o">=</span> <span class="n">next_field_loc</span><span class="p">;</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldnextdup">INKMimeHdrFieldNextDup</h4>
+<p>Returns the next duplicate MIME field after a specified MIME field
+in a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMLoc INKMimeHdrFieldNextDup (INKMBuffer <span class="replaceable">bufp</span>, INKMLoc <span class="replaceable">hdr</span>, INKMLoc <span class="replaceable">field</span>)</code></p>
+<p><strong>Description</strong>
+ ~ MIME headers can 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>
+<div class="codehilite"><pre><span class="n">Your</span> <span class="n">plugins</span> <span class="n">should</span> <span class="n">check</span> <span class="k">for</span> <span class="n">the</span> <span class="n">presence</span> <span class="n">of</span> <span class="n">duplicate</span> <span class="n">fields</span> <span class="ow">and</span>
+<span class="n">iterate</span> <span class="n">over</span> <span class="n">duplicate</span> <span class="n">fields</span> <span class="n">via</span>
+<span class="sb">`INKMimeHdrFieldNextDup. INKMimeHdrFieldNextDup`</span> <span class="n">returns</span> <span class="n">the</span>
+<span class="n">location</span> <span class="n">of</span> <span class="n">the</span> <span class="k">next</span> <span class="n">duplicate</span> <span class="n">field</span> <span class="n">in</span> <span class="n">the</span> <span class="n">list</span> <span class="n">after</span> <span class="n">the</span> <span class="n">field</span>
+<span class="n">located</span> <span class="n">at</span> <span class="sb">`<em class="replaceable"><code>field`</span> <span class="n">within</span> <span class="n">the</span> <span class="n">marshal</span>
+<span class="n">buffer</span> <span class="sb">`<em class="replaceable"><code>bufp`</span><span class="o">.</span> <span class="n">If</span> <span class="n">the</span> <span class="k">next</span> <span class="n">field</span> <span class="n">is</span>
+<span class="ow">not</span> <span class="n">found</span><span class="p">,</span> <span class="k">then</span> <span class="n">a</span> <span class="sb">`NULL`</span> <span class="n">pointer</span> <span class="n">is</span> <span class="n">returned</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ The location of the next duplicate MIME field that follows the
+ specified field within the specified MIME header. Release with a
+ call to <code>INKHandleMLocRelease</code>.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvalueappend">INKMimeHdrFieldValueAppend</h4>
+<p>Appends a string to a specified value in a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueAppend (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>idx</code></em>, const char
+ *<em><code>value</code></em>, int <em><code>length</code></em>)</p>
+<p><strong>Arguments</strong>
+ ~ <code><em class="replaceable"><code>bufp</code> is the marshal buffer
+ containing the MIME field.</p>
+<div class="codehilite"><pre><span class="sb">`<em class="replaceable"><code>hdr`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">location</span> <span class="n">of</span> <span class="n">the</span> <span class="n">parent</span>
+<span class="n">object</span> <span class="n">within</span> <span class="n">the</span> <span class="n">marshal</span> <span class="n">buffer</span>
+<span class="sb">`<em class="replaceable"><code>bufp`</span> <span class="n">from</span> <span class="n">which</span>
+<span class="sb">`<em class="replaceable"><code>field`</span> <span class="n">was</span> <span class="n">retrieved</span><span class="o">.</span>
+
+<span class="sb">`<em class="replaceable"><code>field`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">location</span> <span class="n">of</span> <span class="n">the</span> <span class="n">MIME</span>
+<span class="n">field</span> <span class="n">to</span> <span class="n">be</span> <span class="n">appended</span><span class="o">.</span>
+
+<span class="sb">`<em class="replaceable"><code>idx`</span> <span class="n">is</span> <span class="n">the</span> <span class="nb">index</span> <span class="n">of</span> <span class="n">the</span> <span class="n">field</span> <span class="n">value</span>
+<span class="n">to</span> <span class="n">be</span> <span class="n">appended</span><span class="o">.</span> <span class="n">For</span> <span class="n">example:</span> <span class="n">in</span> <span class="n">the</span> <span class="n">MIME</span> <span class="n">field</span> <span class="sb">`Foo: bar``, car`</span>
+<span class="n">the</span> <span class="nb">index</span> <span class="n">of</span> <span class="n">the</span> <span class="n">value</span> <span class="sb">`bar`</span> <span class="n">is</span> <span class="sb">`0`</span> <span class="ow">and</span> <span class="n">the</span> <span class="nb">index</span> <span class="n">of</span> <span class="sb">`car`</span> <span class="n">is</span> <span class="sb">`1`</span><span class="o">.</span>
+
+<span class="sb">`<em class="replaceable"><code>value`</span> <span class="n">is</span> <span class="n">the</span> <span class="n">string</span> <span class="n">that</span> <span class="n">will</span> <span class="n">be</span>
+<span class="n">appended</span> <span class="n">to</span> <span class="n">the</span> <span class="n">MIME</span> <span class="n">field</span> <span class="sb">`value`</span> <span class="n">at</span>
+<span class="sb">`<em class="replaceable"><code>idx`</span><span class="o">.</span>
+
+<span class="sb">`<em class="replaceable"><code>length`</span> <span class="n">is</span> <span class="n">the</span> <span class="nb">length</span> <span class="n">of</span> <span class="n">the</span> <span class="n">string</span>
+<span class="o">*</span><span class="sb">`value`</span><span class="o">*</span><span class="n">to</span> <span class="n">be</span> <span class="n">appended</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Description</strong>
+ ~ Appends the string stored in
+ <code><em class="replaceable"><code>value</code> to a specific value in the
+ MIME field located at <code><em class="replaceable"><code>field</code> within
+ the marshal buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The effect of <code>INKMimeHdrFieldValueAppend</code> is as if the
+ previous value was retrieved, the string
+ <code><em class="replaceable"><code>value</code> was appended to it, and this
+ new string was stored back in the MIME field at the same position.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ which value in the field to append to. If
+ <code><em class="replaceable"><code>idx</code> is not between <code>0</code> and
+ <code>INKMimeHdrFieldValuesCount (``<em class="replaceable"><code>bufp, hdr, field``) - 1</code>,
+ then no operation is performed.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the string is successfully appended.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">hook</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">added</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvaluedateget">INKMimeHdrFieldValueDateGet</h4>
+<p>Gets the date value from a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueDateGet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, time_t *<em><code>value</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Retrieves a date <code><em class="replaceable"><code>value</code> from
+ within the MIME field located at
+ <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ All values are stored as strings within the MIME field.
+ <code>INKMimeHdrFieldValueDateGet</code> parses the string
+ <code><em class="replaceable"><code>value</code> to return an integer date
+ representation.</p>
+<p><strong>Returns</strong>
+ ~ The date <code><em class="replaceable"><code>value</code> from the
+ specified MIME header.</p>
+<div class="codehilite"><pre><span class="sb">`INK_SUCCESS`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">API</span> <span class="n">is</span> <span class="n">called</span> <span class="n">successfully</span><span class="o">.</span>
+
+<span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvaluedateinsert">INKMimeHdrFieldValueDateInsert</h4>
+<p>Inserts a date value into a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueDateInsert (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, time_t <em><code>value</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Inserts the date <code><em class="replaceable"><code>value</code> into the
+ MIME field located at <code><em class="replaceable"><code>field</code> within
+ the marshal buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ All values are stored as strings within the MIME field.
+ <code>INKMimeHdrFieldValueDateInsert</code> simply formats the date into a
+ string and then calls <code>INKMimeHdrFieldValueInsert</code>.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvaluedateset">INKMimeHdrFieldValueDateSet</h4>
+<p>Sets a date value in a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueDateSet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, time_t <em><code>value</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Sets a value in the MIME field located at
+ <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code> to the date
+ <code><em class="replaceable"><code>value</code>. All values are stored as
+ strings within the MIME field. <code>INKMimeHdrFieldValueDateSet</code> simply
+ formats the date into a string and then calls
+ <code>INKMimeHdrFieldValueStringSet</code>.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvaluedelete">INKMimeHdrFieldValueDelete</h4>
+<p>Deletes a specified value from a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldVcoalueDelete (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>idx</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Removes and deletes a value from the MIME field located at
+ <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ which value should be deleted. If
+ <code><em class="replaceable"><code>idx</code> is not between <code>0</code> and
+ <code>INKMimeHdrFieldValuesCount``(``<em class="replaceable"><code>bufp, hdr, field``) - 1</code>,
+ then no operation is performed.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvalueintget">INKMimeHdrFieldValueIntGet</h4>
+<p>Gets an integer field value in a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueIntGet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>idx</code></em>, int
+ *<em><code>value</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Retrieves an integer value from within the MIME field located
+ at <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ which value within the field to retrieve. The fields are numbered
+ from <code>0</code> to
+ <code>INKMimeHdrFieldValuesCount``(``<em class="replaceable"><code>bufp, hdr, field``) - 1</code>.
+ If <code><em class="replaceable"><code>idx</code> does not lie within that
+ range, then <code>INKMimeHdrFieldValueIntGet</code> returns <code>(int) 0</code>.</p>
+<p>~ All values are stored as strings within the MIME field;
+ <code>INKMimeHdrFieldValueIntGet</code> parses the string
+ <code><em class="replaceable"><code>value</code> to return an integer.</p>
+<p><strong>Returns</strong>
+ ~ The integer value from the specified MIME field.</p>
+<div class="codehilite"><pre><span class="sb">`INK_SUCCESS`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">API</span> <span class="n">is</span> <span class="n">called</span> <span class="n">successfully</span><span class="o">.</span>
+
+<span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvalueintinsert">INKMimeHdrFieldValueIntInsert</h4>
+<p>Inserts an integer value into a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueIntInsert (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>value</code></em>, int
+ <em><code>idx</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Inserts the integer <code><em class="replaceable"><code>value</code> into
+ the MIME field located at <code><em class="replaceable"><code>field</code>
+ within the marshal buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ where the inserted value should be placed with respect to the other
+ values already in the MIME field. If
+ <code><em class="replaceable"><code>idx</code> is <code>0</code>, then the value is
+ prepended to the list of values in the field. Increasing values of
+ <code><em class="replaceable"><code>idx</code> places the value farther down
+ the list of values. If <code><em class="replaceable"><code>idx</code> is <code>-1</code>,
+ then the <code><em class="replaceable"><code>value</code> is appended to the
+ list of values. Normal usage is to specify <code>-1</code> for
+ <code><em class="replaceable"><code>idx</code> so that the value is appended
+ to the list of values.</p>
+<p>~ All values are stored as strings within the MIME field.
+ <code>INKMimeHdrFieldValueIntInsert</code> simply formats the integer into a
+ string and then calls <code>INKMimeHdrFieldValueInsert</code>.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvalueintset">INKMimeHdrFieldValueIntSet</h4>
+<p>Sets an integer value within a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueIntSet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>idx</code></em>, int
+ <em><code>value</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Sets a value in the MIME field located at
+ <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ which value in the field to change. If
+ <code><em class="replaceable"><code>idx</code> is not between <code>0</code> and
+ <code>INKMimeHdrFieldValuesCount (``<em class="replaceable"><code>bufp, hdr, field``) - 1</code>,
+ then no operation is performed.</p>
+<p>~ All values are stored as strings within the MIME field.
+ <code>INKMimeHdrFieldValueIntSet</code> simply formats the integer into a
+ string and then calls <code>INKMimeHdrFieldValueSet</code>.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvaluestringget">INKMimeHdrFieldValueStringGet</h4>
+<p>Gets a specified field value from a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueStringGet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>idx</code></em>, const char
+ **<em><code>value</code></em>, int *<em><code>value_len</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Retrieves a string <code><em class="replaceable"><code>value</code> from
+ within the MIME <code><em class="replaceable"><code>field</code> within the
+ marshal buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ which field to retrieve. The fields are numbered from <code>0</code> to
+ <code>INKMimeHdrFieldValuesCount``(``<em class="replaceable"><code>bufp, hdr, field``) - 1</code>.
+ If <code><em class="replaceable"><code>idx</code> does not lie within that
+ range, then <code>NULL</code> is returned.</p>
+<p>~ The length of the returned string is placed in the
+ <code><em class="replaceable"><code>value_len</code> argument. If
+ <code><em class="replaceable"><code>value_len</code> is <code>NULL</code>, then no
+ attempt is made to dereference it.</p>
+<p><strong>Returns</strong>
+ ~ A pointer to the specified field
+ <code><em class="replaceable"><code>value</code> in the MIME header. Release
+ with a call to <code>INKHandleStringRelease</code>.</p>
+<div class="codehilite"><pre><span class="sb">`INK_SUCCESS`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">API</span> <span class="n">is</span> <span class="n">called</span> <span class="n">successfully</span><span class="o">.</span>
+
+<span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvaluestringinsert">INKMimeHdrFieldValueStringInsert</h4>
+<p>Inserts a value into a specified location within a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueStringInsert (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>idx</code></em>, const char
+ *<em><code>value</code></em>, int <em><code>length</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Inserts the string <code><em class="replaceable"><code>value</code> into
+ the MIME field located at <code><em class="replaceable"><code>field</code>
+ within the marshal buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ If <code><em class="replaceable"><code>len</code> is <code>-1</code>, then
+ <code>INKMimeHdrFieldValueStringInsert</code> assumes that
+ <code><em class="replaceable"><code>value</code> is null-terminated.
+ Otherwise, the length of the string
+ <code><em class="replaceable"><code>value</code> is taken to be
+ <code><em class="replaceable"><code>length</code>.</p>
+<p>~ <code>INKMimeHdrFieldValueStringInsert</code> copies the string to within
+ <code><em class="replaceable"><code>bufp</code>, so it is okay to modify or
+ delete <code><em class="replaceable"><code>value</code> after calling
+ <code>INKMimeHdrFieldValueStringSet</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ where the inserted value should be placed with respect to the other
+ values already in the MIME field. If
+ <code><em class="replaceable"><code>idx</code> is <code>0</code>, then
+ <code>INKMimeHdrFieldValueStringInsert</code> prepends the value to the list
+ of values in the field. Increasing values of
+ <code><em class="replaceable"><code>idx</code> place the value farther down
+ the list of values. If <code><em class="replaceable"><code>idx</code> is<code>-1</code>,
+ then <code>INKMimeHdrFieldValueStringInsert</code> appends the value to the
+ list of values. Normal usage is to specify<code>-1</code> for <code>idx</code> so that
+ the value is appended to the list of values.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvaluestringset">INKMimeHdrFieldValueStringSet</h4>
+<p>Sets a value in a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueStringSet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>idx</code></em>, const char
+ *<em><code>value</code></em>, int <em><code>len</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Sets a value in the MIME field located at
+ <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code> to the string
+ <code><em class="replaceable"><code>value</code>.</p>
+<p>~ If <code><em class="replaceable"><code>len</code> is <code>-1</code>, then it is
+ assumed that <code><em class="replaceable"><code>value</code> is
+ null-terminated. Otherwise, the length of the string
+ <code><em class="replaceable"><code>value</code> is taken to be
+ <code><em class="replaceable"><code>len</code>.</p>
+<p>~ The string is copied to within
+ <code><em class="replaceable"><code>bufp</code>, so it is okay to modify or
+ delete <code><em class="replaceable"><code>value</code> after calling
+ <code>INKMimeHdrFieldValueStringSet</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ which value in the field to change. If
+ <code><em class="replaceable"><code>idx</code> is not between <code>0</code> and
+ <code>INKMimeHdrFieldValuesCount</code>
+ <code>(``<em class="replaceable"><code>bufp, hdr, field``) - 1</code>, then no
+ operation will be performed. If <code><em class="replaceable"><code>idx</code>
+ is set to <code>-1</code>, then all the MIME field values are returned.</p>
+<p><strong>Example</strong>
+ ~ Suppose the MIME field is <code>MyField: value1</code>,<code>value2</code>, <code>value3</code>.
+ If <code>INKMimeHdrFieldGet</code> is called with
+ <code><em class="replaceable"><code>idx</code> set to <code>-1</code>, then it will
+ return a pointer to "<code>value1</code>, <code>value2</code>, <code>value3</code>".</p>
+<div class="codehilite"><pre><span class="o">!</span><span class="p">[[</span><span class="n">Note</span><span class="p">]](</span><span class="n">images</span><span class="sr">/docbook/</span><span class="n">note</span><span class="o">.</span><span class="n">png</span><span class="p">)</span>
+<span class="n">Note</span>
+<span class="n">As</span> <span class="n">with</span> <span class="n">other</span> <span class="n">MIME</span> <span class="n">header</span> <span class="n">manipulation</span> <span class="n">APIs</span><span class="p">,</span> <span class="n">the</span> <span class="n">string</span> <span class="n">is</span> <span class="ow">not</span>
+<span class="n">null</span><span class="o">-</span><span class="n">terminated</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvalueuintget">INKMimeHdrFieldValueUintGet</h4>
+<p>Gets an unsigned integer field value in a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueUintGet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>idx</code></em>, unsigned int
+ *<em><code>value</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Retrieves an unsigned integer
+ <code><em class="replaceable"><code>value</code> from within the MIME field
+ located at <code><em class="replaceable"><code>field</code> within the marshal
+ buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ which field to retrieve. The fields are numbered from <code>0</code> to
+ <code>INKMimeHdrFieldValuesCount</code>
+ <code>(``<em class="replaceable"><code>bufp, hdr, field``) - 1</code>.
+ If <code><em class="replaceable"><code>idx</code> does not lie within that
+ range, then <code>INKMimeHdrFieldValueGetUnit</code> returns
+ <code>(unsigned int) 0</code>.</p>
+<p>~ All values are stored as strings within the MIME field.
+ <code>INKMimeHdrFieldValueUintGet</code> parses the string
+ <code><em class="replaceable"><code>value</code> to return an unsigned
+ integer.</p>
+<div class="codehilite"><pre><span class="n">It</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">possible</span> <span class="n">to</span> <span class="n">determine</span> <span class="k">if</span> <span class="sb">`INKMimeHdrFieldValueUintGet`</span> <span class="n">is</span>
+<span class="n">returning</span> <span class="n">an</span> <span class="n">unsigned</span> <span class="sb">`int`</span> <span class="n">value</span> <span class="n">in</span> <span class="n">error</span><span class="o">.</span> <span class="n">If</span> <span class="n">you</span> <span class="n">need</span> <span class="n">to</span> <span class="n">check</span>
+<span class="k">for</span> <span class="n">errors</span> <span class="n">in</span> <span class="n">MIME</span> <span class="n">header</span> <span class="n">field</span> <span class="nb">values</span><span class="p">,</span> <span class="k">then</span> <span class="n">you</span> <span class="n">can</span> <span class="n">fetch</span> <span class="n">the</span>
+<span class="n">header</span> <span class="n">as</span> <span class="n">a</span> <span class="n">string</span> <span class="ow">and</span> <span class="n">examine</span> <span class="n">it</span> <span class="p">(</span><span class="n">see</span> <span class="n">the</span> <span class="n">example</span> <span class="n">below</span><span class="p">)</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ The unsigned integer <code>value</code> from the specified MIME field.</p>
+<div class="codehilite"><pre><span class="sb">`INK_SUCCESS`</span> <span class="k">if</span> <span class="n">the</span> <span class="n">API</span> <span class="n">is</span> <span class="n">called</span> <span class="n">successfully</span><span class="o">.</span>
+
+<span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Example</strong>
+ ~ 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>
+<p>~ static void
+ handle_string (INKHttpTxn txnp, INKCont contp) {
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKMLoc field;
+ int len;
+ char<em> output_string;
+ const char</em> value;
+ /<em> Fetch the transaction's client request header into a marshal buffer. </em>/
+ if (!INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ INKError ("couldn't retrieve client request headern");
+ goto done;
+ }
+ field=INKMimeHdrFieldFind(bufp, hdr_loc,
+ INK_MIME_FIELD_CONTENT_LENGTH);</p>
+<div class="codehilite"><pre> <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">field</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKError</span> <span class="p">(</span><span class="s">"Content-Length field not found.\n"</span><span class="p">);</span>
+ <span class="n">INKHandleMLocRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">);</span>
+ <span class="nb">goto</span> <span class="n">done</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="o">/*</span> <span class="n">Obtain</span> <span class="n">the</span> <span class="n">value</span> <span class="n">of</span> <span class="n">the</span> <span class="n">content</span> <span class="nb">length</span> <span class="p">(</span><span class="n">normally</span> <span class="n">an</span>
+ <span class="o">*</span> <span class="n">unsigned</span> <span class="nb">int</span><span class="p">)</span> <span class="n">as</span> <span class="n">a</span> <span class="n">string</span><span class="o">.</span> <span class="o">*/</span>
+ <span class="n">value</span><span class="o">=</span><span class="n">INKMimeHdrFieldValueGet</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">,</span> <span class="n">field</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="o">&</span><span class="n">len</span><span class="p">);</span>
+
+ <span class="k">if</span> <span class="p">((</span><span class="o">!</span><span class="n">value</span><span class="p">)</span> <span class="o">||</span> <span class="p">(</span><span class="n">len</span><span class="o"><=</span><span class="mi">0</span><span class="p">))}</span>
+ <span class="n">INKHandleMLocRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">,</span> <span class="n">field</span><span class="p">);</span>
+ <span class="n">INKHandleMLocRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">hdr_loc</span><span class="p">);</span>
+ <span class="nb">goto</span> <span class="n">done</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="sr">/* Allocate the string with an extra byte for the string terminator. */</span>
+ <span class="n">output_string</span> <span class="o">=</span> <span class="p">(</span><span class="n">char</span><span class="o">*</span><span class="p">)</span> <span class="n">INKmalloc</span><span class="p">(</span><span class="n">len</span> <span class="o">+</span> <span class="mi">1</span><span class="p">);</span>
+
+ <span class="sr">/* Copy the value. */</span>
+ <span class="n">strncpy</span> <span class="p">(</span><span class="n">output_string</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">len</span><span class="p">);</span>
+
+ <span class="sr">/* Terminate the string */</span>
+ <span class="n">output_string</span><span class="p">[</span><span class="n">len</span><span class="p">]</span> <span class="o">=</span> <span class="s">'\0'</span><span class="p">;</span>
+ <span class="o">/*</span> <span class="n">Now</span> <span class="n">that</span> <span class="n">you</span> <span class="n">have</span> <span class="n">the</span> <span class="n">MIME</span> <span class="n">fields</span> <span class="n">as</span> <span class="n">a</span> <span class="n">string</span><span class="p">,</span> <span class="n">you</span> <span class="n">can</span> <span class="k">do</span>
+ <span class="n">whatever</span> <span class="n">you</span> <span class="n">want</span> <span class="n">with</span> <span class="n">it</span><span class="o">.</span> <span class="n">For</span> <span class="n">example:</span> <span class="n">you</span> <span class="n">can</span> <span class="k">print</span> <span class="n">it</span> <span class="ow">or</span>
+ <span class="n">make</span> <span class="n">sure</span> <span class="n">it</span><span class="err">'</span><span class="n">s</span> <span class="n">an</span> <span class="n">unsigned</span> <span class="n">integer</span><span class="p">,</span> <span class="n">either</span> <span class="n">by</span> <span class="n">using</span> <span class="n">the</span>
+ <span class="n">atol</span> <span class="n">C</span> <span class="n">function</span> <span class="ow">or</span> <span class="n">by</span> <span class="n">scanning</span> <span class="nb">each</span> <span class="n">ASCII</span> <span class="n">character</span><span class="o">.</span> <span class="o">*/</span>
+ <span class="n">INKDebug</span><span class="p">(</span><span class="s">"my-plugin"</span><span class="p">,</span> <span class="s">"%s"</span><span class="p">,</span> <span class="n">output_string</span><span class="p">);</span>
+
+ <span class="sr">/* Release handles and allocated memory. */</span>
+ <span class="n">INKHandleStringRelease</span> <span class="p">(</span><span class="n">bufp</span><span class="p">,</span> <span class="n">field</span><span class="p">,</span> <span class="n">value</span><span class="p">);</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvalueuintinsert">INKMimeHdrFieldValueUintInsert</h4>
+<p>Inserts an unsigned integer value into a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueUintInsert (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, unsigned int <em><code>value</code></em>, int
+ <em><code>idx</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Inserts the unsigned integer
+ <code><em class="replaceable"><code>value</code> into the MIME field located
+ at <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ where the inserted value should be placed with respect to other
+ values already in the MIME field.
+ If<code><em class="replaceable"><code> idx</code> is <code>0</code>, then the value is
+ prepended to the list of values in the field. Increasing values of
+ <code><em class="replaceable"><code>idx</code> simply places the value farther
+ down on the list of values. If <code><em class="replaceable"><code>idx</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><em class="replaceable"><code>idx</code> so
+ that the value will be appended to the existing list of values.</p>
+<p>~ All values are stored as strings within the MIME field.
+ <code>INKMimeHdrFieldValueUintInsert</code> simply formats the unsigned
+ integer into a string and then calls
+ <code>INKMimeHdrFieldValueStringInsert</code>.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvalueuintset">INKMimeHdrFieldValueUintSet</h4>
+<p>Sets a value in a MIME field to a specified unsigned integer.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValueUintSet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>, int <em><code>idx</code></em>, unsigned int
+ <em><code>value</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Sets a value in the MIME field located at
+ <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code> to the unsigned integer
+ <code><em class="replaceable"><code>value</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ which value in the field to change. If
+ <code><em class="replaceable"><code>idx</code> is not between <code>0</code> and
+ <code>INKMimeHdrFieldValuesCount</code>
+ <code>(``<em class="replaceable"><code>bufp, hdr, field``) - 1</code>, then no
+ operation is performed.</p>
+<p>~ All values are stored as strings within the MIME field.
+ <code>INKMimeHdrFieldValueUintSet</code> simply formats the unsigned integer
+ into a string and then calls <code>INKMimeHdrFieldValueStringSet</code>.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the API is called successfully.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span> <span class="k">while</span> <span class="n">calling</span> <span class="n">the</span> <span class="n">API</span> <span class="ow">or</span> <span class="k">if</span> <span class="n">an</span>
+<span class="n">argument</span> <span class="n">is</span> <span class="n">invalid</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvaluesclear">INKMimeHdrFieldValuesClear</h4>
+<p>Clears all values in a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldValuesClear (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr</code></em>, INKMLoc <em><code>field</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Removes and destroys all values within the MIME field located
+ at <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<div class="codehilite"><pre><span class="n">Make</span> <span class="n">sure</span> <span class="n">you</span> <span class="n">release</span> <span class="n">any</span> <span class="n">corresponding</span> <span class="sb">`INKMLoc`</span> <span class="ow">or</span> <span class="n">string</span> <span class="n">handles</span>
+<span class="n">via</span> <span class="sb">`INKHandleMLocRelease`</span> <span class="ow">or</span> <span class="sb">`INKHandleStringRelease`</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldvaluescount">INKMimeHdrFieldValuesCount</h4>
+<p>Counts the values in a MIME field.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int INKMimeHdrFieldValuesCount (INKMBuffer <span class="replaceable">bufp</span>, INKMLoc <span class="replaceable">hdr</span>, INKMLoc <span class="replaceable">field</span>)</code></p>
+<p><strong>Description</strong>
+ ~ Retrieves a count of the number of values in the MIME field
+ located at <code><em class="replaceable"><code>field</code> within the marshal
+ buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<p><strong>Returns</strong>
+ ~ The number of values in the specified MIME field.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrclone">INKMimeHdrClone</h4>
+<p>Copies a MIME header and returns the location of the copied
+header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMLoc INKMimeHdrClone(INKMBuffer <em class="replaceable"><code>dest_bufp</code>,
+ INKMBuffer <em><code>src_bufp</code></em>, INKMLoc <em><code>src_hdr_loc</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Copies the contents of the MIME header located at
+ <code><em class="replaceable"><code> src_hdr_loc</code> within the marshal
+ buffer <code><em class="replaceable"><code>src_bufp</code> to the marshal
+ buffer <code><em class="replaceable"><code>dest_bufp</code>.</p>
+<p><strong>Returns</strong>
+ ~ The <code>INKMLoc</code> location of the copied header. Release the
+ returned handle with a call to <code>INKHandleMLocRelease</code>.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrcopy">INKMimeHdrCopy</h4>
+<p>Copies a MIME header to a specified MIME header location.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrCopy (INKMBuffer <em class="replaceable"><code>dest_bufp</code>,
+ INKMLoc <em><code>dest_hdr_loc</code></em>, INKMBuffer <em><code>src_bufp</code></em>, INKMLoc
+ <em><code>src_hdr_loc</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Copies the contents of the MIME header located at
+ <code><em class="replaceable"><code> src_hdr_loc</code> within the marshal
+ buffer <code><em class="replaceable"><code>src_bufp</code> to the MIME header
+ located at <code><em class="replaceable"><code>dest_hdr_loc</code> within the
+ marshal buffer <code><em class="replaceable"><code>dest_bufp</code>.</p>
+<p>~ <code>INKMimeHdrCopy</code> works correctly even if
+ <code><em class="replaceable"><code>src_bufp</code> and
+ <code><em class="replaceable"><code>dest_bufp</code> point to different
+ marshal buffers.</p>
+<div class="codehilite"><pre><span class="o">!</span><span class="p">[[</span><span class="n">Note</span><span class="p">]](</span><span class="n">images</span><span class="sr">/docbook/</span><span class="n">note</span><span class="o">.</span><span class="n">png</span><span class="p">)</span>
+<span class="n">Note</span>
+<span class="n">Make</span> <span class="n">sure</span> <span class="n">the</span> <span class="n">destination</span> <span class="n">marshal</span> <span class="n">buffer</span> <span class="ow">and</span> <span class="n">the</span> <span class="n">destination</span> <span class="n">MIME</span>
+<span class="n">header</span> <span class="n">location</span> <span class="n">have</span> <span class="n">been</span> <span class="n">created</span> <span class="n">before</span> <span class="n">copying</span> <span class="p">(</span><span class="n">see</span> <span class="n">the</span> <span class="n">example</span>
+<span class="n">below</span><span class="p">)</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Example</strong>
+ ~ static void
+ copyResponseMimeHdr (INKCont pCont, INKHttpTxn pTxn)
+ {
+ INKMBuffer respHdrBuf, tmpBuf;
+ INKMLoc respHttpHdrLoc, tmpMimeHdrLoc; </p>
+<div class="codehilite"><pre> <span class="k">if</span> <span class="p">(</span> <span class="o">!</span><span class="n">INKHttpTxnClientRespGet</span> <span class="p">(</span><span class="n">pTxn</span><span class="p">,</span> <span class="o">&</span><span class="n">respHdrBuf</span><span class="p">,</span> <span class="o">&</span><span class="n">respHttpHdrLoc</span><span class="p">)</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="n">INKError</span> <span class="p">(</span><span class="s">"couldn't retrieve client response header\n"</span><span class="p">);</span>
+ <span class="n">INKHandleMLocRelease</span> <span class="p">(</span><span class="n">respHdrBuf</span><span class="p">,</span> <span class="n">INK_NULL_MLOC</span><span class="p">,</span>
+ <span class="n">respHttpHdrLoc</span><span class="p">);</span>
+ <span class="nb">goto</span> <span class="n">done</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="n">tmpBuf</span> <span class="o">=</span> <span class="n">INKMBufferCreate</span> <span class="p">();</span>
+ <span class="n">tmpMimeHdrLoc</span> <span class="o">=</span> <span class="n">INKMimeHdrCreate</span><span class="p">(</span><span class="n">tmpBuf</span><span class="p">);</span>
+
+ <span class="n">INKMimeHdrCopy</span><span class="p">(</span><span class="n">tmpBuf</span><span class="p">,</span> <span class="n">tmpMimeHdrLoc</span><span class="p">,</span> <span class="n">respHdrBuf</span><span class="p">,</span> <span class="n">respHttpHdrLoc</span><span class="p">);</span>
+
+ <span class="n">INKHandleMLocRelease</span> <span class="p">(</span><span class="n">tmpBuf</span><span class="p">,</span> <span class="n">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">tmpMimeHdrLoc</span><span class="p">);</span>
+ <span class="n">INKHandleMLocRelease</span> <span class="p">(</span><span class="n">respHdrBuf</span><span class="p">,</span> <span class="n">INK_NULL_MLOC</span><span class="p">,</span> <span class="n">respHttpHdrLoc</span><span class="p">);</span>
+
+ <span class="n">INKMBufferDestroy</span><span class="p">(</span><span class="n">tmpBuf</span><span class="p">);</span>
+
+ <span class="n">done:</span>
+ <span class="n">INKHttpTxnReenable</span><span class="p">(</span><span class="n">pTxn</span><span class="p">,</span> <span class="n">INK_EVENT_HTTP_CONTINUE</span><span class="p">);</span> <span class="p">}</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrcreate">INKMimeHdrCreate</h4>
+<p>Creates a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMLoc INKMimeHdrCreate (INKMBuffer <em class="replaceable"><code>bufp</code>)</p>
+<p><strong>Description</strong>
+ ~ Creates a new MIME header within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p><strong>Returns</strong>
+ ~ Location of the newly-created MIME header. Release with a call
+ to <code>INKHandleMLocRelease</code>.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrdestroy">INKMimeHdrDestroy</h4>
+<p>Destroys a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrDestroy (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Destroys the MIME header located at
+ <code><em class="replaceable"><code>hdr_loc</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<div class="codehilite"><pre><span class="n">Release</span> <span class="n">the</span> <span class="sb">`INKMLoc`</span> <span class="n">handle</span>
+<span class="sb">`<em class="replaceable"><code>hdr_loc`</span> <span class="n">with</span> <span class="n">a</span> <span class="n">call</span> <span class="n">to</span>
+<span class="sb">`INKHandleMLocRelease`</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldfind">INKMimeHdrFieldFind</h4>
+<p>Finds specific fields in a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMLoc INKMimeHdrFieldFind (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>loc</code></em>, const char* <em><code>name</code></em>, int <em><code>length</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Retrieves a MIME field from within the MIME header located at
+ <code><em class="replaceable"><code>loc</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The <code><em class="replaceable"><code>name</code> and
+ <code><em class="replaceable"><code>length</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><em class="replaceable"><code>name</code>. The
+ <code><em class="replaceable"><code>length</code> parameter specifies the
+ length of the string that <code><em class="replaceable"><code>name</code>
+ points to. If <code><em class="replaceable"><code>length</code> is <code>-1</code>, then
+ <code><em class="replaceable"><code> name</code> is assumed to be
+ null-terminated. If the requested field cannot be found, then <code>0</code>
+ is returned.</p>
+<p><strong>Returns</strong>
+ ~ The location of the retrieved MIME header. Release with a call
+ to <code>INKHandleMLocRelease</code>.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldget">INKMimeHdrFieldGet</h4>
+<p>Gets a field in a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMLoc INKMimeHdrFieldGet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, int <em><code>idx</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Retrieves a MIME field from within the MIME header located at
+ <code><em class="replaceable"><code>hdr_loc</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code>.</p>
+<p>~ The <code><em class="replaceable"><code>idx</code> parameter specifies
+ which field to retrieve. The fields are numbered from <code>0</code> to
+ <code>INKMimeHdrFieldsCount</code>
+ <code>(``<em class="replaceable"><code>bufp, hdr_loc``) - 1</code>. If
+ <code><em class="replaceable"><code>idx</code> does not lie within that range,
+ then <code>0</code> is returned.</p>
+<p><strong>Returns</strong>
+ ~ The location of the MIME field from within the MIME header.
+ Release with a call to <code>INKHandleMLocRelease</code>.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR_PTR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldremove">INKMimeHdrFieldRemove</h4>
+<p>Removes a field in a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldRemove (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>, INKMLoc <em><code>field</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Removes the MIME header located at
+ <code><em class="replaceable"><code>field</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code> from the MIME header located
+ at <code><em class="replaceable"><code>hdr_loc</code> within the marshal
+ buffer <code><em class="replaceable"><code>bufp</code>. If the specified field
+ cannot be found in the list of fields associated with the header,
+ then nothing is done.</p>
+<div class="codehilite"><pre><span class="n">After</span> <span class="n">the</span> <span class="n">call</span> <span class="n">to</span> <span class="sb">`INKMimeHdrFieldDestroy`</span><span class="p">,</span> <span class="n">you</span> <span class="n">must</span> <span class="n">release</span> <span class="n">the</span>
+<span class="sb">`INKMLoc`</span> <span class="n">handle</span> <span class="n">field</span> <span class="n">with</span> <span class="n">a</span> <span class="n">call</span> <span class="n">to</span> <span class="sb">`INKHandleMLocRelease`</span><span class="o">.</span>
+
+<span class="o">!</span><span class="p">[[</span><span class="n">Note</span><span class="p">]](</span><span class="n">images</span><span class="sr">/docbook/</span><span class="n">note</span><span class="o">.</span><span class="n">png</span><span class="p">)</span>
+<span class="n">Note</span>
+<span class="n">Removing</span> <span class="n">the</span> <span class="n">MIME</span> <span class="n">field</span> <span class="n">doesn</span><span class="err">'</span><span class="n">t</span> <span class="n">destroy</span> <span class="n">the</span> <span class="n">field</span> <span class="o">-</span> <span class="n">it</span> <span class="n">only</span>
+<span class="n">detaches</span> <span class="n">it</span> <span class="ow">and</span> <span class="n">hides</span> <span class="n">it</span> <span class="n">from</span> <span class="n">the</span> <span class="n">printed</span> <span class="n">output</span><span class="o">.</span><span class="n">The</span> <span class="n">field</span> <span class="n">can</span> <span class="n">be</span>
+<span class="n">reattached</span> <span class="n">by</span> <span class="n">calling</span> <span class="sb">`INKMimeHdrFieldAppend`</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldsclear">INKMimeHdrFieldsClear</h4>
+<p>Clears all the fields in a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMimeHdrFieldsClear (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Removes and destroys all MIME fields in the MIME header located
+ at <code><em class="replaceable"><code>hdr_loc</code> within the marshal
+ buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<div class="codehilite"><pre><span class="n">Make</span> <span class="n">sure</span> <span class="n">that</span> <span class="n">you</span> <span class="n">release</span> <span class="n">any</span> <span class="n">corresponding</span> <span class="sb">`INKMLoc`</span> <span class="ow">or</span> <span class="n">string</span>
+<span class="n">handles</span> <span class="n">using</span> <span class="sb">`INKHandleMLocRelease`</span> <span class="ow">or</span> <span class="sb">`INKHandleStringRelease`</span><span class="o">.</span>
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if successful.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrfieldscount">INKMimeHdrFieldsCount</h4>
+<p>Counts the fields in a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int INKMimeHdrFieldsCount (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Obtains a count of the number of MIME fields within the MIME
+ header located at <code><em class="replaceable"><code>hdr_loc</code> within
+ the marshal buffer <code><em class="replaceable"><code>bufp</code>.</p>
+<p><strong>Returns</strong>
+ ~ The number of fields within the specified MIME header.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrlengthget">INKMimeHdrLengthGet</h4>
+<p>Gets the length of a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int INKMimeHdrLengthGet (INKMBuffer <em class="replaceable"><code>bufp</code>,
+ INKMLoc <em><code>hdr_loc</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Calculates the length of the MIME header located at
+ <code><em class="replaceable"><code>hdr_loc</code> within the marshal buffer
+ <code><em class="replaceable"><code>bufp</code> if it was returned as a
+ string. This is the length of the MIME header in its unparsed
+ form.</p>
+<p><strong>Returns</strong>
+ ~ The length of the specified MIME header.</p>
+<div class="codehilite"><pre><span class="sb">`INK_ERROR`</span> <span class="k">if</span> <span class="n">an</span> <span class="n">error</span> <span class="n">occurs</span><span class="o">.</span>
+</pre></div>
+
+
+<h4 id="inkmimehdrparse">INKMimeHdrParse</h4>
+<p>Parses a MIME header.</p>
+<p><strong>Prototype</strong>
+ ~ <code>int INKMimeHdrParse (INKMimeParser <em class="replaceable"><code>parser</code>,
+ INKMBuffer <em><code>bufp</code></em>, INKMLoc <em><code>hdr_loc</code></em>, const char **<em><code>start</code></em>,
+ const char *<em><code>end</code></em>)</p>
+<p><strong>Description</strong>
+ ~ Parses a MIME header. The MIME header must have already been
+ allocated, and both <code><em class="replaceable"><code>bufp</code> and
+ <code><em class="replaceable"><code>hdr_loc</code> must point within that
+ header.</p>
+<p>~ The <code><em class="replaceable"><code>start</code> argument points to
+ the current position of the buffer being parsed and the
+ <code><em class="replaceable"><code>end</code> argument points to one byte
+ after the end of the buffer. Upon return,
+ <code><em class="replaceable"><code>start</code> is modified to point past the
+ last character parsed.</p>
+<p>~ It is possible to parse a MIME header a single byte at a time
+ using repeated calls to <code>INKMimeHdrParse</code>. As long as an error does
+ not occur, the <code>INKMimeHdrParse</code> function consumes that single byte
+ and asks for more.</p>
+<p><strong>Returns</strong>
+ ~ <code>INK_PARSE_ERROR</code> if an error occurs.</p>
+<div class="codehilite"><pre><span class="sb">`INK_PARSE_DONE`</span> <span class="n">when</span> <span class="n">a</span> <span class="sb">`\r\n\r\n`</span> <span class="n">pattern</span> <span class="n">is</span> <span class="n">encountered</span><span class="p">,</span>
+<span class="n">indicating</span> <span class="n">the</span> <span class="n">end</span> <span class="n">of</span> <span class="n">the</span> <span class="n">header</span><span class="o">.</span>
+</pre></div>
+
+
+<p>~ <code>INK_PARSE_CONT</code> if parsing of the header stopped because the
+ end of the buffer was reached.</p>
+<h4 id="inkmimeparserclear">INKMimeParserClear</h4>
+<p>Clears a MIME header parser so it can be reused.</p>
+<p><strong>Prototype</strong>
[... 60 lines stripped ...]