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 <jpe...@apache.org> Authored: Thu Dec 20 09:37:02 2012 -0800 Committer: James Peach <jpe...@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
