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 2013/04/18 15:20:24 UTC
[4/7] add sdk docs.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/setting-a-transaction-hook.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/setting-a-transaction-hook.en.rst b/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/setting-a-transaction-hook.en.rst
new file mode 100644
index 0000000..c7c8708
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/setting-a-transaction-hook.en.rst
@@ -0,0 +1,56 @@
+Setting a Transaction Hook
+**************************
+
+.. 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.
+
+If the request does not have the ``Proxy-Authorization`` field set to
+Basic authorization or a valid username/password, then the plugin sends
+the 407 Proxy authorization ``required`` status code back to the client.
+The client will then prompt the user for a username and password, and
+then resend the request.
+
+In the ``handle_dns`` routine, the following lines handle the
+authorization error case:
+
+::
+
+ :::c
+ done:
+ TSHttpTxnHookAdd (txnp, TS_HTTP_SEND_RESPONSE_HDR_HOOK, contp);
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_ERROR);
+
+If ``handle_dns`` does not find the ``Proxy-Authorization`` field set to
+Basic authorization or a valid username/password, then it adds a
+``SEND_RESPONSE_HDR_HOOK`` to the transaction being processed. This
+means that Traffic Server will call the plugin back when sending the
+client response. ``handle_dns`` reenables the transaction with
+``TS_EVENT_HTTP_ERROR``, which means that the plugin wants Traffic
+Server to terminate the transaction.
+
+When Traffic Server terminates the transaction, it sends the client an
+error message. Because of the ``SEND_RESPONSE_HDR_HOOK``, Traffic Server
+calls the plugin back. The ``auth-plugin`` routine calls
+``handle_response`` to send the client a ``407`` status code. When the
+client resends the request with the ``Proxy-Authorization`` field, a new
+transaction begins.
+
+``handle_dns`` calls ``base64_decode`` to decode the username and
+password; ``handle_dns`` also calls ``authorized`` to validate the
+username and password. In this plugin, sample NT code is provided for
+password validation. UNIX programmers can supply their own validation
+mechanism.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/working-with-http-headers.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/working-with-http-headers.en.rst b/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/working-with-http-headers.en.rst
new file mode 100644
index 0000000..a3b382c
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/working-with-http-headers.en.rst
@@ -0,0 +1,98 @@
+Working With HTTP Headers
+*************************
+
+.. 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.
+
+The plugin checks all client request headers for the Proxy-Authorization
+MIME field, which should contain the user name and password. The
+plugin's continuation handler, ``auth-plugin``, calls ``handle_dns`` to
+check the ``Proxy-Authorization`` field. The ``handle_dns`` routine uses
+``TSHttpTxnClientReqGet`` and ``TSMimeHdrFieldFind`` to obtain the
+``Proxy-Authorization`` field:
+
+::
+
+ :::c
+ {
+ TSMBuffer bufp;
+ TSMLoc hdr_loc;
+ TSMLoc field_loc;
+ const char *val;
+ char *user, *password;
+
+ if (!TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
+ TSError ("couldn't retrieve client request header\n");
+ goto done;
+ }
+
+ field_loc = TSMimeHdrFieldFind (bufp, hdr_loc,
+ TS_MIME_FIELD_PROXY_AUTHORIZATION);
+
+If the ``Proxy-Authorization`` field is present, then the plugin checks
+that the authentication type is "Basic", and the user name and password
+are present and valid:
+
+::
+
+ :::c
+ val = TSMimeHdrFieldValueStringGet (bufp, hdr_loc, field_loc, 0, &authval_length);
+ if (!val) {
+ TSError ("no value in Proxy-Authorization field\n");
+ TSHandleMLocRelease (bufp, hdr_loc, field_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ if (strncmp (val, "Basic", 5) != 0) {
+ TSError ("no Basic auth type in Proxy-Authorization\n");
+ TSHandleMLocRelease (bufp, hdr_loc, field_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ val += 5;
+ while ((*val == ' ') || (*val == '\t')) {
+ val += 1;
+ }
+
+ user = base64_decode (val);
+ password = strchr (user, ':');
+ if (!password) {
+ TSError ("no password in authorization information\n");
+ TSfree (user);
+ TSHandleMLocRelease (bufp, hdr_loc, field_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+ *password = '\0';
+ password += 1;
+
+ if (!authorized (user, password)) {
+ TSError ("%s:%s not authorized\n", user, password);
+ TSfree (user);
+ TSHandleMLocRelease (bufp, hdr_loc, field_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ TSfree (user);
+ TSHandleMLocRelease (bufp, hdr_loc, field_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
+ return;
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples/blacklist-plugin.en.rst b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
new file mode 100644
index 0000000..738a189
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin.en.rst
@@ -0,0 +1,107 @@
+The Blacklist Plugin
+********************
+
+.. 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.
+
+The sample blacklisting plugin included in the Traffic Server SDK is
+``blacklist-1.c``. This plugin checks every incoming HTTP client request
+against a list of blacklisted web sites. If the client requests a
+blacklisted site, then the plugin returns an ``Access forbidden``
+message to the client.
+
+The flow of HTTP processing with the blacklist plugin is illustrated in
+the figure titled `"Blacklist
+Plugin" <../../how-to-create-trafficserver-plugins#BlacklistPlugin>`__.
+This example also contains a simple configuration management interface.
+It can read a list of blacklisted sites from a file (``blacklist.txt``)
+that can be updated by a Traffic Server administrator. When the
+configuration file is updated, Traffic Server sends an event to the
+plugin that wakes it up to do some work.
+
+Creating the Parent Continuation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You create the static parent continuation in the mandatory
+``TSPluginInit`` function. This parent continuation effectively **is**
+the plugin: the plugin executes only when this continuation receives an
+event from Traffic Server. Traffic Server passes the event as an
+argument to the continuation's handler function. When you create
+continuations, you must create and specify their handler functions.
+
+You can specify an optional mutex lock when you create continuations.
+The mutex lock protects data shared by asynchronous processes. Because
+Traffic Server has a multi-threaded design, race conditions can occur if
+several threads try to access the same continuation's data.
+
+Here is how the static parent continuation is created in
+``blacklist-1.c``:
+
+::
+
+ :::c
+ void
+ TSPluginInit (int argc, const char *argv[])
+ { ...
+ TSCont contp;
+
+ contp = TSContCreate (blacklist_plugin, NULL);
+ ...
+ }
+
+The handler function for the plugin is ``blacklist_plugin``, and the
+mutex is null. The continuation handler function's job is to handle the
+events that are sent to it; accordingly, the ``blacklist_plugin``
+routine consists of a switch statement that covers each of the events
+that might be sent to it:
+
+::
+
+ :::c
+ static int
+ blacklist_plugin (TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+ switch (event) {
+ case TS_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ default:
+ TSDebug ("blacklist_plugin", "This event was unexpected: %d\n", );
+ break;
+ }
+ return 0;
+ }
+
+When you write handler functions, you have to anticipate any events that
+might be sent to the handler by hooks or by other functions. In the
+Blacklist plugin, ``TS_EVENT_OS_DNS`` is sent because of the global hook
+established in ``TSPluginInit``, ``TS_EVENT_HTTP_SEND_RESPONSE_HDR`` is
+sent because the plugin contains a transaction hook (see `Setting Up a
+Transaction Hook <setting-a-transaction-hook.html>`__). It is good
+practice to have a default case in your switch statements.
+.. toctree::
+ :maxdepth: 2
+
+ setting-a-global-hook.en
+ accessing-the-transaction-being-processed.en
+ setting-up-a-transaction-hook.en
+ working-with-http-header-functions.en
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en.rst b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en.rst
new file mode 100644
index 0000000..084c091
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en.rst
@@ -0,0 +1,61 @@
+Accessing the Transaction Being Processed
+*****************************************
+
+.. 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.
+
+A continuation's handler function is of type ``TSEventFunc``; the
+prototype is as follows:
+
+``static int function_name (TSCont contp, TSEvent event, void *edata)``
+
+In general, the return value of the handler function is not used. The
+continuation argument is the continuation being called back, the event
+is the event being sent to the continuation, and the data pointed to by
+``void *edata`` depends on the type of event. The data types for each
+event type are listed in `Writing Handler
+Functions <../../continuations/writing-handler-functions>`__
+
+The key here is that if the event is an HTTP transaction event, then the
+data passed to the continuation's handler is of type ``TSHttpTxn`` (a
+data type that represents HTTP transactions). Your plugin can then do
+things with the transaction. Here's how it looks in the code for the
+Blacklist plugin's handler:
+
+::
+
+ :::c
+ static int
+ blacklist_plugin (TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+ switch (event) {
+ case TS_EVENT_HTTP_OS_DNS:
+ handle_dns (txnp, contp);
+ return 0;
+ case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
+ handle_response (txnp);
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+ }
+
+For example: when the origin server DNS lookup event is sent,
+``blacklist_plugin`` can call ``handle_dns``\ and pass ``txnp`` as an
+argument.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/setting-a-global-hook.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/setting-a-global-hook.en.rst b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/setting-a-global-hook.en.rst
new file mode 100644
index 0000000..df86efd
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/setting-a-global-hook.en.rst
@@ -0,0 +1,37 @@
+Setting a Global Hook
+*********************
+
+.. 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.
+
+Global hooks are always added in ``TSPluginInit`` using
+``TSHttpHookAdd``. The two arguments of ``TSHttpHookAdd`` are the hook
+ID and the continuation to call when processing the event corresponding
+to the hook. In ``blacklist-1.c``, the global hook is added as follows:
+
+::
+
+ :::c
+ TSHttpHookAdd (TS_HTTP_OS_DNS_HOOK, contp);
+
+Above, ``TS_HTTP_OS_DNS_HOOK`` is the ID for the origin server DNS
+lookup hook and ``contp`` is the parent continuation created earlier.
+
+This means that the Blacklist plugin is called at every origin server
+DNS lookup. When it is called, the handler functio ``blacklist_plugin``
+receives ``TS_EVENT_HTTP_OS_DNS`` and calls ``handle_dns`` to see if the
+request is forbidden.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/setting-up-a-transaction-hook.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/setting-up-a-transaction-hook.en.rst b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/setting-up-a-transaction-hook.en.rst
new file mode 100644
index 0000000..0590e09
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/setting-up-a-transaction-hook.en.rst
@@ -0,0 +1,81 @@
+Setting Up a Transaction Hook
+*****************************
+
+.. 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.
+
+The Blacklist plugin sends "access forbidden" messages to clients if
+their requests are directed to blacklisted hosts. Therefore, the plugin
+needs a transaction hook so it will be called back when Traffic Server's
+HTTP state machine reaches the "send response header" event. In the
+Blacklist plugin's ``handle_dns`` routine, the transaction hook is added
+as follows:
+
+::
+
+ :::c
+ TSMutexLock (sites_mutex);
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host, sites[i], host_length) == 0) {
+ printf ("blacklisting site: %s\n", sites[i]);
+ TSHttpTxnHookAdd (txnp,
+ TS_HTTP_SEND_RESPONSE_HDR_HOOK,
+ contp);
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_ERROR);
+ TSMutexUnlock (sites_mutex);
+ return;
+ }
+ }
+ TSMutexUnlock (sites_mutex);
+ done:
+ TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
+
+This code fragment shows some interesting features. The plugin is
+comparing the requested site to the list of blacklisted sites. While the
+plugin is using the blacklist, it must acquire the mutex lock for the
+blacklist to prevent configuration changes in the middle of a
+blacklisting operation. If the requested site is blacklisted, then the
+following things happen:
+
+1. A transaction hook is added with ``TSHttpTxnHookAdd``; the plugin is
+ called back at the "send response header" event (i.e., the plugin
+ sends an Access forbidden message to the client). You can see that in
+ order to add a transaction hook, you need a handle to the transaction
+ being processed.
+
+2. The transaction is reenabled using ``TSHttpTxnReenable`` with
+ ``TS_EVENT_HTTP_ERROR`` as its event argument. Reenabling with an
+ error event tells the HTTP state machine to stop the transaction and
+ jump to the "send response header" state. Notice that if the
+ requested site is not blacklisted, then the transaction is reenabled
+ with the ``TS_EVENT_HTTP_CONTINUE`` event.
+
+3. The string and ``TSMLoc`` data stored in the marshal buffer ``bufp``
+ is released by ``TSHandleMLocRelease`` (see `Release Marshal Buffer
+ Handles <RlsMarshalBufHandles.html>`__). Release these handles before
+ reenabling the transaction.
+
+In general, whenever the plugin is doing something to a transaction, it
+must reenable the transaction when it is finished. In other words: every
+time your handler function handles a transaction event, it must call
+``TSHttpTxnReenable`` when it is finished. Similarly, after your plugin
+handles session events (``TS_EVENT_HTTP_SSN_START`` and
+``TS_EVENT_HTTP_SSN_CLOSE``), it must reenable the session with
+``TSHttpSsnReenable``. Reenabling the transaction twice in the same
+plugin routine is a bad error.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/working-with-http-header-functions.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/working-with-http-header-functions.en.rst b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/working-with-http-header-functions.en.rst
new file mode 100644
index 0000000..bb510e3
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples/blacklist-plugin/working-with-http-header-functions.en.rst
@@ -0,0 +1,63 @@
+Working with HTTP Header Functions
+**********************************
+
+.. 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.
+
+The Blacklist plugin examines the host header in every client
+transaction. This is done in the ``handle_dns`` routine, using
+``TSHttpTxnClientIPGet``, ``TSHttpHdrUrlGet``, and ``TSUrlHostGet``.
+
+::
+
+ :::c
+ static void
+ handle_dns (TSHttpTxn txnp, TSCont contp)
+ {
+ TSMBuffer bufp;
+ TSMLoc hdr_loc;
+ TSMLoc url_loc;
+ const char *host;
+ int i;
+
+ if (!TSHttpTxnClientIPGet (txnp, &bufp, &hdr_loc)) {
+ TSError ("couldn't retrieve client request header\n");
+ goto done;
+ }
+
+ url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
+
+ if (!url_loc) {
+ TSError ("couldn't retrieve request url\n");
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+ host = TSUrlHostGet (bufp, url_loc, NULL);
+ if (!host) {
+ TSError ("couldn't retrieve request hostname\n");
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+ goto done;
+ }
+
+To access the host header, the plugin must first get the client request,
+retrieve the URL portion, and then obtain the host header. See `HTTP
+Headers <../../http-headers>`__ for more information about these calls.
+See `Release Marshal Buffer
+Handles <../../http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles>`__
+for guidelines on using ``TSHandleMLocRelease``.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/how-to-create-trafficserver-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/how-to-create-trafficserver-plugins.en.rst b/doc/source/sdk/how-to-create-trafficserver-plugins.en.rst
new file mode 100644
index 0000000..5b8bc1d
--- /dev/null
+++ b/doc/source/sdk/how-to-create-trafficserver-plugins.en.rst
@@ -0,0 +1,227 @@
+How to Create Traffic Server Plugins
+************************************
+
+.. 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.
+
+.. toctree::
+ :maxdepth: 2
+
+ how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en
+
+This chapter provides a foundation for designing and writing plugins.
+Reading this chapter will help you to understand:
+
+- The asynchronous event mode. This is the design paradigm used
+ throughout Traffic Server; plugins must also follow this design. It
+ includes the callback mechanism for Traffic Server to "wake up" your
+ plugin and put it to work.
+
+- Traffic Server's HTTP processing, with an overview of the HTTP state
+ machine.
+
+- How plugins can hook onto and modify/extend Traffic Server's HTTP
+ processing.
+
+- A `roadmap for writing plugins <roadmap-for-creating-plugins>`__,
+ with an overview of the functionality provided by the Traffic Server
+ API.
+
+The Asynchronous Event Model
+----------------------------
+
+Traffic Server is a multi-threaded process. There are two main reasons
+why a server might use multiple threads:
+
+- To take advantage of the concurrency available with multiple CPUs and
+ multiple I/O devices.
+
+- To manage concurrency from having many simultaneous client
+ connections. For example, a server could create one thread for each
+ connection, allowing the operating system (OS) to control switching
+ between threads.
+
+Traffic Server uses multiple threads for the first reason. However,
+Traffic Server does not use a separate OS thread per transaction because
+it would not be efficient when handling thousands of simultaneous
+connections.
+
+Instead, Traffic Server provides special event-driven mechanisms for
+efficiently scheduling work: the event system and continuations. The
+**event system** is used to schedule work to be done on threads. A
+**continuation** is a passive, event-driven state machine that can do
+some work until it reaches a waiting point; it then sleeps until it
+receives notification that conditions are right for doing more work. For
+example, HTTP state machines (which handle HTTP transactions) are
+implemented as continuations.
+
+Continuation objects are used throughout Traffic Server. Some might live
+for the duration of the Traffic Server process, while others are created
+(perhaps by other continuations) for specific needs and then destroyed.
+`Traffic Server Internals <#TSInternals>`__ (below) shows how the major
+components of Traffic Server interact. Traffic Server has several
+**processors**, such as *cache processor* and *net processor*, that
+consolidate cache or network I/O tasks. Processors talk to the event
+system and schedule work on threads. An executing thread calls back a
+continuation by sending it an event. When a continuation receives an
+event, it wakes up, does some work, and either destroys itself or goes
+back to sleep & waits for the next event.
+
+**Traffic Server Internals** {#TSInternals}
+
+.. figure:: /images/sdk/event_sys80.jpg
+ :alt: Traffic Server Internals
+
+ Traffic Server Internals
+Plugins are typically implemented as continuations. All of the sample
+code plugins (except ``hello-world``) are continuations that are created
+when Traffic Server starts up; they then wait for events that trigger
+them into activity.
+
+**Traffic Server with Plugins** {#TSwithPlugins}
+
+.. figure:: /images/sdk/evt_plugin120.jpg
+ :alt: Traffic Server with Plugins
+
+ Traffic Server with Plugins
+A plugin may consist of just one static continuation that is called
+whenever certain events happen. Examples of such plugins include
+``blacklist-1.c``, ``basic-auth.c``, and ``redirect-1.c``.
+Alternatively, a plugin might dynamically create other continuations as
+needed. Transform plugins are built in this manner: a static parent
+continuation checks all transactions to see if any are transformable;
+when a transaction is transformable, the static continuation creates a
+type of continuation called a **vconnection**. The vconnection lives as
+long as it takes to complete the transform and then destroys itself.
+This design can be seen in all of the sample transform plugins. Plugins
+that support new protocols also have this architecture: a static
+continuation listens for incoming client connections and then creates
+transaction state machines to handle each protocol transaction.
+
+When you write plugins, there are several ways to send events to
+continuations. For HTTP plugins, there is a "hook" mechanism that
+enables the Traffic Server HTTP state machine to send your plugin wakeup
+calls when needed. Additionally, several Traffic Server API functions
+trigger Traffic Server sub-processes to send events to plugins:
+``TSContCall``, ``TSVConnRead``, ``TSCacheWrite``, and
+``TSMgmtUpdateRegister``, to name a few.
+
+Traffic Server HTTP State Machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Traffic Server performs sophisticated HTTP caching and proxying.
+Important features include checking for alternates and document
+freshness, filtering, supporting cache hierarchies, and hosting. Traffic
+Server handles thousands of client requests at a time and each request
+is handled by an HTTP state machine. These machines follow a complex
+state diagram that includes all of the states required to support
+Traffic Server's features. The Traffic Server API provides hooks to a
+subset of these states, chosen for their relevance to plugins. You can
+view the API hooks and corresponding HTTP states in the `HTTP
+Transaction State
+Diagram <../http-hoooks-and-transactions#HHTTPTransactionStateDiagram>`__.
+
+The example in this section (below) explains how a plugin typically
+intervenes and extends Traffic Server's processing of an HTTP
+transaction. Complete details about hooking on to Traffic Server
+processes are provided in `HTTP Hooks and
+Transactions <HTTPHooksAndTransactions.html>`__.
+
+HTTP Transaction
+^^^^^^^^^^^^^^^^
+
+An HTTP transaction consists of a client request for a web document and
+Traffic Server's response. The response could be the requested web
+server content or it could be an error message. The content could come
+from the Traffic Server cache or Traffic Server might fetch it from the
+origin server. The following diagram shows some states in a typical
+transaction - specifically, the scenario wherein content is served from
+cache.
+
+**Simplified HTTP Transaction** {#SimplifiedHTTPTransaction}
+
+.. figure:: /images/sdk/transact75.jpg
+ :alt: Simplified HTTP Transaction
+
+ Simplified HTTP Transaction
+In the diagram above, Traffic Server accepts the client connection,
+reads the request headers, looks up the origin server's IP address, and
+looks for the requested content in the cache. If the content is not in
+the cache (a "miss"), then Traffic Server opens a connection to the
+origin server and issues a request for the content. If the content is in
+the cache (a "hit"), then Traffic Server checks it for freshness.
+
+If the content is fresh, then Traffic Server sends a reply header to the
+client. If the content is stale, then Traffic Server opens a connection
+to the origin server and requests the content. The figure above,
+`Simplified HTTP Transaction <#SimplifiedHTTPTransaction>`__, does *not*
+show behavior in the event of an error. If there is an error at a any
+stage, then the HTTP state machine jumps to the "send reply header"
+state and sends a reply. If the reply is an error, then the transaction
+closes. If the reply is not an error, then Traffic Server first sends
+the response content before it closes the transaction.
+
+**API Hooks Corresponding to States** {#APIHooksCorrespondingtoStates}
+
+.. figure:: /images/sdk/transact_hook75.jpg
+ :alt: API Hooks Corresponding to States Listed in
+
+ API Hooks Corresponding to States Listed in
+You use hooks as triggers to start your plugin. The name of a hook
+reflects the Traffic Server state that was *just completed*. For
+example, the "OS DNS lookup" hook wakes up a plugin right *after* the
+origin server DNS lookup. For a plugin that requires the IP address of
+the requested origin server, this hook is the right one to use. The
+Blacklist plugin works in this manner, as shown in the `Blacklist
+Plugin <#BlacklistPlugin>`__ diagram below.
+
+**Blacklist Plugin** {#BlacklistPlugin}
+
+.. figure:: /images/sdk/blacklist75.jpg
+ :alt: Blacklist Plugin
+
+ Blacklist Plugin
+Traffic Server calls the Blacklist plugin right after the origin server
+DNS lookup. The plugin checks the requested host against a list of
+blacklisted servers; if the request is allowed, then the transaction
+proceeds. If the host is forbidden, then the Blacklist plugin sends the
+transaction into an error state. When the HTTP state machine gets to the
+"send reply header" state, it then calls the Blacklist plugin to provide
+the error message that's sent to the client.
+
+Types of Hooks
+^^^^^^^^^^^^^^
+
+The Blacklist plugin's hook to the "origin server DNS lookup" state is a
+****global hook****, meaning that the plugin is called *every time*
+there's an HTTP transaction with a DNS lookup event. The plugin's hook
+to the "send reply header" state is a **tr**\ ***ansaction hook***,
+meaning that this hook is only invoked for *specified transactions* (in
+the Blacklist example, it's only used for requests to blacklisted
+servers). Several examples of setting up hooks are provided in the code
+example chapters: `Header-Based Plugin
+Examples <../header-based-plugin-examples>`__ and `HTTP Transformation
+Plugins <../http-transformation-plugin>`__
+
+**Header manipulation plugins**, such as filtering, basic authorization,
+or redirects, usually have a global hook to the DNS lookup or the read
+request header states. If specific actions need to be done to the
+transaction further on, then the plugin adds itself to a transaction
+hook. **Transformation plugins** require a \*\*global hook \*\*to check
+all transactions for transformability followed by a **transform hook**,
+which is a type of transaction hook used specifically for transforms.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst b/doc/source/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
new file mode 100644
index 0000000..191b224
--- /dev/null
+++ b/doc/source/sdk/how-to-create-trafficserver-plugins/roadmap-for-creating-plugins.en.rst
@@ -0,0 +1,90 @@
+Roadmap for Creating Plugins
+****************************
+
+.. 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.
+
+This chapter has provided an overview of Traffic Server's HTTP
+processing, API hooks, and the asynchronous event model. Next, you must
+understand the capabilities of Traffic Server API functions. These are
+quite broad:
+
+- **HTTP header manipulation functions**
+
+ Obtain information about and manipulate HTTP headers, URLs, & MIME
+ headers.
+
+- **HTTP transaction functions**
+
+ Get information about and modify HTTP transactions (for example: get
+ the client IP associated to the transaction; get the server IP; get
+ parent proxy information)
+
+- **IO functions**
+
+ Manipulate vconnections (virtual connections, used for network and
+ disk I/O)
+
+- **Network connection functions**
+
+ Open connections to remote servers.
+
+- **Statistics functions**
+
+ Define and compute statistics for your plugin's activity.
+
+- **Traffic Server management functions**
+
+ Obtain values for Traffic Server configuration and statistics
+ variables.
+
+Below are some guidelines for creating a plugin:
+
+1. Decide what you want your plugin to do, based on the capabilities of
+ the API and Traffic Server. Two main kinds of example plugins
+ provided with this SDK are HTTP-based (includes header-based and
+ response transform plugins), and non-HTTP-based (a protocol plugin).
+ These examples are discussed in the next three chapters.
+
+2. Determine where your plugin needs to hook on to Traffic Server's HTTP
+ processing (view the `HTTP Transaction State
+ Diagram <../http-hoooks-and-transactions#HTTPTransactionStateDiagram>`__
+
+3. Read `Header-Based Plugin
+ Examples <../header-based-plugin-examples>`__ to learn the basics of
+ writing plugins: creating continuations and setting up hooks. If you
+ want to write a plugin that transforms data, then read `HTTP
+ Transformation Plugins <HTTPTransformationPlugins.html>`__.
+
+4. Figure out what parts of the Traffic Server API you need to use and
+ then read about the details of those APIs in this manual's reference
+ chapters.
+
+5. Compile and load your plugin (see `Getting
+ Started <../getting-started>`__
+
+6. Depending on your plugin's functionality, you might start testing it
+ by issuing requests by hand and checking for the desired behavior in
+ Traffic Server log files. See the ***Traffic Server Administrator's
+ Guide*** for information about Traffic Server logs.
+
+7. You can test the performance of Traffic Server running with your
+ plugin using SDKTest. You can also customize SDKTest to perform
+ functional testing on your plugin; for more information see the
+ ***Traffic Server SDKTest User's Guide***.
+
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/http-headers.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/http-headers.en.rst b/doc/source/sdk/http-headers.en.rst
new file mode 100644
index 0000000..811cf1c
--- /dev/null
+++ b/doc/source/sdk/http-headers.en.rst
@@ -0,0 +1,141 @@
+HTTP Headers
+************
+
+.. 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.
+
+This chapter explains the functions used to manipulate HTTP headers.
+
+.. toctree::
+ :maxdepth: 2
+
+ http-headers/guide-to-trafficserver-http-header-system.en
+ http-headers/marshal-buffers.en
+ http-headers/http-headers.en
+ http-headers/urls.en
+ http-headers/mime-headers.en
+
+About HTTP Headers
+------------------
+
+An ***HTTP message*** consists of the following:
+
+- HTTP header
+- body
+- trailer
+
+The ***HTTP header*** consists of:
+
+- A request or response line
+
+ - An HTTP **request line** contains a method, URL, and version
+ - A **response line** contains a version, status code, and reason
+ phrase
+
+- A MIME header
+
+A **MIME header** is comprised of zero or more MIME fields. A **MIME
+field** is composed of a field name, a colon, and (zero or more) field
+values. The values in a field are separated by commas. An HTTP header
+containing a request line is usually referred to as a **request**. The
+following example shows a typical request header.
+
+::
+
+ ::::text
+ GET http://www.tiggerwigger.com/ HTTP/1.0
+ Proxy-Connection: Keep-Alive
+ User-Agent: Mozilla/5.0 [en] (X11; I; Linux 2.2.3 i686)
+ Host: www.tiggerwigger.com
+ Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */
+ *
+
+ Accept-Encoding: gzip
+ Accept-Language: en
+ Accept-Charset: iso-8859-1, *, utf-8
+
+The **response header** for the above request might look like the
+following:
+
+::
+
+ ::::plain
+ HTTP/1.0 200 OK
+ Date: Fri, 13 Nov 2009 06:57:43 GMT
+ Content-Location: http://locutus.tiggerwigger.com/index.html
+ Etag: "07db14afa76be1:1074"
+ Last-Modified: Thu, 05 Nov 2009 20:01:38 GMT
+ Content-Length: 7931
+ Content-Type: text/html
+ Server: Microsoft-IIS/4.0
+ Age: 922
+ Proxy-Connection: close
+
+The following figure illustrates an HTTP message with an expanded HTTP
+header.
+
+**Figure 10.1. HTTP Request/Response and Header Structure**
+
+.. figure:: /images/sdk/http_header_struct.jpg
+ :alt: HTTP Request/Response and Header Structure
+
+ HTTP Request/Response and Header Structure
+The figure below shows example HTTP request and response headers.
+
+**Figure 10.2. Examples of HTTP Request and Response Headers**
+
+.. figure:: /images/sdk/http_headers.jpg
+ :alt: Examples of HTTP Request and Response Headers
+
+ Examples of HTTP Request and Response Headers
+The marshal buffer or ``TSMBuffer`` 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 the marshal
+buffer. Whenever you manipulate an object, you must require the handle
+to the object (``TSMLoc``) and the marshal buffer containing the object
+(``TSMBuffer``).
+
+**Figure 10.3. Marshal Buffers and Header Locations**
+
+.. figure:: /images/sdk/marshall_buffers.jpg
+ :alt: Marshal Buffers and Header Locations
+
+ Marshal Buffers and Header Locations
+The figure above shows the following:
+
+- The marshal buffer containing the HTTP request, ``reqest_bufp``
+
+- ``TSMLoc`` location pointer for the HTTP header (``http_hdr_loc``)
+
+- ``TSMLoc`` location pointer for the request URL (``url_loc``)
+
+- ``TSMLoc`` location pointers for the MIME header (``mime_hdr_loc``)
+
+- ``TSMLoc`` location pointers for MIME fields (``fieldi_loc``)
+
+- ``TSMLoc`` location pointer for the next duplicate MIME field
+ (``next_dup_loc``)
+
+The diagram also shows that an HTTP header contains pointers to the URL
+location and the MIME header location. You can obtain the URL location
+from an HTTP header using the function ``TSHttpHdrUrlGet``. To work with
+MIME headers, you can pass either a MIME header location or an HTTP
+header location to MIME header functions . If you pass an HTTP header to
+a MIME header function, then the system locates the associated MIME
+header and executes the MIME header function on the MIME header
+location.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system.en.rst b/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system.en.rst
new file mode 100644
index 0000000..9fc32bd
--- /dev/null
+++ b/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system.en.rst
@@ -0,0 +1,63 @@
+Guide to Traffic Server HTTP Header System
+
+.. 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.
+
+
+No Null-Terminated Strings
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's not safe to assume that string data contained in marshal buffers
+(such as URLs and MIME fields) is stored in null-terminated string
+copies. Therefore, your plugins should always use the length parameter
+when retrieving or manipulating these strings. You **cannot** pass in
+``NULL`` for string-length return values; string values returned from
+marshall buffers are not null-terminated. If you need a null-terminated
+value, then use ``TSstrndup`` to automatically null-terminate a string.
+The strings that come back and are not null-terminated **cannot** be
+passed into the common ``str*()`` routines
+
+.. figure:: /images/docbook/note.png
+ :alt: [Note]
+
+ [Note]
+**Note**
+
+Values returned from a marshall buffer can be ``NULL``, which means the
+field or object requested does not exist.
+
+For example (from the ``blacklist-1`` sample):
+
+::
+
+ :::c
+ char *host_string;
+ int host_length;
+ host_string = TSUrlHostGet (bufp, url_loc, &host_length);
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host_string, sites[i], host_length) == 0) {
+ ...
+ }
+
+See the sample plugins for additional examples.
+.. toctree::
+ :maxdepth: 2
+
+ duplicate-mime-fields-are-not-coalesced.en
+ mime-fields-always-belong-to-an-associated-mime-header.en
+ release-marshal-buffer-handles.en
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.rst b/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.rst
new file mode 100644
index 0000000..14849a1
--- /dev/null
+++ b/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.rst
@@ -0,0 +1,30 @@
+Duplicate MIME Fields Are Not Coalesced
+***************************************
+
+.. 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.
+
+MIME headers can contain more than one MIME field with the same name.
+Earlier versions of Traffic Server joined multiple fields with the same
+name into one field with composite values. This behavior came at a
+performance cost and caused interoperability problems with older clients
+and servers. Therefore, this version of Traffic Server does not coalesce
+duplicate fields.
+
+Properly-behaving plugins should check for the presence of duplicate
+fields and then iterate over the duplicate fields via
+```TSMimeHdrFieldNextDup`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#af2d776615afe959ed7c3639830a7061f>`__.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.rst b/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.rst
new file mode 100644
index 0000000..39b5fe0
--- /dev/null
+++ b/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.rst
@@ -0,0 +1,70 @@
+MIME Fields Always Belong to an Associated MIME Header
+
+.. 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.
+
+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
+``TSMimeField*`` 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
+**``TSMimeHdrField``** series, which require you to specify the location
+of the parent header along with the location of the MIME field. For
+every deprecated *``TSMimeField``* function, there is a new, preferred
+``TSMimeHdrField*`` function. Therefore, you should use the
+**``TSMimeHdrField``** functions instead of the deprecated
+*``TSMimeField``* series. Examples are provided below.
+
+Instead of:
+
+::
+
+ :::c
+ TSMLoc TSMimeFieldCreate (TSMBuffer bufp)
+
+You should use:
+
+::
+
+ :::c
+ TSMLoc TSMimeHdrFieldCreate (TSMBuffer bufp, TSMLoc hdr)
+
+Instead of:
+
+::
+
+ :::c
+ void TSMimeFieldCopyValues (TSMBuffer dest_bufp, TSMLoc dest_offset,
+ TSMBuffer src_bufp, TSMLoc src_offset)
+
+You should use:
+
+::
+
+ :::c
+ void TSMimeHdrFieldCopyValues (TSMBuffer dest_bufp, TSMLoc dest_hdr,
+ TSMLoc dest_field, TSMBuffer src_bufp, TSMLoc src_hdr, TSMLoc
+ src_field)
+
+In the ``TSMimeHdrField*`` function prototypes, the ``TSMLoc`` field
+corresponds to the ``TSMLoc`` offset used the deprecated
+``TSMimeField*`` functions (see the discussion of parent ``TSMLoc`` in
+the following section).
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles.en.rst b/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles.en.rst
new file mode 100644
index 0000000..9e7d55d
--- /dev/null
+++ b/doc/source/sdk/http-headers/guide-to-trafficserver-http-header-system/release-marshal-buffer-handles.en.rst
@@ -0,0 +1,88 @@
+Release Marshal Buffer Handles
+******************************
+
+.. 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.
+
+When you fetch a component object or create a new object, you get back a
+handle to the object location. The handle is either an ``TSMLoc`` for an
+object location or ``char *`` for a string location. You can manipulate
+the object through these handles, but when you are finished you need to
+release the handle to free up system resources.
+
+The general guideline is to release all ``TSMLoc`` and string handles
+you retrieve. The one exception is the string returned by
+``TSUrlStringGet``, which must be freed by a call to ``TSfree``.
+
+The handle release functions expect three arguments: the marshal buffer
+containing the data, the location of the parent object, and the location
+of the object to be released. The parent location is usually clear from
+the creation of the ``TSMLoc`` or string. For example, if your plugin
+had the following calls:
+
+::
+
+ ::::c
+ url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
+ host_string = TSUrlHostGet (bufp, url_loc, &host_length);
+
+then your plugin would have to call:
+
+::
+
+ ::::c
+ TSHandleMLocRelease (bufp, hdr_loc, url_loc);
+
+If an ``TSMLoc`` is obtained from a transaction, then it does not have a
+parent ``TSMLoc``. Use the null ``TSMLoc`` constant ``TS_NULL_MLOC`` as
+its parent. For example, if your plugin calls:
+
+::
+
+ ::::c
+ TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc);
+
+then you must release ``hdr_loc`` with:
+
+::
+
+ ::::c
+ TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
+
+You need to use ``TS_NULL_MLOC`` to release any ``TSMLoc`` handles
+retrieved by the ``TSHttpTxn*Get`` functions.
+
+Here's an example using a new ``TSMimeHdrField`` function:
+
+::
+
+ ::::c
+ TSHttpTxnServerRespGet( txnp, &resp_bufp, &resp_hdr_loc );
+ new_field_loc = TSMimeHdrFieldCreate (resp_bufp, resp_hdr_loc);
+ TSHandleMLocRelease ( resp_bufp, resp_hdr_loc, new_field_loc);
+ TSHandleMLocRelease ( resp_bufp, TS_NULL_MLOC, resp_hdr_loc);
+
+See the sample plugins for many more examples.
+
+.. figure:: /images/docbook/tip.png
+ :alt: [Tip]
+
+ [Tip]
+**Tip**
+
+You should release handles before reenabling the HTTP transaction. In
+other words, call ``TSHandleMLocRelease`` before ``TSHttpTxnReenable``.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/http-headers/http-headers.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/http-headers/http-headers.en.rst b/doc/source/sdk/http-headers/http-headers.en.rst
new file mode 100644
index 0000000..d8b1c40
--- /dev/null
+++ b/doc/source/sdk/http-headers/http-headers.en.rst
@@ -0,0 +1,172 @@
+HTTP Headers
+************
+
+.. 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.
+
+The Traffic Server API HTTP header functions enable you to work with
+HTTP header data stored in marshal buffers.
+
+The HTTP header data structure is a parsed version of the HTTP header
+defined in the HTTP protocol specification. An HTTP header is composed
+of a request or response line followed by zero or more MIME fields. In
+fact, an HTTP header is a subclass of a MIME header; all of the MIME
+header routines operate on HTTP headers.
+
+An HTTP **request line** is composed of a method, a URL, and version. A
+**response line** is composed of a version, status code, and reason
+phrase. See `About HTTP Headers <../http-headers#AboutHTTPHeaders>`__
+for additional details and examples.
+
+To facilitate fast comparisons and reduce storage size, Traffic Server
+defines several pre-allocated method names. These names correspond to
+the methods defined in the HTTP 1.1 specification
+
+``TS_HTTP_METHOD_CONNECT``
+ "CONNECT"
+
+``TS_HTTP_METHOD_DELETE``
+ "DELETE"
+
+``TS_HTTP_METHOD_GE``
+ "GET"
+
+``TS_HTTP_METHOD_HEAD``
+ "HEAD"
+
+``TS_HTTP_METHOD_ICP_QUERY``
+ "ICP\_QUERY"
+
+``TS_HTTP_METHOD_OPTIONS``
+ "OPTIONS"
+
+``TS_HTTP_METHOD_POST``
+ "POST"
+
+``TS_HTTP_METHOD_PURGE``
+ "PURGE"
+
+``TS_HTTP_METHOD_PUT``
+ "PUT"
+
+``TS_HTTP_METHOD_TRACE``
+ "TRACE"
+
+Traffic Server also defines several common values that appear in HTTP
+headers.
+
+``TS_HTTP_VALUE_BYTES``
+ "bytes"
+
+``TS_HTTP_VALUE_CHUNKED``
+ "chunked"
+
+``TS_HTTP_VALUE_CLOSE``
+ "close"
+
+``TS_HTTP_VALUE_COMPRESS``
+ "compress"
+
+``TS_HTTP_VALUE_DEFLATE``
+ "deflate"
+
+``TS_HTTP_VALUE_GZIP``
+ "gzip"
+
+``TS_HTTP_VALUE_IDENTITY``
+ "identity"
+
+``TS_HTTP_VALUE_KEEP_ALIVE``
+ "keep-alive"
+
+``TS_HTTP_VALUE_MAX_AGE``
+ "max-age"
+
+``TS_HTTP_VALUE_MAX_STALE``
+ "max-stale"
+
+``TS_HTTP_VALUE_MIN_FRESH``
+ "min-fresh"
+
+``TS_HTTP_VALUE_MUST_REVALIDATE``
+ "must-revalidate"
+
+``TS_HTTP_VALUE_NONE``
+ "none"
+
+``TS_HTTP_VALUE_NO_CACHE``
+ "no-cache"
+
+``TS_HTTP_VALUE_NO_STORE``
+ "no-store"
+
+``TS_HTTP_VALUE_NO_TRANSFORM``
+ "no-transform"
+
+``TS_HTTP_VALUE_ONLY_IF_CACHED``
+ "only-if-cached"
+
+``TS_HTTP_VALUE_PRIVATE``
+ "private"
+
+``TS_HTTP_VALUE_PROXY_REVALIDATE``
+ "proxy-revalidate"
+
+``TS_HTTP_VALUE_PUBLIC``
+ "public"
+
+``TS_HTTP_VALUE_S_MAX_AGE``
+ "s-maxage"
+
+The method names and header values above are defined in ``ts.h`` as
+``const char*`` strings. When Traffic Server sets a method or a header
+value, it checks to make sure that the new value is one of the known
+values. If it is, then it stores a pointer into a global table (instead
+of storing the known value in the marshal buffer). The method names and
+header values listed above are also pointers into this table. This
+allows simple pointer comparison of the value returned from
+``TSHttpMethodGet`` with one of the values listed above. It is also
+recommended that you use the above values when referring to one of the
+known schemes, since this removes the possibility of a spelling error.
+
+The **HTTP Header Functions** are listed below:
+
+- ```TSHttpHdrClone`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#abd410a18e8bc73298302c4ff3ee9b0c6>`__
+- ```TSHttpHdrCopy`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a5ff26f3836a74e885113423dfd4d9ed6>`__
+- ```TSHttpHdrCreate`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a8bbd8c2aaf70fb579af4520053fd5e10>`__
+- ```TSHttpHdrDestroy`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a500ac4aae8f369221cf3ac2e3ce0d2a0>`__
+- ```TSHttpHdrLengthGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a3afc557e4e99565ab81bf6437b65181b>`__
+- ```TSHttpHdrMethodGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a358627e05506baa5c8270891652ac4d2>`__
+- ```TSHttpHdrMethodSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a32bbcacacbef997e89c04cc3898b0ca4>`__
+- ```TSHttpHdrPrint`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a7c88f30d6325a461fb038e6a117b3731>`__
+- ```TSHttpHdrReasonGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a8b1609e9c8a8a52ebe7762b6109d3bef>`__
+- ```TSHttpHdrReasonLookup`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ab49fded8874b8e3e17cf4395c9832378>`__
+- ```TSHttpHdrReasonSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ab86e5f5e7c0af2092c77327d2e0d3b23>`__
+- ```TSHttpHdrStatusGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac29d5acc357a0c82c83874f42b1e487b>`__
+- ```TSHttpHdrStatusSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#af34459170ed7f3b002ddd597ae38af12>`__
+- ```TSHttpHdrTypeGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#afc1c6f0a3258c4bc6567805df1db1ca3>`__
+- ```TSHttpHdrTypeSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a86058d8590a665dbf43a529714202d3f>`__
+- ```TSHttpHdrUrlGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#af149d7b5c1b8902363afc0ad658c494e>`__
+- ```TSHttpHdrUrlSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ad935635a3918575fa6cca6843c474cfe>`__
+- ```TSHttpHdrVersionGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a90cc8783f5d0bc159f226079aa0104e4>`__
+- ```TSHttpHdrVersionSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aa2a2c03399cdc8dc39b8756f13e7f189>`__
+- ```TSHttpParserClear`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a7cb1b53b4464dc71287351616d6e7509>`__
+- ```TSHttpParserCreate`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a6075fb4e8fc41eb75d640f258722115b>`__
+- `TSHttpParserDestroy <link/to/doxyge>`__
+- ```TSHttpHdrParseReq`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a64193b3c9ddff8bc434c1cc9332004cc>`__
+- ```TSHttpHdrParseResp`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a03c8a14b6ab2b7896ef0e4005222ecff>`__
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/http-headers/marshal-buffers.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/http-headers/marshal-buffers.en.rst b/doc/source/sdk/http-headers/marshal-buffers.en.rst
new file mode 100644
index 0000000..9271a9b
--- /dev/null
+++ b/doc/source/sdk/http-headers/marshal-buffers.en.rst
@@ -0,0 +1,56 @@
+Marshal Buffers
+***************
+
+.. 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.
+
+A **marshal buffer**, or ``TSMBuffer``, 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 (``TSMLoc``) and the marshal buffer containing the object
+(``TSMBuffer``).
+
+Routines exist for manipulating the object based on these two pieces of
+information. For example, see one of the following:
+
+- `HTTP Headers <http-headers>`__
+- `URLs <urls>`__
+- `MIME Headers <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.
+
+.. figure:: /images/docbook/caution.png
+ :alt: [Caution]
+
+ [Caution]
+**Caution**
+
+Any marshal buffer fetched by ``TSHttpTxn*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:
+
+- ```TSHttpTxnCachedReqGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a889b626142157077f4f3cfe479e8b8e2>`__
+- ```TSHttpTxnCachedRespGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#ae8f24b8dabb5008ad11620a11682ffd6>`__
+- ```TSHttpTxnClientReqGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#acca66f22d0f87bf8f08478ed926006a5>`__
+- ```TSHttpTxnClientRespGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a92349c8363f72b1f6dfed3ae80901fff>`__
+- ```TSHttpTxnServerReqGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aac2343a8b47bf9150f3ff7cd4e692d57>`__
+- ```TSHttpTxnServerRespGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a39e8bfb199eadabb54c067ff25a9a400>`__
+- ```TSHttpTxnTransformRespGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a20367f5469e8b7e73621c1316091d578>`__
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/http-headers/mime-headers.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/http-headers/mime-headers.en.rst b/doc/source/sdk/http-headers/mime-headers.en.rst
new file mode 100644
index 0000000..ec9b0e8
--- /dev/null
+++ b/doc/source/sdk/http-headers/mime-headers.en.rst
@@ -0,0 +1,437 @@
+MIME Headers
+************
+
+.. 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.
+
+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.
+
+::
+
+ :::text
+ 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.
+
+::
+
+ :::text
+ 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>`__). The actual data is stored in a
+marshal buffer; the MIME header functions operate on a marshal buffer
+and a location (``TSMLoc``) within the buffer.
+
+After a call to ``TSMimeHdrFieldDestroy``, ``TSMimeHdrFieldRemove``, or
+``TSUrlDestroy`` is made, you must deallocate the ``TSMLoc`` handle with
+a call to ``TSHandleMLocRelease``. You do not need to deallocate a
+``NULL`` handles. For example: if you call
+``TSMimeHdrFieldValueStringGet`` to get the value of the content type
+field and the field does not exist, then it returns ``TS_NULL_MLOC``. In
+such a case, you wouldn't need to deallocate the handle with a call to
+``TSHandleMLocRelease``.
+
+The location (``TSMLoc``) in the `MIME header
+functions <#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
+```TSMimeHdrCopy`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a6e0a392b2e072db8e7f1d795151203b4>`__).
+
+**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 ``TSMimeHdrFieldNextDup``.
+
+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.
+
+``TS_MIME_FIELD_ACCEPT``
+ "Accept"
+ ``TS_MIME_LEN_ACCEPT``
+
+``TS_MIME_FIELD_ACCEPT_CHARSET``
+ "Accept-Charset"
+ ``TS_MIME_LEN_ACCEPT_CHARSET``
+
+``TS_MIME_FIELD_ACCEPT_ENCODING``
+ "Accept-Encoding"
+ ``TS_MIME_LEN_ACCEPT_ENCODING``
+
+``TS_MIME_FIELD_ACCEPT_LANGUAGE``
+ "Accept-Language"
+ ``TS_MIME_LEN_ACCEPT_LANGUAGE``
+
+``TS_MIME_FIELD_ACCEPT_RANGES``
+ "Accept-Ranges"
+ ``TS_MIME_LEN_ACCEPT_RANGES``
+
+``TS_MIME_FIELD_AGE``
+ "Age"
+ ``TS_MIME_LEN_AGE``
+
+``TS_MIME_FIELD_ALLOW``
+ "Allow"
+ ``TS_MIME_LEN_ALLOW``
+
+``TS_MIME_FIELD_APPROVED``
+ "Approved"
+ ``TS_MIME_LEN_APPROVED``
+
+``TS_MIME_FIELD_AUTHORIZATION``
+ "Authorization"
+ ``TS_MIME_LEN_AUTHORIZATION``
+
+``TS_MIME_FIELD_BYTES``
+ "Bytes"
+ ``TS_MIME_LEN_BYTES``
+
+``TS_MIME_FIELD_CACHE_CONTROL``
+ "Cache-Control"
+ ``TS_MIME_LEN_CACHE_CONTROL``
+
+``TS_MIME_FIELD_CLIENT_IP``
+ "Client-ip"
+ ``TS_MIME_LEN_CLIENT_IP``
+
+``TS_MIME_FIELD_CONNECTION``
+ "Connection"
+ ``TS_MIME_LEN_CONNECTION``
+
+``TS_MIME_FIELD_CONTENT_BASE``
+ "Content-Base"
+ ``TS_MIME_LEN_CONTENT_BASE``
+
+``TS_MIME_FIELD_CONTENT_ENCODING``
+ "Content-Encoding"
+ ``TS_MIME_LEN_CONTENT_ENCODING``
+
+``TS_MIME_FIELD_CONTENT_LANGUAGE``
+ "Content-Language"
+ ``TS_MIME_LEN_CONTENT_LANGUAGE``
+
+``TS_MIME_FIELD_CONTENT_LENGTH``
+ "Content-Length"
+ ``TS_MIME_LEN_CONTENT_LENGTH``
+
+``TS_MIME_FIELD_CONTENT_LOCATION``
+ "Content-Location"
+ ``TS_MIME_LEN_CONTENT_LOCATION``
+
+``TS_MIME_FIELD_CONTENT_MD5``
+ "Content-MD5"
+ ``TS_MIME_LEN_CONTENT_MD5``
+
+``TS_MIME_FIELD_CONTENT_RANGE``
+ "Content-Range"
+ ``TS_MIME_LEN_CONTENT_RANGE``
+
+``TS_MIME_FIELD_CONTENT_TYPE``
+ "Content-Type"
+ ``TS_MIME_LEN_CONTENT_TYPE``
+
+``TS_MIME_FIELD_CONTROL``
+ "Control"
+ ``TS_MIME_LEN_CONTROL``
+
+``TS_MIME_FIELD_COOKIE``
+ "Cookie"
+ ``TS_MIME_LEN_COOKIE``
+
+``TS_MIME_FIELD_DATE``
+ "Date"
+ ``TS_MIME_LEN_DATE``
+
+``TS_MIME_FIELD_DISTRIBUTION``
+ "Distribution"
+ ``TS_MIME_LEN_DISTRIBUTION``
+
+``TS_MIME_FIELD_ETAG``
+ "Etag"
+ ``TS_MIME_LEN_ETAG``
+
+``TS_MIME_FIELD_EXPECT``
+ "Expect"
+ ``TS_MIME_LEN_EXPECT``
+
+``TS_MIME_FIELD_EXPIRES``
+ "Expires"
+ ``TS_MIME_LEN_EXPIRES``
+
+``TS_MIME_FIELD_FOLLOWUP_TO``
+ "Followup-To"
+ ``TS_MIME_LEN_FOLLOWUP_TO``
+
+``TS_MIME_FIELD_FROM``
+ "From"
+ ``TS_MIME_LEN_FROM``
+
+``TS_MIME_FIELD_HOST``
+ "Host"
+ ``TS_MIME_LEN_HOST``
+
+``TS_MIME_FIELD_IF_MATCH``
+ "If-Match"
+ ``TS_MIME_LEN_IF_MATCH``
+
+``TS_MIME_FIELD_IF_MODIFIED_SINCE``
+ "If-Modified-Since"
+ ``TS_MIME_LEN_IF_MODIFIED_SINCE``
+
+``TS_MIME_FIELD_IF_NONE_MATCH``
+ "If-None-Match"
+ ``TS_MIME_LEN_IF_NONE_MATCH``
+
+``TS_MIME_FIELD_IF_RANGE``
+ "If-Range"
+ ``TS_MIME_LEN_IF_RANGE``
+
+``TS_MIME_FIELD_IF_UNMODIFIED_SINCE``
+ "If-Unmodified-Since"
+ ``TS_MIME_LEN_IF_UNMODIFIED_SINCE``
+
+``TS_MIME_FIELD_KEEP_ALIVE``
+ "Keep-Alive"
+ ``TS_MIME_LEN_KEEP_ALIVE``
+
+``TS_MIME_FIELD_KEYWORDS``
+ "Keywords"
+ ``TS_MIME_LEN_KEYWORDS``
+
+``TS_MIME_FIELD_LAST_MODIFIED``
+ "Last-Modified"
+ ``TS_MIME_LEN_LAST_MODIFIED``
+
+``TS_MIME_FIELD_LINES``
+ "Lines"
+ ``TS_MIME_LEN_LINES``
+
+``TS_MIME_FIELD_LOCATION``
+ "Location"
+ ``TS_MIME_LEN_LOCATION``
+
+``TS_MIME_FIELD_MAX_FORWARDS``
+ "Max-Forwards"
+ ``TS_MIME_LEN_MAX_FORWARDS``
+
+``TS_MIME_FIELD_MESSAGE_ID``
+ "Message-ID"
+ ``TS_MIME_LEN_MESSAGE_ID``
+
+``TS_MIME_FIELD_NEWSGROUPS``
+ "Newsgroups"
+ ``TS_MIME_LEN_NEWSGROUPS``
+
+``TS_MIME_FIELD_ORGANIZATION``
+ "Organization"
+ ``TS_MIME_LEN_ORGANIZATION``
+
+``TS_MIME_FIELD_PATH``
+ "Path"
+ ``TS_MIME_LEN_PATH``
+
+``TS_MIME_FIELD_PRAGMA``
+ "Pragma"
+ ``TS_MIME_LEN_PRAGMA``
+
+``TS_MIME_FIELD_PROXY_AUTHENTICATE``
+ "Proxy-Authenticate"
+ ``TS_MIME_LEN_PROXY_AUTHENTICATE``
+
+``TS_MIME_FIELD_PROXY_AUTHORIZATION``
+ "Proxy-Authorization"
+ ``TS_MIME_LEN_PROXY_AUTHORIZATION``
+
+``TS_MIME_FIELD_PROXY_CONNECTION``
+ "Proxy-Connection"
+ ``TS_MIME_LEN_PROXY_CONNECTION``
+
+``TS_MIME_FIELD_PUBLIC``
+ "Public"
+ ``TS_MIME_LEN_PUBLIC``
+
+``TS_MIME_FIELD_RANGE``
+ "Range"
+ ``TS_MIME_LEN_RANGE``
+
+``TS_MIME_FIELD_REFERENCES``
+ "References"
+ ``TS_MIME_LEN_REFERENCES``
+
+``TS_MIME_FIELD_REFERER``
+ "Referer"
+ ``TS_MIME_LEN_REFERER``
+
+``TS_MIME_FIELD_REPLY_TO``
+ "Reply-To"
+ ``TS_MIME_LEN_REPLY_TO``
+
+``TS_MIME_FIELD_RETRY_AFTER``
+ "Retry-After"
+ ``TS_MIME_LEN_RETRY_AFTER``
+
+``TS_MIME_FIELD_SENDER``
+ "Sender"
+ ``TS_MIME_LEN_SENDER``
+
+``TS_MIME_FIELD_SERVER``
+ "Server"
+ ``TS_MIME_LEN_SERVER``
+
+``TS_MIME_FIELD_SET_COOKIE``
+ "Set-Cookie"
+ ``TS_MIME_LEN_SET_COOKIE``
+
+``TS_MIME_FIELD_SUBJECT``
+ "Subject"
+ ``TS_MIME_LEN_SUBJECTTS_MIME_LEN_SUBJECT``
+
+``TS_MIME_FIELD_SUMMARY``
+ "Summary"
+ ``TS_MIME_LEN_SUMMARY``
+
+``TS_MIME_FIELD_TE``
+ "TE"
+ ``TS_MIME_LEN_TE``
+
+``TS_MIME_FIELD_TRANSFER_ENCODING``
+ "Transfer-Encoding"
+ ``TS_MIME_LEN_TRANSFER_ENCODING``
+
+``TS_MIME_FIELD_UPGRADE``
+ "Upgrade"
+ ``TS_MIME_LEN_UPGRADE``
+
+``TS_MIME_FIELD_USER_AGENT``
+ "User-Agent"
+ ``TS_MIME_LEN_USER_AGENT``
+
+``TS_MIME_FIELD_VARY``
+ "Vary"
+ ``TS_MIME_LEN_VARY``
+
+``TS_MIME_FIELD_VIA``
+ "Via"
+ ``TS_MIME_LEN_VIA``
+
+``TS_MIME_FIELD_WARNING``
+ "Warning"
+ ``TS_MIME_LEN_WARNING``
+
+``TS_MIME_FIELD_WWW_AUTHENTICATE``
+ "Www-Authenticate"
+ ``TS_MIME_LEN_WWW_AUTHENTICATE``
+
+``TS_MIME_FIELD_XREF``
+ "Xref"
+ ``TS_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 ``TSMimeHdrFieldNameGet`` 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:
+
+- ```TSMimeHdrFieldAppend`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ae36c9bab9147a30b259d8e0223d697f2>`__
+- ```TSMimeHdrFieldClone`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ade66cd69ddff40d14b015a9e2cd7b46f>`__
+- ```TSMimeHdrFieldCopy`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a612ebefde403abc216af99f9150dd66f>`__
+- ```TSMimeHdrFieldCopyValues`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a5e4b2f68392a26643620641e50e5045b>`__
+- ```TSMimeHdrFieldCreate`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a7f79c0bea2ce14ced3b017eac08f8916>`__
+- ```TSMimeHdrFieldDestroy`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a6bf2d8e95e6f3ef351f63dbe8bc54020>`__
+- ```TSMimeHdrFieldLengthGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a8a906f22ccf7a4a04fac817dc57a785f>`__
+- ```TSMimeHdrFieldNameGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ad68f51073e4630ad6a0433efbfeef2ea>`__
+- ```TSMimeHdrFieldNameSet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a6856f6069fa4ee67d1a788bd642d59f0>`__
+- ```TSMimeHdrFieldNext`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#aaf3a205e8a4e7128f3fa3de70991df80>`__
+- ```TSMimeHdrFieldNextDup`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#af2d776615afe959ed7c3639830a7061f>`__
+- ```TSMimeHdrFieldValueAppend`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#ad1d4d1dda95311e3389245fd9fa961b5>`__
+- ```TSMimeHdrFieldValueAppend`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#ad1d4d1dda95311e3389245fd9fa961b5>`__
+- ```TSMimeHdrFieldValueDateGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#ad74a60f0da93397ee015d82f30021d15>`__
+- ```TSMimeHdrFieldValueDateInsert`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a0520a29de96736b04f14e9d790ec8e9c>`__
+- ```TSMimeHdrFieldValueDateSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#abf85e014cb316977dedca38c341d4369>`__
+- ```TSMimeHdrFieldValueIntGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ace1fac92d2be75ff7cbd8eb7725d3fac>`__
+- ```TSMimeHdrFieldValueIntSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aec96c5629a750cdaec709228c4bd8a76>`__
+- ```TSMimeHdrFieldValueStringGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a4aa55cd4eeb9e6d0a5151c02f0c18c28>`__
+- ```TSMimeHdrFieldValueStringInsert`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a979d1591becf1c59de830af117d54923>`__
+- ```TSMimeHdrFieldValueStringSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac21e44e84b25c23e52ba7bea7bd09ed6>`__
+- ```TSMimeHdrFieldValueUintGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a116b4c9144ad6eda66213adb0167706a>`__
+- ```TSMimeHdrFieldValueUintInsert`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a88db3a90d3ac7766e55c734c89dfe86f>`__
+- ```TSMimeHdrFieldValueUintSet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a63b0a686b4a6ec6b8a4f1b796009c3cd>`__
+- ```TSMimeHdrFieldValuesClear`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a8fd3afaf88f6c76793fdb635bbd22113>`__
+- ```TSMimeHdrFieldValuesCount`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a326283521986acf9b8a9ec00f3d6d164>`__
+- ```TSMimeHdrClone`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aa8ab95bda93c3e16e6d134fe35acd1b6>`__
+- ```TSMimeHdrCopy`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a6e0a392b2e072db8e7f1d795151203b4>`__
+- ```TSMimeHdrCreate`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a3427dfbd6b79c531fcba4e8c8b4e217d>`__
+- ```TSMimeHdrDestroy`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a60ad7f4f4f9e2559dcc2ff28ebe8d96c>`__
+- ```TSMimeHdrFieldFind`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a30e4ce224761b273a119dcd57f5a352b>`__
+- ```TSMimeHdrFieldGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a31c0c307010a5d19d027ffb3a2656745>`__
+- ```TSMimeHdrFieldRemove`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a96d9a50d0687456e6e67eb2e9a9c2d72>`__
+- ```TSMimeHdrFieldsClear`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a65d7539e48c9f5c26075344dee6c6ae2>`__
+- ```TSMimeHdrFieldsCount`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ab02f7d0cba75cf0146c6a9b507c79fcf>`__
+- ```TSMimeHdrLengthGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a001cd786282f5c9d04189ddf7c96e269>`__
+- ```TSMimeHdrParse`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a4a6042bcd5b5b0a21267c03cf102e90d>`__
+- ```TSMimeParserClear`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac173b595659d1909aae5410ecd1ce028>`__
+- ```TSMimeParserCreate`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a518072dc5a90b753df7726878119506b>`__
+- ```TSMimeParserDestroy`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a5f287f5016d931842c0a5012c3d227b7>`__
+- ```TSMimeHdrPrint`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#adfca8722edc6469df4410b8050406bb0>`__
+