You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2013/07/13 06:32:53 UTC
[2/3] git commit: doc: convert TSHttpHookAdd to sphinx
doc: convert TSHttpHookAdd to sphinx
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/60dbe3e7
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/60dbe3e7
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/60dbe3e7
Branch: refs/heads/master
Commit: 60dbe3e7f1101bff1b1a0b8024c3674a62672f58
Parents: d12b21e
Author: James Peach <jp...@apache.org>
Authored: Fri Jul 12 21:31:37 2013 -0700
Committer: James Peach <jp...@apache.org>
Committed: Fri Jul 12 21:31:37 2013 -0700
----------------------------------------------------------------------
doc/conf.py | 1 +
doc/sdk/man/TSHttpHookAdd.en.rst | 120 ++++++++++++++++++++++++++++++++++
doc/sdk/man/index.en.rst | 1 +
3 files changed, 122 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/60dbe3e7/doc/conf.py
----------------------------------------------------------------------
diff --git a/doc/conf.py b/doc/conf.py
index ba55897..82212a9 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -215,6 +215,7 @@ latex_documents = [
man_pages = [
('sdk/man/TSAPI.en', 'TSAPI', u'Introduction to the Apache Traffic Server API', None, u'3ts'),
('sdk/man/TSDebug.en', 'TSDebug', u'Traffic Server Debugging APIs', None, u'3ts'),
+ ('sdk/man/TSHttpHookAdd.en', 'TSHttpHookAdd', u'Intercept Traffic Server events', None, u'3ts'),
]
# If true, show URL addresses after external links.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/60dbe3e7/doc/sdk/man/TSHttpHookAdd.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/man/TSHttpHookAdd.en.rst b/doc/sdk/man/TSHttpHookAdd.en.rst
new file mode 100644
index 0000000..d791db5
--- /dev/null
+++ b/doc/sdk/man/TSHttpHookAdd.en.rst
@@ -0,0 +1,120 @@
+.. 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.
+
+.. default-domain:: c
+
+===============
+`TSHttpHookAdd`
+===============
+
+Library
+=======
+Apache Traffic Server plugin API
+
+Synopsis
+========
+`#include <ts/ts.h>`
+
+.. function:: void TSHttpHookAdd(TSHttpHookID id, TSCont contp)
+.. function:: void TSHttpSsnHookAdd(TSHttpSsn ssnp, TSHttpHookID id, TSCont contp)
+.. function:: void TSHttpTxnHookAdd(TSHttpTxn txnp, TSHttpHookID id, TSCont contp)
+
+Description
+===========
+
+Hooks are points in Apache Traffic Server transaction HTTP processing
+where plugins can step in and do some work. Registering a plugin
+function for callback amounts to adding the function to a hook. You
+can register your plugin to be called back for every single
+transaction, or for specific transactions only.
+
+HTTP transaction hooks are set on a global basis using the function
+:func:`TSHttpHookAdd`. This means that the continuation specified
+as the parameter to :func:`TSHttpHookAdd` is called for every
+transaction. :func:`TSHttpHookAdd` is typically called from
+:func:`TSPluginInit` or :func:`TSRemapInit`.
+
+A session consists of a single client connection to Traffic Server.
+A session can consist of several transactions in succession. The
+session starts when the client connection opens, and ends when the
+connection closes. :func:`TSHttpSsnHookAdd` adds :data:`contp` to
+the end of the list of HTTP transaction hooks specified by :data:`id`.
+This means that :data:`contp` is called back for every transaction
+within the session, at the point specified by the hook ID. Since
+:data:`contp` is added to a session, it is not possible to call
+:func:`TSHttpSsnHookAdd` from the plugin initialization routine;
+the plugin needs a handle to an HTTP session.
+
+A transaction consists of a single HTTP request from a client and
+the response that Traffic Server sends to that client. A transaction
+begins when Traffic Server receives a request, and ends when Traffic
+Server sends the response. :func:`TSHttpTxnHookAdd` adds :data:`contp`
+to the end of the list of HTTP transaction hooks specified by
+:data:`id`. Since :data:`contp` is added to a transaction, it is
+not possible to call :func:`TSHttpTxnHookAdd` from the plugin
+initialization routine but only when the plugin has a handle to an
+HTTP transaction.
+
+Return values
+=============
+
+None. Adding hooks is always successful.
+
+Examples
+========
+
+The following example demonstrates how to add global, session and
+transaction hooks::
+
+ #include <ts/ts.h>
+
+ static int
+ handler(TSCont contp, TSEvent event, void *edata)
+ {
+ TSHttpSsn ssnp;
+ TSHttpTxn txnp;
+
+ switch (event){
+ case TS_EVENT_HTTP_SSN_START:
+ ssnp = (TSHttpSsn) edata;
+ // Add a session hook ...
+ TSHttpSsnHookAdd(ssnp, TS_HTTP_TXN_START_HOOK, contp);
+ TSHttpSsnReenable(ssnp, TS_EVENT_HTTP_CONTINUE);
+ return 0;
+ case TS_EVENT_HTTP_TXN_START:
+ txnp = (TSHttpTxn) edata;
+ // Add a transaction hook ...
+ TSHttpTxnHookAdd(ssnp, TS_HTTP_READ_REQUEST_HDR_HOOK, contp);
+ TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE);
+ return 0;
+ default:
+ break;
+ }
+
+ return 0;
+ }
+
+ void
+ TSPluginInit (int argc, const char *argv[])
+ {
+ TSCont contp;
+ contp = TSContCreate(handler, NULL);
+ TSHttpHookAdd(TS_HTTP_SSN_START_HOOK, contp);
+ }
+
+SEE ALSO
+========
+:manpage:`TSAPI(3ts)`, :manpage:`TSContCreate(3ts)`
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/60dbe3e7/doc/sdk/man/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/man/index.en.rst b/doc/sdk/man/index.en.rst
index 55f4b09..17b7210 100644
--- a/doc/sdk/man/index.en.rst
+++ b/doc/sdk/man/index.en.rst
@@ -23,4 +23,5 @@ API Reference
TSAPI.en
TSDebug.en
+ TSHttpHookAdd.en