Commit 905dbd8f authored by Eric Covener's avatar Eric Covener
Browse files

Merge r1721973 from trunk: 

PR58761: developer doc improvements.

Submitted By: Luca Toscano
 



git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1721974 13f79535-47bb-0310-9956-ffa450edef68
parent 1011739d

docs/manual/developer/filters.html.en

+8 −6
Original line number Diff line number Diff line
@@ -105,12 +105,14 @@ 
    <p>This is actually rather simple in theory, but the code is

    complex.  First of all, it is important that everybody realize that

    there are three filter lists for each request, but they are all

    concatenated together.  So, the first list is

    <code>r-&gt;output_filters</code>, then <code>r-&gt;proto_output_filters</code>,

    and finally <code>r-&gt;connection-&gt;output_filters</code>. These correspond

    to the <code>RESOURCE</code>, <code>PROTOCOL</code>, and

    <code>CONNECTION</code> filters respectively. The problem previously, was

    that we used a singly linked list to create the filter stack, and we

    concatenated together:</p>

    <ul>

        <li><code>r-&gt;output_filters</code> (corresponds to RESOURCE)</li>

        <li><code>r-&gt;proto_output_filters</code> (corresponds to PROTOCOL)</li>

        <li><code>r-&gt;connection-&gt;output_filters</code> (corresponds to CONNECTION)</li>

    </ul> 

    

    <p>The problem previously, was that we used a singly linked list to create the filter stack, and we

    started from the "correct" location.  This means that if I had a

    <code>RESOURCE</code> filter on the stack, and I added a

    <code>CONNECTION</code> filter, the <code>CONNECTION</code> filter would

docs/manual/developer/filters.xml

+8 −6
Original line number Diff line number Diff line
@@ -99,12 +99,14 @@ 
    <p>This is actually rather simple in theory, but the code is

    complex.  First of all, it is important that everybody realize that

    there are three filter lists for each request, but they are all

    concatenated together.  So, the first list is

    <code>r->output_filters</code>, then <code>r->proto_output_filters</code>,

    and finally <code>r->connection->output_filters</code>. These correspond

    to the <code>RESOURCE</code>, <code>PROTOCOL</code>, and

    <code>CONNECTION</code> filters respectively. The problem previously, was

    that we used a singly linked list to create the filter stack, and we

    concatenated together:</p>

    <ul>

        <li><code>r->output_filters</code> (corresponds to RESOURCE)</li>

        <li><code>r->proto_output_filters</code> (corresponds to PROTOCOL)</li>

        <li><code>r->connection->output_filters</code> (corresponds to CONNECTION)</li>

    </ul> 

    

    <p>The problem previously, was that we used a singly linked list to create the filter stack, and we

    started from the "correct" location.  This means that if I had a

    <code>RESOURCE</code> filter on the stack, and I added a

    <code>CONNECTION</code> filter, the <code>CONNECTION</code> filter would

docs/manual/developer/hooks.html.en

+21 −2
Original line number Diff line number Diff line
@@ -36,11 +36,29 @@ 
    Modules can provide functions that are called, and specify when 

    they get called in comparison to other modules.</p>

</div>

<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#create">Creating a hook function</a></li>

<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#corehooks">Core Hooks</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#create">Creating a hook function</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#hooking">Hooking the hook</a></li>

</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>

<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>

<div class="section">

<h2><a name="corehooks" id="corehooks">Core Hooks</a></h2>

    <p>The httpd's core modules offer a predefinined list of hooks

    used during the standard <a href="./request.html">request processing</a>

    phase. Creating a new hook will expose a function that 

    implements it (see sections below) but it is essential to undestand that you will not 

    extend the httpd's core hooks. Their presence and order in the request processing is in fact 

    a consequence of how they are called in <code>server/request.c</code> 

    (check <a href="./modguide.html#hooking">this section</a> 

    for an overview). The core hooks are listed in the 

    <a href="https://ci.apache.org/projects/httpd/trunk/doxygen/group__hooks.html">doxygen documentation</a>.</p>



    <p>Reading <a href="./modguide.html">guide for developing modules</a> and 

    <a href="./request.html">request processing</a> before proceeding is 

    highly recomended.

    </p> 

</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>

<div class="section">

<h2><a name="create" id="create">Creating a hook function</a></h2>

    <p>In order to create a new hook, four things need to be

    done:</p>
@@ -172,7 +190,8 @@ mode MODULE_VAR_EXPORT my_module = 


    <h3><a name="hooking-order" id="hooking-order">Controlling hook calling order</a></h3>

      <p>In the example above, we didn't use the three arguments in

      the hook registration function that control calling order.

      the hook registration function that control calling order of 

      all the functions registered within the hook.

      There are two mechanisms for doing this. The first, rather

      crude, method, allows us to specify roughly where the hook is

      run relative to other modules. The final argument control this.

docs/manual/developer/hooks.xml

+19 −1
Original line number Diff line number Diff line
@@ -37,6 +37,23 @@ 
    they get called in comparison to other modules.</p>

</summary>



<section id="corehooks"><title>Core Hooks</title>

    <p>The httpd's core modules offer a predefinined list of hooks

    used during the standard <a href="./request.html">request processing</a>

    phase. Creating a new hook will expose a function that 

    implements it (see sections below) but it is essential to undestand that you will not 

    extend the httpd's core hooks. Their presence and order in the request processing is in fact 

    a consequence of how they are called in <code>server/request.c</code> 

    (check <a href="./modguide.html#hooking">this section</a> 

    for an overview). The core hooks are listed in the 

    <a href="https://ci.apache.org/projects/httpd/trunk/doxygen/group__hooks.html">doxygen documentation</a>.</p>



    <p>Reading <a href="./modguide.html">guide for developing modules</a> and 

    <a href="./request.html">request processing</a> before proceeding is 

    highly recomended.

    </p> 

</section>



<section id="create"><title>Creating a hook function</title>

    <p>In order to create a new hook, four things need to be

    done:</p>
@@ -177,7 +194,8 @@ mode MODULE_VAR_EXPORT my_module = 


    <section id="hooking-order"><title>Controlling hook calling order</title>

      <p>In the example above, we didn't use the three arguments in

      the hook registration function that control calling order.

      the hook registration function that control calling order of 

      all the functions registered within the hook.

      There are two mechanisms for doing this. The first, rather

      crude, method, allows us to specify roughly where the hook is

      run relative to other modules. The final argument control this.

docs/manual/developer/index.html.en

+5 −4
Original line number Diff line number Diff line
@@ -30,9 +30,8 @@ 
    <div class="warning"><h3>Warning</h3>

    <p>Many of the documents listed here are in need of update.

    They are in different stages of progress.

    Please be patient, and point out any discrepancies or

    errors on the developer/ pages directly to the

    <a href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a> mailing list.</p>

    Please be patient and follow <a href="https://httpd.apache.org/docs-project/">this link</a>

    to propose a fix or point out any error/discrepancy.</p>

    </div>

</div>

<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#developing">2.4 development documents</a></li>
@@ -62,7 +61,9 @@ 
<div class="section">

<h2><a name="external" id="external">External Resources</a></h2>

    <ul>

      <li><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/">Autogenerated Apache HTTP Server (trunk) code documentation</a></li>

      <li><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/">Autogenerated Apache HTTP Server (trunk) code documentation</a> (the link is built by

        this <a href="https://ci.apache.org/builders/httpd-doxygen-nightly">job</a>).

      </li>



      <li>Developer articles at <a href="http://www.apachetutor.org/">apachetutor</a> include:

      <ul>