trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject [18/26] Separate the Admin and SDK guides.
Date Sun, 02 Jun 2013 05:02:15 GMT
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/continuations.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/continuations.en.rst b/doc/sdk/continuations.en.rst
new file mode 100644
index 0000000..df93565
--- /dev/null
+++ b/doc/sdk/continuations.en.rst
@@ -0,0 +1,135 @@
+Continuations
+*************
+
+.. 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
+
+   continuations/how-to-activate-continuations.en
+   continuations/writing-handler-functions.en
+
+The continuation interface is Traffic Server's basic callback mechanism.
+**Continuations** are instances of the opaque data type ``TSCont``. In
+its basic form, a continuation represents a handler function and a
+mutex.
+
+This chapter covers the following topics:
+
+-  `Mutexes and Data <MutexesData>`__
+
+-  `How to Activate Continuations <ActivateContinuations.html>`__
+
+-  `Writing Handler Functions <WritingHandlerFunctions.html>`__
+
+Mutexes and Data
+----------------
+
+A continuation must be created with a mutex if your continuation does
+one of the following:
+
+-  is registered globally (``TSHttpHookAdd`` or ``TSHttpSsnHookAdd``) to
+   an HTTP hook and uses ``TSContDataSet/Get``
+
+-  is registered locally (``TSHttpTxnHookAdd``), but for multiple
+   transactions uses ``TSContDataSet/Get``
+
+-  uses ``TSCacheXXX``, ``TSNetXXX``, ``TSHostLookup``, or
+   ``TSContSchedule`` APIs
+
+Before being activated, a caller must grab the continuation's mutex.
+This requirement makes it possible for a continuation's handler function
+to safely access its data and to prevent multiple callers from running
+it at the same time (see the `sample Protocol
+plugin <../new-protocol-plugins#AboutSampleProtocol>`__ for usage). The
+data protected by the mutex is any global or continuation data
+associated to the continuation by ``TSContDataSet``. This does not
+include the local data created by the continuation handler function. A
+typical example of continuations created with associated data structures
+and mutexes is the transaction state machine created in the sample
+Protocol plugin (see `One Way to Implement a Transaction State
+Machine <../new-protocol-plugins#OneWayImplementaTransactionStateMachine>`__).
+
+A reentrant call occurs when the continuation passed as an argument to
+the API can be called in the same stack trace as the function calling
+the API. For example, if you call ``TSCacheRead`` (``contp, mykey``), it
+is possible that ``contp``'s handler will be called directly and then
+``TSCacheRead`` returns.
+
+Caveats that could cause issues include the following:
+
+-  a continuation has data associated with it (``TSContDataGet``).
+
+| \*
+| the reentrant call passes itself as a continuation to the reentrant
+API. In this case, the continuation should not try to access its data
+after calling the reentrant API. The reason for this is that data may be
+modified by the section of code in the continuation's handler that
+handles the event sent by the API. It is recommended that you always
+return after a reentrant call to avoid accessing something that has been
+deallocated.
+
+Below is an example, followed by an explanation.
+
+::
+
+        ::::c
+    continuation_handler (TSCont contp, TSEvent event, void *edata) {
+        switch (event) {
+            case event1:
+                TSReentrantCall (contp);
+                /* Return right away after this call */
+                break;
+            case event2:
+                TSContDestroy (contp);
+                break;
+        }
+    }
+
+The above example first assumes that the continuation is called back
+with ``event1``; it then does the first reentrant call that schedules
+the continuation to receive ``event2``. Because the call is reentrant,
+the processor calls back the continuation right away with ``event2`` and
+the continuation is destroyed. If you try to access the continuation or
+one of its members after the reentrant call, then you might access
+something that has been deallocated. To avoid accessing something that
+has been deallocated, never access the continuation or any of its
+members after a reentrant call - just exit the handler.
+
+**Note:** Most HTTP transaction plugin continuations do not need
+non-null mutexes because they're called within the processing of an HTTP
+transaction, and therefore have the transaction's mutex.
+
+It is also possible to specify a continuation's mutex as ``NULL``. This
+should be done only when registering a continuation to a global hook, by
+a call to ``TSHttpHookAdd``. In this case, the continuation can be
+called simultaneously by different instances of HTTP SM running on
+different threads. Having a mutex here would slow and/or hinder Traffic
+Server performance, since all the threads will try to lock the same
+mutex. The drawback of not having a mutex is that such a continuation
+cannot have data associated with it (i.e., ``TSContDataGet/Set`` cannot
+be used).
+
+When using a ``NULL`` mutex it is dangerous to access the continuation's
+data, but usually continuations with ``NULL`` mutexes have no data
+associated with them anyway. An example of such a continuation is one
+that gets called back every time an HTTP request is read, and then
+determines from the request alone if the request should go through or be
+rejected. An HTTP transaction gives its continuation data to the
+``contp``.
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/continuations/how-to-activate-continuations.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/continuations/how-to-activate-continuations.en.rst b/doc/sdk/continuations/how-to-activate-continuations.en.rst
new file mode 100644
index 0000000..1dd23c2
--- /dev/null
+++ b/doc/sdk/continuations/how-to-activate-continuations.en.rst
@@ -0,0 +1,36 @@
+How to Activate Continuations
+*****************************
+
+.. 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.
+
+Continuations are activated when they receive an event or by
+``TSContSchedule`` (which schedules a continuation to receive an event).
+Continuations might receive an event because:
+
+-  Your plugin calls ``TSContCall``
+
+-  The Traffic Server HTTP state machine sends an event corresponding to
+   a particular HTTP hook
+
+-  A Traffic Server IO processor (such as a cache processor or net
+   processor) is letting a continuation know there is data (cache or
+   network) available to read or write. These callbacks are a result of
+   using functions such ``TSVConnRead``/``Write`` or
+   ``TSCacheRead``/``Write``
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/continuations/writing-handler-functions.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/continuations/writing-handler-functions.en.rst b/doc/sdk/continuations/writing-handler-functions.en.rst
new file mode 100644
index 0000000..7945f7e
--- /dev/null
+++ b/doc/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/a782694b/doc/sdk/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started.en.rst b/doc/sdk/getting-started.en.rst
new file mode 100644
index 0000000..36a4d94
--- /dev/null
+++ b/doc/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/a782694b/doc/sdk/getting-started/a-simple-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started/a-simple-plugin.en.rst b/doc/sdk/getting-started/a-simple-plugin.en.rst
new file mode 100644
index 0000000..30bd81d
--- /dev/null
+++ b/doc/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/a782694b/doc/sdk/getting-started/naming-conventions.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started/naming-conventions.en.rst b/doc/sdk/getting-started/naming-conventions.en.rst
new file mode 100644
index 0000000..45794a2
--- /dev/null
+++ b/doc/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/a782694b/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst b/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
new file mode 100644
index 0000000..b7171c7
--- /dev/null
+++ b/doc/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");
+    }
+


Mime
View raw message