You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2010/11/06 07:30:02 UTC
svn commit: r1031963 [11/13] - in /trafficserver/site/branches/ats-cms:
content/docs/trunk/sdk/ templates/
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/NewProtocolPlugins.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/NewProtocolPlugins.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/NewProtocolPlugins.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/NewProtocolPlugins.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,373 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](SampleBufferedNullTransformPlugin) - The Sample
+Buffered Null Transform Plugin
+Chapter 7. Cache Plugin - [Next](ch07)
+## Chapter 6. New Protocol Plugins
+
+**Table of Contents**
+
+- [Protocol Plugin Structure](NewProtocolPlugins#ProtocolPluginStructure)
+- [Continuations in the Protocol Plugin](NewProtocolPlugins#ContinuationsInProtocolPlugin)
+- [Event Flow](NewProtocolPlugins#EventFlow)
+- [One Way to Implement a Transaction State Machine](NewProtocolPlugins#ImplementTransStMachine)
+- [Processing a Typical Transaction](NewProtocolPlugins#ProcTypicalTransaction)
+
+The new protocol APIs enable you to extend Traffic Server to be a
+web proxy for any protocol. This chapter describes new protocol
+APIs and the plugins that support new protocols. It also provides a
+detailed review of code for a sample Protocol plugin that supports
+a very simple artificial HTTP-like protocol.
+
+## About the Sample Protocol
+
+The sample protocol enables a client to ask a server for a file.
+Clients send requests to a specific Traffic Server port (specified
+in `plugin.config`); each request has the following structure:
+
+**`server_name file_name\n\n`**
+
+Using the Protocol plugin, Traffic Server can accept these
+requests, parse them, and act as a proxy cache (i.e., request the
+file from the origin server on the client's behalf and store copies
+of response messages in cache). The Protocol plugin is a state
+machine that flows through the states illustrated in the
+[Sample Protocol State Diagram](NewProtocolPlugins#Fig_SampleProtocolStDiag "Figure 6.1. Sample Protocol State Diagram").
+This figure illustrates the steps that Traffic Server and the
+Protocol plugin go through in order to support the sample
+protocol.
+
+In more specific terms, Traffic Server and the Protocol plugin
+must:
+
+- Listen for and accept client connections (on the accept port
+ specified in `plugin.config`)
+
+- Read incoming client requests
+
+- Look up the requested content in the Traffic Server cache
+
+- Serve content from cache if the request is a cache hit (this
+ simple example does not do freshness checking)
+
+- Open a connection to the origin server if the request is a
+ cache miss (on the server port specified in `plugin.config`)
+
+- Forward the request to the origin server
+
+- Receive the origin server response
+
+- Cache the response and send it on to the client
+
+
+**Figure 6.1. Sample Protocol State Diagram**
+
+
+### Protocol Plugin Structure
+
+To see how the Protocol plugin works, you need to understand some
+broader concepts. This section assumes you're familiar with the
+concepts of **continuation**, Traffic Server's
+**asynchronous event model**, and basic Traffic Server
+**plugin structure**. If you are not familiar with these concepts,
+then reference [Getting Started](GetingStarted#GettingStarted)
+and
+[How to Create Traffic Server Plugins](CreatingTSPlugins "Chapter 2. How to Create Traffic Server Plugins").
+
+### Continuations in the Protocol Plugin
+
+The Protocol plugin creates a static continuation that is an
+*"***accept" state machine** - that is, a state machine whose job
+is to accept client connections on the appropriate port. When
+Traffic Server accepts a net connection from a client on that port,
+the accept state machine is activated. It then creates a new
+continuation: a transaction state machine. The accept state machine
+creates one transaction state machine for each transaction (where a
+**transaction** consists of a client request and Traffic Server's
+response). Each transaction state machine lives until the
+transaction completes; then it is destroyed. If the client's
+request for content is a cache miss, then a transaction state
+machine might need to open a connection to the origin server. This
+is illustrated in the
+[Protocol Plugin Overview](NewProtocolPlugins#Fig_ProtocolPluginOverview "Figure 6.2. Protocol Plugin Overview")
+diagram below.
+
+**Figure 6.2. Protocol Plugin Overview**
+
+
+The first steps for writing the Protocol plugin are now clear: in
+`INKPluginInit`, you must create a continuation that listens for
+net connections on the client port specified in `plugin.config`
+(this continuation is the accept state machine).
+
+Below is a summary of the continuations implemented for the
+Protocol plugin:
+
+- An **accept state machine** that listens for client
+ connections, and then creates transaction state machines whenever
+ Traffic Server accepts a new client connection. The accept state
+ machine lives as long as Traffic Server is running.
+
+- **Transaction state machines** that read client requests,
+ process them, and are then destroyed when the transaction is
+ finished.
+
+
+### Event Flow
+
+Implementing the rest of the Protocol plugin requires that you
+understand the flow of events during the course of a transaction.
+Unlike HTTP transaction plugins, this plugin must read data from
+network connections and then read/write data to the Traffic Server
+cache. This means that its continuations do not receive HTTP state
+machine events; they receive events from Traffic Server's processor
+subsystems. For example: the accept state machine is activated by
+an `INK_EVENT_NET_ACCEPT` event from Traffic Server's Net
+Processor; the handler function for the accept state machine must
+therefore be able to handle that event.
+
+The transaction state machines are activated when the client
+connection receives incoming request data. The **Net Processor**
+notifies the transaction state machine of incoming data. The
+transaction state machine reads the data; when finished, it
+initiates a cache lookup of the requested file. When the cache
+lookup completes, the transaction state machine is activated by the
+Traffic Server **Cache Processor**.
+
+If the transaction state machine needs to open a connection to the
+origin server to fetch content (in the case of a cache miss), then
+the transaction state machine initiates a DNS lookup of the server
+name. The transaction state machine is activated by a DNS lookup
+event from the Traffic Server **Host Database Processor**. If the
+transaction must connect to the origin server, then the transaction
+state machine initiates a net connection and waits for an event
+from the Net Processor.
+
+**Figure 6.3. Protocol Plugin Flow of Events**
+
+
+The flow of events is illustrated in the
+[Protocol Plugin Flow of Events](NewProtocolPlugins#Fig_ProtocolPluginFlow "Figure 6.3. Protocol Plugin Flow of Events")
+diagram above. The thin straight lines show Net Processor event
+flow, the thin dashed lines represent Host Database event flow, and
+the thick dashed lines show Cache event flow.
+
+Notice that this flow of events is independent of the Protocol
+plugin's design (i.e., whether you build **accept** or
+**transaction** state machines). Any plugin that supports network
+connections uses the net vconnection interfaces (`INKNetAccept`,
+`INKNetConnect`) and thus receives events from the Net Processor.
+Any plugin that performs cache lookups or cache writes uses
+`INKCacheRead`, `INKCacheWrite`, `INKVConnRead`, and
+`INKVConnWrite` and thus receives events from the Cache Processor
+and Traffic Server event system. Similarly, any plugin that does
+DNS lookups receives events from the Host Database Processor.
+
+### One Way to Implement a Transaction State Machine
+
+**Transaction state machines** (**TSMs**) in the Protocol plugin
+must do the following:
+
+- Keep track of the state of the transaction
+
+- Handle events received (based on the state of the transaction
+ and the event received)
+
+- Update the state of the transaction as it changes
+
+
+Below is one way you can implement TSMs. Details about how the
+Protocol plugin does this are provided in the next section.
+
+- Create a data structure for transactions that contains all of
+ the state data you need to keep track of. In the Protocol plugin
+ this is a struct, `Txn_SM`.
+
+- When you create the TSM's continuation, initialize data of type
+ `Txn_SM`. Initialize the data to the initial state of a transaction
+ (in this case, a net connection has just been accepted). Associate
+ this data to the TSM continuation using `INKContDataSet`.
+
+- Write state handler functions that handle the expected events
+ for each state.
+
+- Write the handler for the TSM. Its job is to receive events,
+ examine the current state, and execute the appropriate state
+ handler function. In the Protocol plugin, the handler is
+ `main_handler`. `main_handler` calls the state handler functions to
+ handle each state.
+
+
+The steps below describe the flow of execution illustrated in
+["How Transaction State Machines are Implemented in the Protocol Plugin"](NewProtocolPlugins#Fig_ImplementTransStMachine "Figure 6.4. How Transaction State Machines are Implemented in the
+ Protocol Plugin").
+
+1. The handler for the TSM, (called `<b>main_handler</b>` in the
+ Protocol plugin) receives events from the TSM.
+
+2. `<b>main_handler</b>` examines the state of the transaction-in
+ particular, it examines the current handler.
+
+3. `<b>main_handler</b>` calls the `<b>current_handler</b>` (which
+ is one of the state handler functions), and then passes the current
+ event to `<b>current_handler</b>`.
+ In
+ [Figure 6.4](NewProtocolPlugins#Fig_ImplementTransStMachine "Figure 6.4. How Transaction State Machines are Implemented in the
+ Protocol Plugin")
+ below, the current handler is called `<b>state2_handler</b>`.
+
+4. The `<b>current_handler</b>` handles the event and updates the
+ data.
+ In
+ [Figure 6.4](NewProtocolPlugins#Fig_ImplementTransStMachine "Figure 6.4. How Transaction State Machines are Implemented in the
+ Protocol Plugin")
+ below, the state is changed from `<b>state2</b>` to `<b>state3</b>`
+ (and the current handler is changed from `<b>state2_handler</b>` to
+ `<b>state3_handler</b>`).
+ The next time `<b>main_handler</b>` receives an event, it will be
+ processed by `<b>state3_handler</b>`.
+
+5. `<b>state2_handler</b>` arranges the next callback of the TSM.
+ Typically, it gives Traffic Server additional work to do (such as
+ writing a file to cache)so that it can progress to the next
+ state.
+ The TSM (`<b>main_handler</b>`) then waits for the next event to
+ arrive from Traffic Server.
+
+
+**Figure 6.4. How Transaction State Machines are Implemented in the Protocol Plugin**
+
+
+### Processing a Typical Transaction
+
+The code is contained in the following files:
+
+- `Protocol.c` and `Protocol.h`
+
+- `Accept.c` and `Accept.h`
+
+- `TxnSM.c` and `TxnSM.h`
+
+
+Below is a step-by-step walk-through of the code that processes a
+typical transaction.
+
+1. The `INKPluginInit` function is in the `Protocol.c` file. It
+ checks the validity of the `plugin.config` entries (there must be
+ two: a client accept port and a server port) and runs an
+ initialization routine, `init`.
+
+2. The `<b>init</b>` function (in `Protocol.c`) creates the
+ plugin's log file using `<b>INKTextLogObjectCreate</b>`.
+
+3. The `<b>init</b>` function creates the accept state machine
+ using `<b>AcceptCreate</b>`. The code for `<b>AcceptCreate</b>` is
+ in the `Accept.c` file.
+
+4. The accept state machine, like the transaction state machine,
+ keeps track of its state with a data structure. This data
+ structure, `<b>Accept</b>`, is defined in the `Accept.h` file.
+ State data in `<b>AcceptCreate</b>` is associated with the new
+ accept state machine via `<b>INKContDataSet</b>`.
+
+5. The `<b>init</b>` function arranges the callback of the accept
+ state machine when there is a network connection by using
+ `<b>INKNetAccept</b>`.
+
+6. The handler for the accept state machine is
+ `<b>accept_event</b>` in the `Accept.c` file. When Traffic Server's
+ Net Processor sends `<b>INK_EVENT_NET_ACCEPT</b>` to the accept
+ state machine, `<b>accept_event</b>` creates a transaction state
+ machine (`<b>txn_sm</b>`) by calling `<b>TxnSMCreate</b>`.
+ Notice that `<b>accept_event</b>` creates a mutex for the
+ transaction state machine, since each transaction state machine has
+ its own mutex.
+
+7. The `<b>TxnSMCreate</b>` function is in the `TxnSM.c` file. The
+ first thing it does is initialize the transaction's data, which is
+ of type `TxnSM` (as defined in `TxnSM.h`).
+ Notice that the current handler (`<b>q_current_handler</b>`) is set
+ to `<b>state_start</b>`.
+
+8. `<b>TxnSMCreate</b>` then creates a transaction state machine
+ using `<b>INKContCreate</b>`. The handler for the transaction state
+ machine is `<b>main_handler</b>`, which is in the `TxnSM.c` file.
+
+9. When `<b>accept_event</b>` receives
+ `<b>INK_EVENT_NET_ACCEPT</b>`, it calls the transaction state
+ machine ( `<b>INKContCall</b>`**(`txn_sm, 0, NULL);`**
+ ). The event passed to `<b>main_handler</b>` is `0`
+ (`<b>INK_EVENT_NONE</b>`).
+
+10. The first thing `<b>main_handler</b>` does is examine the
+ current `<b>txn_sm</b>` state by calling `<b>INKContDataGet</b>`.
+ The state is `<b>state_start</b>`.
+
+11. `<b>main_handler</b>` then invokes the handler for
+ `<b>state_start</b>` by using the function pointer
+ `<b>TxnSMHandler</b>` (as defined in `TxnSM.h`).
+
+12. The `<b>state_start</b>` handler function (in the `TxnSM.c`
+ file) is handed an event (at this stage, the event is
+ `<b>INK_EVENT_NET_ACCEPT</b>`) and a client vconnection.
+ `<b>state_start</b>` checks to see if this client vconnection is
+ closed; if it is not, then `<b>state_start</b>` attempts to read
+ data from the client vconnection into an `<b>INKIOBuffer</b>`
+ (`<b>state_start</b>` is handling the event it receives).
+
+13. `<b>state_start</b>` changes the current handler to
+ `<b>state_interface_with_client</b>` (that is, it updates the state
+ of the transaction to the next state).
+
+14. `<b>state_start</b>` initiates a read of the client vconnection
+ (arranges for Traffic Server to send
+ `<b>INK_EVENT_VCONN_READ_READY</b>` events to the TSM) by calling
+ `<b>INKVConnRead</b>`.
+
+15. `<b>state_interface_with_client</b>` is activated by the next
+ event from Traffic Server. It checks for errors and examines the
+ read VIO for the read operation initiated by
+ `<b>INKVConnRead</b>`.
+
+16. If the read VIO is the `<b>client_read_VIO</b>` (which we are
+ expecting at this stage in the transaction), then
+ `<b>state_interface_with_client</b>` updates the state to
+ `<b>state_read_request_from_client</b>` .
+
+17. `<b>state_read_request_from_client</b>` handles actual
+ `<b>INK_EVENT_READ_READY</b>` events and reads the client request.
+
+18. `<b>state_read_request_from_client</b>` parses the client
+ request.
+
+19. `<b>state_read_request_from_client</b>` updates the current
+ state to the next state, `<b>state_handle_cache_lookup</b>` .
+
+20. `<b>state_read_request_from_client</b>` arranges for Traffic
+ Server to call back the TSM with the next set of events (initiating
+ the cache lookup) by calling `<b>INKCacheRead</b>`.
+
+21. When the `<b>INKCacheRead</b>` sends the TSM either
+ `<b>INK_EVENT_OPEN_READ</b>` (a cache hit) or
+ `<b>INK_EVENT_OPEN_READ_FAILED</b>` (a cache miss),
+ `<b>main_handler</b>` calls `<b>state_handle_cache_lookup</b>`.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/OtherDeprecatedFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/OtherDeprecatedFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/OtherDeprecatedFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/OtherDeprecatedFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,66 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](App_DeprecatedFunctions) - Appendix B. Deprecated Fxns
+- MIME Header Fxns
+Deprecated IO Buffer Interface Fxns-
+[Next](Dep_IOBufferInterface)
+## Other Deprecated Functions
+
+**Table Of Contents**
+
+****
+[Statistics Functions](OtherDeprecatedFunctions#Dep_StatisticFunctions)
+- [INKStatFloatRead](OtherDeprecatedFunctions#INKStatFloatRead)
+- [INKStatIntRead](OtherDeprecatedFunctions#INKStatIntRead)
+
+[IO Buffer Interface Functions](Dep_IOBufferInterface)
+- [INKIOBufferAppend](Dep_IOBufferInterface#INKIOBufferAppend)
+- [INKIOBufferBlockCreate](Dep_IOBufferInterface#INKIOBufferBlockCreate)
+- [INKIOBufferDataCreate](Dep_IOBufferInterface#INKIOBufferDataCreate)
+
+[Mutex Functions](Dep_MutexFunctions)
+- [INKMutexTryLock](Dep_MutexFunctions#INKMutexTryLock)
+
+### Deprecated Statistics Functions
+
+****
+[INKStatFloatRead](OtherDeprecatedFunctions#INKStatFloatRead)
+[INKStatIntRead](OtherDeprecatedFunctions#INKStatIntRead)
+#### INKStatFloatRead
+
+Obtains the value of a float statistic. This API has been succeeded
+by `INKStatFloatGet`.
+
+**Prototype**
+ ~ `float INKStatFloat(INKStat <em class="replaceable"><code>the_stat`
+ )
+
+
+#### INKStatIntRead
+
+Obtains the value of an integer statistic. This API has been
+succeeded by `INKStatIntGet`.
+
+**Prototype**
+ ~ `INK64 INKStatIntRead(INKStat <em class="replaceable"><code>the_stat`
+ )
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginConfigurationFunctions.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginConfigurationFunctions.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginConfigurationFunctions.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginConfigurationFunctions.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,45 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](INKContSchedule) - INKContSchedule
+INKConfigGet - [Next](INKConfigGet)
+## Plugin Configuration Functions
+
+****
+[INKConfigDataGet](PluginConfigurationFunctions#INKConfigDataGet)
+[INKConfigGet](INKConfigGet)
+[INKConfigRelease](INKConfigRelease)
+[INKConfigSet](INKConfigSet)
+### INKConfigDataGet
+
+Gets configuration data.
+
+**Prototype**
+ ~ `void* INKConfigDataGet (INKConfig <em class="replaceable"><code>configp`)
+
+**Description**
+ ~ Retrieves the data pointer from within the configuration
+ pointer `<em class="replaceable"><code>configp`. Before using
+ `INKConfigDataGet`, you must give the configuration data an
+ identifier with `INKConfigSet` and then retrieve the `INKConfig`
+ pointer `<em class="replaceable"><code>configp` with a call to
+ `INKConfigGet` (see the code snippet in the previous section).
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginConfigurations.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginConfigurations.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginConfigurations.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginConfigurations.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,118 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](WritingHandlerFunctions) - Writing Handler Functions
+Chapter 14. Actions Guide - [Next](ActionsGuide)
+## Chapter 13. Plugin Configurations
+
+This chapter contains the following section:
+
+- [Plugin Configurations](PluginConfigurations#Plugin_Configs "Plugin Configurations")
+
+
+## Plugin Configurations
+
+The `INKConfig` family of functions provides a mechanism for
+accessing and changing global configuration information within a
+plugin.
+
+The functions discussed in this section do not examine or modify
+Traffic Server configuration variables. To examine Traffic Server
+configuration and statistics variables, see
+["Reading Traffic Server Settings and Statistics"](ReadTESettingStats "Reading Traffic Server Settings and Statistics").
+
+The `INKConfig` family of functions is designed to provide a fast
+and efficient mechanism for accessing and changing global
+configuration information within a plugin. Such a mechanism is
+simple enough to provide in a single-threaded program, but the
+translation to a multi-threaded program such as Traffic Server is
+difficult. A common technique is to have a single mutex protect the
+global configuration information; however, the problem with this
+solution is that a single mutex becomes a performance bottleneck
+very quickly.
+
+The `INKConfig` family of functions define an interface to storing
+and retrieving an opaque data pointer. Internally, Traffic Server
+maintains reference count information about the data pointer so
+that a call to `INKConfigSet` will not disturb another thread using
+the current data pointer. The philosophy is that once a user has a
+hold of the configuration pointer, it is okay for it to be used
+even if the configuration changes; all that a user typically wants
+is a non-changing snapshot of the configuration. You should use
+`INKConfigSet` for all global data updates.
+
+Here's how the interface works:
+
+ /* Assume that you have previously defined a plugin configuration
+ * data structure named ConfigData, along with its constructor
+ * plugin_config_allocator () and its destructor
+ * plugin_config_destructor (ConfigData *data)
+ */
+ ConfigData *plugin_config;
+
+ /* You will need to assign plugin_config a unique identifier of type
+ * unsigned int. It is important to initialize this identifier to zero
+ * (see the documentation of the function).
+ */
+ static unsigned int my_id = 0;
+
+ /* You will need an INKConfig pointer to access a snapshot of the
+ * current plugin_config.
+ */
+ INKConfig config_ptr;
+
+ /* Initialize plugin_config. */
+ plugin_config = plugin_config_allocator();
+
+ /* Assign plugin_config an identifier using INKConfigSet. */
+ my_id = INKConfigSet (my_id, plugin_config, plugin_config_destructor);
+
+ /* Get a snapshot of the current configuration using INKConfigGet. */
+ config_ptr = INKConfigGet (my_id);
+
+ /* With an INKConfig pointer to the current configuration, you can
+ * retrieve the configuration's current data using INKConfigDataGet.
+ */
+ plugin_config = (ConfigData*) INKConfigDataGet (config_ptr);
+
+ /* Do something with plugin_config here. */
+
+ /* When you are done with retrieving or modifying the plugin data, you
+ * release the pointers to the data with a call to INKConfigRelease.
+ */
+ INKConfigRelease (my_id, config_ptr);
+
+ /* Any time you want to modify plugin_config, you must repeat these
+ * steps, starting with
+ * my_id = INKConfigSet (my_id,plugin_config, plugin_config_destructor);
+ * and continuing up to INKConfigRelease.
+ */
+
+The configuration functions are:
+
+- `<a href="PluginConfigurationFunctions#INKConfigDataGet" title="INKConfigDataGet">INKConfigDataGet</a>`
+
+- `<a href="INKConfigGet.html" title="INKConfigGet">INKConfigGet</a>`
+
+- `<a href="INKConfigRelease.html" title="INKConfigRelease">INKConfigRelease</a>`
+
+- `<a href="INKConfigSet.html" title="INKConfigSet">INKConfigSet</a>`
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginManagement.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginManagement.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginManagement.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PluginManagement.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,51 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](CacheAPI_Example) - Example
+Reading Traffic Server Settings and Statistics -
+[Next](ReadTESettingStats)
+## Chapter 16. Plugin Management
+
+This chapter covers the following topics:
+
+- [Reading Traffic Server Settings and Statistics](ReadTESettingStats "Reading Traffic Server Settings and Statistics")
+
+ Using the functions in this chapter, plugins read Traffic Server
+ configuration settings and statistics from the `records.config`
+ file.
+
+- [Accessing Installed Plugin Files](AccessPluginFiles "Accessing Installed Plugin Files")
+
+ Put plugin access-related files in the plugin installation
+ directory and make sure your plugins are preserved during Traffic
+ Server upgrades.
+
+- [Licensing Your Plugin](LicensingPlugin "Licensing Your Plugin")
+
+ - [Setting Up Licensing](SetUpLicensing)
+ - [Generating a License Key](GenerateLicenseKey)
+
+- [Guide to the Logging API](LoggingAPI "Guide to the Logging API")
+
+ The logging API enables your plugin to log text entries in a custom
+ Traffic Server log file. This section provides a basic overview of
+ the logging interface.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PlusingRegisAndVersionCkg.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PlusingRegisAndVersionCkg.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PlusingRegisAndVersionCkg.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/PlusingRegisAndVersionCkg.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,87 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](RestartingTS) - Restart Traffic Server
+Naming Conventions - [Next](NamingConventions)
+## Plugin Registration and Version Checking
+
+Make sure that the functions in your plugin are supported in your
+version of Traffic Server.
+
+Use the following interfaces:
+
+- [INKPluginRegister](INKPluginRegister "INKPluginRegister")
+- [INKTrafficServerVersionGet](INKTrafficServerVersionGet "INKTrafficServerVersionGet")
+
+The following version of `hello-world` registers the plugin and
+ensures it's running with a compatible version of Traffic Server.
+
+ #include <stdio.h>
+ #include <ts/ts.h>
+ int
+ check_ts_version()
+ {
+
+ const char *ts_version = INKTrafficServerVersionGet();
+ 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
+ INKPluginInit (int argc, const char *argv[])
+ {
+
+ INKPluginRegistrationInfo info;
+
+ info.plugin_name = "hello-world";
+ info.vendor_name = "MyCompany";
+ info.support_email = "ts-api-support@MyCompany.com";
+
+ if (!INKPluginRegister (INK_SDK_VERSION_2_0 , &info)) {
+ INKError ("Plugin registration failed. \n");
+ }
+
+ if (!check_ts_version()) {
+ INKError ("Plugin requires Traffic Server 2.0 or later\n");
+ return;
+ }
+
+ INKDebug ("debug-hello", "Hello World!\n");
+ }
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Preface.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Preface.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Preface.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Preface.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,53 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](index) - Traffic Server Software Developers Kit
+How to Use This Book - [Next](pr01s02)
+## Preface
+
+**Table of Contents**
+
+[](Preface#Audience)
+[How to Use This Book](pr01s02)
+[Typographical Conventions](Conventions)
+The *Traffic Server Software Developer's Kit* is a reference for
+creating plugins. **Plugins** are programs that add services (such
+as filtering or content transformation) or entire features (such as
+new protocol support) to Traffic Server. If you are new to writing
+Traffic Server plugins, then read the first two chapters,
+[Getting Started](GetingStarted#GettingStarted) and
+[Creating Traffic Server Plugins](CreatingTSPlugins "Chapter 2. How to Create Traffic Server Plugins"),
+and use the remaining chapters as needed.
+[Header-Based Plugin Examples](HeaderBasedPluginEx "Chapter 4. Header-Based Plugin Examples")
+provides details about plugins that work on HTTP headers, while
+[HTTP Transformation Plugins](HTTPTransformationPlugins "Chapter 5. HTTP Transformation Plugins")
+explains how to write a plugin that transforms or scans the body of
+an HTTP response. If you want to support your own protocol on
+Traffic Server, then reference
+[New Protocol Plugins](NewProtocolPlugins "Chapter 6. New Protocol Plugins").
+
+## Audience
+
+This manual is intended for programmers who want to write plugin
+programs that add services or features to Traffic Server. It
+assumes a cursory knowledge of the C programming language,
+Hyper-Text Transfer Protocol (HTTP), and Multipurpose Internet Mail
+Extensions (MIME).
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ReadTESettingStats.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ReadTESettingStats.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ReadTESettingStats.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/ReadTESettingStats.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,62 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](PluginManagement) - Chapter 16. Plugin Management
+Accessing Installed Plugin Files - [Next](AccessPluginFiles)
+## Reading Traffic Server Settings and Statistics
+
+Your plugin might need to know information about Traffic Server's
+current configuration and performance. The functions described in
+this section read this information from the Traffic Server
+`records.config` file. Configuration settings are stored in
+`CONFIG` variables and statistics are stored in `PROCESS`
+variables.
+
+![[Caution]](images/docbook/caution.png)
+Caution
+Not all `CONFIG` and `PROCESS` variables in `records.config` are
+relevant to Traffic Server's configuration and statistics.
+Therefore, retrieve only the `records.config` variables that are
+documented in the
+[Traffic Server Administrator's Guide](../admin/).
+
+To retrieve a variable, you need to know its type (`int`,
+`counter`, `float`, or `string`). Plugins store the
+`records.config` values as an `INKMgmtInt`, `INKMgmtCounter`,
+`INKMgmtFloat`, or `INKMgmtString`. You can look up
+`records.config` variable types in the
+[Traffic Server Administrator's Guide](../admin/).
+
+Depending on the result type, you'll use `INKMgmtIntGet`,
+`INKMgmtCounterGet`, `INKMgmtFloatGet`, or `INKMgmtStringGet` to
+obtain the variable value (see the example for
+[INKMgmtIntGet](INKMgmtIntGet "INKMgmtIntGet")).
+
+The `INKMgmt*Get` functions are:
+
+- [INKMgmtCounterGet](TEConfigReadFunctions#INKMgmtCounterGet "INKMgmtCounterGet")
+
+- [INKMgmtFloatGet](INKMgmtFloatGet "INKMgmtFloatGet")
+
+- [INKMgmtIntGet](INKMgmtIntGet "INKMgmtIntGet")
+
+- [INKMgmtStringGet](INKMgmtStringGet "INKMgmtStringGet")
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RemapAPI_Example.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RemapAPI_Example.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RemapAPI_Example.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RemapAPI_Example.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,82 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](ch03) - Chapter 3. Remap Plugin: Getting Started
+Remap Plugin Function Reference [Next](ch03s02)
+## Example: Query Remap Plugin
+
+The sample remap plugin, `query_remap.c`, maps client requests to a
+number of servers based on a hash of the request's URL query
+parameter. This can be useful for spreading load for a given type
+of request among backend servers, while still maintaining
+"stickiness" to a single server for similar requests. For example,
+a search engine may want to send repeated queries for the same
+keywords to a server that has likely cached the result from a prior
+query.
+
+### Configuration of query\_remap
+
+The query remap plugin will allow the query parameter name to be
+specified, along with the hostnames of the servers to hash across.
+Sample `remap.config` rules using `query_remap` will look like:
+
+ map http://www.example.com/search http://srch1.example.com/search @plugin=query_remap.so @pparam=q @pparam=srch1.example.com @pparam=srch2.example.com @pparam=srch3.example.com
+
+ map http://www.example.com/profiles http://prof1.example.com/profiles @plugin=query_remap.so @pparam=user_id @pparam=prof1.example.com @pparam=prof2.example.com
+
+The first `@pparam` specifies the query param key for which the
+value will be hashed. The remaining parameters list the hostnames
+of the servers. A request for
+`http://www.example.com/search?q=apache` will match the first rule.
+The plugin will look for the `<em class="replaceable">q</em>`
+parameter and hash the value '`apache`' to pick from among
+`srch<em class="replaceable">[1-3]</em>.example.com` to send the
+request.
+
+If the request does not include a `<em class="replaceable">q</em>`
+query parameter and the plugin decides not to modify the request,
+the default toURL '`http://srch1.example.com/search`' will be used
+by TS.
+
+The parameters are passed to the plugin's `tsremap_new_instance`
+function. In `query_remap`, `tsremap_new_instance` creates a
+plugin-defined `query_remap_info` struct to store its configuration
+parameters. The ihandle, an opaque pointer that can be used to pass
+per-instance data, is set to this struct pointer and will be passed
+to the `tsremap_remap` function when it is triggered for a
+request.
+
+Another way remap plugins may want handle more complex
+configuration is to specify a configuration filename as a `pparam`
+and parse the specified file during instance initialization.
+
+### Performing the Remap
+
+The plugin implements the `tsremap_remap` function, which is called
+when TS has read the client HTTP request headers and matched the
+request to a remap rule configured for the plugin. The
+`TSRemapRequestInfo` struct contains input and output members for
+the remap operation.
+
+`tsremap_remap` uses the configuration information passed via the
+`ihandle` and checks the `request_query` for the configured query
+parameter. If the parameter is found, the plugin sets a `new_host`
+to modify the request host:
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RestartingTS.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RestartingTS.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RestartingTS.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RestartingTS.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,49 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](SpecifyingPluginLocation) - Specify the Plugin's
+Location
+Plugin Registration and Version Checking -
+[Next](PlusingRegisAndVersionCkg)
+### 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.
+
+ # grep proxy.config.plugin.plugin_dir config/records.config
+ CONFIG proxy.config.plugin.plugin_dir STRING config/plugins
+ # ls config/plugins
+ 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 'config/plugins/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.
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RlsMarshalBufHandles.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RlsMarshalBufHandles.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RlsMarshalBufHandles.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/RlsMarshalBufHandles.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,78 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](MIMEFldsBelongAssocMIMEHdr) - MIME Fields Always Belong
+to an Associated MIME Header
+Deprecated Functions - [Next](DeprecatedMarshBufFuncs)
+### Release Marshal Buffer Handles
+
+When you fetch a component object or create a new object, you get
+back a handle to the object location. The handle is either an
+`INKMLoc` for an object location or `char *` for a string
+location. You can manipulate the object through these handles, but
+when you are finished you need to release the handle to free up
+system resources.
+
+The general guideline is to release all `INKMLoc` and string
+handles you retrieve. The one exception is the string returned by
+`INKUrlStringGet`, which must be freed by a call to `INKfree`.
+
+The handle release functions expect three arguments: the marshal
+buffer containing the data, the location of the parent object, and
+the location of the object to be released. The parent location is
+usually clear from the creation of the `INKMLoc` or string. For
+example, if your plugin had the following calls:
+
+ url_loc = INKHttpHdrUrlGet (bufp, hdr_loc);
+ host_string = INKUrlHostGet (bufp, url_loc, &host_length);
+
+then your plugin would have to call:
+
+ INKHandleStringRelease (bufp, url_loc, host_string);
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+
+If an `INKMLoc` is obtained from a transaction, then it does not
+have a parent `INKMLoc`. Use the null `INKMLoc` constant
+`INK_NULL_MLOC` as its parent. For example, if your plugin calls:
+
+ INKHttpTxnClientReqGet (txnp, &bufp, &hdr_loc);
+
+then you must release `hdr_loc` with:
+
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+
+You need to use `INK_NULL_MLOC` to release any `INKMLoc` handles
+retrieved by the `INKHttpTxn*Get` functions.
+
+Here's an example using a new `INKMimeHdrField` function:
+
+ INKHttpTxnServerRespGet( txnp, &resp_bufp, &resp_hdr_loc );
+ new_field_loc = INKMimeHdrFieldCreate (resp_bufp, resp_hdr_loc);
+ INKHandleMLocRelease ( resp_bufp, resp_hdr_loc, new_field_loc);
+ INKHandleMLocRelease ( resp_bufp, INK_NULL_MLOC, resp_hdr_loc);
+
+See the sample plugins for many more examples.
+
+![[Tip]](images/docbook/tip.png)
+Tip
+You should release handles before reenabling the HTTP transaction.
+In other words, call `INKHandleMLocRelease` or
+`INKHandleStringRelease` before `INKHttpTxnReenable`.
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Roadmap_CreatingPlugins.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Roadmap_CreatingPlugins.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Roadmap_CreatingPlugins.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/Roadmap_CreatingPlugins.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,99 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](CreatingTSPlugins) - Chapter 2. How to Create Traffic
+Server Plugins
+Chapter 3. Remap Plugin - [Next](ch03)
+## Roadmap for Creating Plugins
+
+This chapter has provided an overview of Traffic Server's HTTP
+processing, API hooks, and the asynchronous event model. Next, you
+must understand the capabilities of Traffic Server API functions.
+These are quite broad:
+
+- **HTTP header manipulation functions**
+
+ Obtain information about and manipulate HTTP headers, URLs, & MIME
+ headers.
+
+- **HTTP transaction functions**
+
+ Get information about and modify HTTP transactions (for example:
+ get the client IP associated to the transaction; get the server IP;
+ get parent proxy information)
+
+- **IO functions**
+
+ Manipulate vconnections (virtual connections, used for network and
+ disk I/O)
+
+- **Network connection functions**
+
+ Open connections to remote servers.
+
+- **Statistics functions**
+
+ Define and compute statistics for your plugin's activity.
+
+- **Traffic Server management functions**
+
+ Obtain values for Traffic Server configuration and statistics
+ variables.
+
+
+Below are some guidelines for creating a plugin:
+
+1. Decide what you want your plugin to do, based on the
+ capabilities of the API and Traffic Server. Two main kinds of
+ example plugins provided with this SDK are HTTP-based (includes
+ header-based and response transform plugins), and non-HTTP-based (a
+ protocol plugin). These examples are discussed in the next three
+ chapters.
+
+2. Determine where your plugin needs to hook on to Traffic
+ Server's HTTP processing (view the
+ [HTTP Transaction State Diagram](HTTPHooksAndTransactions#Fig_HHTTPTxStateDiag "Figure 8.1. HTTP Transaction State Diagram")).
+
+3. Read
+ [Header-Based Plugin Examples](HeaderBasedPluginEx "Chapter 4. Header-Based Plugin Examples")
+ to learn the basics of writing plugins: creating continuations and
+ setting up hooks. If you want to write a plugin that transforms
+ data, then read
+ [HTTP Transformation Plugins](HTTPTransformationPlugins "Chapter 5. HTTP Transformation Plugins").
+
+4. Figure out what parts of the Traffic Server API you need to use
+ and then read about the details of those APIs in this manual's
+ reference chapters.
+
+5. Compile and load your plugin (see
+ [Getting Started](GetingStarted#GettingStarted)).
+
+6. Depending on your plugin's functionality, you might start
+ testing it by issuing requests by hand and checking for the desired
+ behavior in Traffic Server log files. See the
+ ***Traffic Server Administrator's Guide*** for information about
+ Traffic Server logs.
+
+7. You can test the performance of Traffic Server running with
+ your plugin using SDKTest. You can also customize SDKTest to
+ perform functional testing on your plugin; for more information see
+ the ***Traffic Server SDKTest User's Guide***.
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SampleBufferedNullTransformPlugin.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SampleBufferedNullTransformPlugin.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SampleBufferedNullTransformPlugin.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SampleBufferedNullTransformPlugin.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,191 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](AppendTransformPlugin) - The Append-Transform Plugin
+Chapter 6. New Protocol Plugins - [Next](NewProtocolPlugins)
+## The Sample Buffered Null Transform Plugin
+
+The buffered null transform, `bnull-transform.c`, reads the
+response content into a buffer and then writes the full buffer out
+to the client. Many examples of transformations, such as
+compression, require you to gather the full response content in
+order to perform the transformation.
+
+The buffered null transform uses a state variable to keep track of
+when it is (a) reading data into the buffer and (b) writing the
+data from the buffer to the downstream vconnection.
+
+The following is a step-by-step walk through the buffered null
+transform:
+
+1. Gets a handle to HTTP transactions.
+
+ void
+ INKPluginInit (int argc, const char *argv[]) {
+ INKHttpHookAdd (INK_HTTP_READ_RESPONSE_HDR_HOOK,
+ INKContCreate (transform_plugin, NULL)); }
+
+ With this `INKPluginInit` routine, the plugin is called back every
+ time Traffic Server reads a response header.
+
+2. Checks to see if the transaction response is transformable.
+
+ static int transform_plugin (INKCont contp, INKEvent event, void *edata) {
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+ switch (event) {
+ case INK_EVENT_HTTP_READ_RESPONSE_HDR:
+ if (transformable (txnp)) {
+ transform_add (txnp);}
+
+ The default behavior for transformations is to cache the
+ transformed content (if desired, you also can tell Traffic Server
+ to cache untransformed content). Therefore, only responses received
+ directly from an origin server need to be transformed. Objects
+ served from the cache are already transformed. To determine whether
+ the response is from the origin server, the routine transformable
+ checks the response header for the "200 OK" server response.
+
+ {
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKHttpStatus resp_status;
+
+ INKHttpTxnServerRespGet (txnp, &bufp, &hdr_loc);
+
+ if(INK_HTTP_STATUS_OK==
+ (resp_status=INKHttpHdrStatusGet(bufp,hdr_loc)))
+ {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }
+
+3. If the response is transformable, then the plugin creates a
+ transformation vconnection that gets called back when the response
+ data is ready to be transformed (as it is streaming from the origin
+ server).
+
+ static void transform_add (INKHttpTxn txnp)
+ {
+ INKVConn connp;
+ connp = INKTransformCreate (bnull_transform, txnp);
+ INKHttpTxnHookAdd (txnp, INK_HTTP_RESPONSE_TRANSFORM_HOOK, connp);
+ }
+
+ The previous code fragment shows that the handler function for the
+ transformation vconnection is `bnull_transform`.
+
+4. The `bnull_transform` function has to handle `ERROR`,
+ `WRITE_COMPLETE`, `WRITE_READY`, and `IMMEDIATE` events. If the
+ transform is just beginning, the event received is probably
+ `IMMEDIATE`. The `bnull_transform` function calls
+ `handle_transform` to handle `WRITE_READY` and `IMMEDIATE`.
+
+5. The `handle_transform` function examines the data parameter for
+ the continuation passed to it (the continuation passed to
+ `handle_transform` is the transformation vconnection). The data
+ structure keeps track of two states: copying the data into the
+ buffer (`STATE_BUFFER_DATA`) and writing the contents of the buffer
+ to the output vconnection (`STATE_OUTPUT_DATA`).
+
+6. Get a handle to the input VIO (see the `handle_buffering`
+ function).
+
+ input_vio = INKVConnWriteVIOGet (contp);
+
+ This is so that the transformation can get information about the
+ upstream vconnection's write operation to the input buffer.
+
+7. Copy data from the input buffer to the output buffer. See the
+ `handle_buffering` function for the following code fragment:
+
+ INKIOBufferCopy (data->output_buffer,
+ INKVIOReaderGet (write_vio), towrite, 0);
+
+8. Tell the input buffer that the transformation has read the
+ data. See the `handle_buffering` function for the following code
+ fragment:
+
+ INKIOBufferReaderConsume (INKVIOReaderGet (write_vio), towrite);
+
+9. Modify the input VIO to tell it how much data has been read
+ (increase the value of `ndone`). See the `handle_buffering`
+ function for the following code fragment:
+
+ INKVIONDoneSet (write_vio, INKVIONDoneGet (write_vio) + towrite); }
+
+10. If there is more data left to read
+ (`if ndone < nbytes`), then the `handle_buffering`
+ function wakes up the upstream vconnection by sending it
+ `WRITE_READY`:
+
+ if (INKVIONTodoGet (write_vio) > 0) {
+ if (towrite > 0) {
+ INKContCall (INKVIOContGet (write_vio),
+ INK_EVENT_VCONN_WRITE_READY, write_vio);
+ }
+ } else {
+
+ The process of passing data through the transformation is
+ illustrated in the following diagram. The transformation sends
+ `WRITE_READY` events when it needs more data; when data is
+ available, the upstream vconnection reenables the transformation
+ with an `IMMEDIATE` event.
+
+ **Figure 5.4. Reading Data Into the Buffer (the `STATE_BUFFER_DATA` State)**
+
+ 
+11. When the data is read into the output buffer, the
+ `handle_buffering` function sets the state of the transformation's
+ data structure to `STATE_OUTPUT_DATA` and calls the upstream
+ vconnection back with the `WRITE_COMPLETE` event.
+
+ data->state = STATE_OUTPUT_DATA;
+ INKContCall (INKVIOContGet (write_vio),
+ INK_EVENT_VCONN_WRITE_COMPLETE, write_vio);
+
+12. The upstream vconnection will probably shut down the write
+ operation when it receives the `WRITE_COMPLETE` event. The handler
+ function of the transformation, `bnull_transform`, receives an
+ `IMMEDIATE` event and calls the `handle_transform` function. This
+ time, the state is `STATE_OUTPUT_DATA`, so `handle_transform` calls
+ `handle_output`.
+
+13. The `handle_output` function gets a handle to the output
+ vconnection:
+
+ output_conn = INKTransformOutputVConnGet (contp);
+
+14. The `handle_output` function writes the buffer to the output
+ vconnection:
+
+ data->output_vio =
+ INKVConnWrite (output_conn, contp, data->output_reader,
+ INKIOBufferReaderAvail (data->output_reader) );
+
+ The following diagram illustrates the write to the output
+ vconnection:
+
+ **Figure 5.5. Writing the Buffered Data to the Output Vconnection**
+
+ 
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SampleNullTransformPlugin.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SampleNullTransformPlugin.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SampleNullTransformPlugin.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SampleNullTransformPlugin.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,193 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](HTTPTransformationPlugins) - Chapter 5. HTTP
+Transformation Plugins
+The Append-Transform Plugin - [Next](AppendTransformPlugin)
+## The Sample Null Transform Plugin
+
+This section provides a step-by-step description of what the null
+transform plugin does, along with sections of code that apply. For
+context, you can find each code snippet in the complete source
+code. Some of the error checking details are left out - to give the
+description a step-by-step flow, only the highlights of the
+transform are included.
+
+Below is an overview of the null transform plugin:
+
+1. Gets a handle to HTTP transactions.
+
+ void
+ INKPluginInit (int argc, const char *argv[]) {
+ INKHttpHookAdd (INK_HTTP_READ_RESPONSE_HDR_HOOK,
+ INKContCreate (transform_plugin, NULL));
+
+ With this `INKPluginInit` routine, the plugin is called back every
+ time Traffic Server reads a response header.
+
+2. Checks to see if the transaction response is transformable.
+
+ static int transform_plugin (INKCont contp, INKEvent event, void *edata) {
+ INKHttpTxn txnp = (INKHttpTxn) edata;
+ switch (event) {
+ case INK_EVENT_HTTP_READ_RESPONSE_HDR:
+ if (transformable (txnp)) {
+ transform_add (txnp);}
+
+ The default behavior for transformations is to cache the
+ transformed content (you can also tell Traffic Server to cache
+ untransformed content, if you want). Therefore, only responses
+ received directly from an origin server need to be transformed.
+ Objects served from cache are already transformed. To determine
+ whether the response is from the origin server, the routine
+ `transformable` checks the response header for the "200 OK" server
+ response.
+
+ static int transformable (INKHttpTxn txnp)
+ {
+ INKMBuffer bufp;
+ INKMLoc hdr_loc;
+ INKHttpStatus resp_status;
+ INKHttpTxnServerRespGet (txnp, &bufp, &hdr_loc);
+
+ if (INK_HTTP_STATUS_OK == (resp_status =
+ INKHttpHdrStatusGet (bufp, hdr_loc)) ) {
+ return 1;
+ } else {
+ return 0;
+ }
+ }
+
+3. If the response is transformable, then the plugin creates a
+ transformation vconnection that gets called back when the response
+ data is ready to be transformed (as it is streaming from the origin
+ server).
+
+ static void transform_add (INKHttpTxn txnp)
+ {
+ INKVConn connp;
+ connp = INKTransformCreate (null_transform, txnp);
+ INKHttpTxnHookAdd (txnp, INK_HTTP_RESPONSE_TRANSFORM_HOOK, connp);
+ }
+
+ The previous code fragment shows that the handler function for the
+ transformation vconnection is `null_transform`.
+
+4. Get a handle to the output vconnection (that receives data from
+ the tranformation).
+
+ output_conn = INKTransformOutputVConnGet (con
+
+5. Get a handle to the input VIO. (See the `handle_transform`
+ function.)
+
+ input_vio = INKVConnWriteVIOGet (contp);
+
+ This is so that the transformation can get information about the
+ upstream vconnection's write operation to the input buffer.
+
+6. Initiate a write to the output vconnection of the specified
+ number of bytes. When the write is initiated, the transformation
+ expects to receive `WRITE_READY`, `WRITE_COMPLETE`, or `ERROR`
+ events from the output vconnection.
+
+ See the `handle_transform` function for the following code
+ fragment:
+
+ data->output_vio = INKVConnWrite (output_conn, contp,
+ data->output_reader, INKVIONBytesGet (input_vio));
+
+7. Copy data from the input buffer to the output buffer. See the
+ `handle_transform` function for the following code fragment:
+
+ INKIOBufferCopy (INKVIOBufferGet (data->output_vio),
+ INKVIOReaderGet (input_vio), towrite, 0);
+
+8. Tell the input buffer that the transformation has read the
+ data. See the `handle_transform` function for the following code
+ fragment:
+
+ INKIOBufferReaderConsume (INKVIOReaderGet (input_vio), towrite);
+
+9. Modify the input VIO to tell it how much data has been read
+ (increase the value of `ndone`). See the `handle_transform`
+ function for the following code fragment:
+
+ INKVIONDoneSet (input_vio, INKVIONDoneGet (input_vio) + towrite);
+
+10. If there is more data left to read
+ (`if ndone < nbytes`), then the `handle_transform`
+ function wakes up the downstream vconnection with a reenable and
+ wakes up the upstream vconnection by sending it `WRITE_READY`:
+
+ if (INKVIONTodoGet (input_vio) > 0) {
+ if (towrite > 0) {
+ INKVIOReenable (data->output_vio);
+
+ INKContCall (INKVIOContGet (input_vio),
+ INK_EVENT_VCONN_WRITE_READY, input_vio);
+ }
+ } else {
+
+ The process of passing data through the transformation is
+ illustrated in the following diagram. The downstream vconnections
+ send `WRITE_READY` events when they need more data; when data is
+ available, the upstream vconnections reenable the downstream
+ vconnections. In this instance, the `INKVIOReenable` function sends
+ `INK_EVENT_IMMEDIATE`.
+
+ **Figure 5.2. Passing Data Through a Transformation**
+
+ 
+11. If the `handle_transform` function finds there is no more data
+ to read, then it sets `nbytes` to `ndone` on the output
+ (downstream) VIO and wakes up the output vconnection with a
+ reenable. It then triggers the end of the write operation from the
+ upstream vconnection by sending the upstream vconnection a
+ `WRITE_COMPLETE` event.
+
+ } else {
+
+ INKVIONBytesSet (data->output_vio, INKVIONDoneGet (input_vio));
+ INKVIOReenable (data->output_vio);
+ INKContCall (INKVIOContGet (input_vio),
+ INK_EVENT_VCONN_WRITE_COMPLETE, input_vio);
+ }
+
+ When the upstream vconnection receives the `WRITE_COMPLETE` event,
+ it will probably shut down the write operation.
+
+12. Similarly, when the downstream vconnection has consumed all of
+ the data, it sends the transformation a `WRITE_COMPLETE` event. The
+ transformation handles this event with a shut down (the
+ transformation shuts down the write operation to the downstream
+ vconnection). See the `null_plugin` function for the following code
+ fragment:
+
+ case INK_EVENT_VCONN_WRITE_COMPLETE:
+ INKVConnShutdown (INKTransformOutputVConnGet (contp), 0, 1
+ break;
+
+ The following diagram illustrates the flow of events:
+
+ **Figure 5.3. Ending the Transformation**
+
+ 
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SetTransactionHook.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SetTransactionHook.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SetTransactionHook.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SetTransactionHook.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,59 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](WorkWithHTTPHeaders) - Working With HTTP Headers
+Chapter 5. HTTP Transformation Plugins -
+[Next](HTTPTransformationPlugins)
+### Setting a Transaction Hook
+
+If the request does not have the `Proxy-Authorization` field set to
+Basic authorization or a valid username/password, then the plugin
+sends the `407 Proxy authorization` `required` status code
+back to the client. The client will then prompt the user for a
+username and password, and then resend the request.
+
+In the `handle_dns` routine, the following lines handle the
+authorization error case:
+
+ done:
+ INKHttpTxnHookAdd (txnp, INK_HTTP_SEND_RESPONSE_HDR_HOOK, contp);
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_ERROR);
+
+If `handle_dns` does not find the `Proxy-Authorization` field set
+to Basic authorization or a valid username/password, then it adds a
+`SEND_RESPONSE_HDR_HOOK` to the transaction being processed. This
+means that Traffic Server will call the plugin back when sending
+the client response. `handle_dns` reenables the transaction with
+`INK_EVENT_HTTP_ERROR`, which means that the plugin wants Traffic
+Server to terminate the transaction.
+
+When Traffic Server terminates the transaction, it sends the client
+an error message. Because of the `SEND_RESPONSE_HDR_HOOK`, Traffic
+Server calls the plugin back. The `auth-plugin` routine calls
+`handle_response` to send the client a `407` status code. When the
+client resends the request with the `Proxy- Authorization`
+field, a new transaction begins.
+
+`handle_dns` calls `base64_decode` to decode the username and
+password; `handle_dns` also calls `authorized` to validate the
+username and password. In this plugin, sample NT code is provided
+for password validation. UNIX programmers can supply their own
+validation mechanism.
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SetUpLicensing.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SetUpLicensing.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SetUpLicensing.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SetUpLicensing.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,74 @@
+[](/index)â¢
+# Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](LicensingPlugin) - Licensing Your Plugin
+Generating a License Key - [Next](GenerateLicenseKey)
+## Setting Up Licensing
+
+Set up licensing with the steps below:
+
+1. Develop your plugin using the `INKPluginLicenseRequired`
+ function.
+
+2. Create an installation program for your plugin. The
+ installation program must update both `plugin.config` and
+ `plugin.db`. When your plugin customer installs the plugin, the
+ program should ask the customer for the license key.
+
+3. Use the `gen_key` tool to generate license keys. You can
+ generate different keys for different customers and you can set
+ expiration dates for each key.
+
+4. Distribute your plugin, with the license key, to customers.
+
+
+When the customer installs the plugin, the installation program
+should ask for the license key. The installation program should
+then make an entry in `plugin.db` and `plugin.config` for the new
+plugin. When the customer runs the plugin, Traffic Server checks
+the license key. If it passes, then Traffic Server calls
+`INKPluginInit`.
+
+### Example
+
+- Suppose you have a plugin filtering, implemented in the object
+ `filtering.so`
+
+- Generate a key for your plugin filtering via:
+
+ `gen_key filtering ABCDE 03312002`
+
+- The key generated by `gen_key` is:
+
+ `ABCDE2E01E07D95`
+
+- Update `plugin.db` by adding the following lines:
+
+ [filtering]
+ Object=filtering.so
+ License=ABCDE2E01E07D95
+
+
+The following function is used to license your plugin:
+
+- [INKPluginLicenseRequired](INKPluginLicenseRequired "INKPluginLicenseRequired")
+
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SettingGlobalHook.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SettingGlobalHook.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SettingGlobalHook.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SettingGlobalHook.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,42 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](BlacklistPlugin) - The Blacklist Plugin
+Setting Up UI Update Callbacks -
+[Next](SettingUpUIUpdateCallbacks)
+### Setting a Global Hook
+
+Global hooks are always added in `INKPluginInit` using
+`INKHttpHookAdd`. The two arguments of `INKHttpHookAdd` are the
+hook ID and the continuation to call when processing the event
+corresponding to the hook. In `blacklist-1.c`, the global hook is
+added as follows:
+
+ INKHttpHookAdd (INK_HTTP_OS_DNS_HOOK, contp);
+
+Above, `INK_HTTP_OS_DNS_HOOK` is the ID for the origin server DNS
+lookup hook and `contp` is the parent continuation created
+earlier.
+
+This means that the Blacklist plugin is called at every origin
+server DNS lookup. When it is called, the handler
+function`blacklist_plugin` receives `INK_EVENT_HTTP_OS_DNS` and
+calls `handle_dn``s` to see if the request is forbidden.
+
Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SettingUpTransacHook.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SettingUpTransacHook.en.mdtext?rev=1031963&r1=1031962&r2=1031963&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SettingUpTransacHook.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/SettingUpTransacHook.en.mdtext Sat Nov 6 06:29:56 2010
@@ -1,2 +1,89 @@
+Title: Apache Traffic Server⢠Software Developers Kit
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+[Prev](AccessingTransactionProc) - Accessing the Transaction
+Being Processed
+Working with HTTP Header Functions -
+[Next](WorkWHTTPHeaderFunc)
+### Setting Up a Transaction Hook
+
+The Blacklist plugin sends "access forbidden" messages to clients
+if their requests are directed to blacklisted hosts. Therefore, the
+plugin needs a transaction hook so it will be called back when
+Traffic Server's HTTP state machine reaches the "send response
+header" event. In the Blacklist plugin's `handle_dns` routine, the
+transaction hook is added as follows:
+
+ INKMutexLock (sites_mutex);
+ for (i = 0; i < nsites; i++) {
+ if (strncmp (host, sites[i], host_length) == 0) {
+ printf ("blacklisting site: %s\n", sites[i]);
+ INKHttpTxnHookAdd (txnp,
+ INK_HTTP_SEND_RESPONSE_HDR_HOOK,
+ contp);
+ INKHandleStringRelease (bufp, url_loc, host);
+ INKHandleMLocRelease (bufp, hdr_loc, url_loc);
+ INKHandleMLocRelease (bufp, INK_NULL_MLOC, hdr_loc);
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_ERROR);
+ INKMutexUnlock (sites_mutex);
+ return;
+ }
+ }
+ INKMutexUnlock (sites_mutex);
+ done:
+ INKHttpTxnReenable (txnp, INK_EVENT_HTTP_CONTINUE);
+ }
+
+This code fragment shows some interesting features. The plugin is
+comparing the requested site to the list of blacklisted sites.
+While the plugin is using the blacklist, it must acquire the mutex
+lock for the blacklist to prevent configuration changes in the
+middle of a blacklisting operation. If the requested site is
+blacklisted, then the following things happen:
+
+1. A transaction hook is added with `INKHttpTxnHookAdd`; the
+ plugin is called back at the "send response header" event (i.e.,
+ the plugin sends an `Access forbidden` message to the
+ client). You can see that in order to add a transaction hook, you
+ need a handle to the transaction being processed.
+
+2. The transaction is reenabled using `INKHttpTxnReenable` with
+ `INK_EVENT_HTTP_ERROR` as its event argument. Reenabling with an
+ error event tells the HTTP state machine to stop the transaction
+ and jump to the "send response header" state. Notice that if the
+ requested site is not blacklisted, then the transaction is
+ reenabled with the `INK_EVENT_HTTP_CONTINUE` event.
+
+3. The string and `INKMLoc` data stored in the marshal buffer
+ `bufp` is released by `INKHandleStringRelease` and
+ `INKHandleMLocRelease` (see
+ [Release Marshal Buffer Handles](RlsMarshalBufHandles "Release Marshal Buffer Handles")).
+ Release these handles before reenabling the transaction.
+
+
+In general, whenever the plugin is doing something to a
+transaction, it must reenable the transaction when it is finished.
+In other words: every time your handler function handles a
+transaction event, it must call `INKHttpTxnReenable` when it is
+finished. Similarly, after your plugin handles session events
+(`INK_EVENT_HTTP_SSN_START` and `INK_EVENT_HTTP_SSN_CLOSE`), it
+must reenable the session with `INKHttpSsnReenable`. Reenabling the
+transaction twice in the same plugin routine is a bad error.
+