You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by di...@apache.org on 2010/03/24 22:49:03 UTC

svn commit: r927195 - /incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html

Author: dianes
Date: Wed Mar 24 21:49:02 2010
New Revision: 927195

URL: http://svn.apache.org/viewvc?rev=927195&view=rev
Log:
closed ts-270

Modified:
    incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html

Modified: incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html?rev=927195&r1=927194&r2=927195&view=diff
==============================================================================
--- incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html (original)
+++ incubator/trafficserver/site/trunk/docs/v2/sdk/ch03s02.html Wed Mar 24 21:49:02 2010
@@ -21,7 +21,7 @@
   <li><a href=ch03s02.html#tsremap_delete_instance>tsremap_delete_instance </a> </li>
   <li><a href=ch03s02.html#tsremap_os_response>tsremap_os_response </a> </li>
   </ul>
-  </p>
+  <p></p>
 </div></div></div>
 <h4 class="title"><a name="tsremap_init"></a>tsremap_init</h4>
 <p>The remap plugin initialization function.</p>
@@ -29,13 +29,13 @@
   <dl>
     <dt><span class="term"><b>Prototype</b></span></dt>
     <dd>
-      <p><code class="code">int tsremap_init(TSRemapInterface * <span class="replaceable">api_info</span>, char *<span class="replaceable">errbuf</span>, int <span class="replaceable">errbuf_size</span>);</code></p>
+      <p><code class="code">int tsremap_init(TSRemapInterface *<span class="replaceable">api_info</span>, char *<span class="replaceable">errbuf</span>, int <span class="replaceable">errbuf_size</span>);</code></p>
     </dd>
     <dt><span class="term"><b>Arguments</b></span></dt>
     <dd>
-      <p><code class="code"><em class="replaceable">api_info </em></code> is a <code class="code">TSRemapInterface</code> struct containing remap API interface version information</p>
-      <p><code class="code"><em class="replaceable">errbuf </em></code> is a buffer in which the plugin may write informational error messages about initialization errors.</p>
-      <p><code class="code"><em class="replaceable">errbuf_size </em></code> is the size, in bytes, of the buffer pointed to by <code class="code">errbuf</code></p>
+      <p><code class="code"><em class="replaceable">api_info </em></code> is a <code class="code">TSRemapInterface</code> struct containing remap API interface version information.</p>
+      <p><code class="code"><em class="replaceable">errbuf </em></code> is a buffer to which the plugin may write  error messages about initialization errors.</p>
+      <p><code class="code"><em class="replaceable">errbuf_size </em></code> is the size, in bytes, of the buffer pointed to by <code class="code">errbuf</code>.</p>
     </dd>
     <dt><span class="term"><b>Description</b></span></dt>
     <dd>
@@ -43,29 +43,26 @@
     </dd>
     <dt><span class="term"><b>Returns</b></span></dt>
     <dd>
-      <p>The function must return <code class="code">0</code> upon successful plugin initialization.</p>
-    </dd>
-  </dl>
-</div>
+      <p>The function must return <code class="code">0</code> upon successful plugin initialization.</p></dd></dl></div>
 <h4 class="title"><a name="tsremap_new_instance"></a>tsremap_new_instance</h4>
 <p>The remap instance initialization function.</p>
 <div class="variablelist">
   <dl>
     <dt><span class="term"><b>Prototype</b></span></dt>
     <dd>
-      <p><code class="code">int tsremap_new_instance(int argc, char *argv[], ihandle * <span class="replaceable">ih</span>, char *<span class="replaceable">errbuf</span>, int <span class="replaceable">errbuf_size</span>);</code></p>
+      <p><code class="code">int tsremap_new_instance(int <em class="replaceable">argc</em>, char *<em class="replaceable">argv</em>[], ihandle *<em class="replaceable">ih</em>, char *<em class="replaceable">errbuf</em>, int <span class="replaceable"> </span><em class="replaceable">errbuf_size</em>);</code></p>
     </dd>
     <dt><span class="term"><b>Arguments</b></span></dt>
     <dd>
