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 2012/12/20 18:38:54 UTC
git commit: Partial TSRemap man page
Updated Branches:
refs/heads/master 39ad174d5 -> 4ed5db50b
Partial TSRemap man page
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/4ed5db50
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/4ed5db50
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/4ed5db50
Branch: refs/heads/master
Commit: 4ed5db50baa2b4c21f6a9a8c8e623da49aded1c8
Parents: 39ad174
Author: James Peach <jp...@apache.org>
Authored: Thu Dec 20 09:37:02 2012 -0800
Committer: James Peach <jp...@apache.org>
Committed: Thu Dec 20 09:37:29 2012 -0800
----------------------------------------------------------------------
doc/Makefile.am | 3 +-
doc/sdk/TSRemap.3 | 131 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 133 insertions(+), 1 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ed5db50/doc/Makefile.am
----------------------------------------------------------------------
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 81312c2..784e70e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -80,13 +80,14 @@ man1_MANS = \
man/traffic_shell.1
man3_MANS = \
- sdk/TSHttpHookAdd.3 \
sdk/TSAPI.3 \
sdk/TSDebug.3 \
+ sdk/TSHttpHookAdd.3 \
sdk/TSInstallDirGet.3 \
sdk/TSMBufferCreate.3 \
sdk/TSMalloc.3 \
sdk/TSPluginInit.3 \
+ sdk/TSRemap.3 \
sdk/TSRemapInit.3 \
sdk/TSTrafficServerVersionGet.3 \
sdk/TSUrlCreate.3
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4ed5db50/doc/sdk/TSRemap.3
----------------------------------------------------------------------
diff --git a/doc/sdk/TSRemap.3 b/doc/sdk/TSRemap.3
new file mode 100644
index 0000000..db0e329
--- /dev/null
+++ b/doc/sdk/TSRemap.3
@@ -0,0 +1,131 @@
+.\" 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 .\"
+.Dd October 30, 2012
+.Dt TSRemapInit 3ts TSAPI
+.Sh NAME
+.Nm TSRemapInit,
+.Nm TSRemapDone,
+.Nm TSRemapDoRemap,
+.Nm TSRemapNewInstance,
+.Nm TSRemapDeleteInstance,
+.Nm TSRemapOSResponse
+.Nd remap plugin entry points
+.Sh LIBRARY
+Apache Traffic Server remap plugin API
+.Sh SYNOPSIS
+.In ts/ts.h
+.In ts/remap.h
+.Ft "TSReturnCode"
+.Fo TSRemapInit
+.Fa "TSRemapInterface* api_info"
+.Fa "char* errbuf"
+.Fa "int errbuf_size"
+.Fc
+.Ft "void"
+.Fo TSRemapDone
+.Fa "void"
+.Fc
+.Ft "TSRemapStatus"
+.Fo TSRemapDoRemap
+.Fa "void* ih"
+.Fa "TSHttpTxn rh"
+.Fa "TSRemapRequestInfo* rri"
+.Fc
+.Ft "TSReturnCode"
+.Fo TSRemapNewInstance
+.Fa "int argc"
+.Fa "char* argv[]"
+.Fa "void** ih"
+.Fa "char* errbuf"
+.Fa "int errbuf_size"
+.Fc
+.Ft "void"
+.Fo TSRemapDeleteInstance
+.Fa "void*"
+.Fc
+.Ft "void"
+.Fo TSRemapOSResponse
+.Fa "void* ih"
+.Fa "TSHttpTxn rh"
+.Fa "int os_response_type"
+.Fc
+.Sh DESCRIPTION
+The Traffic Server remap interface provides a simplified mechanism
+for plugins to manipulate HTTP transactions. A remap plugin is not
+global; it is configured on a per-remap rule basis, which enables
+you to customize how URLs are redirected based on individual rules
+in the remap.config file. Writing a remap plugin consists of implementing one
+or more of the remap entry points and configuring the remap.config
+configuration file to route the transaction through your plugin. Multiple
+remap plugins can be specified for a single remap rule, resulting in a remap
+plugin chain where each pligin is given an opportunity to examine the HTTP
+transaction.
+.Pp
+.Fn TSRemapInit
+is a required entry point. This function will be called once when Traffic
+Server loads the plugin. If the optional
+.Fn TSRemapDone
+entry point is available, Traffic Server will call then when unloading the
+remap plugin.
+.Pp
+A remap plugin may be invoked for different remap rules. Traffic Server will
+call the
+.fn TSRemapNewInstance
+entry point each time a plugin is specified in a remap rule. When a remap
+plugin instance is no longer required, Traffic Server will call
+.Fn TSRemapDeleteInstance .
+.Pp
+.Fn TSRemapDoRemap
+is called for each HTTP transaction. This is a mandatory entry point. In this
+function, the remap plugin may examine and modify the HTTP transaction.
+.Sh RETURN VALUES
+.Fn TSRemapInit
+and
+.Fn TSRemapNewInstance
+should return
+.Fa TS_SUCCESS
+on success, and
+.Fa TS_ERROR
+otherwise. A return value of
+.Fa TS_ERROR
+is unrecoverable.
+.Pp
+.Fn TSRemapDoRemap
+returns a status code that indicates whether the HTTP transaction has been
+modified and whether Traffic Server should continue to evaluate the chain of
+remap plugins. If the transaction was modified, the plugin should return
+.Fa TSREMAP_DID_REMAP
+or
+.Fa TSREMAP_DID_REMAP_STOP ;
+otherwise it should return
+.Fa TSREMAP_NO_REMAP
+or
+.Fa TSREMAP_NO_REMAP_STOP .
+If Traffic Server should not send the transaction to subsequent plugins in the
+remap chain, return
+.Fa TSREMAP_NO_REMAP_STOP
+or
+.Fa TSREMAP_DID_REMAP_STOP .
+Returning
+.Fa TSREMAP_ERROR
+causes Traffic Server to stop evaluating the remap chain and respond with an
+error.
+.Sh EXAMPLES
+.nf
+#include <ts/ts.h>
+#include <ts/remap.h>
+.fi
+.Sh SEE ALSO
+.Xr TSAPI 3ts