[18/52] [abbrv] git commit: doc: convert TSRemap(3) to sphinx

[zw...@apache.org]

doc: convert TSRemap(3) to sphinx


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

Branch: refs/heads/3.3.x
Commit: fa4be92b4d59ecc64fff75c827390c1abc5ffed0
Parents: 80b644e
Author: James Peach <jp...@apache.org>
Authored: Thu Aug 1 11:27:56 2013 -0700
Committer: James Peach <jp...@apache.org>
Committed: Thu Aug 1 11:27:56 2013 -0700

----------------------------------------------------------------------
 doc/conf.py                      |  1 +
 doc/reference/api/TSRemap.en.rst | 85 +++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/fa4be92b/doc/conf.py
----------------------------------------------------------------------
diff --git a/doc/conf.py b/doc/conf.py
index 9d8edfd..e2067b0 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -222,6 +222,7 @@ man_pages = [
    ('reference/api/TSMBufferCreate.en', 'TSMBufferCreate', u'Traffic Server marshall buffer API', None, u'3ts'),
    ('reference/api/TSmalloc.en', 'TSmalloc', u'Traffic Server memory allocation API', None, u'3ts'),
    ('reference/api/TSPluginInit.en', 'TSPluginInit', u'Traffic Server plugin loading and registration', None, u'3ts'),
+   ('reference/api/TSRemap.en', 'TSRemap', u'Traffic Server remap plugin entry points ', None, u'3ts'),
 
    ('reference/commands/traffic_cop.en', 'traffic_cop', u'Traffic Server watchdog', None, '8'),
    ('reference/commands/traffic_line.en', 'traffic_line', u'Traffic Server command line', None, '8'),

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/fa4be92b/doc/reference/api/TSRemap.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/api/TSRemap.en.rst b/doc/reference/api/TSRemap.en.rst
new file mode 100644
index 0000000..53668e7
--- /dev/null
+++ b/doc/reference/api/TSRemap.en.rst
@@ -0,0 +1,85 @@
+.. 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
+
+===========
+TSRemapInit
+===========
+
+Synopsis
+========
+
+`#include <ts/ts.h>`
+`#include <ts/remap.h>`
+
+.. function:: TSReturnCode TSRemapInit(TSRemapInterface * api_info, char* errbuf, int errbuf_size)
+.. function:: void TSRemapDone(void)
+.. function:: TSRemapStatus TSRemapDoRemap(void * ih, TSHttpTxn rh, TSRemapRequestInfo * rri)
+.. function:: TSReturnCode TSRemapNewInstance(int argc, char * argv[], void ** ih, char * errbuf, int errbuf_size)
+.. function:: void TSRemapDeleteInstance(void * )
+.. function:: void TSRemapOSResponse(void * ih, TSHttpTxn rh, int os_response_type)
+
+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.
+
+:func:`TSRemapInit` is a required entry point. This function will be called
+once when Traffic Server loads the plugin. If the optional :func:`TSRemapDone`
+entry point is available, Traffic Server will call then when unloading
+the remap plugin.
+
+A remap plugin may be invoked for different remap rules. Traffic Server
+will call the 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 :func:`TSRemapDeleteInstance`.
+
+:func:`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.
+
+Return values
+=============
+
+:func:`TSRemapInit` and :func:`TSRemapNewInstance` should return
+:data:`TS_SUCCESS` on success, and :data:`TS_ERROR` otherwise. A
+return value of :data:`TS_ERROR` is unrecoverable.
+
+:func:`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
+:data:`TSREMAP_DID_REMAP` or :data:`TSREMAP_DID_REMAP_STOP`; otherwise
+it should return :data:`TSREMAP_NO_REMAP` or :data:`TSREMAP_NO_REMAP_STOP`.
+If Traffic Server should not send the transaction to subsequent
+plugins in the remap chain, return :data:`TSREMAP_NO_REMAP_STOP`
+or :data:`TSREMAP_DID_REMAP_STOP`.  Returning :data:`TSREMAP_ERROR`
+causes Traffic Server to stop evaluating the remap chain and respond
+with an error.
+
+See also
+========
+
+:manpage:`TSAPI(3ts)`