[2/2] git commit: Add man page for TSRemapInit

[jp...@apache.org]

Add man page for TSRemapInit


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/15c4d788
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/15c4d788
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/15c4d788

Branch: refs/heads/master
Commit: 15c4d78818fd6bc2fb10e144ed786ce9f09cbbad
Parents: c847b2c
Author: James Peach <jp...@apache.org>
Authored: Tue Oct 30 10:02:26 2012 -0700
Committer: James Peach <jp...@apache.org>
Committed: Tue Oct 30 10:02:26 2012 -0700

----------------------------------------------------------------------
 doc/Makefile.am       |    1 +
 doc/sdk/TSRemapInit.3 |  131 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 132 insertions(+), 0 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/15c4d788/doc/Makefile.am
----------------------------------------------------------------------
diff --git a/doc/Makefile.am b/doc/Makefile.am
index c6866e2..2a84596 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -85,6 +85,7 @@ man3_MANS = \
   sdk/TSMBufferCreate.3 \
   sdk/TSMalloc.3 \
   sdk/TSPluginInit.3 \
+  sdk/TSRemapInit.3 \
   sdk/TSTrafficServerVersionGet.3 \
   sdk/TSUrlCreate.3
 

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/15c4d788/doc/sdk/TSRemapInit.3
----------------------------------------------------------------------
diff --git a/doc/sdk/TSRemapInit.3 b/doc/sdk/TSRemapInit.3
new file mode 100644
index 0000000..896d502
--- /dev/null
+++ b/doc/sdk/TSRemapInit.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