You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2010/11/06 07:30:02 UTC
svn commit: r1031963 [9/13] - in /trafficserver/site/branches/ats-cms:
content/docs/trunk/sdk/ templates/
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/InterceptingHTTPTransactionFuncs.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/InterceptingHTTPTransactionFuncs.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/InterceptingHTTPTransactionFuncs.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/InterceptingHTTPTransactionFuncs.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,99 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](InitiateConnectionFunctions) - Initiate Connection
+INKHttpTxnServerIntercept - [Next](INKHttpTxnServerIntercept)
+## Intercepting HTTP Transaction Functions
+
+****
+[INKHttpTxnIntercept](InterceptingHTATPTAransactionFuncts#INKHttpTxnIntercept)
+[INKHttpTxnServerIntercept](INKHttpTxnServerIntercept)
+### INKHttpTxnIntercept
+
+Enables a plugin to intercept an HTTP client's request and serve
+content in place of the origin server.
+
+**Prototype**
+ ~ `INKReturnCode INKHttpTxnIntercept (INKCont <em class="replaceable"><code>contp`,
+ INKHttpTxn *`txnp`*)
+
+**Arguments**
+ ~ `INKCont``<em class="replaceable"><code>contp` is the
+ continuation called to accept the connection.
+
+ `INKHttpTxn``<em class="replaceable"><code>txnp` is the current
+ HTTP transaction the plugin wants to intercept.
+
+**Description**
+ ~ Enables a plugin to intercept an HTTP client's request and
+ serve content in place of the origin server. The request is
+ intercepted immediately after it is read by Traffic Server; the
+ origin server is not contacted. This API should be used in the
+ `INK_HTTP_READ_REQUEST_HDR_HOOK` hook.
+
+ Once `INKHttpTxnIntercept` is called, the handler of the
+ continuation `<em class="replaceable"><code>contp` receives an
+ event `INK_EVENT_NET_ACCEPT`. Note that the continuation passed
+ should not have a `NULL` mutex; if it does, then an error is
+ returned. The `void``<em class="replaceable"><code>*data` passed to
+ the handler of the continuation
+ `<em class="replaceable"><code>contp` is a data of type
+ `netvconnection` that represents the connection. Once a vconnection
+ is established, the user can use regular vconnection operations
+ (`INKVConnRead`, `INKVConnWrite`, etc...).
+
+ A typical scenario for using `INKHttpTxnIntercept` is as follows:
+
+ - Call `INKHttpTxnIntercept` from hook
+ `INK_HTTP_READ_REQUEST_HDR_HOOK`.
+
+ - Get called back on the continuation's handler that's passed as
+ an argument to `INKHttpTxnIntercept`.
+
+ - Get the vconnection from the argument
+ `void *``<em class="replaceable"><code>data` .
+
+ - Use `INKVConnRead` to get the HTTP request. Note that you will
+ not receive the event `INK_VCONN_READ_COMPLETE` - you will only
+ receive the `INK_VCONN_READ_READY` event because the number of
+ characters to be read is unknown. You should rely on
+ `INKTHttpParser` to parse the request and return a status
+ `INK_PARSE_DONE` when the request is fully received (escape
+ sequence `\r\n\r\n read`).
+
+ - Use `INKHttpParser` to parse the request.
+
+ - Use `INKVConnWrite` to write the HTTP response.
+
+
+ ![[Note]](images/docbook/note.png)
+ Note
+ Because the request and response do not go through the Traffic
+ Server HTTP state machine, neither is cached by Traffic Server. The
+ request is logged in `squid.log`.
+
+**Returns**
+ ~ `INK_SUCCESS` if the API is called successfully.
+
+ `INK_ERROR` if an error occurs while calling the API or if an
+ argument is invalid. This error is also returned if the
+ continuation passed has a `NULL` mutex.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/InterceptingHTTPTx.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/InterceptingHTTPTx.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/InterceptingHTTPTx.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/InterceptingHTTPTx.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,35 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](HTTP_Transactions) - HTTP Transactions
+Initiate HTTP Connection - [Next](InitiateHTTPConnection)
+## Intercepting HTTP Transactions
+
+The intercepting HTTP transaction functions enable plugins to
+intercept transactions either after the request is received or upon
+contact with the origin server. The plugin then acts as the origin
+server using the `INKVConn` interface. The intercepting HTTP
+transaction function allow for reading `POST` bodies in plugins as
+well as using alternative transports to the origin server.The
+intercepting HTTP transaction functions are:
+
+- [INKHttpTxnIntercept](InterceptingHTTPTransactionFuncs#INKHttpTxnIntercept "INKHttpTxnIntercept")
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Interface_ThreadFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Interface_ThreadFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Interface_ThreadFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Interface_ThreadFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,39 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](MemoryAllocation) - Memory Allocation
+Chapter 10. HTTP Headers - [Next](HTTPHeaders)
+## Thread Functions
+
+The Traffic Server API thread functions enable you to create,
+destroy, and identify threads within Traffic Server. Multithreading
+enables a single program to have more than one stream of execution
+and to process more than one transaction at a time. Threads
+serialize their access to shared resources and data using the
+`INKMutex` type, as described in
+[Mutexes](MutexGuide#Mutexes "Mutexes").
+
+The thread functions are listed below:
+
+****
+[INKThreadCreate](ThreadFunctions#INKThreadCreate "INKThreadCreate")
+[INKThreadDestroy](INKThreadDestroy "INKThreadDestroy")
+[INKThreadInit](INKThreadInit "INKThreadInit")
+[INKThreadSelf](INKThreadSelf "INKThreadSelf")
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LicensingPlugin.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LicensingPlugin.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LicensingPlugin.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LicensingPlugin.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,57 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](AccessPluginFiles) - Accessing Installed Plugin Files
+Setting Up Licensing - [Next](SetUpLicensing)
+## Licensing Your Plugin
+
+When installing a plugin that requires a license, `plugin.db` must
+be updated. This file contains the license keys for the plugins. At
+load time, Traffic Server reads the keys in the `plugin.db` file
+and checks the validity of each. If a key is not valid, then the
+plugin is not executed.
+
+### Format of plugin.db
+
+\# comments start with a `#` character
+
+ [plugin_name]
+ Object=plugin.so
+ License=Key
+
+Be careful with the syntax:
+
+- Object is with an uppercase 'O'
+
+ Example: `object=plugin.so is bad`
+
+- License is with an uppercase 'L'
+
+ Example: `license=key is bad`
+
+- No blank between '=' and value.
+
+ Example: `Object = plugin.so is bad`
+
+- No blank after the value, either.
+
+ Example: `License=Key is bad`
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LoggingAPI.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LoggingAPI.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LoggingAPI.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LoggingAPI.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,109 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](GenerateLicenseKey) - Generating a License Key
+Chapter 17. Adding Statistics - [Next](AddingStatistics)
+## Guide to the Logging API
+
+The logging API enables your plugin to log entries in a custom text
+log file that you create with the call `INKTextLogObjectCreate`.
+This log file is part of Traffic Server's logging system; by
+default, it is stored in the logging directory. Once you have
+created the log object, you can set log properties.
+
+The logging API enables you to:
+
+- Establish a custom text log for your plugin: see
+ [INKTextLogObjectCreate](LoggingFunctions#INKTextLogObjectCreate "INKTextLogObjectCreate")
+
+- Set the log header for your custom text log: see
+ [INKTextLogObjectHeaderSet](INKTextLogObjectHeaderSet "INKTextLogObjectHeaderSet")
+
+- Enable or disable rolling your custom text log: see
+ [INKTextLogObjectRollingEnabledSet](INKTextLogObjectRollingEnabledSet "INKTextLogObjectRollingEnabledSet")
+
+- Set the rolling interval (in seconds) for your custom text log:
+ see
+ [INKTextLogObjectRollingIntervalSecSet](INKTextLogObjectRollingIntervalSecSet "INKTextLogObjectRollingIntervalSecSet")
+
+- Set the rolling offset for your custom text log: see
+ [INKTextLogObjectRollingOffsetHrSet](INKTextLogObjectRollingOffsetHrSet "INKTextLogObjectRollingOffsetHrSet")
+
+- Write text entries to the custom text log: see
+ [INKTextLogObjectWrite](INKTextLogObjectWrite "INKTextLogObjectWrite")
+
+- Flush the contents of the custom text log's write buffer to
+ disk: see
+ [INKTextLogObjectFlush](INKTextLogObjectFlush "INKTextLogObjectFlush")
+
+- Destroy custom text logs when you are done with them: see
+ [INKTextLogObjectDestroy](INKTextLogObjectDestroy "INKTextLogObjectDestroy")
+
+
+The steps below show how the logging API is used in the
+`blacklist-1.c` sample plugin. For the complete source code, see
+the
+[*Sample Source Code*](App_SampleSourceCode "Appendix A. Sample Source Code")
+appendix.
+
+1. A new log file is defined as a global variable.
+
+ static INKTextLogObject log;
+
+2. In `INKPluginInit`, a new log object is allocated:
+
+ log = INKTextLogObjectCreate("blacklist", INK_LOG_MODE_ADD_TIMESTAMP,
+ NULL, &error);
+
+ The new log is named `blacklist.log`. Each entry written to the log
+ will have a timestamp. The `NULL` argument specifies that the new
+ log does not have a log header. The error argument stores the
+ result of the log creation; if the log is created successfully,
+ then an error will be equal to `INK_LOG_ERROR_NO_ERROR`.
+
+3. After creating the log, the plugin makes sure that the log was
+ created successfully:
+
+ if (!log) {
+ printf("Blacklist plugin: error %d while creating log\n", error);
+ }
+
+4. The `blacklist-1` plugin matches the host portion of the URL
+ (in each client request) with a list of blacklisted sites (stored
+ in the array `sites[`]):
+
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host, sites[i], host_length) == 0) {
+
+ If the host matches one of the blacklisted sites (such as
+ `sites[i]`), then the plugin writes a blacklist entry to
+ `blacklist.log`:
+
+ if (log) {
+ INKTextLogObjectWrite(log, "blacklisting site: %s", sites[i]);
+
+ The format of the log entry is as follows:
+
+ `<timestamp>``blacklisting site:``sites[i]`
+
+ The log is not flushed or destroyed in the `blacklist-1` plugin -
+ it lives for the life of the plugin.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LoggingFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LoggingFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LoggingFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/LoggingFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,121 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](CoupledStatsFunctions) - Coupled Statistics Functions
+INKTextLogObjectDestroy - [Next](INKTextLogObjectDestroy)
+## Logging Functions
+
+****
+[INKTextLogObjectCreate](LoggingFunctions#INKTextLogObjectCreate)
+[INKTextLogObjectDestroy](INKTextLogObjectDestroy)
+[INKTextLogObjectFlush](INKTextLogObjectFlush)
+[INKTextLogObjectHeaderSet](INKTextLogObjectHeaderSet)
+[INKTextLogObjectRollingEnabledSet](INKTextLogObjectRollingEnabledSet)
+[INKTextLogObjectRollingIntervalSecSet](INKTextLogObjectRollingIntervalSecSet)
+[INKTextLogObjectRollingOffsetHrSet](INKTextLogObjectRollingOffsetHrSet)
+[INKTextLogObjectWrite](INKTextLogObjectWrite)
+### INKTextLogObjectCreate
+
+Creates a new custom log for your plugin.
+
+**Prototype**
+ ~ `INKReturnCode INKTextLogObjectCreate (const char *<em class="replaceable"><code>filename`,
+ int *`mode`*, INKTextLogObject \**`new_logobj`*)
+
+**Arguments**
+ ~ `const char *<em class="replaceable"><code>filename`
+ is the name of the new log file created in the `log` directory. You
+ can specify a path to a subdirectory within the `log` directory
+ (e.g. `subdir/filename`), but make sure you create the subdirectory
+ first. If you do not specify a file name extension, then the
+ extension `.log` is automatically added.
+
+ The logs you create are treated like ordinary logs - that is, they
+ are rolled if log rolling is enabled. Log collation, however, is
+ not supported.
+
+ `int <em class="replaceable"><code>mode` can be `0` and/or the
+ following:
+
+ INK_LOG_MODE_ADD_TIMESTAMP
+
+ Whenever the plugin makes a log entry using `INKTextLogObjectWrite`
+ (see below), it prepends the entry with a timestamp.
+
+ INK_LOG_MODE_DO_NOT_RENAME
+
+ This means that if there is a filename conflict, then Traffic
+ Server should not attempt to rename the custom log. As a
+ consequence of the name conflict, the custom log is not created.
+
+ `INKTextLogObject *<i class="replaceable">new_logobj </i>` is set
+ to the newly-created log object.
+
+**Description**
+ ~ Creates a custom log for your plugin. Once the log object is
+ created, use the APIs below to set properties.
+
+ - [INKTextLogObjectRollingEnabledSet](INKTextLogObjectRollingEnabledSet)
+ - [INKTextLogObjectRollingIntervalSecSet](INKTextLogObjectRollingIntervalSecSet)
+ - [INKTextLogObjectRollingOffsetHrSet](INKTextLogObjectRollingOffsetHrSet)
+
+ If the value of `<em class="replaceable"><code> mode` is not valid,
+ then the behavior of the API cannot be predicted.
+
+**Example**
+ ~ Suppose you call:
+
+ INKTextLogObjectCreate ("squid" , mode, NULL, &log);
+
+ If `<em class="replaceable"><code> mode` is
+ `INK_LOG_MODE_DO_NOT_RENAME`, then you will not get a new log if
+ `squid.log` already exists (you'll get an error instead).
+
+ If `<em class="replaceable"><code> mode` is not
+ `INK_LOG_MODE_DO_NOT_RENAME`, then Traffic Server tries to rename
+ the log to a new name (it will try `squid_1.log`).
+
+ If a log object is created with `INK_LOG_MODE_DO_NOT_RENAME` `mode`
+ and a log with the same file name already exists, then the
+ signature (i.e., the type of log file) is compared. If the
+ signatures of the log files match, then the pre-existing file is
+ opened and logging is resumed at the end of the file. If the
+ signatures do not match, then an error is returned.
+
+ If a log object is created without `INK_LOG_MODE_DO_NOT_RENAME`
+ `mode` and a log with the same file name already exists, then the
+ signatures are compared. If the signatures of the log files match,
+ then the pre-existing file is opened and logging is resumed at the
+ end of the file. If the signatures do not match, then another file
+ with `filename_1.log` is tried and so on.
+
+ **Note:** The log file signature indicates log file type. Log files
+ can be structured (fixed format) log files or unstructured (free
+ format) log files. All free format log files have the same
+ signature, while fixed format log files have the same structured
+ (fixed) format as the signature.
+
+**Returns**
+ ~ `INK_SUCCESS` if the API is called successfully.
+
+ `INK_ERROR` if an error occurs while calling the API or if an
+ argument is invalid.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MIMEFldsBelongAssocMIMEHdr.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MIMEFldsBelongAssocMIMEHdr.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MIMEFldsBelongAssocMIMEHdr.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MIMEFldsBelongAssocMIMEHdr.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,66 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](DuplicateMIMEFlds) - Duplicate MIME Fields Are Not
+Coalesced
+Release Marshal Buffer Handles - [Next](RlsMarshalBufHandles)
+### MIME Fields Always Belong to an Associated MIME Header
+
+When using Traffic Server, you cannot create a new MIME field
+without an associated MIME header or HTTP header; MIME fields are
+always seen as part of a MIME header or HTTP header.
+
+To use a MIME field, you must specify the MIME header or HTTP
+header to which it belongs - this is called the field's
+**parent header**. The `INKMimeField*` functions in older versions
+of the SDK have been deprecated, as they do not require the parent
+header as inputs. The current version of Traffic Server uses new
+functions, the `<b>INKMimeHdrField*</b>` series, which require you
+to specify the location of the parent header along with the
+location of the MIME field. For every deprecated `INKMimeField*`
+function, there is a new, preferred `INKMimeHdrField*` function.
+Therefore, you should use the `<b>INKMimeHdrField*</b>` functions
+instead of the deprecated `INKMimeField*` series. Examples are
+provided below.
+
+Instead of:
+
+ INKMLoc INKMimeFieldCreate (INKMBuffer bufp)
+
+You should use:
+
+ INKMLoc INKMimeHdrFieldCreate (INKMBuffer bufp, INKMLoc hdr)
+
+Instead of:
+
+ void INKMimeFieldCopyValues (INKMBuffer dest_bufp, INKMLoc dest_offset,
+ INKMBuffer src_bufp, INKMLoc src_offset)
+
+You should use:
+
+ void INKMimeHdrFieldCopyValues (INKMBuffer dest_bufp, INKMLoc dest_hdr,
+ INKMLoc dest_field, INKMBuffer src_bufp, INKMLoc src_hdr, INKMLoc
+ src_field)
+
+In the `INKMimeHdrField*` function prototypes, the `INKMLoc` field
+corresponds to the `INKMLoc` offset used the deprecated
+`INKMimeField*` functions (see the discussion of parent `INKMLoc`
+in the following section).
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MIMEHeaders.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MIMEHeaders.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MIMEHeaders.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MIMEHeaders.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,376 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](URLs) - URLs
+Chapter 11. Mutex Guide - [Next](MutexGuide)
+## MIME Headers
+
+The Traffic Server **MIME header functions** enable you to retrieve
+and modify information about HTTP MIME fields.
+
+An HTTP request or response consists of a header, body, and
+trailer. The **HTTP** **header** contains a request (or response)
+line and a MIME header. A **MIME** **header** is composed of zero
+or more MIME fields. A **MIME** **field** is composed of a field
+name, a colon, and zero or more field values (values in a field are
+separated by commas).
+
+In the example below: `Foo` is the MIME field name, `bar` is the
+first MIME field value, and `car` is the second MIME field value.
+
+ Foo: bar, car
+
+The following example is an augmented **Backus-Naur Form** (BNF)
+for the form of a MIME header - it specifies exactly what was
+described above. A **header** consists of zero or more **fields**
+that contain a name, separating colon, and zero or more values. A
+**name** or **value** is simply a string of tokens that is
+potentially zero length; a **token** 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 `Foo`, `foo` and `fOO` are all
+equivalent.
+
+ MIME-header = *MIME-field
+ MIME-field = field-name ":" #field-value
+ field-name = *token
+ field-value = *token
+
+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 [URLs](URLs "URLs")). The actual
+data is stored in a marshal buffer; the MIME header functions
+operate on a marshal buffer and a location (`INKMLoc`) within the
+buffer.
+
+After a call to `INKMimeHdrFieldDestroy`, `INKMimeHdrFieldRemove`,
+or `INKUrlDestroy` is made, you must deallocate the `INKMLoc`
+handle with a call to `INKHandleMLocRelease`. You do not need to
+deallocate a `NULL` handles. For example: if you call
+`INKMimeHdrFieldValueStringGet` to get the value of the content
+type field and the field does not exist, then it returns
+`INK_NULL_MLOC`. In such a case, you wouldn't need to deallocate
+the handle with a call to `INKHandleMLocRelease`.
+
+The location (`INKMLoc`) in the
+[MIME header functions](MIMEHeaders#MimeHeaderFxns) 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
+[`INKMimeHdrCopy`](MimeHeadersFunctions#INKMimeHdrCopy "INKMimeHdrCopy")).
+
+**Note:**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
+`INKMimeHdrFieldNextDup`.
+
+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.
+
+**Traffic Server Pre-allocated Field Names**
+**HTTP and NNTP Header Field Names**
+**Associated String Lengths**
+`INK_MIME_FIELD_ACCEPT`
+"Accept"
+`INK_MIME_LEN_ACCEPT`
+`INK_MIME_FIELD_ACCEPT_CHARSET`
+"Accept-Charset"
+`INK_MIME_LEN_ACCEPT_CHARSET`
+`INK_MIME_FIELD_ACCEPT_ENCODING`
+"Accept-Encoding"
+`INK_MIME_LEN_ACCEPT_ENCODING`
+`INK_MIME_FIELD_ACCEPT_LANGUAGE`
+"Accept-Language"
+`INK_MIME_LEN_ACCEPT_LANGUAGE`
+`INK_MIME_FIELD_ACCEPT_RANGES`
+"Accept-Ranges"
+`INK_MIME_LEN_ACCEPT_RANGES`
+`INK_MIME_FIELD_AGE`
+"Age"
+`INK_MIME_LEN_AGE`
+`INK_MIME_FIELD_ALLOW`
+"Allow"
+`INK_MIME_LEN_ALLOW`
+`INK_MIME_FIELD_APPROVED`
+"Approved"
+`INK_MIME_LEN_APPROVED`
+`INK_MIME_FIELD_AUTHORIZATION`
+"Authorization"
+`INK_MIME_LEN_AUTHORIZATION`
+`INK_MIME_FIELD_BYTES`
+"Bytes"
+`INK_MIME_LEN_BYTES`
+`INK_MIME_FIELD_CACHE_CONTROL`
+"Cache-Control"
+`INK_MIME_LEN_CACHE_CONTROL`
+`INK_MIME_FIELD_CLIENT_IP`
+"Client-ip"
+`INK_MIME_LEN_CLIENT_IP`
+`INK_MIME_FIELD_CONNECTION`
+"Connection"
+`INK_MIME_LEN_CONNECTION`
+`INK_MIME_FIELD_CONTENT_BASE`
+"Content-Base"
+`INK_MIME_LEN_CONTENT_BASE`
+`INK_MIME_FIELD_CONTENT_ENCODING`
+"Content-Encoding"
+`INK_MIME_LEN_CONTENT_ENCODING`
+`INK_MIME_FIELD_CONTENT_LANGUAGE`
+"Content-Language"
+`INK_MIME_LEN_CONTENT_LANGUAGE`
+`INK_MIME_FIELD_CONTENT_LENGTH`
+"Content-Length"
+`INK_MIME_LEN_CONTENT_LENGTH`
+`INK_MIME_FIELD_CONTENT_LOCATION`
+"Content-Location"
+`INK_MIME_LEN_CONTENT_LOCATION`
+`INK_MIME_FIELD_CONTENT_MD5`
+"Content-MD5"
+`INK_MIME_LEN_CONTENT_MD5`
+`INK_MIME_FIELD_CONTENT_RANGE`
+"Content-Range"
+`INK_MIME_LEN_CONTENT_RANGE`
+`INK_MIME_FIELD_CONTENT_TYPE`
+"Content-Type"
+`INK_MIME_LEN_CONTENT_TYPE`
+`INK_MIME_FIELD_CONTROL`
+"Control"
+`INK_MIME_LEN_CONTROL`
+`INK_MIME_FIELD_COOKIE`
+"Cookie"
+`INK_MIME_LEN_COOKIE`
+`INK_MIME_FIELD_DATE`
+"Date"
+`INK_MIME_LEN_DATE`
+`INK_MIME_FIELD_DISTRIBUTION`
+"Distribution"
+`INK_MIME_LEN_DISTRIBUTION`
+`INK_MIME_FIELD_ETAG`
+"Etag"
+`INK_MIME_LEN_ETAG`
+`INK_MIME_FIELD_EXPECT`
+"Expect"
+`INK_MIME_LEN_EXPECT`
+`INK_MIME_FIELD_EXPIRES`
+"Expires"
+`INK_MIME_LEN_EXPIRES`
+`INK_MIME_FIELD_FOLLOWUP_TO`
+"Followup-To"
+`INK_MIME_LEN_FOLLOWUP_TO`
+`INK_MIME_FIELD_FROM`
+"From"
+`INK_MIME_LEN_FROM`
+`INK_MIME_FIELD_HOST`
+"Host"
+`INK_MIME_LEN_HOST`
+`INK_MIME_FIELD_IF_MATCH`
+"If-Match"
+`INK_MIME_LEN_IF_MATCH`
+`INK_MIME_FIELD_IF_MODIFIED_SINCE`
+"If-Modified-Since''
+`INK_MIME_LEN_IF_MODIFIED_SINCE`
+`INK_MIME_FIELD_IF_NONE_MATCH`
+"If-None-Match''
+`INK_MIME_LEN_IF_NONE_MATCH`
+`INK_MIME_FIELD_IF_RANGE`
+"If-Range''
+`INK_MIME_LEN_IF_RANGE`
+`INK_MIME_FIELD_IF_UNMODIFIED_SINCE`
+"If-Unmodified-Since''
+`INK_MIME_LEN_IF_UNMODIFIED_SINCE`
+`INK_MIME_FIELD_KEEP_ALIVE`
+"Keep-Alive''
+`INK_MIME_LEN_KEEP_ALIVE`
+`INK_MIME_FIELD_KEYWORDS`
+"Keywords''
+`INK_MIME_LEN_KEYWORDS`
+`INK_MIME_FIELD_LAST_MODIFIED`
+"Last-Modified''
+`INK_MIME_LEN_LAST_MODIFIED`
+`INK_MIME_FIELD_LINES`
+"Lines''
+`INK_MIME_LEN_LINES`
+`INK_MIME_FIELD_LOCATION`
+"Location''
+`INK_MIME_LEN_LOCATION`
+`INK_MIME_FIELD_MAX_FORWARDS`
+"Max-Forwards''
+`INK_MIME_LEN_MAX_FORWARDS`
+`INK_MIME_FIELD_MESSAGE_ID`
+"Message-ID''
+`INK_MIME_LEN_MESSAGE_ID`
+`INK_MIME_FIELD_NEWSGROUPS`
+"Newsgroups''
+`INK_MIME_LEN_NEWSGROUPS`
+`INK_MIME_FIELD_ORGANIZATION`
+"Organization''
+`INK_MIME_LEN_ORGANIZATION`
+`INK_MIME_FIELD_PATH`
+"Path''
+`INK_MIME_LEN_PATH`
+`INK_MIME_FIELD_PRAGMA`
+"Pragma''
+`INK_MIME_LEN_PRAGMA`
+`INK_MIME_FIELD_PROXY_AUTHENTICATE`
+"Proxy-Authenticate''
+`INK_MIME_LEN_PROXY_AUTHENTICATE`
+`INK_MIME_FIELD_PROXY_AUTHORIZATION`
+"Proxy-Authorization''
+`INK_MIME_LEN_PROXY_AUTHORIZATION`
+`INK_MIME_FIELD_PROXY_CONNECTION`
+"Proxy-Connection''
+`INK_MIME_LEN_PROXY_CONNECTION`
+`INK_MIME_FIELD_PUBLIC`
+"Public''
+`INK_MIME_LEN_PUBLIC`
+`INK_MIME_FIELD_RANGE`
+"Range''
+`INK_MIME_LEN_RANGE`
+`INK_MIME_FIELD_REFERENCES`
+"References''
+`INK_MIME_LEN_REFERENCES`
+`INK_MIME_FIELD_REFERER`
+"Referer''
+`INK_MIME_LEN_REFERER`
+`INK_MIME_FIELD_REPLY_TO`
+"Reply-To''
+`INK_MIME_LEN_REPLY_TO`
+`INK_MIME_FIELD_RETRY_AFTER`
+"Retry-After''
+`INK_MIME_LEN_RETRY_AFTER`
+`INK_MIME_FIELD_SENDER`
+"Sender''
+`INK_MIME_LEN_SENDER`
+`INK_MIME_FIELD_SERVER`
+"Server''
+`INK_MIME_LEN_SERVER`
+`INK_MIME_FIELD_SET_COOKIE`
+"Set-Cookie''
+`INK_MIME_LEN_SET_COOKIE`
+`INK_MIME_FIELD_SUBJECT`
+"Subject''
+`INK_MIME_LEN_SUBJECTINK_MIME_LEN_SUBJECT`
+`INK_MIME_FIELD_SUMMARY`
+"Summary''
+`INK_MIME_LEN_SUMMARY`
+`INK_MIME_FIELD_TE`
+"TE''
+`INK_MIME_LEN_TE`
+`INK_MIME_FIELD_TRANSFER_ENCODING`
+"Transfer-Encoding''
+`INK_MIME_LEN_TRANSFER_ENCODING`
+`INK_MIME_FIELD_UPGRADE`
+"Upgrade''
+`INK_MIME_LEN_UPGRADE`
+`INK_MIME_FIELD_USER_AGENT`
+"User-Agent''
+`INK_MIME_LEN_USER_AGENT`
+`INK_MIME_FIELD_VARY`
+"Vary''
+`INK_MIME_LEN_VARY`
+`INK_MIME_FIELD_VIA`
+"Via''
+`INK_MIME_LEN_VIA`
+`INK_MIME_FIELD_WARNING`
+"Warning''
+`INK_MIME_LEN_WARNING`
+`INK_MIME_FIELD_WWW_AUTHENTICATE`
+"Www-Authenticate''
+`INK_MIME_LEN_WWW_AUTHENTICATE`
+`INK_MIME_FIELD_XREF`
+"Xref''
+`INK_MIME_LEN_XREF`
+The header field names above are defined in `ts.h` as `const char*`
+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
+`INKMimeHdrFieldNameGet` 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.
+
+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 '`@`' symbol. For example: a plugin
+can add the field "`@My-Field`" 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.
+
+The MIME header functions are listed below:
+
+- [INKMimeHdrFieldAppend](MimeHeadersFunctions#INKMimeHdrFieldAppend)
+- [INKMimeHdrFieldClone](MimeHeadersFunctions#INKMimeHdrFieldClone)
+- [INKMimeHdrFieldCopy](MimeHeadersFunctions#INKMimeHdrFieldCopy)
+- [INKMimeHdrFieldCopyValues](MimeHeadersFunctions#INKMimeHdrFieldCopyValues)
+- [INKMimeHdrFieldCreate](MimeHeadersFunctions#INKMimeHdrFieldCreate)
+- [INKMimeHdrFieldDestroy](MimeHeadersFunctions#INKMimeHdrFieldDestroy)
+- [INKMimeHdrFieldLengthGet](MimeHeadersFunctions#INKMimeHdrFieldLengthGet)
+- [INKMimeHdrFieldNameGet](MimeHeadersFunctions#INKMimeHdrFieldNameGet)
+- [INKMimeHdrFieldNameSet](MimeHeadersFunctions#INKMimeHdrFieldNameSet)
+- [INKMimeHdrFieldNext](MimeHeadersFunctions#INKMimeHdrFieldNext)
+- [INKMimeHdrFieldNextDup](MimeHeadersFunctions#INKMimeHdrFieldNextDup)
+- [INKMimeHdrFieldValueAppend](MimeHeadersFunctions#INKMimeHdrFieldValueAppend)
+- [INKMimeHdrFieldValueAppend](MimeHeadersFunctions#INKMimeHdrFieldValueAppend)
+- [INKMimeHdrFieldValueDateGet](MimeHeadersFunctions#INKMimeHdrFieldValueDateGet)
+- [INKMimeHdrFieldValueDateInsert](MimeHeadersFunctions#INKMimeHdrFieldValueDateInsert)
+- [INKMimeHdrFieldValueDateSet](MimeHeadersFunctions#INKMimeHdrFieldValueDateSet)
+- [INKMimeHdrFieldValueInsert](MimeHeadersFunctions#INKMimeHdrFieldValueInsert)
+- [INKMimeHdrFieldValueIntGet](MimeHeadersFunctions#INKMimeHdrFieldValueIntGet)
+- [INKMimeHdrFieldValueIntSet](MimeHeadersFunctions#INKMimeHdrFieldValueIntSet)
+- [INKMimeHdrFieldValueStringGet](MimeHeadersFunctions#INKMimeHdrFieldValueStringGet)
+- [INKMimeHdrFieldValueStringInsert](MimeHeadersFunctions#INKMimeHdrFieldValueStringInsert)
+- [INKMimeHdrFieldValueStringSet](MimeHeadersFunctions#INKMimeHdrFieldValueStringSet)
+- [INKMimeHdrFieldValueUintGet](MimeHeadersFunctions#INKMimeHdrFieldValueUintGet)
+- [INKMimeHdrFieldValueUintInsert](MimeHeadersFunctions#INKMimeHdrFieldValueUintInsert)
+- [INKMimeHdrFieldValueUintSet](MimeHeadersFunctions#INKMimeHdrFieldValueUintSet)
+- [INKMimeHdrFieldValuesClear](MimeHeadersFunctions#INKMimeHdrFieldValuesClear)
+- [INKMimeHdrFieldValuesCount](MimeHeadersFunctions#INKMimeHdrFieldValuesCount)
+- [INKMimeHdrClone](MimeHeadersFunctions#INKMimeHdrClone)
+- [INKMimeHdrCopy](MimeHeadersFunctions#INKMimeHdrCopy)
+- [INKMimeHdrCreate](MimeHeadersFunctions#INKMimeHdrCreate)
+- [INKMimeHdrDestroy](MimeHeadersFunctions#INKMimeHdrDestroy)
+- [INKMimeHdrFieldFind](MimeHeadersFunctions#INKMimeHdrFieldFind)
+- [INKMimeHdrFieldGet](MimeHeadersFunctions#INKMimeHdrFieldGet)
+- [INKMimeHdrFieldRemove](MimeHeadersFunctions#INKMimeHdrFieldRemove)
+- [INKMimeHdrFieldsClear](MimeHeadersFunctions#INKMimeHdrFieldsClear)
+- [INKMimeHdrFieldsCount](MimeHeadersFunctions#INKMimeHdrFieldsCount)
+- [INKMimeHdrLengthGet](MimeHeadersFunctions#INKMimeHdrLengthGet)
+- [INKMimeHdrParse](MimeHeadersFunctions#INKMimeHdrParse)
+- [INKMimeParserClear](MimeHeadersFunctions#INKMimeParserClear)
+- [INKMimeParserCreate](MimeHeadersFunctions#INKMimeParserCreate)
+- [INKMimeParserDestroy](MimeHeadersFunctions#INKMimeParserDestroy)
+- [INKMimeHdrPrint](MimeHeadersFunctions#INKMimeHdrPrint)
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ManagementInterfaceFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ManagementInterfaceFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ManagementInterfaceFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ManagementInterfaceFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,56 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](INKIOBufferWrite) - INKIOBufferWrite
+Configuration Read Functions - [Next](TEConfigReadFunctions)
+## Management Interface Functions
+
+****
+[INKMgmtUpdateRegister](ManagementInterfaceFunctions#INKMgmtUpdateRegister)
+### INKMgmtUpdateRegister
+
+Sets up a plugin's management interface.
+
+**Prototype**
+ ~ `INKReturnCode INKMgmtUpdateRegister (INKCont contp, const char *<i class="replaceable">plugin_name</i>, const char *<i class="replaceable">path</i>)`
+
+**Arguments**
+ ~ `contp` is the continuation to be called back if the plugin's
+ configuration is changed. The handler function for this
+ continuation must handle the event `INK_EVENT_MGMT_UPDATE`.
+
+ `<i>plugin_name </i>` 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`.
+
+ `<i>path </i>` is the location of the plugin's interface, relative
+ to the Traffic Server plugin directory (as specified by the
+ `records.config` variable `<i>proxy.config.plugin.plugin_dir</i>`).
+ If your plugin has a web user interface, then the path should be
+ located in the Traffic Server `config` directory. For example,
+ `<i> path </i>` could be `Blacklist/ui/index.html` or
+ `Blacklist/ui/index.cgi`.
+
+**Returns**
+ ~ `INK_SUCCESS` if the operation completes successfully.
+
+ `INK_ERROR` if an error occurs.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MarshalBuffers.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MarshalBuffers.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MarshalBuffers.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MarshalBuffers.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,56 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](DeprecatedMarshBufFuncs) - Deprecated Functions
+HTTP Headers - [Next](HTTPHeaders2)
+## Marshal Buffers
+
+A **marshal buffer**, or `INKMBuffer`, 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 (`INKMLoc`) and the marshal buffer
+containing the object (`INKMBuffer`).
+
+Routines exist for manipulating the object based on these two
+pieces of information. For example, see one of the following:
+
+- [HTTP Headers](HTTPHeaders2 "HTTP Headers")
+- [URLs](URLs "URLs")
+- [MIME Headers](MIMEHeaders "MIME Headers")
+
+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.
+
+![[Caution]](images/docbook/caution.png)
+Caution
+Any marshal buffer fetched by `INKHttpTxn*Get` 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:
+
+- `<a href="HTTPTransactionFunctions#INKHttpTxnCachedReqGet">INKHttpTxnCachedReqGet</a>`
+- `<a href="HTTPTransactionFunctions#INKHttpTxnCachedRespGet">INKHttpTxnCachedRespGet</a>`
+- `<a href="HTTPTransactionFunctions#INKHttpTxnClientReqGet">INKHttpTxnClientReqGet</a>`
+- `<a href="HTTPTransactionFunctions#INKHttpTxnClientRespGet">INKHttpTxnClientRespGet</a>`
+- `<a href="HTTPTransactionFunctions#INKHttpTxnServerReqGet">INKHttpTxnServerReqGet</a>`
+- `<a href="HTTPTransactionFunctions#INKHttpTxnServerRespGet">INKHttpTxnServerRespGet</a>`
+- `<a href="HTTPTransactionFunctions#INKHttpTxnTransformRespGet">INKHttpTxnTransformRespGet</a>`
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MarshallBuffersFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MarshallBuffersFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MarshallBuffersFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MarshallBuffersFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,69 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](ch18s09s04) - Handle Release Functions
+INKMBufferDestroy - [Next](INKMBufferDestroy)
+## Marshal Buffers
+
+****
+[INKMBufferCreate](MarshallBuffersFunctions#INKMBufferCreate)
+[INKMBufferDestroy](INKMBufferDestroy)
+A **marshal buffer**, or `INKMBuffer`, 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 (`INKMLoc`) and the marshal
+buffer containing the object (`INKMBuffer`).
+
+Routines exist for manipulating the object based on these two
+pieces of information. See, for example, the following:
+
+- [HTTP Header Functions](HTTPHeaderFunctions "HTTP Header Functions")
+- [URL Functions](URLFunctions "URL Functions")
+- [MIIME Headers](MimeHeadersFunctions "MIIME Headers")
+
+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.
+
+![[Caution]](images/docbook/caution.png)
+Caution
+Any marshal buffer fetched by `INKHttpTxn*Get` (for example,
+[`INKHttpTxnClientReqGet`](HTTPTransactionFunctions#INKHttpTxnClientReqGet)
+or
+`<a href="HTTPTransactionFunctions#INKHttpTxnServerRespGet">INKHttpTxnServerRespGet</a>`)
+will be used by other parts of the system. Be careful not to
+destroy these shared transaction marshal buffers.
+
+### INKMBufferCreate
+
+Creates a new marshal buffer.
+
+**Prototype**
+ ~ `INKMBuffer INKMBufferCreate (void)`
+
+**Description**
+ ~ Creates a new marshal buffer and initializes the reference
+ count to `1`.
+
+**Returns**
+ ~ A pointer to the new marshal buffer.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MemoryAllocation.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MemoryAllocation.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MemoryAllocation.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MemoryAllocation.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,51 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](INKfopenFamily) - The INKfopen Family
+Thread Functions - [Next](Interface_ThreadFunctions)
+## Memory Allocation
+
+Traffic Server provides five routines for allocating and freeing
+memory. These routines correspond to similar routines in the C
+library. For example, `INKrealloc` behaves like the C library
+routine `realloc`.
+
+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, `realloc` does not accept an argument of
+`NULL` 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.
+
+The memory allocation functions are:
+
+- [INKfree](MemoryAllocationFunctions#INKfree "INKfree")
+
+- [INKmalloc](INKmalloc "INKmalloc")
+
+- [INKrealloc](INKrealloc "INKrealloc")
+
+- [INKstrdup](INKstrdup "INKstrdup")
+
+- [INKstrndup](INKstrndup "INKstrndup")
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MemoryAllocationFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MemoryAllocationFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MemoryAllocationFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/MemoryAllocationFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,64 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: 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.
+
+[Prev](INKfwrite) - INKfwrite
+INKmalloc - [Next](INKmalloc)
+## Memory Allocation
+
+Traffic Server provides five routines for allocating and freeing
+memory. These routines correspond to similar routines in the C
+library. For example, `INKrealloc` behaves like the C library
+routine `realloc`.
+
+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, `realloc` does not accept an argument of `NULL` 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.
+
+The memory allocation functions are described below.
+
+****
+- [INKfree](MemoryAllocationFunctions#INKfree)
+- [INKmalloc](INKmalloc)
+- [INKrealloc](INKrealloc)
+- [INKstrndup](INKstrndup)
+- [INKstrndup](INKstrndup)
+
+### INKfree
+
+Frees memory allocated by `INKmalloc` or `INKrealloc`.
+
+**Prototype**
+ ~ `void INKfree (void <em class="replaceable"><code>*ptr`)
+
+**Arguments**
+ ~ `<em class="replaceable"><code>ptr` is a pointer to the memory
+ to deallocate.
+
+**Description**
+ ~ Releases the memory allocated by `INKmalloc` or `INKrealloc`.
+ If `<em class="replaceable"><code>ptr` is `NULL`, then `INKfree`
+ does not perform an operation.
+
+