-      <p><code class="code"><em class="replaceable">argc </em></code> is a count of the number of arguments in the argument vector, argv.</p>
-      <p><code class="code"><em class="replaceable">argv </em></code> is the vector of arguments. The number of arguments in the vector is <code class="code">argc</code>. <code class="code">argv[0]</code> and <code class="code">argv[1] </code> contain the <code class="code">fromURL</code> and <code class="code">toURL</code>, respectively, from the remap rule in canonical form. Additional plugin parameters may be passed to the plugin using <code class="code">@pparam=plugin_name</code> in the configuration file.</p>
+      <p><code class="code"><em class="replaceable">argc </em></code> is a count of the number of arguments in the argument vector,<code class="code"><em class="replaceable"> argv</em></code>.</p>
+      <p><code class="code"><em class="replaceable">argv </em></code> is the vector of arguments. The number of arguments in the vector is <code class="code">argc</code>. <code class="code"> argv[0]</code> and <code class="code">argv[1] </code> contain the <code class="code">fromURL</code> and <code class="code">toURL</code>, respectively, from the remap rule in canonical form. Additional plugin parameters can be passed to the plugin by using <code class="code">@pparam=plugin_name</code> in the configuration file.</p>
       <p>The <code class="code"><em class="replaceable">ih, </em></code> or <code class="code">ihandle</code>, is a opaque pointer that can be used by the plugin to store per-instance data.  Traffic Server  passes this handle to <code class="code">tsremap_remap</code>, <code class="code">tsremap_os_response</code>, and <code class="code">tsremap_delete_instance</code> for operations on this instance.  If memory is allocated for the ihandle, then it can be freed via <code class="code">tsremap_delete_instance</code>.</p>
-      <p><code class="code"><em class="replaceable">errbuf </em></code> is a  buffer in which the plugin may write informational error messages about instance initialization errors.</p>
-      <p><code class="code"><em class="replaceable">errbuf_size </em></code> is the size, in bytes, of the buffer pointed to by <code class="replaceable">errbuf</code>.</p>
+      <p><code class="code"><em class="replaceable">errbuf </em></code> is a  buffer to which the plugin may write informational error messages about instance initialization errors.</p>
+      <p><code class="code"><em class="replaceable">errbuf_size </em></code> is the size, in bytes, of the buffer pointed to by <code class="code"><em class="replaceable"> errbuf</em></code>.</p>
     </dd>
     <dt><span class="term"><b>Description</b></span></dt>
     <dd>
-      <p>Traffic Server calls this initialization routine once per remap instance for which the plugin is configured (i.e. once per rule in remap.config that has <code class="code">@pplugin=</code>).  All remap plugins are required to implement this function.</p>
+      <p>Traffic Server calls this initialization routine once per remap instance for which the plugin is configured (i.e. once per rule in <code>remap.config</code> that has <code class="code">@pplugin=</code>).  All remap plugins are required to implement this function.</p>
     </dd>
     <dt><span class="term"><b>Returns</b></span></dt>
     <dd>
@@ -79,13 +76,13 @@
   <dl>
     <dt><span class="term"><b>Prototype</b></span></dt>
     <dd>
-      <p><code class="code">int tsremap_remap(ihandle <span class="replaceable">ih</span>, rhandle <span class="replaceable">rh</span>, TSRemapRequestInfo * <span class="replaceable">rri</span>)</code></p>
+      <p><code class="code">int tsremap_remap(ihandle<em class="replaceable"> ih</em>, rhandle <span class="replaceable"> </span><em class="replaceable">rh</em>, TSRemapRequestInfo *<em class="replaceable">rri</em>)</code></p>
     </dd>
     <dt><span class="term"><b>Arguments</b></span></dt>
     <dd>
-      <p><code class="code"><em class="replaceable">ih </em></code> is the ihandle for the instance set during tsremap_new_instance</p>
-      <p><code class="code"><em class="replaceable">rh</em></code> is the INKHttpTxn for the request.  This allows remap plugins to use APIs from ts.h</p>
-      <p><code class="code"><em class="replaceable">rri</em></code> The TSRemapRequestInfo struct contains input and output parameters for the remap operation for a single request. The struct members are as follows:</p>
+      <p><code class="code"><em class="replaceable">ih </em></code> is the ihandle for the instance set during <code>tsremap_new_instance</code>.</p>
+      <p><code class="code"><em class="replaceable">rh </em></code> is the <code>INKHttpTxn</code> for the request.  This allows remap plugins to use APIs from<code> ts.h</code>.</p>
+      <p><code class="code"><em class="replaceable">rri </em></code> is the <code>TSRemapRequestInfo</code> struct contains input and output parameters for the remap operation for a single request. The struct members are as follows:</p>
       <h5 class="title">Input (read-only) members</h5>
       <pre class="programlisting">    unsigned long size;          /* sizeof(TSRemapRequestInfo) */      int request_port;            /* request port number */     int remap_from_port;         /* fromURL port number (from remap rule string) */     int remap_to_port;           /* toURL port number (from remap rule string) */      const char *orig_url;        /* request URL (not NULL terminated) */     int orig_url_size;           /* request URL size */      const char *request_host;    /* request host string (not NULL terminated) */     int request_host_size;       /* request host string size */      const char *remap_from_host; /* fromURL host (from remap rule string) */     int remap_from_host_size;    /* fromURL host size */      const char *remap_to_host;   /* toURL host (from remap rule string) */     int remap_to_host_size;      /* toURL host size */      const char *request_path;    /* request path (not NULL terminated) */     int request_path_size;       /* request pa
 th size */      const char *remap_from_path; /* fromURL path (from remap rule string) */     int remap_from_path_size;    /* fromURL path size */      const char *remap_to_path;   /* toURL path (from remap rule string) */     int remap_to_path_size;      /* toURL path size */      const char *request_cookie;  /* request cookie string (not NULL terminated) */     int request_cookie_size;     /* request cookie string size */      const char *request_query;   /* request query string (not NULL terminated) */     int request_query_size;      /* request query string size. */      const char *request_matrix;  /* request matrix string (not NULL terminated) */     int request_matrix_size;     /* request matrix string size. */      const char *from_scheme;    /* The "from" scheme (e.g. http) */     int from_scheme_len;        /* The len of the "from" scheme */      const char *to_scheme;      /* The "to" scheme (e.g. http) */     int to_scheme_len;          /* The len of the "to" sche
 me */      unsigned int client_ip;     /* The client IP is an unsigned network order (big-endian) 32-bit number. */ </pre>
       <h5 class="title">Output members</h5>
