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:25 UTC
[5/7] add sdk docs.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/continuations/writing-handler-functions.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/continuations/writing-handler-functions.en.rst b/doc/source/sdk/continuations/writing-handler-functions.en.rst
new file mode 100644
index 0000000..7945f7e
--- /dev/null
+++ b/doc/source/sdk/continuations/writing-handler-functions.en.rst
@@ -0,0 +1,109 @@
+Writing Handler 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 handler function is the key component of a continuation. It is
+supposed to examine the event and event data, and then do something
+appropriate. The probable action might be to schedule another event for
+the continuation to received, to open up a connection to a server, or
+simply to destroy itself.
+
+The continuation's handler function is a function of type
+``TSEventFunc``. Its arguments are a continuation, an event, and a
+pointer to some data (this data is passed to the continuation by the
+caller - do not confuse this data with the continuation's own data,
+associated by ``TSContDataSet``). When the continuation is called back,
+the continuation and an event are passed to the handler function. The
+continuation is a handle to the same continuation that is invoked. The
+handler function typically has a switch statement to handle the events
+it receives:
+
+::
+
+ ::::c
+ static int some_handler (TScont contp, TSEvent event, void *edata)
+ {
+ .....
+ switch(event) {
+ case TS_EVENT_SOME_EVENT_1:
+ do_some_thing_1;
+ return;
+ case TS_EVENT_SOME_EVENT_2:
+ do_some_thing_2;
+ return;
+ case TS_EVENT_SOME_EVENT_3:
+ do_some_thing_3;
+ return;
+ default: break;
+ }
+ return 0;
+ }
+
+.. figure:: /images/docbook/caution.png
+ :alt: [Caution]
+
+ [Caution]
+**Caution**
+
+You might notice that a continuation cannot determine if more events are
+"in flight" toward it. Do not use ``TSContDestroy`` to delete a
+continuation before you make sure that all incoming events, such as
+those sent because of ``TSHttpTxnHookAdd``, have been handled.
+
+The following table lists events and the corresponding type of
+``void *``\ data passed to handler functions:
+
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| Event | Hook or API Function That Sends the Event
| Event Data Type |
++=======================================+============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================
=====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================
====================================================================================================+===================+
+| ``TS_EVENT_HTTP_READ_REQUEST_HDR`` | ``TS_HTTP_READ_REQUEST_HDR_HOOK``
| ``TSHttpTxn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_OS_DNS`` | ``TS_HTTP_OS_DNS_HOOK``
| ``TSHttpTxn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_SEND_REQUEST_HDR`` | ``TS_HTTP_SEND_REQUEST_HDR_HOOK``
| ``TSHttpTxn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_READ_CACHE_HDR`` | ``TS_HTTP_READ_CACHE_HDR_HOOK``
| ``TSHttpTxn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_READ_RESPONSE_HDR`` | ``TS_HTTP_READ_RESPONSE_HDR_HOOK``
| ``TSHttpTxn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_SEND_RESPONSE_HDR`` | ``TS_HTTP_SEND_RESPONSE_HDR_HOOK``
| ``TSHttpTxn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_SELECT_ALT`` | ``TS_HTTP_SELECT_ALT_HOOK``
| ``TSHttpTxn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_TXN_START`` | ``TS_HTTP_TXN_START_HOOK``
| ``TSHttpTxn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_TXN_CLOSE`` | ``TS_HTTP_TXN_CLOSE_HOOK``
| ``TSHttpTxn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_SSN_START`` | ``TS_HTTP_SSN_START_HOOK``
| ``TSHttpSsn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_HTTP_SSN_CLOSE`` | ``TS_HTTP_SSN_CLOSE_HOOK``
| ``TSHttpSsn`` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+| ``TS_EVENT_NONE`` | ``` |`` ``| |``\ TS\_EVENT\_CACHE\_LOOKUP\_COMPLETE\ ``|``\ TS\_HTTP\_CACHE\_LOOKUP\_COMPLETE\_HOOK\ ``|``\ TSHttpTxn\ ``| |``\ TS\_EVENT\_IMMEDIATE\ ``|``\ TSVConnClose, TSVIOReenable, TSContSchedule\ ``|`` ``| |``\ TS\_EVENT\_IMMEDIATE\ ``|``\ TS\_HTTP\_REQUEST\_TRANSFORM\_HOOK\ ``|`` ``| |``\ TS\_EVENT\_IMMEDIATE\ ``|``\ TS\_HTTP\_RESPONSE\_TRANSFORM\_HOOK\ ``|`` ``| |``\ TS\_EVENT\_CACHE\_OPEN\_READ\ ``|``\ TSCacheRead\ ``| Cache VC | |``\ TS\_EVENT\_CACHE\_OPEN\_READ\_FAILED\ ``|``\ TSCacheRead\ ``| Error code, see``\ TS\_CACHE\_ERROR\_XXX\ ``| |``\ TS\_EVENT\_CACHE\_OPEN\_WRITE\ ``|``\ TSCacheWrite\ ``| Cache VC | |``\ TS\_EVENT\_CACHE\_OPEN\_WRITE\_FAILED\ ``|``\ TSCacheWrite\ ``| Error code, see``\ TS\_CACHE\_ERROR\_XXX\ ``| |``\ TS\_EVENT\_CACHE\_REMOVE\ ``|``\ TSCacheRemove\ ``|`` ``| |``\ TS\_EVENT\_CACHE\_REMOVE\_FAILED\ ``|``\ TSCacheRemove\ ``| Error code, see``\ TS\_CACHE\_ERROR\_XXX\ ``| |``\ TS\_EVENT\_NET\_ACCEPT\ ``| TSNet
Accept, TSHttpTxnServerIntercept, TSHttpTxnIntercept| NetVConnection | |``\ TS\_EVENT\_NET\_ACCEPT\_FAILED\ ``| TSNetAccept, TSHttpTxnServerIntercept, TSHttpTxnIntercept|`` ``| |``\ TS\_EVENT\_HOST\_LOOKUP\ ``|``\ TSHostLookup\ ``| Null pointer - error; Non null pointer -``\ TSHostLookupResult\ ``| |``\ TS\_EVENT\_TIMEOUT\ ``|``\ TSContSchedule\ ``|`` ``| |``\ TS\_EVENT\_ERROR\ ``|`` ``|`` ``| |``\ TS\_EVENT\_VCONN\_READ\_READY\ ``|``\ TSVConnRead\ ``|``\ TSVConn\ ``| |``\ TS\_EVENT\_VCONN\_WRITE\_READY\ ``|``\ TSVConnWrite\ ``|``\ TSVConn\ ``| |``\ TS\_EVENT\_VCONN\_READ\_COMPLETE\ ``|``\ TSVConnRead\ ``|``\ TSVConn\ ``| |``\ TS\_EVENT\_VCONN\_WRITE\_COMPLETE\ ``|``\ TSVConnWrite\ ``|``\ TSVConn\ ``| |``\ TS\_EVENT\_VCONN\_EOS\ ``|``\ TSVConnRead\ ``|``\ TSVConn\ ``| |``\ TS\_EVENT\_NET\_CONNECT\ ``|``\ TSNetConnect\ ``|``\ TSVConn\ ``| |``\ TS\_EVENT\_NET\_CONNECT\_FAILED\ ``|``\ TSNetConnect\ ``|``\ TSVConn\ ``| |``\ TS\_EVENT\_HTTP\_CONTINUE\ ``|`` ``|`` ``| |``\ TS\_EVENT\_HTTP
\_ERROR\ ``|`` ``|`` ``| |``\ TS\_EVENT\_MGMT\_UPDATE\ ``|``\ TSMgmtUpdateRegister\ ``|``\ NULL\` |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
----------------------------------------------------------------------------------------------------+-------------------+
+
+The continuation functions are listed below:
+
+- ``TSContCall``
+- ``TSContCreate``
+- ``TSContDataGet``
+- ``TSContDataSet``
+- ``TSContDestroy``
+- ``TSContMutexGet``
+- ``TSContSchedule``
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/getting-started.en.rst b/doc/source/sdk/getting-started.en.rst
new file mode 100644
index 0000000..36a4d94
--- /dev/null
+++ b/doc/source/sdk/getting-started.en.rst
@@ -0,0 +1,249 @@
+Getting Started
+***************
+
+.. 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
+
+ getting-started/a-simple-plugin.en
+ getting-started/plugin-registration-and-version-checking.en
+ getting-started/naming-conventions.en
+
+The Traffic Server API enables you to create plugins, using the C
+programming language, that customize the behavior of your Traffic Server
+installation. This chapter contains the following sections:
+
+- `Understanding Traffic Server Plugins <#UnderstandingTSPlugins>`__ --
+ a brief introduction to plugins. For more details, see `How to Create
+ Traffic Server Plugins <../how-to-create-trafficserver-plugins>`__
+
+- `A Simple Plugin <a-simple-plugin>`__ -- walks through compiling and
+ loading an example ``hello world`` plugin.
+
+- `Plugin Registration and Version
+ Checking <plugin-registration-and-version-checking>`__ -- shows you
+ how to register your plugin and make sure it's compatible with the
+ version of Traffic Server you're using.
+
+- `Naming Conventions <NamingConventions.html>`__ -- outlines Traffic
+ Server API naming conventions. For guidelines on creating plugin
+ source code, see `How to Create Traffic Server
+ Plugins <../how-to-create-trafficserver-plugins>`__
+
+Understanding Traffic Server Plugins
+------------------------------------
+
+Traffic Server enables sophisticated caching and processing of
+web-related traffic, such as DNS and HTTP requests and responses.
+
+Traffic Server itself consists of an event-driven loop that can be
+simplified as follows:
+
+::
+
+ :::C
+ for (;;) {
+ event = get_next_event();
+ handle_event (event);
+ }
+
+The Role of Plugins
+~~~~~~~~~~~~~~~~~~~
+
+You compile your plugin source code to create a shared library that
+Traffic Server loads when it is started. Your plugin contains callback
+functions that are registered for specific Traffic Server events. When
+Traffic Server needs to process an event, it invokes any and all
+call-back functions you've registered for that event type.
+
+|[Caution]| **Caution**
+
+Since plugins add object code to Traffic Server, programming errors in a
+plugin can have serious implications. Bugs in your plugin, such as an
+out-of-range pointer, can cause Traffic Server processes to crash and
+may ultimately result in unpredictable behavior.
+
+**Plugin Process** {#PluginProcess}
+
+.. figure:: /images/sdk/plugin_process.jpg
+ :alt: Plugin Process
+
+ Plugin Process
+Possible Uses for Plugins
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Possible uses for plugins include the following:
+
+- HTTP processing: plugins can filter, blacklist, authorize users,
+ transform content
+
+- Protocol support: plugins can enable Traffic Server to proxy-cache
+ new protocol content
+
+Some examples of plugins include:
+
+- **Blacklisting plugin**: denies attempts to access web sites that are
+ off-limits.
+
+- **Append transform plugin**: adds text to HTTP response content.
+
+- **Image conversion plugin**: transforms JPEG images to GIF images.
+
+- **Compression plugin**: sends response content to a compression
+ server that compresses the data (alternatively, a compression library
+ local to the Traffic Server host machine could do the compression).
+
+- **Authorization plugin**: checks a user's permissions to access
+ particular web sites. The plugin could consult a local authorization
+ program or send queries to an authorization server.
+
+- **A plugin that gathers client information** from request headers and
+ enters this information in a database.
+
+- **Protocol plugin**: listens for specific protocol requests on a
+ designated port and then uses Traffic Server's proxy server & cache
+ to serve client requests.
+
+The figure below, `Possible Traffic Server
+Plugins <#possibleTSplugins>`__, illustrates several types of plugins.
+
+**Possible Traffic Server Plugins** {#possibleTSplugins}
+
+.. figure:: /images/sdk/Uses.jpg
+ :alt: Possible Traffic Server Plugins
+
+ Possible Traffic Server Plugins
+You can find basic examples for many plugins in the SDK sample code:
+
+- ``append-transform.c`` adds text from a specified file to HTTP/text
+ responses. This plugin is explained in `The Append-Transform
+ Plugin <../http-transformation-plugin/append-transform-plugin>`__
+
+- The compression plugin in the figure communicates with the server
+ that actually does the compression. The ``server-transform.c`` plugin
+ shows how to open a connection to a transformation server, have the
+ server do the transformation, and send transformed data back to the
+ client. Although the transformation is null in
+ ``server-transform.c``, a compression or image translation plugin
+ could be implemented in a similar way.
+
+- ``basic-auth.c`` performs basic HTTP proxy authorization.
+
+- ``blacklist-1.c`` reads blacklisted servers from a configuration file
+ and denies client access to these servers. This plugin is explained
+ in `The Blacklist
+ Plugin <../header-based-plugin-examples/blacklist-plugin>`__.
+
+Plugin Loading
+~~~~~~~~~~~~~~
+
+When Traffic Server is first started, it consults the ``plugin.config``
+file to determine the names of all shared plugin libraries that need to
+be loaded. The ``plugin.config`` file also defines arguments that are to
+be passed to each plugin's initialization function, ``TSPluginInit``.
+The ``records.config`` file defines the path to each plugin shared
+library, as described in `Specify the Plugin's
+Location <SpecifyingPluginLocation.html>`__.
+
+|[Note]| **Note**
+
+The path for each of these files is *``<root_dir>``*\ ``/config/``,
+where *``<root_dir>``* is where you installed Traffic Server.
+
+Plugin Configuration
+~~~~~~~~~~~~~~~~~~~~
+
+The sample ``plugin.config`` file below contains a comment line, a blank
+line, and two plugin configurations:
+
+::
+
+ # This is a comment line.
+
+ my-plugin.so junk.example.com trash.example.org garbage.example.edu
+ some-plugin.so arg1 arg2 $proxy.config.http.cache.on
+
+Each plugin configuration in the ``plugin.config`` file resembles a UNIX
+or DOS shell command; each line in ``plugin.config`` cannot exceed 1023
+characters.
+
+The first plugin configuration is for a plugin named ``my-plugin.so``.
+It contains three arguments that are to be passed to that plugin's
+initialization routine. The second configuration is for a plugin named
+``some-plugin.so``; it contains three arguments. The last argument,
+*``$proxy.config.http.cache.on``*, is actually a configuration variable.
+Traffic Server will look up the specified configuration variable and
+substitute its value.
+
+Plugins with global variables should not appear more than once in
+``plugin.config``. For example, if you enter:
+
+::
+
+ add-header.so header1
+ add-header.so header2
+
+then the second global variable, ``header2``, will be used for both
+instances. A simple workaround is to give different names to different
+instances of the same plugin. For example:
+
+::
+
+ cp add-header.so add-header1.so
+ cp add-header.so add-header2.so
+
+These entries will produce the desired result below:
+
+::
+
+ add-header1.so header1
+ add-header2.so header2
+
+Configuration File Rules
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Comment lines begin with **#** and continue to the end of the line.
+
+- Blank lines are ignored.
+
+- Plugins are loaded and initialized by Traffic Server in the order
+ they appear in the ``plugin.config`` file.
+
+Plugin Initialization
+~~~~~~~~~~~~~~~~~~~~~
+
+Each plugin must define an initialization function named
+``TSPluginInit`` that Traffic Server invokes when the plugin is loaded.
+The ``TSPluginInit`` function is commonly used to read configuration
+information and register hooks for event notification.
+
+The ``TSPluginInit`` function has two arguments:
+
+- The ``argc`` argument represents the number of arguments defined in
+ the ``plugin.config`` file for that particular plugin
+
+- The ``argv`` argument is an array of pointers to the actual arguments
+ defined in the ``plugin.config`` file for that plugin
+
+See `TSPluginInit <InitializationFunctions.html#TSPluginInit>`__ for
+details about ``TSPluginInit``.
+
+.. |[Caution]| image:: /images/docbook/caution.png
+.. |[Note]| image:: /images/docbook/note.png
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/getting-started/a-simple-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/getting-started/a-simple-plugin.en.rst b/doc/source/sdk/getting-started/a-simple-plugin.en.rst
new file mode 100644
index 0000000..30bd81d
--- /dev/null
+++ b/doc/source/sdk/getting-started/a-simple-plugin.en.rst
@@ -0,0 +1,118 @@
+A Simple 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.
+
+This section describes how to write, compile, configure, and run a
+simple Traffic Server plugin. You'll follow the steps below:
+
+1. Make sure that your plugin source code contains an ``TSPluginInit``
+ initialization function.
+
+2. Compile your plugin source code, creating a shared library.
+
+3. Add an entry to your plugin's ``plugin.config`` file.
+
+4. Add the path to your plugin shared library into the
+ ``records.config`` file.
+
+5. Restart Traffic Server.
+
+Compile Your Plugin
+~~~~~~~~~~~~~~~~~~~
+
+The process for compiling a shared library varies with the platform
+used, so the Traffic Server API provides the tsxs tool which you can use
+to create shared libraries on all the supported Traffic Server
+platforms.
+
+Example
+^^^^^^^
+
+Assuming the sample program is stored in the file ``hello-world.c``, you
+could use the following commands to build a shared library
+
+::
+
+ tsxs -o hello-world.so -c hello-world.c
+
+This shared library will be your plugin. In order to install it, run
+
+::
+
+ sudo tsxs -o hello-world.so -i
+
+or the equivalent to ``sudo`` on your platform.
+
+Update the ``plugin.config`` File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your next step is to tell Traffic Server about the plugin by adding the
+following line to the ``plugin.config`` file. Since our simple plugin
+does not require any arguments, the following ``plugin.config`` will
+work:
+
+::
+
+ # a simple plugin.config for hello-world
+ hello-world.so
+
+Traffic Server can accommodate multiple plugins. If several plugin
+functions are triggered by the same event, then Traffic Server invokes
+each plugin's function in the order each was defined in the
+``plugin.config`` file.
+
+Specify the Plugin's Location
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All plugins must be located in the directory specified by the
+configuration variable ``proxy.config.plugin.plugin_dir``, which is
+located in the ``records.config`` file. The directory can be specified
+as an absolute or relative path.
+
+If a relative path is used, then the starting directory will be the
+Traffic Server installation directory as specified in
+``/etc/traffic_server``. The default value is ``libexec/trafficserver``,
+but this can vary based on how the software was configured and built. It
+is common to use the default directory. Be sure to place the shared
+library ``hello-world.so`` inside the directory you've configured.
+
+Restart Traffic Server
+~~~~~~~~~~~~~~~~~~~~~~
+
+The last step is to start/restart Traffic Server. Shown below is the
+output displayed after you've created and loaded your ``hello-world``
+plugin.
+
+::
+
+ # ls libexec/trafficserver
+ hello-world.so*
+ # bin/traffic_server
+ [Mar 27 19:06:31.669] NOTE: updated diags config
+ [Mar 27 19:06:31.680] NOTE: loading plugin 'libexec/trafficserver/hello-world.so'
+ hello world
+ [Mar 27 19:06:32.046] NOTE: cache disabled (initializing)
+ [Mar 27 19:06:32.053] NOTE: cache enabled
+ [Mar 27 19:06:32.526] NOTE: Traffic Server running
+
+**Note:** in the example above, Traffic Server notes are directed to the
+console by specifying ``E`` for ``proxy.config.diags.output.note`` in
+``records.config``. The second note shows Traffic Server attempting to
+load the ``hello-world`` plugin. The third line of Traffic Server output
+is from your plugin.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/getting-started/naming-conventions.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/getting-started/naming-conventions.en.rst b/doc/source/sdk/getting-started/naming-conventions.en.rst
new file mode 100644
index 0000000..45794a2
--- /dev/null
+++ b/doc/source/sdk/getting-started/naming-conventions.en.rst
@@ -0,0 +1,51 @@
+Naming Conventions
+******************
+
+.. 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 adheres to the following naming conventions:
+
+- The ``TS`` prefix is used for all function and variable names defined
+ in the Traffic Server API. **Examples**:
+ ``TS_EVENT_NONE``,\ ``TSMutex``, and ``TSContCreate``
+
+- Enumerated values are always written in all uppercase letters.
+ **Examples**: *``TS_EVENT_NONE``* and *``TS_VC_CLOSE_ABORT``*
+
+- Constant values are all uppercase; enumerated values can be seen as a
+ subset of constants. **Examples**: ``TS_URL_SCHEME_FILE`` and
+ ``TS_MIME_FIELD_ACCEPT``
+
+- The names of defined types are mixed-case. **Examples**:
+ *``TSHttpSsn``* and *``TSHttpTxn``*
+
+- Function names are mixed-case. **Examples**: ``TSUrlCreate`` and
+ ``TSContDestroy``
+
+- Function names use the following subject-verb naming style:
+ ``TS-<subject>-<verb>``, where ``<subject>`` goes from general to
+ specific. This makes it easier to determine what a function does by
+ reading its name. **For** **example**: the function to retrieve the
+ password field (the specific subject) from a URL (the general
+ subject) is ``TSUrlPasswordGet``.
+
+- Common verbs like ``Create``, ``Destroy``, ``Get``, ``Set``,
+ ``Copy``, ``Find``, ``Retrieve``, ``Insert``, ``Remove``, and
+ ``Delete`` are used only when appropriate.
+
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/getting-started/plugin-registration-and-version-checking.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/getting-started/plugin-registration-and-version-checking.en.rst b/doc/source/sdk/getting-started/plugin-registration-and-version-checking.en.rst
new file mode 100644
index 0000000..b7171c7
--- /dev/null
+++ b/doc/source/sdk/getting-started/plugin-registration-and-version-checking.en.rst
@@ -0,0 +1,86 @@
+Plugin Registration and Version Checking
+****************************************
+
+.. 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.
+
+Make sure that the functions in your plugin are supported in your
+version of Traffic Server.
+
+Use the following interfaces:
+
+- ```TSPluginRegister`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a6d7f514e70abaf097c4a3f1ba01f6df8>`__
+- ```TSTrafficServerVersionGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a3ef91e01612ffdce6dd040f836db08e8>`__
+
+The following version of ``hello-world`` registers the plugin and
+ensures it's running with a compatible version of Traffic Server.
+
+::
+
+ :::c
+ #include <stdio.h>
+ #include <ts/ts.h>
+ int
+ check_ts_version()
+ {
+
+ const char *ts_version = TSTrafficServerVersionGet();
+ int result = 0;
+
+ if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;
+
+ if (sscanf(ts_version, "%d.%d.%d", &major_ts_version,
+ &minor_ts_version, &patch_ts_version) != 3) {
+ return 0;
+ }
+
+ /* We need at least Traffic Server 2.0 */
+
+ if (major_ts_version >= 2) {
+ result = 1;
+ }
+
+ }
+
+ return result;
+ }
+
+ void
+ TSPluginInit (int argc, const char *argv[])
+ {
+
+ TSPluginRegistrationInfo info;
+
+ info.plugin_name = "hello-world";
+ info.vendor_name = "MyCompany";
+ info.support_email = "ts-api-support@MyCompany.com";
+
+ if (!TSPluginRegister (TS_SDK_VERSION_2_0 , &info)) {
+ TSError ("Plugin registration failed. \n");
+ }
+
+ if (!check_ts_version()) {
+ TSError ("Plugin requires Traffic Server 2.0 or later\n");
+ return;
+ }
+
+ TSDebug ("debug-hello", "Hello World!\n");
+ }
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples.en.rst b/doc/source/sdk/header-based-plugin-examples.en.rst
new file mode 100644
index 0000000..beb30db
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples.en.rst
@@ -0,0 +1,68 @@
+Header-Based Plugin Examples
+*****************************
+
+.. 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
+
+ header-based-plugin-examples/blacklist-plugin.en
+ header-based-plugin-examples/basic-authorization-plugin.en
+
+Header-based plugins read or modify the headers of HTTP messages that
+Traffic Server sends and receives. Reading this chapter will help you to
+understand the following topics:
+
+- Creating continuations for your plugins
+
+- Adding global hooks
+
+- Adding transaction hooks
+
+- Working with HTTP header functions
+
+The two sample plugins discussed in this chapter are ``blacklist-1.c``
+and ``basic-auth.c``.
+
+Overview
+--------
+
+Header-based plugins take actions based on the contents of HTTP request
+or response headers. Examples include filtering (on the basis of
+requested URL, source IP address, or other request header), user
+authentication, or user redirection. Header-based plugins have the
+following common elements:
+
+- The plugin has a static parent continuation that scans all Traffic
+ Server headers (either request headers, response headers, or both).
+
+- The plugin has a global hook. This enables the plugin to check all
+ transactions to determine if the plugin needs to do something.
+
+- The plugin gets a handle to the transaction being processed through
+ the global hook.
+
+- If the plugin needs to do something to transactions in specific
+ cases, then it sets up a transaction hook for a particular event.
+
+- The plugin obtains client header information and does something based
+ on that information.
+
+This chapter demonstrates how these components are implemented in SDK
+sample code.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin.en.rst b/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin.en.rst
new file mode 100644
index 0000000..6b1e10e
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin.en.rst
@@ -0,0 +1,43 @@
+The Basic Authorization 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 basic authorization plugin, ``basic-auth.c``, checks for
+basic HTTP proxy authorization. In HTTP basic proxy authorization,
+client user names and passwords are contained in the
+``Proxy-Authorization`` header. The password is encoded using base64
+encoding. The plugin checks all incoming requests for the authorization
+header, user name, and password. If the plugin does not find all of the
+these, then it reenables with an error (effectively stopping the
+transaction) and adds a transaction hook to the send response header
+event.
+
+Creating the Plugin's Parent Continuation and Global Hook
+=========================================================
+
+The parent continuation and global hook are created as follows:
+
+``TSHttpHookAdd (TS_HTTP_OS_DNS_HOOK, TSContCreate (auth_plugin, NULL));``
+.. toctree::
+ :maxdepth: 2
+
+ implementing-the-handler-and-getting-a-handle-to-the-transaction.en
+ working-with-http-headers.en
+ setting-a-transaction-hook.en
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/implementing-the-handler-and-getting-a-handle-to-the-transaction.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/implementing-the-handler-and-getting-a-handle-to-the-transaction.en.rst b/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/implementing-the-handler-and-getting-a-handle-to-the-transaction.en.rst
new file mode 100644
index 0000000..5ea3f05
--- /dev/null
+++ b/doc/source/sdk/header-based-plugin-examples/basic-authorization-plugin/implementing-the-handler-and-getting-a-handle-to-the-transaction.en.rst
@@ -0,0 +1,45 @@
+Implementing the Handler and Getting a Handle to the Transaction
+****************************************************************
+
+.. 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 handler function for the plugin's parent continuation is implemented
+as follows:
+
+::
+
+ :::c
+ static int
+ auth_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;
+ }
+