From 2f54bf7f33d60e83a16774d077c0b4df067d43fd Mon Sep 17 00:00:00 2001 From: Daniel Gruno Date: Sun, 22 Apr 2012 16:32:52 +0000 Subject: [PATCH] Try to fix up some of the XML errors git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1328895 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/developer/modguide.xml | 38 +++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/manual/developer/modguide.xml b/docs/manual/developer/modguide.xml index ea0ef578feb..3a878e39543 100644 --- a/docs/manual/developer/modguide.xml +++ b/docs/manual/developer/modguide.xml @@ -74,15 +74,16 @@ To compile the source code we are building in this document, we will be using APXS. Assuming your source file is called mod_example.c, compiling, installing and activating the module is as simple as: +

 apxs -i -a -c mod_example.c
-

+
Defining a module -
+Module name tags

Every module starts with the same declaration, or name tag if you will, that defines a module as a separate entity within Apache: @@ -106,13 +107,17 @@ module AP_MODULE_DECLARE_DATA example_module =example_module. The name of the module is used primarily for two things:
+

+

For now, we're only concerned with the first purpose of the module name, -which comes into play when we need to load the module:
+which comes into play when we need to load the module: +

LoadModule example_module modules/mod_example.so
 +

In essence, this tells the server to open up mod_example.so and look for a module called example_module.

@@ -142,7 +147,7 @@ request, and will ask each module whether they have an interest in a given request or not. It is then up to each module to either gently decline serving a request, accept serving it or flat out deny the request from being served, as authentication/authorization modules do:
-
+Hook handling in httpd
To make it a bit easier for handlers such as our mod_example to know whether the client is requesting content we should handle or not, the server has directives for hinting to modules whether their assistance is needed or @@ -152,9 +157,11 @@ an example using AddHandler. In our example case, we want every request ending with .sum to be served by mod_example, so we'll add a configuration directive that tells the server to do just that: +

 AddHandler example-handler .sum
+

What this tells the server is the following: Whenever we receive a request for a URI ending in .sum, we are to let all modules know that we are looking for whoever goes by the name of "example-handler" . @@ -693,17 +700,22 @@ advanced configurations for your modules.

An introduction to configuration -directives If you are reading this, then you probably already know +directives +

+If you are reading this, then you probably already know what a configuration directive is. Simply put, a directive is a way of telling an individual module (or a set of modules) how to behave, such as these directives control how mod_rewrite works: +

 RewriteEngine On
 RewriteCond %{REQUEST_URI} ^/foo/bar
 RewriteRule ^/foo/bar/(.*)$ /foobar?page=$1
+

Each of these configuration directives are handled by a separate function, that parses the parameters given and sets up a configuration accordingly. +

Making an example configuration To begin with, we'll create a basic configuration in C-space: @@ -825,7 +837,7 @@ static const command_rec example_directives[] = -
+Directives structure

As you can see, each directive needs at least 5 parameters set:

    @@ -1020,11 +1032,13 @@ module AP_MODULE_DECLARE_DATA example_module = In our httpd.conf file, we can now change the hard-coded configuration by adding a few lines: +

     ExampleEnabled On
 ExamplePath "/usr/bin/foo"
 ExampleAction file allow
    +

    And thus we apply the configuration, visit /example on our web site, and we see the configuration has adapted to what we wrote in our configuration file. @@ -1041,6 +1055,7 @@ In Apache HTTP Server 2.4, different URLs, virtual hosts, directories etc can ha different meanings to the user of the server, and thus different contexts within which modules must operate. For example, let's assume you have this configuration set up for mod_rewrite: +

     <Directory "/var/www">
     RewriteCond %{HTTP_HOST} ^example.com$
@@ -1050,6 +1065,7 @@ configuration set up for mod_rewrite:
     RewriteRule ^foobar$ index.php?foobar=true
 </Directory>
    +

    In this example, you will have set up two different contexts for mod_rewrite:

      @@ -1179,7 +1195,7 @@ module AP_MODULE_DECLARE_DATA example_module = -
      Creating new context configurations +
      Creating new context configurations

      Now that we have told the server to help us create and manage configurations, our first step is to make a function for creating new, blank @@ -1206,11 +1222,12 @@ our name tag as the Per-directory configuration handler:

      -
      Merging configurations +
      Merging configurations

      Our next step in creating a context aware configuration is merging configurations. This part of the process particularly apply to scenarios where you have a parent configuration and a child, such as the following: +

       <Directory "/var/www">
     ExampleEnable On
@@ -1221,6 +1238,7 @@ where you have a parent configuration and a child, such as the following:
     ExampleAction file deny
 </Directory>
      +

      In this example, it is natural to assume that the directory /var/www/subdir should inherit the value set for the /var/www directory, as we did not specify a ExampleEnable nor @@ -1257,11 +1275,12 @@ two configurations and decide how they are to be merged:

      -
      Trying out our new context aware configurations +
      Trying out our new context aware configurations

      Now, let's try putting it all together to create a new module that is context aware. First off, we'll create a configuration that lets us test how the module works: +

       <Location "/a">
     SetHandler example-handler
@@ -1281,6 +1300,7 @@ how the module works:
     ExampleEnabled on
 </Location>
      +

      Then we'll assemble our module code. Note, that since we are now using our name tag as reference when fetching configurations in our handler, I have added some prototypes to keep the compiler happy: -- 2.47.2