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 [15/21] - in
/websites/staging/trafficserver/trunk/content/docs/trunk: admin/ sdk/
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MIMEHeaders.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MIMEHeaders.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MIMEHeaders.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MIMEHeaders.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,365 @@
<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="URLs">Prev</a> - URLs
+Chapter 11. Mutex Guide - <a href="MutexGuide">Next</a></p>
+<h2 id="mime_headers">MIME Headers</h2>
+<p>The Traffic Server <strong>MIME header functions</strong> enable you to retrieve
+and modify information about HTTP MIME fields.</p>
+<p>An HTTP request or response consists of a header, body, and
+trailer. The <strong>HTTP</strong> <strong>header</strong> contains a request (or response)
+line and a MIME header. A <strong>MIME</strong> <strong>header</strong> is composed of zero
+or more MIME fields. A <strong>MIME</strong> <strong>field</strong> is composed of a field
+name, a colon, and zero or more field values (values in a field are
+separated by commas).</p>
+<p>In the example below: <code>Foo</code> is the MIME field name, <code>bar</code> is the
+first MIME field value, and <code>car</code> is the second MIME field value.</p>
+<div class="codehilite"><pre><span class="err">Foo:</span> <span class="err">bar,</span> <span class="err">car</span>
+</pre></div>
+
+
+<p>The following example is an augmented <strong>Backus-Naur Form</strong> (BNF)
+for the form of a MIME header - it specifies exactly what was
+described above. A <strong>header</strong> consists of zero or more <strong>fields</strong>
+that contain a name, separating colon, and zero or more values. A
+<strong>name</strong> or <strong>value</strong> is simply a string of tokens that is
+potentially zero length; a <strong>token</strong> is any character except
+certain control characters and separators (such as colons). For the
+purpose of retrieving a field, field names are not case-sensitive;
+therefore, the field names <code>Foo</code>, <code>foo</code> and <code>fOO</code> are all
+equivalent.</p>
+<div class="codehilite"><pre><span class="n">MIME</span><span class="o">-</span><span class="n">header</span> <span class="o">=</span> <span class="o">*</span><span class="n">MIME</span><span class="o">-</span><span class="n">field</span>
+<span class="n">MIME</span><span class="o">-</span><span class="n">field</span> <span class="o">=</span> <span class="n">field</span><span class="o">-</span><span class="n">name</span> <span class="s">":"</span> <span class="c1">#field-value</span>
+<span class="n">field</span><span class="o">-</span><span class="n">name</span> <span class="o">=</span> <span class="o">*</span><span class="n">token</span>
+<span class="n">field</span><span class="o">-</span><span class="n">value</span> <span class="o">=</span> <span class="o">*</span><span class="n">token</span>
+</pre></div>
+
+
+<p>The MIME header data structure is a parsed version of a standard
+Internet MIME header. The MIME header data structure is similar to
+the URL data structure (see <a href="URLs" title="URLs">URLs</a>). The actual
+data is stored in a marshal buffer; the MIME header functions
+operate on a marshal buffer and a location (<code>INKMLoc</code>) within the
+buffer.</p>
+<p>After a call to <code>INKMimeHdrFieldDestroy</code>, <code>INKMimeHdrFieldRemove</code>,
+or <code>INKUrlDestroy</code> is made, you must deallocate the <code>INKMLoc</code>
+handle with a call to <code>INKHandleMLocRelease</code>. You do not need to
+deallocate a <code>NULL</code> handles. For example: if you call
+<code>INKMimeHdrFieldValueStringGet</code> to get the value of the content
+type field and the field does not exist, then it returns
+<code>INK_NULL_MLOC</code>. In such a case, you wouldn't need to deallocate
+the handle with a call to <code>INKHandleMLocRelease</code>.</p>
+<p>The location (<code>INKMLoc</code>) in the
+<a href="MIMEHeaders#MimeHeaderFxns">MIME header functions</a> can be
+either an HTTP header location or a MIME header location. If an
+HTTP header location is passed to these functions, then the system
+locates the MIME header associated with that HTTP header and
+executes the corresponding MIME header operations specified by the
+functions (see the example in the description of
+<a href="MimeHeadersFunctions#INKMimeHdrCopy" title="INKMimeHdrCopy"><code>INKMimeHdrCopy</code></a>).</p>
+<p><strong>Note:</strong>MIME headers may contain more than one MIME field with the
+same name. Previous versions of Traffic Server joined multiple
+fields with the same name into one field with composite values, but
+this behavior came at a performance cost and caused compatability
+issues with older clients and servers. Hence, the current version
+of Traffic Server does not coalesce duplicate fields.
+Correctly-behaving plugins should check for the presence of
+duplicate fields and iterate over the duplicate fields by using
+<code>INKMimeHdrFieldNextDup</code>.</p>
+<p>To facilitate fast comparisons and reduce storage size, Traffic
+Server defines several pre-allocated field names. These field names
+correspond to the field names in HTTP and NNTP headers.</p>
+<p><strong>Traffic Server Pre-allocated Field Names</strong>
+<strong>HTTP and NNTP Header Field Names</strong>
+<strong>Associated String Lengths</strong>
+<code>INK_MIME_FIELD_ACCEPT</code>
+"Accept"
+<code>INK_MIME_LEN_ACCEPT</code>
+<code>INK_MIME_FIELD_ACCEPT_CHARSET</code>
+"Accept-Charset"
+<code>INK_MIME_LEN_ACCEPT_CHARSET</code>
+<code>INK_MIME_FIELD_ACCEPT_ENCODING</code>
+"Accept-Encoding"
+<code>INK_MIME_LEN_ACCEPT_ENCODING</code>
+<code>INK_MIME_FIELD_ACCEPT_LANGUAGE</code>
+"Accept-Language"
+<code>INK_MIME_LEN_ACCEPT_LANGUAGE</code>
+<code>INK_MIME_FIELD_ACCEPT_RANGES</code>
+"Accept-Ranges"
+<code>INK_MIME_LEN_ACCEPT_RANGES</code>
+<code>INK_MIME_FIELD_AGE</code>
+"Age"
+<code>INK_MIME_LEN_AGE</code>
+<code>INK_MIME_FIELD_ALLOW</code>
+"Allow"
+<code>INK_MIME_LEN_ALLOW</code>
+<code>INK_MIME_FIELD_APPROVED</code>
+"Approved"
+<code>INK_MIME_LEN_APPROVED</code>
+<code>INK_MIME_FIELD_AUTHORIZATION</code>
+"Authorization"
+<code>INK_MIME_LEN_AUTHORIZATION</code>
+<code>INK_MIME_FIELD_BYTES</code>
+"Bytes"
+<code>INK_MIME_LEN_BYTES</code>
+<code>INK_MIME_FIELD_CACHE_CONTROL</code>
+"Cache-Control"
+<code>INK_MIME_LEN_CACHE_CONTROL</code>
+<code>INK_MIME_FIELD_CLIENT_IP</code>
+"Client-ip"
+<code>INK_MIME_LEN_CLIENT_IP</code>
+<code>INK_MIME_FIELD_CONNECTION</code>
+"Connection"
+<code>INK_MIME_LEN_CONNECTION</code>
+<code>INK_MIME_FIELD_CONTENT_BASE</code>
+"Content-Base"
+<code>INK_MIME_LEN_CONTENT_BASE</code>
+<code>INK_MIME_FIELD_CONTENT_ENCODING</code>
+"Content-Encoding"
+<code>INK_MIME_LEN_CONTENT_ENCODING</code>
+<code>INK_MIME_FIELD_CONTENT_LANGUAGE</code>
+"Content-Language"
+<code>INK_MIME_LEN_CONTENT_LANGUAGE</code>
+<code>INK_MIME_FIELD_CONTENT_LENGTH</code>
+"Content-Length"
+<code>INK_MIME_LEN_CONTENT_LENGTH</code>
+<code>INK_MIME_FIELD_CONTENT_LOCATION</code>
+"Content-Location"
+<code>INK_MIME_LEN_CONTENT_LOCATION</code>
+<code>INK_MIME_FIELD_CONTENT_MD5</code>
+"Content-MD5"
+<code>INK_MIME_LEN_CONTENT_MD5</code>
+<code>INK_MIME_FIELD_CONTENT_RANGE</code>
+"Content-Range"
+<code>INK_MIME_LEN_CONTENT_RANGE</code>
+<code>INK_MIME_FIELD_CONTENT_TYPE</code>
+"Content-Type"
+<code>INK_MIME_LEN_CONTENT_TYPE</code>
+<code>INK_MIME_FIELD_CONTROL</code>
+"Control"
+<code>INK_MIME_LEN_CONTROL</code>
+<code>INK_MIME_FIELD_COOKIE</code>
+"Cookie"
+<code>INK_MIME_LEN_COOKIE</code>
+<code>INK_MIME_FIELD_DATE</code>
+"Date"
+<code>INK_MIME_LEN_DATE</code>
+<code>INK_MIME_FIELD_DISTRIBUTION</code>
+"Distribution"
+<code>INK_MIME_LEN_DISTRIBUTION</code>
+<code>INK_MIME_FIELD_ETAG</code>
+"Etag"
+<code>INK_MIME_LEN_ETAG</code>
+<code>INK_MIME_FIELD_EXPECT</code>
+"Expect"
+<code>INK_MIME_LEN_EXPECT</code>
+<code>INK_MIME_FIELD_EXPIRES</code>
+"Expires"
+<code>INK_MIME_LEN_EXPIRES</code>
+<code>INK_MIME_FIELD_FOLLOWUP_TO</code>
+"Followup-To"
+<code>INK_MIME_LEN_FOLLOWUP_TO</code>
+<code>INK_MIME_FIELD_FROM</code>
+"From"
+<code>INK_MIME_LEN_FROM</code>
+<code>INK_MIME_FIELD_HOST</code>
+"Host"
+<code>INK_MIME_LEN_HOST</code>
+<code>INK_MIME_FIELD_IF_MATCH</code>
+"If-Match"
+<code>INK_MIME_LEN_IF_MATCH</code>
+<code>INK_MIME_FIELD_IF_MODIFIED_SINCE</code>
+"If-Modified-Since''
+<code>INK_MIME_LEN_IF_MODIFIED_SINCE</code>
+<code>INK_MIME_FIELD_IF_NONE_MATCH</code>
+"If-None-Match''
+<code>INK_MIME_LEN_IF_NONE_MATCH</code>
+<code>INK_MIME_FIELD_IF_RANGE</code>
+"If-Range''
+<code>INK_MIME_LEN_IF_RANGE</code>
+<code>INK_MIME_FIELD_IF_UNMODIFIED_SINCE</code>
+"If-Unmodified-Since''
+<code>INK_MIME_LEN_IF_UNMODIFIED_SINCE</code>
+<code>INK_MIME_FIELD_KEEP_ALIVE</code>
+"Keep-Alive''
+<code>INK_MIME_LEN_KEEP_ALIVE</code>
+<code>INK_MIME_FIELD_KEYWORDS</code>
+"Keywords''
+<code>INK_MIME_LEN_KEYWORDS</code>
+<code>INK_MIME_FIELD_LAST_MODIFIED</code>
+"Last-Modified''
+<code>INK_MIME_LEN_LAST_MODIFIED</code>
+<code>INK_MIME_FIELD_LINES</code>
+"Lines''
+<code>INK_MIME_LEN_LINES</code>
+<code>INK_MIME_FIELD_LOCATION</code>
+"Location''
+<code>INK_MIME_LEN_LOCATION</code>
+<code>INK_MIME_FIELD_MAX_FORWARDS</code>
+"Max-Forwards''
+<code>INK_MIME_LEN_MAX_FORWARDS</code>
+<code>INK_MIME_FIELD_MESSAGE_ID</code>
+"Message-ID''
+<code>INK_MIME_LEN_MESSAGE_ID</code>
+<code>INK_MIME_FIELD_NEWSGROUPS</code>
+"Newsgroups''
+<code>INK_MIME_LEN_NEWSGROUPS</code>
+<code>INK_MIME_FIELD_ORGANIZATION</code>
+"Organization''
+<code>INK_MIME_LEN_ORGANIZATION</code>
+<code>INK_MIME_FIELD_PATH</code>
+"Path''
+<code>INK_MIME_LEN_PATH</code>
+<code>INK_MIME_FIELD_PRAGMA</code>
+"Pragma''
+<code>INK_MIME_LEN_PRAGMA</code>
+<code>INK_MIME_FIELD_PROXY_AUTHENTICATE</code>
+"Proxy-Authenticate''
+<code>INK_MIME_LEN_PROXY_AUTHENTICATE</code>
+<code>INK_MIME_FIELD_PROXY_AUTHORIZATION</code>
+"Proxy-Authorization''
+<code>INK_MIME_LEN_PROXY_AUTHORIZATION</code>
+<code>INK_MIME_FIELD_PROXY_CONNECTION</code>
+"Proxy-Connection''
+<code>INK_MIME_LEN_PROXY_CONNECTION</code>
+<code>INK_MIME_FIELD_PUBLIC</code>
+"Public''
+<code>INK_MIME_LEN_PUBLIC</code>
+<code>INK_MIME_FIELD_RANGE</code>
+"Range''
+<code>INK_MIME_LEN_RANGE</code>
+<code>INK_MIME_FIELD_REFERENCES</code>
+"References''
+<code>INK_MIME_LEN_REFERENCES</code>
+<code>INK_MIME_FIELD_REFERER</code>
+"Referer''
+<code>INK_MIME_LEN_REFERER</code>
+<code>INK_MIME_FIELD_REPLY_TO</code>
+"Reply-To''
+<code>INK_MIME_LEN_REPLY_TO</code>
+<code>INK_MIME_FIELD_RETRY_AFTER</code>
+"Retry-After''
+<code>INK_MIME_LEN_RETRY_AFTER</code>
+<code>INK_MIME_FIELD_SENDER</code>
+"Sender''
+<code>INK_MIME_LEN_SENDER</code>
+<code>INK_MIME_FIELD_SERVER</code>
+"Server''
+<code>INK_MIME_LEN_SERVER</code>
+<code>INK_MIME_FIELD_SET_COOKIE</code>
+"Set-Cookie''
+<code>INK_MIME_LEN_SET_COOKIE</code>
+<code>INK_MIME_FIELD_SUBJECT</code>
+"Subject''
+<code>INK_MIME_LEN_SUBJECTINK_MIME_LEN_SUBJECT</code>
+<code>INK_MIME_FIELD_SUMMARY</code>
+"Summary''
+<code>INK_MIME_LEN_SUMMARY</code>
+<code>INK_MIME_FIELD_TE</code>
+"TE''
+<code>INK_MIME_LEN_TE</code>
+<code>INK_MIME_FIELD_TRANSFER_ENCODING</code>
+"Transfer-Encoding''
+<code>INK_MIME_LEN_TRANSFER_ENCODING</code>
+<code>INK_MIME_FIELD_UPGRADE</code>
+"Upgrade''
+<code>INK_MIME_LEN_UPGRADE</code>
+<code>INK_MIME_FIELD_USER_AGENT</code>
+"User-Agent''
+<code>INK_MIME_LEN_USER_AGENT</code>
+<code>INK_MIME_FIELD_VARY</code>
+"Vary''
+<code>INK_MIME_LEN_VARY</code>
+<code>INK_MIME_FIELD_VIA</code>
+"Via''
+<code>INK_MIME_LEN_VIA</code>
+<code>INK_MIME_FIELD_WARNING</code>
+"Warning''
+<code>INK_MIME_LEN_WARNING</code>
+<code>INK_MIME_FIELD_WWW_AUTHENTICATE</code>
+"Www-Authenticate''
+<code>INK_MIME_LEN_WWW_AUTHENTICATE</code>
+<code>INK_MIME_FIELD_XREF</code>
+"Xref''
+<code>INK_MIME_LEN_XREF</code>
+The header field names above are defined in <code>ts.h</code> as <code>const char*</code>
+strings. When Traffic Server sets the name portion of a header
+field (or any portion for that matter), it quickly checks to see if
+the new value is one of the known values. If it is, then Traffic
+Server stores a pointer into a global table instead of storing the
+known value in the marshal buffer. The header field names listed
+above are also pointers into this table, which enables simple
+pointer comparison of the value returned from
+<code>INKMimeHdrFieldNameGet</code> with one of the values listed above. It is
+recommended that you use the above values when referring to one of
+the known header field names to avoid the possibility of a spelling
+error.</p>
+<p>Traffic Server adds one important feature to MIME fields that you
+may not know about: Traffic Server does not print a MIME field if
+the field name begins with the '<code>@</code>' symbol. For example: a plugin
+can add the field "<code>@My-Field</code>" to a header. Even though Traffic
+Server never sends that field out in a request to an origin server
+or in a response to a client, it can be printed to Traffic Server
+logs by defining a custom log configuration file that explicitly
+logs such fields. This provides a useful mechanism for plugins to
+store information about an object in one of the MIME headers
+associated with the object.</p>
+<p>The MIME header functions are listed below:</p>
+<ul>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldAppend">INKMimeHdrFieldAppend</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldClone">INKMimeHdrFieldClone</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldCopy">INKMimeHdrFieldCopy</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldCopyValues">INKMimeHdrFieldCopyValues</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldCreate">INKMimeHdrFieldCreate</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldDestroy">INKMimeHdrFieldDestroy</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldLengthGet">INKMimeHdrFieldLengthGet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldNameGet">INKMimeHdrFieldNameGet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldNameSet">INKMimeHdrFieldNameSet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldNext">INKMimeHdrFieldNext</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldNextDup">INKMimeHdrFieldNextDup</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueAppend">INKMimeHdrFieldValueAppend</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueAppend">INKMimeHdrFieldValueAppend</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueDateGet">INKMimeHdrFieldValueDateGet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueDateInsert">INKMimeHdrFieldValueDateInsert</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueDateSet">INKMimeHdrFieldValueDateSet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueInsert">INKMimeHdrFieldValueInsert</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueIntGet">INKMimeHdrFieldValueIntGet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueIntSet">INKMimeHdrFieldValueIntSet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueStringGet">INKMimeHdrFieldValueStringGet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueStringInsert">INKMimeHdrFieldValueStringInsert</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueStringSet">INKMimeHdrFieldValueStringSet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueUintGet">INKMimeHdrFieldValueUintGet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueUintInsert">INKMimeHdrFieldValueUintInsert</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValueUintSet">INKMimeHdrFieldValueUintSet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValuesClear">INKMimeHdrFieldValuesClear</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldValuesCount">INKMimeHdrFieldValuesCount</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrClone">INKMimeHdrClone</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrCopy">INKMimeHdrCopy</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrCreate">INKMimeHdrCreate</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrDestroy">INKMimeHdrDestroy</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldFind">INKMimeHdrFieldFind</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldGet">INKMimeHdrFieldGet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldRemove">INKMimeHdrFieldRemove</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldsClear">INKMimeHdrFieldsClear</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrFieldsCount">INKMimeHdrFieldsCount</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrLengthGet">INKMimeHdrLengthGet</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrParse">INKMimeHdrParse</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeParserClear">INKMimeParserClear</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeParserCreate">INKMimeParserCreate</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeParserDestroy">INKMimeParserDestroy</a></li>
+<li><a href="MimeHeadersFunctions#INKMimeHdrPrint">INKMimeHdrPrint</a></li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ManagementInterfaceFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ManagementInterfaceFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ManagementInterfaceFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/ManagementInterfaceFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,48 @@
<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="INKIOBufferWrite">Prev</a> - INKIOBufferWrite
+Configuration Read Functions - <a href="TEConfigReadFunctions">Next</a></p>
+<h2 id="management_interface_functions">Management Interface Functions</h2>
+<hr />
+<p><a href="ManagementInterfaceFunctions#INKMgmtUpdateRegister">INKMgmtUpdateRegister</a></p>
+<h3 id="inkmgmtupdateregister">INKMgmtUpdateRegister</h3>
+<p>Sets up a plugin's management interface.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKReturnCode INKMgmtUpdateRegister (INKCont contp, const char *<i class="replaceable">plugin_name</i>, const char *<i class="replaceable">path</i>)</code></p>
+<p><strong>Arguments</strong>
+ ~ <code>contp</code> is the continuation to be called back if the plugin's
+ configuration is changed. The handler function for this
+ continuation must handle the event <code>INK_EVENT_MGMT_UPDATE</code>.</p>
+<div class="codehilite"><pre>`<span class="nt"><i></span>plugin_name <span class="nt"></i></span>` is the name of the plugin. This name must
+match the name of the plugin specified in your CGI form submission
+for `INK_PLUGIN_NAME`.
+
+`<span class="nt"><i></span>path <span class="nt"></i></span>` is the location of the plugin's interface, relative
+to the Traffic Server plugin directory (as specified by the
+`records.config` variable `<span class="nt"><i></span>proxy.config.plugin.plugin_dir<span class="nt"></i></span>`).
+If your plugin has a web user interface, then the path should be
+located in the Traffic Server `config` directory. For example,
+`<span class="nt"><i></span> path <span class="nt"></i></span>` could be `Blacklist/ui/index.html` or
+`Blacklist/ui/index.cgi`.
+</pre></div>
+
+
+<p><strong>Returns</strong>
+ ~ <code>INK_SUCCESS</code> if the operation completes 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="o">.</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MarshalBuffers.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MarshalBuffers.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MarshalBuffers.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MarshalBuffers.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,50 @@
<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="DeprecatedMarshBufFuncs">Prev</a> - Deprecated Functions
+HTTP Headers - <a href="HTTPHeaders2">Next</a></p>
+<h2 id="marshal_buffers">Marshal Buffers</h2>
+<p>A <strong>marshal buffer</strong>, or <code>INKMBuffer</code>, is a heap data structure
+that stores parsed URLs, MIME headers, and HTTP headers. You can
+allocate new objects out of marshal buffers and change the values
+within a marshal buffer. Whenever you manipulate an object, you
+require the handle to the object (<code>INKMLoc</code>) and the marshal buffer
+containing the object (<code>INKMBuffer</code>).</p>
+<p>Routines exist for manipulating the object based on these two
+pieces of information. For example, see one of the following:</p>
+<ul>
+<li><a href="HTTPHeaders2" title="HTTP Headers">HTTP Headers</a></li>
+<li><a href="URLs" title="URLs">URLs</a></li>
+<li><a href="MIMEHeaders" title="MIME Headers">MIME Headers</a></li>
+</ul>
+<p>The <strong>marshal buffer functions</strong> enable you to create and destroy
+Traffic Server's marshal buffers, which are the data structures
+that hold parsed URLs, MIME headers, and HTTP headers.</p>
+<p><img alt="[Caution]" src="images/docbook/caution.png" />
+Caution
+Any marshal buffer fetched by <code>INKHttpTxn*Get</code> will be used by
+other parts of the system. Be careful not to destroy these shared
+transaction marshal buffers in functions such as those below:</p>
+<ul>
+<li><code><a href="HTTPTransactionFunctions#INKHttpTxnCachedReqGet">INKHttpTxnCachedReqGet</a></code></li>
+<li><code><a href="HTTPTransactionFunctions#INKHttpTxnCachedRespGet">INKHttpTxnCachedRespGet</a></code></li>
+<li><code><a href="HTTPTransactionFunctions#INKHttpTxnClientReqGet">INKHttpTxnClientReqGet</a></code></li>
+<li><code><a href="HTTPTransactionFunctions#INKHttpTxnClientRespGet">INKHttpTxnClientRespGet</a></code></li>
+<li><code><a href="HTTPTransactionFunctions#INKHttpTxnServerReqGet">INKHttpTxnServerReqGet</a></code></li>
+<li><code><a href="HTTPTransactionFunctions#INKHttpTxnServerRespGet">INKHttpTxnServerRespGet</a></code></li>
+<li><code><a href="HTTPTransactionFunctions#INKHttpTxnTransformRespGet">INKHttpTxnTransformRespGet</a></code></li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MarshallBuffersFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MarshallBuffersFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MarshallBuffersFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MarshallBuffersFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,56 @@
<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="ch18s09s04">Prev</a> - Handle Release Functions
+INKMBufferDestroy - <a href="INKMBufferDestroy">Next</a></p>
+<h2 id="marshal_buffers">Marshal Buffers</h2>
+<hr />
+<p><a href="MarshallBuffersFunctions#INKMBufferCreate">INKMBufferCreate</a>
+<a href="INKMBufferDestroy">INKMBufferDestroy</a>
+A <strong>marshal buffer</strong>, or <code>INKMBuffer</code>, is a heap data structure
+that stores parsed URLs, MIME headers, and HTTP headers. You can
+allocate new objects out of marshal buffers, as well as change the
+values within a marshal buffer. Whenever you manipulate an object,
+you require the handle to the object (<code>INKMLoc</code>) and the marshal
+buffer containing the object (<code>INKMBuffer</code>).</p>
+<p>Routines exist for manipulating the object based on these two
+pieces of information. See, for example, the following:</p>
+<ul>
+<li><a href="HTTPHeaderFunctions" title="HTTP Header Functions">HTTP Header Functions</a></li>
+<li><a href="URLFunctions" title="URL Functions">URL Functions</a></li>
+<li><a href="MimeHeadersFunctions" title="MIIME Headers">MIIME Headers</a></li>
+</ul>
+<p>The marshal buffer functions enable you to create and destroy
+Traffic Server's marshal buffers, which are the data structures
+that hold parsed URLs, MIME headers, and HTTP headers.</p>
+<p><img alt="[Caution]" src="images/docbook/caution.png" />
+Caution
+Any marshal buffer fetched by <code>INKHttpTxn*Get</code> (for example,
+<a href="HTTPTransactionFunctions#INKHttpTxnClientReqGet"><code>INKHttpTxnClientReqGet</code></a>
+or
+<code><a href="HTTPTransactionFunctions#INKHttpTxnServerRespGet">INKHttpTxnServerRespGet</a></code>)
+will be used by other parts of the system. Be careful not to
+destroy these shared transaction marshal buffers.</p>
+<h3 id="inkmbuffercreate">INKMBufferCreate</h3>
+<p>Creates a new marshal buffer.</p>
+<p><strong>Prototype</strong>
+ ~ <code>INKMBuffer INKMBufferCreate (void)</code></p>
+<p><strong>Description</strong>
+ ~ Creates a new marshal buffer and initializes the reference
+ count to <code>1</code>.</p>
+<p><strong>Returns</strong>
+ ~ A pointer to the new marshal buffer.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MemoryAllocation.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MemoryAllocation.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MemoryAllocation.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MemoryAllocation.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,50 @@
<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="INKfopenFamily">Prev</a> - The INKfopen Family
+Thread Functions - <a href="Interface_ThreadFunctions">Next</a></p>
+<h2 id="memory_allocation">Memory Allocation</h2>
+<p>Traffic Server provides five routines for allocating and freeing
+memory. These routines correspond to similar routines in the C
+library. For example, <code>INKrealloc</code> behaves like the C library
+routine <code>realloc</code>.</p>
+<p>There are two main reasons for using the routines provided by
+Traffic Server. The first is portability: the Traffic Server API
+routines behave the same on all of Traffic Server's supported
+platforms. For example, <code>realloc</code> does not accept an argument of
+<code>NULL</code> on some platforms. The second reason is that the Traffic
+Server routines actually track the memory allocations by file and
+line number. This tracking is very efficient, always turned on, and
+quite useful when tracking down memory leaks.</p>
+<p>The memory allocation functions are:</p>
+<ul>
+<li>
+<p><a href="MemoryAllocationFunctions#INKfree" title="INKfree">INKfree</a></p>
+</li>
+<li>
+<p><a href="INKmalloc" title="INKmalloc">INKmalloc</a></p>
+</li>
+<li>
+<p><a href="INKrealloc" title="INKrealloc">INKrealloc</a></p>
+</li>
+<li>
+<p><a href="INKstrdup" title="INKstrdup">INKstrdup</a></p>
+</li>
+<li>
+<p><a href="INKstrndup" title="INKstrndup">INKstrndup</a></p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MemoryAllocationFunctions.en.html
URL: http://svn.apache.org/viewvc/websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MemoryAllocationFunctions.en.html?rev=778776&r1=778775&r2=778776&view=diff
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MemoryAllocationFunctions.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/MemoryAllocationFunctions.en.html Sat Nov 6 06:31:06 2010
@@ -4,17 +4,52 @@
<html>
<!-- This template is for the bulk of the site! -->
<head>
+ <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
<div id="content">
-
+ <p><a href="INKfwrite">Prev</a> - INKfwrite
+INKmalloc - <a href="INKmalloc">Next</a></p>
+<h2 id="memory_allocation">Memory Allocation</h2>
+<p>Traffic Server provides five routines for allocating and freeing
+memory. These routines correspond to similar routines in the C
+library. For example, <code>INKrealloc</code> behaves like the C library
+routine <code>realloc</code>.</p>
+<p>There are two main reasons to use the routines provided by Traffic
+Server. The first is portability: the Traffic Server API routines
+behave the same on all of Traffic Server's supported platforms. For
+example, <code>realloc</code> does not accept an argument of <code>NULL</code> on some
+platforms. The second reason is that the Traffic Server routines
+actually track the memory allocations by file and line number. This
+tracking is very efficient, is always turned on, and is useful for
+tracking down memory leaks.</p>
+<p>The memory allocation functions are described below.</p>
+<hr />
+<ul>
+<li><a href="MemoryAllocationFunctions#INKfree">INKfree</a></li>
+<li><a href="INKmalloc">INKmalloc</a></li>
+<li><a href="INKrealloc">INKrealloc</a></li>
+<li><a href="INKstrndup">INKstrndup</a></li>
+<li><a href="INKstrndup">INKstrndup</a></li>
+</ul>
+<h3 id="inkfree">INKfree</h3>
+<p>Frees memory allocated by <code>INKmalloc</code> or <code>INKrealloc</code>.</p>
+<p><strong>Prototype</strong>
+ ~ <code>void INKfree (void <em class="replaceable"><code>*ptr</code>)</p>
+<p><strong>Arguments</strong>
+ ~ <code><em class="replaceable"><code>ptr</code> is a pointer to the memory
+ to deallocate.</p>
+<p><strong>Description</strong>
+ ~ Releases the memory allocated by <code>INKmalloc</code> or <code>INKrealloc</code>.
+ If <code><em class="replaceable"><code>ptr</code> is <code>NULL</code>, then <code>INKfree</code>
+ does not perform an operation.</p>
</div>
<div id="footer">