@@ -93,11 +90,11 @@
     </dd>
     <dt><span class="term"><b>Returns</b></span></dt>
     <dd>
-      <p>A non-zero return value indicates that the plugin modified the output members of the <code class="code">rri</code> argument. TS will use those values to modify the client request.  Otherwise, the plugin can return <code class="code">0</code> to indicate that TS should use the default <code class="code">toURL</code> from the remap rule.</p>
+      <p>A non-zero return value indicates  that the plugin modified the output members of the <code class="replaceable"> rri </code> argument. Traffic Server  uses those values to modify the client request.  Otherwise, the plugin can return <code class="code">0</code> to indicate that Traffic Server should use the default <code class="code">toURL</code> from the remap rule.</p>
     </dd>
     <dt><span class="term"><b>Description</b></span></dt>
     <dd>
-      <p>This is the main remap function in which the plugin can modify the client request based on the rri input members. The function is called for client requests for which the remap rule associated with the plugin matches (based on <code class="code">fromURL</code>). Note that if multiple rules match the client request, Traffic Server uses the first match. In relation to Traffic Server's HTTP transaction APIs, <code class="code">tsremap_remap</code> is invoked before <code class="code">INK_HTTP_READ_REQUEST_HDR_HOOK</code> and before cache lookup.  Thus, if the plugin modifies the request, then the cache lookup key will be altered.</p>
+      <p>This is the main remap function in which the plugin can modify the client request based on the <code class="replaceable">rri </code> input members. The function is called for client requests matching the remap rule associated with the plugin  (based on <code class="code">fromURL</code>).  If multiple rules match the client request, then Traffic Server uses the first match. In relation to Traffic Server's HTTP transaction APIs, <code class="code">tsremap_remap</code> is invoked before <code class="code">INK_HTTP_READ_REQUEST_HDR_HOOK</code> and before a cache lookup.  Thus, the cache lookup key is altered if the plugin modifies the request.</p>
     </dd>
   </dl>
 </div>
@@ -114,7 +111,7 @@
     </dd>
     <dt><span class="term"><b>Description</b></span></dt>
     <dd>
-      <p>The plugin can optionally define this function, which will be called when a remap instance is released. For example when <code>remap.config</code> is reloaded, all existing instances are released and new instances are created.</p>
+      <p>The plugin can optionally define this function, which is called when a remap instance is released. For example: when <code>remap.config</code> is reloaded, all existing instances are released and new instances are created.</p>
     </dd>
   </dl>
 </div>
@@ -129,11 +126,11 @@
     <dd>
       <p><code class="code"><em class="replaceable">ih </em></code> is the ihandle for the instance set during <code>tsremap_new_instance</code>.</p>
       <p><code class="code"><em class="replaceable">rh </em></code> is the <code>INKHttpTxn</code> for the request.  It enables  remap plugins to use APIs from <code>ts.h</code></p>
-      <p><code class="code"><em class="replaceable">os_response_type </em></code> is a value of <code>INKServerState</code> that indicates the state of the response.</p>
+      <p><code class="code"><em class="replaceable">os_response_type </em></code> is the value of <code>INKServerState</code> that indicates the state of the response.</p>
     </dd>
     <dt><span class="term"><b>Description</b></span></dt>
     <dd>
-      <p>This optional function is called after Traffic Server receives a response from the origin server. If the request is served from cache, then the function is not called .</p>
+      <p>This optional function is called after Traffic Server receives a response from the origin server. If the request is served from cache, then the function is not called.</p>
     </dd>
   </dl>
 </div>