1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="modguide.xml.meta">
24 <parentdocument href="./">Developer</parentdocument>
26 <title>Developing modules for the Apache HTTP Server 2.4</title>
29 <p>This document explains how you can develop modules for the Apache HTTP
33 <seealso><a href="request.html">Request Processing in Apache 2.4</a></seealso>
34 <seealso><a href="hooks.html">Apache 2.x Hook Functions</a></seealso>
36 <section id="introduction"><title>Introduction</title>
37 <section id="what"><title>What we will be discussing in this document</title>
39 This document will discuss how you can easily create modules for the Apache
40 HTTP Server 2.4, by exploring an example module called
41 <code>mod_example</code>. In the first part of this document, the purpose
42 of this module will be to calculate and print out various digest values for
43 existing files on your web server, whenever we access the URL <code>
44 http://hostname/filename.sum</code>. For instance, if we want to know the
45 MD5 digest value of the file located at <code>
46 http://www.example.com/index.html</code>, we would visit <code>
47 http://www.example.com/index.html.sum</code>.
51 In the second part of this document, which deals with configuration
52 directive and context awareness, we will be looking at a module that simply
53 write out its own configuration to the client.
57 <section id="prerequisites"><title>Prerequisites</title>
59 First and foremost, you are expected to have a basic knowledge of how the C
60 programming language works. In most cases, we will try to be as pedagogical
61 as possible and link to documents describing the functions used in the
62 examples, but there are also many cases where it is necessary to either
63 just assume that "it works" or do some digging yourself into what the hows
64 and whys of various function calls.
67 Lastly, you will need to have a basic understanding of how modules are
68 loaded and configured in the Apache HTTP Server, as well as how to get the headers for
69 Apache if you do not have them already, as these are needed for compiling
73 <section id="compiling"><title>Compiling your module</title>
75 To compile the source code we are building in this document, we will be
76 using <a href="../programs/apxs.html">APXS</a>. Assuming your source file
77 is called mod_example.c, compiling, installing and activating the module is
81 apxs -i -a -c mod_example.c
87 <section id="basics"><title>Defining a module</title>
89 <img src="../images/build_a_mod_3.png" alt="Module name tags"/><br/>
90 Every module starts with the same declaration, or name tag if you will,
91 that defines a module as <em>a separate entity within Apache</em>:</p>
94 <!-- BEGIN EXAMPLE CODE -->
96 module AP_MODULE_DECLARE_DATA example_module <code class="sh_misc">=</code>
97 <code class="sh_misc">{</code>
98 STANDARD20_MODULE_STUFF<code class="sh_misc">,</code>
99 create_dir_conf<code class="sh_misc">,</code> <code class="sh_comment">/* Per-directory configuration handler */</code>
100 merge_dir_conf<code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-directory configurations */</code>
101 create_svr_conf<code class="sh_misc">,</code> <code class="sh_comment">/* Per-server configuration handler */</code>
102 merge_svr_conf<code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-server configurations */</code>
103 directives<code class="sh_misc">,</code> <code class="sh_comment">/* Any directives we may have for httpd */</code>
104 register_hooks <code class="sh_comment">/* Our hook registering function */</code>
105 <code class="sh_misc">}</code><code class="sh_misc">;</code>
107 <!-- END EXAMPLE CODE -->
110 This bit of code lets the server know that we have now registered a new module
111 in the system, and that its name is <code>example_module</code>. The name
112 of the module is used primarily for two things:<br/>
115 <li>Letting the server know how to load the module using the LoadModule</li>
116 <li>Setting up a namespace for the module to use in configurations</li>
119 For now, we're only concerned with the first purpose of the module name,
120 which comes into play when we need to load the module:
122 <example><pre><a href="../mod/mod_so.html#LoadModule">LoadModule</a> example_module modules/mod_example.so</pre></example>
124 In essence, this tells the server to open up <code>mod_example.so</code> and look for a module
125 called <code>example_module</code>.
128 Within this name tag of ours is also a bunch of references to how we would
129 like to handle things: Which directives do we respond to in a configuration
130 file or .htaccess, how do we operate within specific contexts, and what
131 handlers are we interested in registering with the Apache HTTP service. We'll
132 return to all these elements later in this document.
135 <section id="hooking"><title>Getting started: Hooking into the server</title>
136 <section id="hook_intro"><title>An introduction to hooks</title>
138 When handling requests in Apache HTTP Server 2.4, the first thing you will need to do is
139 create a hook into the request handling process. A hook is essentially a
140 message telling the server that you are willing to either serve or at least
141 take a glance at certain requests given by clients. All handlers, whether
142 it's mod_rewrite, mod_authn_*, mod_proxy and so on, are hooked into
143 specific parts of the request process. As you are probably aware, modules
144 serve different purposes; Some are authentication/authorization handlers,
145 others are file or script handlers while some third modules rewrite URIs or
146 proxies content. Furthermore, in the end, it is up to the user of the server
147 how and when each module will come into place. Thus, the server itself does not
148 presume to know which module is responsible for handling a specific
149 request, and will ask each module whether they have an interest in a given
150 request or not. It is then up to each module to either gently decline
151 serving a request, accept serving it or flat out deny the request from
152 being served, as authentication/authorization modules do: <br/>
153 <img src="../images/build_a_mod_2.png" alt="Hook handling in httpd"/><br/>
154 To make it a bit easier for handlers such as our mod_example to know
155 whether the client is requesting content we should handle or not, the server
156 has directives for hinting to modules whether their assistance is needed or
157 not. Two of these are <directive module="mod_mime">AddHandler</directive>
158 and <directive module="core">SetHandler</directive>. Let's take a look at
159 an example using <directive module="mod_mime">AddHandler</directive>. In
160 our example case, we want every request ending with .sum to be served by
161 <code>mod_example</code>, so we'll add a configuration directive that tells
162 the server to do just that:
165 AddHandler example-handler .sum
168 What this tells the server is the following: <em>Whenever we receive a request
169 for a URI ending in .sum, we are to let all modules know that we are
170 looking for whoever goes by the name of "example-handler" </em>.
171 Thus, when a request is being served that ends in .sum, the server will let all
172 modules know, that this request should be served by "example-handler
173 ". As you will see later, when we start building mod_example, we will
174 check for this handler tag relayed by <code>AddHandler</code> and reply to
175 the server based on the value of this tag.
178 <section id="hook_declaration"><title>Hooking into httpd</title>
180 To begin with, we only want to create a simple handler, that replies to the
181 client browser when a specific URL is requested, so we won't bother setting
182 up configuration handlers and directives just yet. Our initial module
183 definition will look like this:</p>
186 <!-- BEGIN EXAMPLE CODE -->
188 module AP_MODULE_DECLARE_DATA example_module =
190 STANDARD20_MODULE_STUFF,
191 <code class="sh_constant">NULL</code>,
192 <code class="sh_constant">NULL</code>,
193 <code class="sh_constant">NULL</code>,
194 <code class="sh_constant">NULL</code>,
195 <code class="sh_constant">NULL</code>,
196 <code class="sh_function">register_hooks</code> <code class="sh_comment"><code class="sh_comment">/* Our hook registering function */</code></code>
199 <!-- END EXAMPLE CODE -->
202 <p>This lets the server know that we are not interesting in anything fancy, we
203 just want to hook onto the requests and possibly handle some of them. </p>
205 <p> The reference in our example declaration, <code>register_hooks</code>
206 is the name of a function we will create to manage how we hook onto the
207 request process. In this example module, the function has just one purpose;
208 To create a simple hook that gets called after all the rewrites, access
209 control etc has been handled. Thus, we will let the server know, that we want
210 to hook into its process as one of the last modules:
213 <!-- BEGIN EXAMPLE CODE -->
215 <code class="sh_declare">static</code> <code class="sh_declare">void</code> register_hooks<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">)</code>
216 <code class="sh_misc">{</code>
217 <code class="sh_comment">/* Create a hook in the request handler, so we get called when a request arrives */</code>
218 <code class="sh_function">ap_hook_handler</code><code class="sh_misc">(</code>example_handler<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> APR_HOOK_LAST<code class="sh_misc">)</code><code class="sh_misc">;</code>
219 <code class="sh_misc">}</code>
221 <!-- END EXAMPLE CODE -->
224 The <code>example_handler</code> reference is the function that will handle
225 the request. We will discuss how to create a handler in the next chapter.
228 <section id="hook_others"><title>Other useful hooks</title>
230 Hooking into the request handling phase is but one of many hooks that you
231 can create. Some other ways of hooking are:
234 <li><code>ap_hook_child_init</code>: Place a hook that executes when a child process is spawned (commonly used for initializing modules after the server has forked)</li>
235 <li><code>ap_hook_pre_config</code>: Place a hook that executes before any configuration data has been read (very early hook)</li>
236 <li><code>ap_hook_post_config</code>: Place a hook that executes after configuration has been parsed, but before the server has forked</li>
237 <li><code>ap_hook_translate_name</code>: Place a hook that executes when a URI needs to be translated into a filename on the server (think <code>mod_rewrite</code>)</li>
243 <section id="handling"><title>Building a handler</title>
245 A handler is essentially a function that receives a callback when a request
246 to the server is made. It is passed a record of the current request (how it was
247 made, which headers and requests were passed along, who's giving the
248 request and so on), and is put in charge of either telling the server that it's
249 not interested in the request or handle the request with the tools provided.
251 <section id="simple_handler"><title>A simple "Hello, world!"
253 <p>Let's start off by making a very simple request handler
254 that does the following:
257 <li>Check that this is a request that should be served by "example-handler"</li>
258 <li>Set the content type of our output to <code>text/html</code></li>
259 <li>Write "Hello, world!" back to the client browser</li>
260 <li>Let the server know that we took care of this request and everything went fine</li>
263 In C code, our example handler will now look like this:
266 <!-- BEGIN EXAMPLE CODE -->
268 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
269 <code class="sh_misc">{</code>
270 <code class="sh_comment">/* First off, we need to check if this is a call for the "example-handler" handler.</code>
271 <code class="sh_comment">     * If it is, we accept it and do our things, if not, we simply return DECLINED,</code>
272 <code class="sh_comment">     * and the server will try somewhere else.</code>
273 <code class="sh_comment">     */</code>
274 <code class="sh_declare">if</code> <code class="sh_misc">(</code><code class="sh_misc">!</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code> <code class="sh_misc">|</code><code class="sh_misc">|</code> <code class="sh_function">strcmp</code><code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code><code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">example-handler</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_declare">return</code> <code class="sh_misc">(</code>DECLINED<code class="sh_misc">)</code><code class="sh_misc">;</code>
276 <code class="sh_comment">/* Now that we are handling this request, we'll write out "Hello, world!" to the client.</code>
277 <code class="sh_comment">     * To do so, we must first set the appropriate content type, followed by our output.</code>
278 <code class="sh_comment">     */</code>
279 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#gaa2f8412c400197338ec509f4a45e4579">ap_set_content_type</a><code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">text/html</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
280 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#ga5e91eb6ca777c9a427b2e82bf1eeb81d">ap_rprintf</a><code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Hello, world!</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
282 <code class="sh_comment">/* Lastly, we must tell the server that we took care of this request and everything went fine.</code>
283 <code class="sh_comment">     * We do so by simply returning the value OK to the server.</code>
284 <code class="sh_comment">     */</code>
285 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
286 <code class="sh_misc">}</code>
288 <!-- END EXAMPLE CODE -->
291 Now, we put all we have learned together and end up with a program that
293 <a href="http://people.apache.org/~humbedooh/mods/examples/mod_example_1.c">mod_example_1.c</a>
294 . The functions used in this example will be explained later in the section
295 <a href= "#functions">"Some useful functions you should know"</a>.
298 <section id="request_rec"><title>The request_rec structure</title>
299 <p>The most essential part of any request is the <em>request record
300 </em>. In a call to a handler function, this is represented by the <code>
301 request_req* </code> structure passed along with every call that is made.
302 This struct, typically just refered to as <code>r</code> in modules,
303 contains all the information you need for your module to fully process any
304 HTTP request and respond accordingly.</p> <p>Some key elements of the <code>
305 request_req </code> structure are:
308 <li><code><code class="sh_subobject">r->handler</code> (char*)</code>: Contains the name of the handler the server is currently asking to do the handling of this request</li>
309 <li><code><code class="sh_subobject">r->method</code> (char*)</code>: Contains the HTTP method being used, f.x. GET or POST</li>
310 <li><code><code class="sh_subobject">r->filename</code> (char*)</code>: Contains the translated filename the client is requesting</li>
311 <li><code><code class="sh_subobject">r->args</code> (char*)</code>: Contains the query string of the request, if any</li>
312 <li><code><code class="sh_subobject">r->headers_in</code> (apr_table_t*)</code>: Contains all the headers sent by the client</li>
313 <li><code><code class="sh_subobject">r->connection</code> (conn_rec*)</code>: A record containing information about the current connection</li>
314 <li><code><code class="sh_subobject">r->useragent_ip</code> (char*)</code>: The IP address of the client connecting to us</li>
315 <li><code><code class="sh_subobject">r->pool</code> (apr_pool_t*)</code>: The memory pool of this request. We'll discuss this in the "
316 <a href="#memory">Memory management</a>" chapter.</li>
319 A complete list of all the values contained with in the <code>request_req</code> structure can be found in
320 the <a href="http://svn.apache.org/repos/asf/httpd/httpd/trunk/include/httpd.h"><code>httpd.h</code></a> header
321 file or at <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/structrequest__rec.html">http://ci.apache.org/projects/httpd/trunk/doxygen/structrequest__rec.html</a>.
326 Let's try out some of these variables in another example handler:<br/>
329 <!-- BEGIN EXAMPLE CODE -->
331 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
332 <code class="sh_misc">{</code>
333 <code class="sh_comment">/* Set the appropriate content type */</code>
334 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#gaa2f8412c400197338ec509f4a45e4579">ap_set_content_type</a><code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">text/html</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
336 <code class="sh_comment">/* Print out the IP address of the client connecting to us: */</code>
337 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#ga5e91eb6ca777c9a427b2e82bf1eeb81d">ap_rprintf</a><code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value"><h2>Hello, </code><code class="sh_reference">%s</code><code class="sh_value">!</h2></code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">useragent_ip</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
339 <code class="sh_comment">/* If we were reached through a GET or a POST request, be happy, else sad. */</code>
340 <code class="sh_declare">if</code> <code class="sh_misc">(</code> <code class="sh_misc">!</code><code class="sh_function">strcmp</code><code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">method</code><code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">POST</code><code class="sh_character">"</code><code class="sh_misc">)</code> <code class="sh_misc">|</code><code class="sh_misc">|</code> <code class="sh_misc">!</code><code class="sh_function">strcmp</code><code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">method</code><code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">GET</code><code class="sh_character">"</code><code class="sh_misc">)</code> <code class="sh_misc">)</code> <code class="sh_misc">{</code>
341 ap_rputs<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">You used a GET or a POST method, that makes us happy!<br></code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">)</code><code class="sh_misc">;</code>
342 <code class="sh_misc">}</code>
343 <code class="sh_declare">else</code> <code class="sh_misc">{</code>
344 ap_rputs<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">You did not use POST or GET, that makes us sad :(<br></code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">)</code><code class="sh_misc">;</code>
345 <code class="sh_misc">}</code>
347 <code class="sh_comment">/* Lastly, if there was a query string, let's print that too! */</code>
348 <code class="sh_declare">if</code> <code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">args</code><code class="sh_misc">)</code> <code class="sh_misc">{</code>
349 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#ga5e91eb6ca777c9a427b2e82bf1eeb81d">ap_rprintf</a><code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Your query string was: </code><code class="sh_reference">%s</code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">args</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
350 <code class="sh_misc">}</code>
351 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
352 <code class="sh_misc">}</code>
354 <!-- END EXAMPLE CODE -->
358 <section id="return_value"><title>Return values</title>
360 Apache relies on return values from handlers to signify whether a request
361 was handled or not, and if so, whether the request went well or not. If a
362 module is not interested in handling a specific request, it should always
363 return the value <code>DECLINED</code>. If it is handling a request, it
364 should either return the generic value <code>OK</code>, or a specific HTTP
365 status code, for example:
368 <!-- BEGIN EXAMPLE CODE -->
370 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
371 <code class="sh_misc">{</code>
372 <code class="sh_comment">/* Return 404: Not found */</code>
373 <code class="sh_declare">return</code> HTTP_NOT_FOUND<code class="sh_misc">;</code>
374 <code class="sh_misc">}</code>
376 <!-- END EXAMPLE CODE -->
379 Returning <code>OK</code> or a HTTP status code does not necessarily mean
380 that the request will end. The server may still have other handlers that are
381 interested in this request, for instance the logging modules which, upon a
382 successful request, will write down a summary of what was requested and how
383 it went. To do a full stop and prevent any further processing after your
384 module is done, you can return the value <code>DONE</code> to let the server
385 know that it should cease all activity on this request and carry on with
386 the next, without informing other handlers.
388 <strong>General response codes:</strong>
391 <li><code>DECLINED</code>: We are not handling this request</li>
392 <li><code>OK</code>: We handled this request and it went well</li>
393 <li><code>DONE</code>: We handled this request and the server should just close this thread without further processing</li>
396 <strong>HTTP specific return codes (excerpt):</strong>
399 <li><code>HTTP_OK (200)</code>: Request was okay</li>
400 <li><code>HTTP_MOVED_PERMANENTLY (301)</code>: The resource has moved to a new URL</li>
401 <li><code>HTTP_UNAUTHORIZED (401)</code>: Client is not authorized to visit this page</li>
402 <li><code>HTTP_FORBIDDEN (403)</code>: Permission denied</li>
403 <li><code>HTTP_NOT_FOUND (404)</code>: File not found</li>
404 <li><code>HTTP_INTERNAL_SERVER_ERROR (500)</code>: Internal server error (self explanatory)</li>
408 <section id="functions"><title>Some useful functions you should know</title>
412 <code>ap_rputs(const char *string, request_req *r)</code>: <br/>
413 Sends a string of text to the client. This is a shorthand version of <a
414 href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#gac827cd0537d2b6213a7c06d7c26cc36e">
418 <!-- BEGIN EXAMPLE CODE -->
419 <p class="source">ap_rputs<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">Hello, world!</code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">)</code><code class="sh_misc">;</code></p>
420 <!-- END EXAMPLE CODE -->
426 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#ga5e91eb6ca777c9a427b2e82bf1eeb81d">ap_rprintf</a></code>: <br/>
427 This function works just like <code>printf</code>, except it sends the result to the client.
430 <!-- BEGIN EXAMPLE CODE -->
431 <p class="source"><code class="sh_declare"><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#ga5e91eb6ca777c9a427b2e82bf1eeb81d">ap_rprintf</a></code><code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Hello, </code><code class="sh_reference">%s</code><code class="sh_value">!</code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">useragent_ip</code><code class="sh_misc">)</code><code class="sh_misc">;</code></p>
432 <!-- END EXAMPLE CODE -->
437 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#gaa2f8412c400197338ec509f4a45e4579">ap_set_content_type</a>(request_req *r, const char *type)</code>: <br/>
438 Sets the content type of the output you are sending.
441 <!-- BEGIN EXAMPLE CODE -->
442 <p class="source"><code class="sh_declare"><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#gaa2f8412c400197338ec509f4a45e4579">ap_set_content_type</a></code><code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">text/plain</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code> <code class="sh_comment">/* force a raw text output */</code></p>
443 <!-- END EXAMPLE CODE -->
451 <section id="memory"><title>Memory management</title>
453 Managing your resources in Apache HTTP Server 2.4 is quite easy, thanks to the memory pool
454 system. In essence, each server, connection and request have their own
455 memory pool that gets cleaned up when its scope ends, e.g. when a request
456 is done or when a server process shuts down. All your module needs to do is
457 latch onto this memory pool, and you won't have to worry about having to
458 clean up after yourself - pretty neat, huh?
462 In our module, we will primarily be allocating memory for each request, so
463 it's appropriate to use the <code class="sh_subobject">r->pool</code>
464 reference when creating new objects. A few of the functions for allocating
465 memory within a pool are:
468 <li><code>void* <a href="http://apr.apache.org/docs/apr/1.4/group__apr__pools.html#ga85f1e193c31d109affda72f9a92c6915">apr_palloc</a>(
469 apr_pool_t *p, apr_size_t size)</code>: Allocates <code>size</code> number of bytes in the pool for you</li>
470 <li><code>void* <a href="http://apr.apache.org/docs/apr/1.4/group__apr__pools.html#gaf61c098ad258069d64cdf8c0a9369f9e">apr_pcalloc</a>(
471 apr_pool_t *p, apr_size_t size)</code>: Allocates <code>size</code> number of bytes in the pool for you and sets all bytes to 0</li>
472 <li><code>char* <a href="http://apr.apache.org/docs/apr/1.4/group__apr__strings.html#gabc79e99ff19abbd7cfd18308c5f85d47">apr_pstrdup</a>(
473 apr_pool_t *p, const char *s)</code>: Creates a duplicate of the string <code>s</code>. This is useful for copying constant values so you can edit them</li>
474 <li><code>char* <a href="http://apr.apache.org/docs/apr/1.4/group__apr__strings.html#ga3eca76b8d293c5c3f8021e45eda813d8">apr_psprintf</a>(
475 apr_pool_t *p, const char *fmt, ...)</code>: Similar to <code>sprintf</code>, except the server supplies you with an appropriately allocated target variable</li>
478 <p>Let's put these functions into an example handler:</p>
481 <!-- BEGIN EXAMPLE CODE -->
483 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
484 <code class="sh_misc">{</code>
485 <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc">*</code> original <code class="sh_misc">=</code> <code class="sh_character">"</code><code class="sh_value">You can't edit this!</code><code class="sh_character">"</code><code class="sh_misc">;</code>
486 <code class="sh_declare">char</code><code class="sh_misc">*</code> copy<code class="sh_misc">;</code>
487 <code class="sh_declare">int</code><code class="sh_misc">*</code> integers<code class="sh_misc">;</code>
489 <code class="sh_comment">/* Allocate space for 10 integer values and set them all to zero. */</code>
490 integers <code class="sh_misc">=</code> apr_pcalloc<code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code>pool<code class="sh_misc">,</code> <code class="sh_declare">sizeof</code><code class="sh_misc">(</code><code class="sh_declare">int</code><code class="sh_misc">)</code><code class="sh_misc">*</code><code class="sh_reference">10</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
492 <code class="sh_comment">/* Create a copy of the 'original' variable that we can edit. */</code>
493 copy <code class="sh_misc">=</code> apr_pstrdup<code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code>pool<code class="sh_misc">,</code> original<code class="sh_misc">)</code><code class="sh_misc">;</code>
494 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
495 <code class="sh_misc">}</code>
497 <!-- END EXAMPLE CODE -->
500 This is all well and good for our module, which won't need any
501 pre-initialized variables or structures. However, if we wanted to
502 initialize something early on, before the requests come rolling in, we
503 could simply add a call to a function in our <code>register_hooks</code>
504 function to sort it out:
507 <!-- BEGIN EXAMPLE CODE -->
509 <code class="sh_declare">static</code> <code class="sh_declare">void</code> register_hooks<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">)</code>
510 <code class="sh_misc">{</code>
511 <code class="sh_comment">/* Call a function that initializes some stuff */</code>
512 <code class="sh_function">example_init_function</code><code class="sh_misc">(</code>pool<code class="sh_misc">)</code><code class="sh_misc">;</code>
513 <code class="sh_comment">/* Create a hook in the request handler, so we get called when a request arrives */</code>
514 <code class="sh_function">ap_hook_handler</code><code class="sh_misc">(</code>example_handler<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> APR_HOOK_LAST<code class="sh_misc">)</code><code class="sh_misc">;</code>
515 <code class="sh_misc">}</code>
517 <!-- END EXAMPLE CODE -->
520 In this pre-request initialization function we would not be using the
521 same pool as we did when allocating resources for request-based functions.
522 Instead, we would use the pool given to us by the server for allocating memory
523 on a per-process based level.
527 <section id="parsing"><title>Parsing request data</title>
529 In our example module, we would like to add a feature, that checks which
530 type of digest, MD5 or SHA1 the client would like to see. This could be
531 solved by adding a query string to the request. A query string is typically
532 comprised of several keys and values put together in a string, for instance
533 <code>valueA=yes&valueB=no&valueC=maybe</code>. It is up to the
534 module itself to parse these and get the data it requires. In our example,
535 we'll be looking for a key called <code>digest</code>, and if set to <code>
536 md5</code>, we'll produce an MD5 digest, otherwise we'll produce a SHA1
540 Since the introduction of Apache HTTP Server 2.4, parsing request data from GET and
541 POST requests have never been easier. All we require to parse both GET and
542 POST data is four simple lines:
546 <!-- BEGIN EXAMPLE CODE -->
548 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__apr__tables.html#gad7ea82d6608a4a633fc3775694ab71e4">apr_table_t</a> *GET;
549 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/structapr__array__header__t.html">apr_array_header_t</a> *POST;
551 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__SCRIPT.html#gaed25877b529623a4d8f99f819ba1b7bd">ap_args_to_table</a>(r, &GET);
552 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__DAEMON.html#ga9d426b6382b49754d4f87c55f65af202">ap_parse_form_data</a>(r, <code class="sh_constant">NULL</code>, &POST, -1, 8192);
554 <!-- END EXAMPLE CODE -->
557 In our specific example module, we're looking for the <code>digest</code>
558 value from the query string, which now resides inside a table called <code>
559 GET</code>. To extract this value, we need only perform a simple operation:
563 <!-- BEGIN EXAMPLE CODE -->
565 <code class="sh_comment">/* Get the "digest" key from the query string, if any. */</code>
566 <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc"> *</code>digestType <code class="sh_misc">=</code> <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__apr__tables.html#ga4db13e3915c6b9a3142b175d4c15d915">apr_table_get</a><code class="sh_misc">(</code>GET<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">digest</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
568 <code class="sh_comment">/* If no key was returned, we will set a default value instead. */</code>
569 <code class="sh_declare">if</code> <code class="sh_misc">(</code><code class="sh_misc">!</code>digestType<code class="sh_misc">)</code> digestType <code class="sh_misc">=</code> <code class="sh_character">"</code><code class="sh_value">sha1</code><code class="sh_character">"</code><code class="sh_misc">;</code>
572 <!-- END EXAMPLE CODE -->
575 The structures used for the POST and GET data are not exactly the same, so
576 if we were to fetch a value from POST data instead of the query string, we
577 would have to resort to a few more lines, as outlined in <a href="#get_post"
578 >this example</a> in the last chapter of this document.
582 <section id="advanced_handler"><title>Making an advanced handler</title>
584 Now that we have learned how to parse form data and manage our resources,
585 we can move on to creating an advanced version of our module, that spits
586 out the MD5 or SHA1 digest of files:
590 <!-- BEGIN EXAMPLE CODE -->
592 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
593 <code class="sh_misc">{</code>
594 <code class="sh_declare">int</code> rc<code class="sh_misc">,</code> exists<code class="sh_misc">;</code>
595 apr_finfo_t finfo<code class="sh_misc">;</code>
596 apr_file_t<code class="sh_misc"> *</code>file<code class="sh_misc">;</code>
597 <code class="sh_declare">char</code> <code class="sh_misc">*</code>filename<code class="sh_misc">;</code>
598 <code class="sh_declare">char</code> buffer<code class="sh_misc">[</code><code class="sh_reference">256</code><code class="sh_misc">]</code><code class="sh_misc">;</code>
599 apr_size_t readBytes<code class="sh_misc">;</code>
600 <code class="sh_declare">int</code> n<code class="sh_misc">;</code>
601 apr_table_t<code class="sh_misc"> *</code>GET<code class="sh_misc">;</code>
602 apr_array_header_t<code class="sh_misc"> *</code>POST<code class="sh_misc">;</code>
603 <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc"> *</code>digestType<code class="sh_misc">;</code>
606 <code class="sh_comment">/* Check that the "example-handler" handler is being called. */</code>
607 <code class="sh_declare">if</code> <code class="sh_misc">(</code><code class="sh_misc">!</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code> <code class="sh_misc">|</code><code class="sh_misc">|</code> <code class="sh_function">strcmp</code><code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code><code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">example-handler</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_declare">return</code> <code class="sh_misc">(</code>DECLINED<code class="sh_misc">)</code><code class="sh_misc">;</code>
609 <code class="sh_comment">/* Figure out which file is being requested by removing the .sum from it */</code>
610 filename <code class="sh_misc">=</code> apr_pstrdup<code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">pool</code><code class="sh_misc">,</code> r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">filename</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
611 filename<code class="sh_misc">[</code><code class="sh_function">strlen</code><code class="sh_misc">(</code>filename<code class="sh_misc">)</code><code class="sh_misc">-</code><code class="sh_reference">4</code><code class="sh_misc">]</code> <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code> <code class="sh_comment">/* Cut off the last 4 characters. */</code>
613 <code class="sh_comment">/* Figure out if the file we request a sum on exists and isn't a directory */</code>
614 rc <code class="sh_misc">=</code> apr_stat<code class="sh_misc">(</code><code class="sh_misc">&</code>finfo<code class="sh_misc">,</code> filename<code class="sh_misc">,</code> APR_FINFO_MIN<code class="sh_misc">,</code> r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">pool</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
615 <code class="sh_declare">if</code> <code class="sh_misc">(</code>rc <code class="sh_misc">=</code><code class="sh_misc">=</code> APR_SUCCESS<code class="sh_misc">)</code> <code class="sh_misc">{</code>
616 exists <code class="sh_misc">=</code>
617 <code class="sh_misc">(</code>
618 <code class="sh_misc">(</code>finfo<code class="sh_misc">.</code>filetype <code class="sh_misc">!</code><code class="sh_misc">=</code> APR_NOFILE<code class="sh_misc">)</code>
619 <code class="sh_misc">&</code><code class="sh_misc">&</code> <code class="sh_misc">!</code><code class="sh_misc">(</code>finfo<code class="sh_misc">.</code>filetype <code class="sh_misc">&</code> APR_DIR<code class="sh_misc">)</code>
620 <code class="sh_misc">)</code><code class="sh_misc">;</code>
621 <code class="sh_declare">if</code> <code class="sh_misc">(</code><code class="sh_misc">!</code>exists<code class="sh_misc">)</code> <code class="sh_declare">return</code> HTTP_NOT_FOUND<code class="sh_misc">;</code> <code class="sh_comment">/* Return a 404 if not found. */</code>
622 <code class="sh_misc">}</code>
623 <code class="sh_comment">/* If apr_stat failed, we're probably not allowed to check this file. */</code>
624 <code class="sh_declare">else</code> <code class="sh_declare">return</code> HTTP_FORBIDDEN<code class="sh_misc">;</code>
626 <code class="sh_comment">/* Parse the GET and, optionally, the POST data sent to us */</code>
628 ap_args_to_table<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_misc">&</code>GET<code class="sh_misc">)</code><code class="sh_misc">;</code>
629 ap_parse_form_data<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_misc">&</code>POST<code class="sh_misc">,</code> <code class="sh_misc">-</code><code class="sh_reference">1</code><code class="sh_misc">,</code> <code class="sh_reference">8192</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
631 <code class="sh_comment">/* Set the appropriate content type */</code>
632 ap_set_content_type<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">text/html</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
634 <code class="sh_comment">/* Print a title and some general information */</code>
635 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value"><h2>Information on </code><code class="sh_reference">%s</code><code class="sh_value">:</h2></code><code class="sh_character">"</code><code class="sh_misc">,</code> filename<code class="sh_misc">)</code><code class="sh_misc">;</code>
636 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value"><b>Size:</b> </code><code class="sh_reference">%u</code><code class="sh_value"> bytes<br/></code><code class="sh_character">"</code><code class="sh_misc">,</code> finfo<code class="sh_misc">.</code>size<code class="sh_misc">)</code><code class="sh_misc">;</code>
638 <code class="sh_comment">/* Get the digest type the client wants to see */</code>
639 digestType <code class="sh_misc">=</code> apr_table_get<code class="sh_misc">(</code>GET<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">digest</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
640 <code class="sh_declare">if</code> <code class="sh_misc">(</code><code class="sh_misc">!</code>digestType<code class="sh_misc">)</code> digestType <code class="sh_misc">=</code> <code class="sh_character">"</code><code class="sh_value">MD5</code><code class="sh_character">"</code><code class="sh_misc">;</code>
643 rc <code class="sh_misc">=</code> apr_file_open<code class="sh_misc">(</code><code class="sh_misc">&</code>file<code class="sh_misc">,</code> filename<code class="sh_misc">,</code> APR_READ<code class="sh_misc">,</code> APR_OS_DEFAULT<code class="sh_misc">,</code> r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">pool</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
644 <code class="sh_declare">if</code> <code class="sh_misc">(</code>rc <code class="sh_misc">=</code><code class="sh_misc">=</code> APR_SUCCESS<code class="sh_misc">)</code> <code class="sh_misc">{</code>
646 <code class="sh_comment">/* Are we trying to calculate the MD5 or the SHA1 digest? */</code>
647 <code class="sh_declare">if</code> <code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>digestType<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">md5</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_misc">{</code>
648 <code class="sh_comment">/* Calculate the MD5 sum of the file */</code>
649 <code class="sh_declare">union</code> <code class="sh_misc">{</code>
650 <code class="sh_declare">char</code> chr<code class="sh_misc">[</code><code class="sh_reference">16</code><code class="sh_misc">]</code><code class="sh_misc">;</code>
651 uint32_t num<code class="sh_misc">[</code><code class="sh_reference">4</code><code class="sh_misc">]</code><code class="sh_misc">;</code>
652 <code class="sh_misc">}</code> digest<code class="sh_misc">;</code>
653 apr_md5_ctx_t md5<code class="sh_misc">;</code>
654 apr_md5_init<code class="sh_misc">(</code><code class="sh_misc">&</code>md5<code class="sh_misc">)</code><code class="sh_misc">;</code>
655 readBytes <code class="sh_misc">=</code> <code class="sh_reference">256</code><code class="sh_misc">;</code>
656 <code class="sh_declare">while</code> <code class="sh_misc">(</code> apr_file_read<code class="sh_misc">(</code>file<code class="sh_misc">,</code> buffer<code class="sh_misc">,</code> <code class="sh_misc">&</code>readBytes<code class="sh_misc">)</code> <code class="sh_misc">=</code><code class="sh_misc">=</code> APR_SUCCESS <code class="sh_misc">)</code> <code class="sh_misc">{</code>
657 apr_md5_update<code class="sh_misc">(</code><code class="sh_misc">&</code>md5<code class="sh_misc">,</code> buffer<code class="sh_misc">,</code> readBytes<code class="sh_misc">)</code><code class="sh_misc">;</code>
658 <code class="sh_misc">}</code>
659 apr_md5_final<code class="sh_misc">(</code>digest<code class="sh_misc">.</code>chr<code class="sh_misc">,</code> <code class="sh_misc">&</code>md5<code class="sh_misc">)</code><code class="sh_misc">;</code>
661 <code class="sh_comment">/* Print out the MD5 digest */</code>
662 ap_rputs<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value"><b>MD5: </b><code></code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">)</code><code class="sh_misc">;</code>
663 <code class="sh_declare">for</code> <code class="sh_misc">(</code>n <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code> n <code class="sh_misc"><</code> APR_MD5_DIGESTSIZE<code class="sh_misc">/</code><code class="sh_reference">4</code><code class="sh_misc">;</code> n<code class="sh_misc">+</code><code class="sh_misc">+</code><code class="sh_misc">)</code> <code class="sh_misc">{</code>
664 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_reference">%08x</code><code class="sh_character">"</code><code class="sh_misc">,</code> digest<code class="sh_misc">.</code>num<code class="sh_misc">[</code>n<code class="sh_misc">]</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
665 <code class="sh_misc">}</code>
666 ap_rputs<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value"></code></code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">)</code><code class="sh_misc">;</code>
667 <code class="sh_comment">/* Print a link to the SHA1 version */</code>
668 ap_rputs<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value"><br/><a href='?digest=sha1'>View the SHA1 hash instead</a></code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">)</code><code class="sh_misc">;</code>
669 <code class="sh_misc">}</code>
670 <code class="sh_declare">else</code> <code class="sh_misc">{</code>
671 <code class="sh_comment">/* Calculate the SHA1 sum of the file */</code>
672 <code class="sh_declare">union</code> <code class="sh_misc">{</code>
673 <code class="sh_declare">char</code> chr<code class="sh_misc">[</code><code class="sh_reference">20</code><code class="sh_misc">]</code><code class="sh_misc">;</code>
674 uint32_t num<code class="sh_misc">[</code><code class="sh_reference">5</code><code class="sh_misc">]</code><code class="sh_misc">;</code>
675 <code class="sh_misc">}</code> digest<code class="sh_misc">;</code>
676 apr_sha1_ctx_t sha1<code class="sh_misc">;</code>
677 apr_sha1_init<code class="sh_misc">(</code><code class="sh_misc">&</code>sha1<code class="sh_misc">)</code><code class="sh_misc">;</code>
678 readBytes <code class="sh_misc">=</code> <code class="sh_reference">256</code><code class="sh_misc">;</code>
679 <code class="sh_declare">while</code> <code class="sh_misc">(</code> apr_file_read<code class="sh_misc">(</code>file<code class="sh_misc">,</code> buffer<code class="sh_misc">,</code> <code class="sh_misc">&</code>readBytes<code class="sh_misc">)</code> <code class="sh_misc">=</code><code class="sh_misc">=</code> APR_SUCCESS <code class="sh_misc">)</code> <code class="sh_misc">{</code>
680 apr_sha1_update<code class="sh_misc">(</code><code class="sh_misc">&</code>sha1<code class="sh_misc">,</code> buffer<code class="sh_misc">,</code> readBytes<code class="sh_misc">)</code><code class="sh_misc">;</code>
681 <code class="sh_misc">}</code>
682 apr_sha1_final<code class="sh_misc">(</code>digest<code class="sh_misc">.</code>chr<code class="sh_misc">,</code> <code class="sh_misc">&</code>sha1<code class="sh_misc">)</code><code class="sh_misc">;</code>
684 <code class="sh_comment">/* Print out the SHA1 digest */</code>
685 ap_rputs<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value"><b>SHA1: </b><code></code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">)</code><code class="sh_misc">;</code>
686 <code class="sh_declare">for</code> <code class="sh_misc">(</code>n <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code> n <code class="sh_misc"><</code> APR_SHA1_DIGESTSIZE<code class="sh_misc">/</code><code class="sh_reference">4</code><code class="sh_misc">;</code> n<code class="sh_misc">+</code><code class="sh_misc">+</code><code class="sh_misc">)</code> <code class="sh_misc">{</code>
687 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_reference">%08x</code><code class="sh_character">"</code><code class="sh_misc">,</code> digest<code class="sh_misc">.</code>num<code class="sh_misc">[</code>n<code class="sh_misc">]</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
688 <code class="sh_misc">}</code>
689 ap_rputs<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value"></code></code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">)</code><code class="sh_misc">;</code>
691 <code class="sh_comment">/* Print a link to the MD5 version */</code>
692 ap_rputs<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value"><br/><a href='?digest=md5'>View the MD5 hash instead</a></code><code class="sh_character">"</code><code class="sh_misc">,</code> r<code class="sh_misc">)</code><code class="sh_misc">;</code>
693 <code class="sh_misc">}</code>
694 apr_file_close<code class="sh_misc">(</code>file<code class="sh_misc">)</code><code class="sh_misc">;</code>
696 <code class="sh_misc">}</code>
700 <code class="sh_comment">/* Let the server know that we responded to this request. */</code>
701 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
702 <code class="sh_misc">}</code>
704 <!-- END EXAMPLE CODE -->
707 This version in its entirity can be found here:
708 <a href="http://people.apache.org/~humbedooh/mods/examples/mod_example_2.c">mod_example_2.c</a>.
714 <section id="configuration"><title>Adding configuration options</title>
716 In this next segment of this document, we will turn our eyes away from the
717 digest module and create a new example module, whose only function is to
718 write out its own configuration. The purpose of this is to examine how
719 the server works with configuration, and what happens when you start writing
720 advanced configurations
723 <section id="config_intro"><title>An introduction to configuration
726 If you are reading this, then you probably already know
727 what a configuration directive is. Simply put, a directive is a way of
728 telling an individual module (or a set of modules) how to behave, such as
729 these directives control how <code>mod_rewrite</code> works:
733 RewriteCond %{REQUEST_URI} ^/foo/bar
734 RewriteRule ^/foo/bar/(.*)$ /foobar?page=$1
737 Each of these configuration directives are handled by a separate function,
738 that parses the parameters given and sets up a configuration accordingly.
741 <section id="config_simple"><title>Making an example configuration</title>
742 <p>To begin with, we'll create a basic configuration in C-space:</p>
745 <!-- BEGIN EXAMPLE CODE -->
747 <code class="sh_declare">typedef</code> <code class="sh_declare">struct</code> <code class="sh_misc">{</code>
748 <code class="sh_declare">int</code> enabled<code class="sh_misc">;</code> <code class="sh_comment">/* Enable or disable our module */</code>
749 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>path<code class="sh_misc">;</code> <code class="sh_comment">/* Some path to...something */</code>
750 <code class="sh_declare">int</code> typeOfAction<code class="sh_misc">;</code> <code class="sh_comment">/* 1 means action A, 2 means action B and so on */</code>
751 <code class="sh_misc">}</code> example_config<code class="sh_misc">;</code>
753 <!-- END EXAMPLE CODE -->
756 Now, let's put this into perspective by creating a very small module that
757 just prints out a hard-coded configuration. You'll notice that we use the
758 <code>register_hooks</code> function for initializing the configuration
759 values to their defaults:
762 <!-- BEGIN EXAMPLE CODE -->
764 <code class="sh_declare">typedef</code> <code class="sh_declare">struct</code> <code class="sh_misc">{</code>
765 <code class="sh_declare">int</code> enabled<code class="sh_misc">;</code> <code class="sh_comment">/* Enable or disable our module */</code>
766 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>path<code class="sh_misc">;</code> <code class="sh_comment">/* Some path to...something */</code>
767 <code class="sh_declare">int</code> typeOfAction<code class="sh_misc">;</code> <code class="sh_comment">/* 1 means action A, 2 means action B and so on */</code>
768 <code class="sh_misc">}</code> example_config<code class="sh_misc">;</code>
770 <code class="sh_declare">static</code> example_config config<code class="sh_misc">;</code>
772 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
773 <code class="sh_misc">{</code>
774 <code class="sh_declare">if</code> <code class="sh_misc">(</code><code class="sh_misc">!</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code> <code class="sh_misc">|</code><code class="sh_misc">|</code> <code class="sh_function">strcmp</code><code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code><code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">example-handler</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_declare">return</code><code class="sh_misc">(</code>DECLINED<code class="sh_misc">)</code><code class="sh_misc">;</code>
775 ap_set_content_type<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">text/plain</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
776 ap_rprintf<code class="sh_misc">(r, </code><code class="sh_character">"</code><code class="sh_value">Enabled: </code><code class="sh_reference">%u</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">.</code>enabled<code class="sh_misc">)</code><code class="sh_misc">;</code>
777 ap_rprintf<code class="sh_misc">(r, </code><code class="sh_character">"</code><code class="sh_value">Path: </code><code class="sh_reference">%s</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">.</code>path<code class="sh_misc">)</code><code class="sh_misc">;</code>
778 ap_rprintf<code class="sh_misc">(r, </code><code class="sh_character">"</code><code class="sh_value">TypeOfAction: </code><code class="sh_reference">%x</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">.</code>typeOfAction<code class="sh_misc">)</code><code class="sh_misc">;</code>
779 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
780 <code class="sh_misc">}</code>
782 <code class="sh_declare">static</code> <code class="sh_declare">void</code> register_hooks<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">)</code>
783 <code class="sh_misc">{</code>
784 config<code class="sh_misc">.</code>enabled <code class="sh_misc">=</code> <code class="sh_reference">1</code><code class="sh_misc">;</code>
785 config<code class="sh_misc">.</code>path <code class="sh_misc">=</code> <code class="sh_character">"</code><code class="sh_value">/foo/bar</code><code class="sh_character">"</code><code class="sh_misc">;</code>
786 config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">=</code> <code class="sh_reference">0x00</code><code class="sh_misc">;</code>
787 ap_hook_handler<code class="sh_misc">(</code>example_handler<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> APR_HOOK_LAST<code class="sh_misc">)</code><code class="sh_misc">;</code>
788 <code class="sh_misc">}</code>
790 <code class="sh_comment">/* Define our module as an entity and assign a function for registering hooks */</code>
792 module AP_MODULE_DECLARE_DATA example_module <code class="sh_misc">=</code>
793 <code class="sh_misc">{</code>
794 STANDARD20_MODULE_STUFF<code class="sh_misc">,</code>
795 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Per-directory configuration handler */</code>
796 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-directory configurations */</code>
797 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Per-server configuration handler */</code>
798 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-server configurations */</code>
799 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Any directives we may have for httpd */</code>
800 register_hooks <code class="sh_comment">/* Our hook registering function */</code>
801 <code class="sh_misc">}</code><code class="sh_misc">;</code>
803 <!-- END EXAMPLE CODE -->
806 So far so good. To access our new handler, we could add the following to
810 <Location /example>
811 SetHandler example-handler
815 When we visit, we'll see our current configuration being spit out by our
820 <section id="register_directive"><title>Registering directives with the server</title>
822 What if we want to change our configuration, not by hard-coding new values
823 into the module, but by using either the httpd.conf file or possibly a
824 .htaccess file? It's time to let the server know that we want this to be
825 possible. To do so, we must first change our <em>name tag</em> to include a
826 reference to the configuration directives we want to register with the server:
829 <!-- BEGIN EXAMPLE CODE -->
831 module AP_MODULE_DECLARE_DATA example_module =
833 STANDARD20_MODULE_STUFF,
834 <code class="sh_constant">NULL</code>, <code class="sh_comment">/* Per-directory configuration handler */</code>
835 <code class="sh_constant">NULL</code>, <code class="sh_comment">/* Merge handler for per-directory configurations */</code>
836 <code class="sh_constant">NULL</code>, <code class="sh_comment">/* Per-server configuration handler */</code>
837 <code class="sh_constant">NULL</code>, <code class="sh_comment">/* Merge handler for per-server configurations */</code>
838 example_directives, <code class="sh_comment">/* Any directives we may have for httpd */</code>
839 register_hooks <code class="sh_comment">/* Our hook registering function */</code>
842 <!-- END EXAMPLE CODE -->
845 This will tell the server that we are now accepting directives from the
846 configuration files, and that the structure called <code>example_directives
847 </code> holds information on what our directives are and how they work.
848 Since we have three different variables in our module configuration, we
849 will add a structure with three directives and a NULL at the end:
852 <!-- BEGIN EXAMPLE CODE -->
854 static const command_rec example_directives[] =
856 <code class="sh_declare"><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a></code>("exampleEnabled", example_set_enabled, <code class="sh_constant">NULL</code>, RSRC_CONF, "Enable or disable mod_example"),
857 <code class="sh_declare"><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a></code>("examplePath", example_set_path, <code class="sh_constant">NULL</code>, RSRC_CONF, "The path to whatever"),
858 <code class="sh_declare"><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#gafaec43534fcf200f37d9fecbf9247c21">AP_INIT_TAKE2</a></code>("exampleAction", example_set_action, <code class="sh_constant">NULL</code>, RSRC_CONF, "Special action value!"),
859 { <code class="sh_constant">NULL</code> }
862 <!-- END EXAMPLE CODE -->
865 <img src="../images/build_a_mod_4.png" border="1" alt="Directives structure"/><br/>
866 As you can see, each directive needs at least 5 parameters set:
869 <li><code><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a></code>: This is a macro that tells the server that this directive takes one and only one argument.
870 If we required two arguments, we could use the macro <code><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#gafaec43534fcf200f37d9fecbf9247c21">AP_INIT_TAKE2</a></code> and so on (refer to httpd_conf.h
871 for more macros).</li>
872 <li><code>exampleEnabled</code>: This is the name of our directive. More precisely, it is what the user must put in his/her
873 configuration in order to invoke a configuration change in our module.</li>
874 <li><code>example_set_enabled</code>: This is a reference to a C function that parses the directive and sets the configuration
875 accordingly. We will discuss how to make this in the following paragraph.</li>
876 <li><code>RSRC_CONF</code>: This tells the server where the directive is permitted. We'll go into details on this value in the
877 later chapters, but for now, <code>RSRC_CONF</code> means that the server will only accept these directives in a server context.</li>
878 <li><code>"Enable or disable...."</code>: This is simply a brief description of what the directive does.</li>
881 (<em>The "missing" parameter in our definition, which is usually set to
882 <code>NULL</code>, is an optional function that can be run after the
883 initial function to parse the arguments have been run. This is usually
884 omitted, as the function for verifying arguments might as well be used to
888 <section id="directive_handler"><title>The directive handler function</title>
890 Now that we've told the server to expect some directives for our module, it's
891 time to make a few functions for handling these. What the server reads in the
892 configuration file(s) is text, and so naturally, what it passes along to
893 our directive handler is one or more strings, that we ourselves need to
894 recognize and act upon. You'll notice, that since we set our <code>
895 exampleAction</code> directive to accept two arguments, its C function also
896 has an additional parameter defined:</p>
898 <!-- BEGIN EXAMPLE CODE -->
900 <code class="sh_comment">/* Handler for the "exambleEnabled" directive */</code>
901 <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc"> *</code>example_set_enabled<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg<code class="sh_misc">)</code>
902 <code class="sh_misc">{</code>
903 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>arg<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">on</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> config<code class="sh_misc">.</code>enabled <code class="sh_misc">=</code> <code class="sh_reference">1</code><code class="sh_misc">;</code>
904 <code class="sh_declare">else</code> config<code class="sh_misc">.</code>enabled <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code>
905 <code class="sh_declare">return</code> <code class="sh_constant">NULL</code><code class="sh_misc">;</code>
906 <code class="sh_misc">}</code>
908 <code class="sh_comment">/* Handler for the "examplePath" directive */</code>
909 <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc"> *</code>example_set_path<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg<code class="sh_misc">)</code>
910 <code class="sh_misc">{</code>
911 config<code class="sh_misc">.</code>path <code class="sh_misc">=</code> arg<code class="sh_misc">;</code>
912 <code class="sh_declare">return</code> <code class="sh_constant">NULL</code><code class="sh_misc">;</code>
913 <code class="sh_misc">}</code>
915 <code class="sh_comment">/* Handler for the "exampleAction" directive */</code>
916 <code class="sh_comment">/* Let's pretend this one takes one argument (file or db), and a second (deny or allow), */</code>
917 <code class="sh_comment">/* and we store it in a bit-wise manner. */</code>
918 <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc"> *</code>example_set_action<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg1<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc">*</code> arg2<code class="sh_misc">)</code>
919 <code class="sh_misc">{</code>
920 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>arg1<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">file</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">=</code> <code class="sh_reference">0x01</code><code class="sh_misc">;</code>
921 <code class="sh_declare">else</code> config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">=</code> <code class="sh_reference">0x02</code><code class="sh_misc">;</code>
923 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>arg2<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">deny</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">+</code><code class="sh_misc">=</code> <code class="sh_reference">0x10</code><code class="sh_misc">;</code>
924 <code class="sh_declare">else</code> config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">+</code><code class="sh_misc">=</code> <code class="sh_reference">0x20</code><code class="sh_misc">;</code>
925 <code class="sh_declare">return</code> <code class="sh_constant">NULL</code><code class="sh_misc">;</code>
926 <code class="sh_misc">}</code>
928 <!-- END EXAMPLE CODE -->
932 <section id="directive_complete"><title>Putting it all together</title>
934 Now that we have our directives set up, and handlers configured for them,
935 we can assemble our module into one big file:
938 <!-- BEGIN EXAMPLE CODE -->
940 <code class="sh_comment">/* mod_example_config_simple.c: */</code>
941 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character"><</code><code class="sh_reference">stdio.h</code><code class="sh_character">></code>
942 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">apr_hash.h</code><code class="sh_character">"</code>
943 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">ap_config.h</code><code class="sh_character">"</code>
944 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">ap_provider.h</code><code class="sh_character">"</code>
945 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">httpd.h</code><code class="sh_character">"</code>
946 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_core.h</code><code class="sh_character">"</code>
947 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_config.h</code><code class="sh_character">"</code>
948 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_log.h</code><code class="sh_character">"</code>
949 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_protocol.h</code><code class="sh_character">"</code>
950 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_request.h</code><code class="sh_character">"</code>
952 <code class="sh_comment">/*</code>
953 <code class="sh_comment"> ==============================================================================</code>
954 <code class="sh_comment"> Our configuration prototype and declaration:</code>
955 <code class="sh_comment"> ==============================================================================</code>
956 <code class="sh_comment"> */</code>
957 <code class="sh_declare">typedef</code> <code class="sh_declare">struct</code> <code class="sh_misc">{</code>
958 <code class="sh_declare">int</code> enabled<code class="sh_misc">;</code> <code class="sh_comment">/* Enable or disable our module */</code>
959 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>path<code class="sh_misc">;</code> <code class="sh_comment">/* Some path to...something */</code>
960 <code class="sh_declare">int</code> typeOfAction<code class="sh_misc">;</code> <code class="sh_comment">/* 1 means action A, 2 means action B and so on */</code>
961 <code class="sh_misc">}</code> example_config<code class="sh_misc">;</code>
963 <code class="sh_declare">static</code> example_config config<code class="sh_misc">;</code>
965 <code class="sh_comment">/*</code>
966 <code class="sh_comment"> ==============================================================================</code>
967 <code class="sh_comment"> Our directive handlers:</code>
968 <code class="sh_comment"> ==============================================================================</code>
969 <code class="sh_comment"> */</code>
970 <code class="sh_comment">/* Handler for the "exambleEnabled" directive */</code>
971 <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc"> *</code>example_set_enabled<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg<code class="sh_misc">)</code>
972 <code class="sh_misc">{</code>
973 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>arg<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">on</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> config<code class="sh_misc">.</code>enabled <code class="sh_misc">=</code> <code class="sh_reference">1</code><code class="sh_misc">;</code>
974 <code class="sh_declare">else</code> config<code class="sh_misc">.</code>enabled <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code>
975 <code class="sh_declare">return</code> <code class="sh_constant">NULL</code><code class="sh_misc">;</code>
976 <code class="sh_misc">}</code>
978 <code class="sh_comment">/* Handler for the "examplePath" directive */</code>
979 <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc"> *</code>example_set_path<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg<code class="sh_misc">)</code>
980 <code class="sh_misc">{</code>
981 config<code class="sh_misc">.</code>path <code class="sh_misc">=</code> arg<code class="sh_misc">;</code>
982 <code class="sh_declare">return</code> <code class="sh_constant">NULL</code><code class="sh_misc">;</code>
983 <code class="sh_misc">}</code>
985 <code class="sh_comment">/* Handler for the "exampleAction" directive */</code>
986 <code class="sh_comment">/* Let's pretend this one takes one argument (file or db), and a second (deny or allow), */</code>
987 <code class="sh_comment">/* and we store it in a bit-wise manner. */</code>
988 <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc"> *</code>example_set_action<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg1<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code><code class="sh_misc">*</code> arg2<code class="sh_misc">)</code>
989 <code class="sh_misc">{</code>
990 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>arg1<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">file</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">=</code> <code class="sh_reference">0x01</code><code class="sh_misc">;</code>
991 <code class="sh_declare">else</code> config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">=</code> <code class="sh_reference">0x02</code><code class="sh_misc">;</code>
993 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>arg2<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">deny</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">+</code><code class="sh_misc">=</code> <code class="sh_reference">0x10</code><code class="sh_misc">;</code>
994 <code class="sh_declare">else</code> config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">+</code><code class="sh_misc">=</code> <code class="sh_reference">0x20</code><code class="sh_misc">;</code>
995 <code class="sh_declare">return</code> <code class="sh_constant">NULL</code><code class="sh_misc">;</code>
996 <code class="sh_misc">}</code>
998 <code class="sh_comment">/*</code>
999 <code class="sh_comment"> ==============================================================================</code>
1000 <code class="sh_comment"> The directive structure for our name tag:</code>
1001 <code class="sh_comment"> ==============================================================================</code>
1002 <code class="sh_comment"> */</code>
1003 <code class="sh_declare">static</code> <code class="sh_declare">const</code> command_rec example_directives<code class="sh_misc">[</code><code class="sh_misc">]</code> <code class="sh_misc">=</code>
1004 <code class="sh_misc">{</code>
1005 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a><code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">exampleEnabled</code><code class="sh_character">"</code><code class="sh_misc">,</code> example_set_enabled<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> RSRC_CONF<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Enable or disable mod_example</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">,</code>
1006 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a><code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">examplePath</code><code class="sh_character">"</code><code class="sh_misc">,</code> example_set_path<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> RSRC_CONF<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">The path to whatever</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">,</code>
1007 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#gafaec43534fcf200f37d9fecbf9247c21">AP_INIT_TAKE2</a><code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">exampleAction</code><code class="sh_character">"</code><code class="sh_misc">,</code> example_set_action<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> RSRC_CONF<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Special action value!</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">,</code>
1008 <code class="sh_misc">{</code> <code class="sh_constant">NULL</code> <code class="sh_misc">}</code>
1009 <code class="sh_misc">}</code><code class="sh_misc">;</code>
1010 <code class="sh_comment">/*</code>
1011 <code class="sh_comment"> ==============================================================================</code>
1012 <code class="sh_comment"> Our module handler:</code>
1013 <code class="sh_comment"> ==============================================================================</code>
1014 <code class="sh_comment"> */</code>
1015 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
1016 <code class="sh_misc">{</code>
1017 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code> <code class="sh_misc">|</code><code class="sh_misc">|</code> <code class="sh_function">strcmp</code><code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code><code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">example-handler</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_declare">return</code><code class="sh_misc">(</code>DECLINED<code class="sh_misc">)</code><code class="sh_misc">;</code>
1018 ap_set_content_type<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">text/plain</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1019 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Enabled: </code><code class="sh_reference">%u</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">.</code>enabled<code class="sh_misc">)</code><code class="sh_misc">;</code>
1020 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Path: </code><code class="sh_reference">%s</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">.</code>path<code class="sh_misc">)</code><code class="sh_misc">;</code>
1021 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">TypeOfAction: </code><code class="sh_reference">%x</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">.</code>typeOfAction<code class="sh_misc">)</code><code class="sh_misc">;</code>
1022 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
1023 <code class="sh_misc">}</code>
1025 <code class="sh_comment">/*</code>
1026 <code class="sh_comment"> ==============================================================================</code>
1027 <code class="sh_comment"> The hook registration function (also initializes the default config values):</code>
1028 <code class="sh_comment"> ==============================================================================</code>
1029 <code class="sh_comment"> */</code>
1030 <code class="sh_declare">static</code> <code class="sh_declare">void</code> register_hooks<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">)</code>
1031 <code class="sh_misc">{</code>
1032 config<code class="sh_misc">.</code>enabled <code class="sh_misc">=</code> <code class="sh_reference">1</code><code class="sh_misc">;</code>
1033 config<code class="sh_misc">.</code>path <code class="sh_misc">=</code> <code class="sh_character">"</code><code class="sh_value">/foo/bar</code><code class="sh_character">"</code><code class="sh_misc">;</code>
1034 config<code class="sh_misc">.</code>typeOfAction <code class="sh_misc">=</code> <code class="sh_reference">3</code><code class="sh_misc">;</code>
1035 ap_hook_handler<code class="sh_misc">(</code>example_handler<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> APR_HOOK_LAST<code class="sh_misc">)</code><code class="sh_misc">;</code>
1036 <code class="sh_misc">}</code>
1037 <code class="sh_comment">/*</code>
1038 <code class="sh_comment"> ==============================================================================</code>
1039 <code class="sh_comment"> Our module name tag:</code>
1040 <code class="sh_comment"> ==============================================================================</code>
1041 <code class="sh_comment"> */</code>
1042 module AP_MODULE_DECLARE_DATA example_module <code class="sh_misc">=</code>
1043 <code class="sh_misc">{</code>
1044 STANDARD20_MODULE_STUFF<code class="sh_misc">,</code>
1045 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Per-directory configuration handler */</code>
1046 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-directory configurations */</code>
1047 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Per-server configuration handler */</code>
1048 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-server configurations */</code>
1049 example_directives<code class="sh_misc">,</code> <code class="sh_comment">/* Any directives we may have for httpd */</code>
1050 register_hooks <code class="sh_comment">/* Our hook registering function */</code>
1051 <code class="sh_misc">}</code><code class="sh_misc">;</code>
1053 <!-- END EXAMPLE CODE -->
1057 In our httpd.conf file, we can now change the hard-coded configuration by
1062 ExamplePath "/usr/bin/foo"
1063 ExampleAction file allow
1066 And thus we apply the configuration, visit <code>/example</code> on our
1067 web site, and we see the configuration has adapted to what we wrote in our
1075 <section id="context"><title>Context aware configurations</title>
1076 <section id="context_intro"><title>Introduction to context aware configurations</title>
1078 In Apache HTTP Server 2.4, different URLs, virtual hosts, directories etc can have very
1079 different meanings to the user of the server, and thus different contexts
1080 within which modules must operate. For example, let's assume you have this
1081 configuration set up for mod_rewrite:
1084 <Directory "/var/www">
1085 RewriteCond %{HTTP_HOST} ^example.com$
1086 RewriteRule (.*) http://www.example.com/$1
1088 <Directory "/var/www/sub">
1089 RewriteRule ^foobar$ index.php?foobar=true
1093 In this example, you will have set up two different contexts for
1096 <li>Inside <code>/var/www</code>, all requests for <code>http://example.com</code> must go to <code>http://www.example.com</code></li>
1097 <li>Inside <code>/var/www/sub</code>, all requests for <code>foobar</code> must go to <code>index.php?foobar=true</code></li>
1100 If mod_rewrite (or the entire server for that matter) wasn't context aware, then
1101 these rewrite rules would just apply to every and any request made,
1102 regardless of where and how they were made, but since the module can pull
1103 the context specific configuration straight from the server, it does not need
1104 to know itself, which of the directives are valid in this context, since
1105 the server takes care of this.</p>
1108 So how does a module get the specific configuration for the server,
1109 directory or location in question? It does so by making one simple call:
1112 <!-- BEGIN EXAMPLE CODE -->
1114 <!-- END EXAMPLE CODE -->
1115 example_config *config = (example_config*) <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga1093a5908a384eacc929b028c79f2a02">ap_get_module_config</a>(<code class="sh_subobject">r->per_dir_config</code>, &example_module);
1118 That's it! Of course, a whole lot goes on behind the scenes, which we will
1119 discuss in this chapter, starting with how the server came to know what our
1120 configuration looks like, and how it came to be set up as it is in the
1125 <section id="context_base"><title>Our basic configuration setup</title>
1126 <p>In this chapter, we will be working with a slightly modified version of
1127 our previous context structure. We will set a <code>context</code>
1128 variable that we can use to track which context configuration is being
1129 used by the server in various places:
1131 <!-- BEGIN EXAMPLE CODE -->
1133 <code class="sh_declare">typedef</code> <code class="sh_declare">struct</code> <code class="sh_misc">{</code>
1134 <code class="sh_declare">char</code> context<code class="sh_misc">[</code><code class="sh_reference">256</code><code class="sh_misc">]</code><code class="sh_misc">;</code>
1135 <code class="sh_declare">char</code> path<code class="sh_misc">[</code><code class="sh_reference">256</code><code class="sh_misc">]</code><code class="sh_misc">;</code>
1136 <code class="sh_declare">int</code> typeOfAction<code class="sh_misc">;</code>
1137 <code class="sh_declare">int</code> enabled<code class="sh_misc">;</code>
1138 <code class="sh_misc">}</code> example_config<code class="sh_misc">;</code>
1140 <!-- END EXAMPLE CODE -->
1142 <p>Our handler for requests will also be modified, yet still very simple:</p>
1145 <!-- BEGIN EXAMPLE CODE -->
1147 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
1148 <code class="sh_misc">{</code>
1149 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code> <code class="sh_misc">|</code><code class="sh_misc">|</code> <code class="sh_function">strcmp</code><code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code><code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">example-handler</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_declare">return</code><code class="sh_misc">(</code>DECLINED<code class="sh_misc">)</code><code class="sh_misc">;</code>
1150 example_config<code class="sh_misc"> *</code>config <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config<code class="sh_misc">*</code><code class="sh_misc">)</code> ap_get_module_config<code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">per_dir_config</code><code class="sh_misc">,</code> <code class="sh_misc">&</code>example_module<code class="sh_misc">)</code><code class="sh_misc">;</code>
1151 ap_set_content_type<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">text/plain</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1152 ap_rprintf<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">Enabled: </code><code class="sh_reference">%u</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1153 ap_rprintf<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">Path: </code><code class="sh_reference">%s</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1154 ap_rprintf<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">TypeOfAction: </code><code class="sh_reference">%x</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1155 ap_rprintf<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">Context: </code><code class="sh_reference">%s</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">context</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1156 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
1157 <code class="sh_misc">}</code>
1159 <!-- END EXAMPLE CODE -->
1163 <section id="context_which"><title>Choosing a context</title>
1165 Before we can start making our module context aware, we must first define,
1166 which contexts we will accept. As we saw in the previous chapter, defining
1167 a directive required five elements be set:</p>
1170 <!-- BEGIN EXAMPLE CODE -->
1172 <code class="sh_declare"><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a></code>("exampleEnabled", example_set_enabled, <code class="sh_constant">NULL</code>, RSRC_CONF, "Enable or disable mod_example"),
1174 <!-- END EXAMPLE CODE -->
1177 <p>The <code>RSRC_CONF</code> definition told the server that we would only allow
1178 this directive in a global server context, but since we are now trying out
1179 a context aware version of our module, we should set this to something
1180 more lenient, namely the value <code>ACCESS_CONF</code>, which lets us use
1181 the directive inside <Directory> and <Location> blocks.
1185 <section id="context_pool"><title>Using the server to allocate configuration slots</title>
1186 <p> A much smarter way to manage your configurations is by letting the server
1187 help you create them. To do so, we must first start off by changing our
1188 <em>name tag</em> to let the server know, that it should assist us in creating
1189 and managing our configurations. Since we have chosen the per-directory
1190 (or per-location) context for our module configurations, we'll add a
1191 per-directory creator and merger function reference in our tag:</p>
1193 <!-- BEGIN EXAMPLE CODE -->
1195 module AP_MODULE_DECLARE_DATA example_module <code class="sh_misc">=</code>
1196 <code class="sh_misc">{</code>
1197 STANDARD20_MODULE_STUFF<code class="sh_misc">,</code>
1198 create_dir_conf<code class="sh_misc">,</code> <code class="sh_comment">/* Per-directory configuration handler */</code>
1199 merge_dir_conf<code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-directory configurations */</code>
1200 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Per-server configuration handler */</code>
1201 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-server configurations */</code>
1202 directives<code class="sh_misc">,</code> <code class="sh_comment">/* Any directives we may have for httpd */</code>
1203 register_hooks <code class="sh_comment">/* Our hook registering function */</code>
1204 <code class="sh_misc">}</code><code class="sh_misc">;</code>
1206 <!-- END EXAMPLE CODE -->
1212 <section id="context_new"><title>Creating new context configurations</title>
1214 Now that we have told the server to help us create and manage configurations,
1215 our first step is to make a function for creating new, blank
1216 configurations. We do so by creating the function we just referenced in
1217 our name tag as the Per-directory configuration handler:</p>
1218 <!-- BEGIN EXAMPLE CODE -->
1220 <code class="sh_declare">void</code><code class="sh_misc">*</code> example_create_dir_conf<code class="sh_misc">(</code>apr_pool_t<code class="sh_misc">*</code> pool<code class="sh_misc">,</code> <code class="sh_declare">char</code><code class="sh_misc">*</code> context<code class="sh_misc">)</code> <code class="sh_misc">{</code>
1221 context <code class="sh_misc">=</code> context <code class="sh_misc">?</code> context <code class="sh_misc">:</code> <code class="sh_character">"</code><code class="sh_value">(undefined context)</code><code class="sh_character">"</code><code class="sh_misc">;</code>
1222 example_config<code class="sh_misc"> *</code>cfg <code class="sh_misc">=</code> apr_pcalloc<code class="sh_misc">(</code>pool<code class="sh_misc">,</code> <code class="sh_declare">sizeof</code><code class="sh_misc">(</code>example_config<code class="sh_misc">)</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1223 <code class="sh_declare">if</code><code class="sh_misc">(</code>cfg<code class="sh_misc">)</code> <code class="sh_misc">{</code>
1224 <code class="sh_comment">/* Set some default values */</code>
1225 <code class="sh_function">strcpy</code><code class="sh_misc">(</code>cfg<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">context</code><code class="sh_misc">,</code> x<code class="sh_misc">)</code><code class="sh_misc">;</code>
1226 cfg<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code>
1227 cfg<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code> <code class="sh_misc">=</code> <code class="sh_character">"</code><code class="sh_value">/foo/bar</code><code class="sh_character">"</code><code class="sh_misc">;</code>
1228 cfg<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">=</code> <code class="sh_reference">0x11</code><code class="sh_misc">;</code>
1229 <code class="sh_misc">}</code>
1230 <code class="sh_declare">return</code> cfg<code class="sh_misc">;</code>
1231 <code class="sh_misc">}</code>
1233 <!-- END EXAMPLE CODE -->
1238 <section id="context_merge"><title>Merging configurations</title>
1240 Our next step in creating a context aware configuration is merging
1241 configurations. This part of the process particularly apply to scenarios
1242 where you have a parent configuration and a child, such as the following:
1245 <Directory "/var/www">
1247 ExamplePath /foo/bar
1248 ExampleAction file allow
1250 <Directory "/var/www/subdir">
1251 ExampleAction file deny
1255 In this example, it is natural to assume that the directory <code>
1256 /var/www/subdir</code> should inherit the value set for the <code>/var/www
1257 </code> directory, as we did not specify a <code>ExampleEnable</code> nor
1258 an <code>ExamplePath</code> for this directory. The server does not presume to
1259 know if this is true, but cleverly does the following:
1262 <li>Creates a new configuration for <code>/var/www</code></li>
1263 <li>Sets the configuration values according to the directives given for <code>/var/www</code></li>
1264 <li>Creates a new configuration for <code>/var/www/subdir</code></li>
1265 <li>Sets the configuration values according to the directives given for <code>/var/www/subdir</code></li>
1266 <li><strong>Proposes a merge</strong> of the two configurations into a new configuration for <code>/var/www/subdir</code></li>
1269 This proposal is handled by the <code>merge_dir_conf</code> function we
1270 referenced in our name tag. The purpose of this function is to assess the
1271 two configurations and decide how they are to be merged:</p>
1274 <!-- BEGIN EXAMPLE CODE -->
1276 <code class="sh_declare">void</code><code class="sh_misc">*</code> merge_dir_conf<code class="sh_misc">(</code>apr_pool_t<code class="sh_misc">*</code> pool<code class="sh_misc">,</code> <code class="sh_declare">void</code><code class="sh_misc">*</code> BASE<code class="sh_misc">,</code> <code class="sh_declare">void</code><code class="sh_misc">*</code> ADD<code class="sh_misc">)</code> <code class="sh_misc">{</code>
1277 example_config<code class="sh_misc">*</code> base <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> BASE <code class="sh_misc">;</code>
1278 example_config<code class="sh_misc">*</code> add <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> ADD <code class="sh_misc">;</code>
1279 example_config<code class="sh_misc">*</code> conf <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> create_dir_conf<code class="sh_misc">(</code>pool<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Merged configuration</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1281 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">=</code> <code class="sh_misc">(</code> add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">=</code><code class="sh_misc">=</code> <code class="sh_reference">0</code> <code class="sh_misc">)</code> <code class="sh_misc">?</code> base<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">:</code> add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">;</code>
1282 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">=</code> add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">?</code> add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">:</code> base<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code><code class="sh_misc">;</code>
1283 <code class="sh_function">strcpy</code><code class="sh_misc">(</code>conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">,</code> <code class="sh_function">strlen</code><code class="sh_misc">(</code>add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">)</code> <code class="sh_misc">?</code> add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code> <code class="sh_misc">:</code> base<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1285 <code class="sh_declare">return</code> conf <code class="sh_misc">;</code>
1286 <code class="sh_misc">}</code>
1288 <!-- END EXAMPLE CODE -->
1293 <section id="context_example"><title>Trying out our new context aware configurations</title>
1295 Now, let's try putting it all together to create a new module that is
1296 context aware. First off, we'll create a configuration that lets us test
1297 how the module works:
1300 <Location "/a">
1301 SetHandler example-handler
1303 ExamplePath "/foo/bar"
1304 ExampleAction file allow
1307 <Location "/a/b">
1308 ExampleAction file deny
1312 <Location "/a/b/c">
1313 ExampleAction db deny
1314 ExamplePath "/foo/bar/baz"
1319 Then we'll assemble our module code. Note, that since we are now using our
1320 name tag as reference when fetching configurations in our handler, I have
1321 added some prototypes to keep the compiler happy:
1324 <!-- BEGIN EXAMPLE CODE -->
1326 <code class="sh_comment">/*$6</code>
1327 <code class="sh_comment"> +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++</code>
1328 <code class="sh_comment"> * mod_example_config.c</code>
1329 <code class="sh_comment"> +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++</code>
1330 <code class="sh_comment"> */</code>
1333 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character"><</code><code class="sh_reference">stdio.h</code><code class="sh_character">></code>
1334 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">apr_hash.h</code><code class="sh_character">"</code>
1335 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">ap_config.h</code><code class="sh_character">"</code>
1336 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">ap_provider.h</code><code class="sh_character">"</code>
1337 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">httpd.h</code><code class="sh_character">"</code>
1338 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_core.h</code><code class="sh_character">"</code>
1339 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_config.h</code><code class="sh_character">"</code>
1340 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_log.h</code><code class="sh_character">"</code>
1341 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_protocol.h</code><code class="sh_character">"</code>
1342 <code class="sh_function">#</code><code class="sh_function">include </code><code class="sh_character">"</code><code class="sh_reference">http_request.h</code><code class="sh_character">"</code>
1344 <code class="sh_comment">/*$1</code>
1345 <code class="sh_comment"> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code>
1346 <code class="sh_comment">    Configuration structure</code>
1347 <code class="sh_comment"> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code>
1348 <code class="sh_comment"> */</code>
1350 <code class="sh_declare">typedef</code> <code class="sh_declare">struct</code>
1351 <code class="sh_misc">{</code>
1352 <code class="sh_declare">char</code> context<code class="sh_misc">[</code><code class="sh_reference">256</code><code class="sh_misc">]</code><code class="sh_misc">;</code>
1353 <code class="sh_declare">char</code> path<code class="sh_misc">[</code><code class="sh_reference">256</code><code class="sh_misc">]</code><code class="sh_misc">;</code>
1354 <code class="sh_declare">int</code> typeOfAction<code class="sh_misc">;</code>
1355 <code class="sh_declare">int</code> enabled<code class="sh_misc">;</code>
1356 <code class="sh_misc">}</code> example_config<code class="sh_misc">;</code>
1358 <code class="sh_comment">/*$1</code>
1359 <code class="sh_comment"> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code>
1360 <code class="sh_comment">    Prototypes</code>
1361 <code class="sh_comment"> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code>
1362 <code class="sh_comment"> */</code>
1364 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code><code class="sh_misc">;</code>
1365 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>example_set_enabled<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg<code class="sh_misc">)</code><code class="sh_misc">;</code>
1366 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>example_set_path<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg<code class="sh_misc">)</code><code class="sh_misc">;</code>
1367 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>example_set_action<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg1<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg2<code class="sh_misc">)</code><code class="sh_misc">;</code>
1368 <code class="sh_declare">void</code> <code class="sh_misc">*</code>create_dir_conf<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">,</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>context<code class="sh_misc">)</code><code class="sh_misc">;</code>
1369 <code class="sh_declare">void</code> <code class="sh_misc">*</code>merge_dir_conf<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>BASE<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>ADD<code class="sh_misc">)</code><code class="sh_misc">;</code>
1370 <code class="sh_declare">static</code> <code class="sh_declare">void</code> register_hooks<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">)</code><code class="sh_misc">;</code>
1372 <code class="sh_comment">/*$1</code>
1373 <code class="sh_comment"> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code>
1374 <code class="sh_comment">    Configuration directives</code>
1375 <code class="sh_comment"> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code>
1376 <code class="sh_comment"> */</code>
1378 <code class="sh_declare">static</code> <code class="sh_declare">const</code> command_rec directives<code class="sh_misc">[</code><code class="sh_misc">]</code> <code class="sh_misc">=</code>
1379 <code class="sh_misc">{</code>
1380 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a><code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">exampleEnabled</code><code class="sh_character">"</code><code class="sh_misc">,</code> example_set_enabled<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> ACCESS_CONF<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Enable or disable mod_example</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">,</code>
1381 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a><code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">examplePath</code><code class="sh_character">"</code><code class="sh_misc">,</code> example_set_path<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> ACCESS_CONF<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">The path to whatever</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">,</code>
1382 <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#gafaec43534fcf200f37d9fecbf9247c21">AP_INIT_TAKE2</a><code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">exampleAction</code><code class="sh_character">"</code><code class="sh_misc">,</code> example_set_action<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> ACCESS_CONF<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Special action value!</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">,</code>
1383 <code class="sh_misc">{</code> <code class="sh_constant">NULL</code> <code class="sh_misc">}</code>
1384 <code class="sh_misc">}</code><code class="sh_misc">;</code>
1386 <code class="sh_comment">/*$1</code>
1387 <code class="sh_comment"> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code>
1388 <code class="sh_comment">    Our name tag</code>
1389 <code class="sh_comment"> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~</code>
1390 <code class="sh_comment"> */</code>
1392 module AP_MODULE_DECLARE_DATA example_module <code class="sh_misc">=</code>
1393 <code class="sh_misc">{</code>
1394 STANDARD20_MODULE_STUFF<code class="sh_misc">,</code>
1395 create_dir_conf<code class="sh_misc">,</code> <code class="sh_comment">/* Per-directory configuration handler */</code>
1396 merge_dir_conf<code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-directory configurations */</code>
1397 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Per-server configuration handler */</code>
1398 <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_comment">/* Merge handler for per-server configurations */</code>
1399 directives<code class="sh_misc">,</code> <code class="sh_comment">/* Any directives we may have for httpd */</code>
1400 register_hooks <code class="sh_comment">/* Our hook registering function */</code>
1401 <code class="sh_misc">}</code><code class="sh_misc">;</code>
1403 <code class="sh_comment">/*</code>
1404 <code class="sh_comment"> =======================================================================================================================</code>
1405 <code class="sh_comment">    Hook registration function</code>
1406 <code class="sh_comment"> =======================================================================================================================</code>
1407 <code class="sh_comment"> */</code>
1408 <code class="sh_declare">static</code> <code class="sh_declare">void</code> register_hooks<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">)</code>
1409 <code class="sh_misc">{</code>
1410 ap_hook_handler<code class="sh_misc">(</code>example_handler<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> APR_HOOK_LAST<code class="sh_misc">)</code><code class="sh_misc">;</code>
1411 <code class="sh_misc">}</code>
1413 <code class="sh_comment">/*</code>
1414 <code class="sh_comment"> =======================================================================================================================</code>
1415 <code class="sh_comment">    Our example web service handler</code>
1416 <code class="sh_comment"> =======================================================================================================================</code>
1417 <code class="sh_comment"> */</code>
1418 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
1419 <code class="sh_misc">{</code>
1420 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code> <code class="sh_misc">|</code><code class="sh_misc">|</code> <code class="sh_function">strcmp</code><code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">handler</code><code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">example-handler</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_declare">return</code><code class="sh_misc">(</code>DECLINED<code class="sh_misc">)</code><code class="sh_misc">;</code>
1422 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1423 example_config <code class="sh_misc">*</code>config <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> ap_get_module_config<code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">per_dir_config</code><code class="sh_misc">,</code> <code class="sh_misc">&</code>example_module<code class="sh_misc">)</code><code class="sh_misc">;</code>
1424 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1426 ap_set_content_type<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">text/plain</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1427 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Enabled: </code><code class="sh_reference">%u</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1428 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Path: </code><code class="sh_reference">%s</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1429 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">TypeOfAction: </code><code class="sh_reference">%x</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1430 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Context: </code><code class="sh_reference">%s</code><code class="sh_reference">\n</code><code class="sh_character">"</code><code class="sh_misc">,</code> config<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">context</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1431 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
1432 <code class="sh_misc">}</code>
1434 <code class="sh_comment">/*</code>
1435 <code class="sh_comment"> =======================================================================================================================</code>
1436 <code class="sh_comment">    Handler for the "exambleEnabled" directive</code>
1437 <code class="sh_comment"> =======================================================================================================================</code>
1438 <code class="sh_comment"> */</code>
1439 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>example_set_enabled<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg<code class="sh_misc">)</code>
1440 <code class="sh_misc">{</code>
1441 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1442 example_config <code class="sh_misc">*</code>conf <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> cfg<code class="sh_misc">;</code>
1443 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1445 <code class="sh_declare">if</code><code class="sh_misc">(</code>conf<code class="sh_misc">)</code>
1446 <code class="sh_misc">{</code>
1447 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>arg<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">on</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code>
1448 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">=</code> <code class="sh_reference">1</code><code class="sh_misc">;</code>
1449 <code class="sh_declare">else</code>
1450 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code>
1451 <code class="sh_misc">}</code>
1453 <code class="sh_declare">return</code> <code class="sh_constant">NULL</code><code class="sh_misc">;</code>
1454 <code class="sh_misc">}</code>
1456 <code class="sh_comment">/*</code>
1457 <code class="sh_comment"> =======================================================================================================================</code>
1458 <code class="sh_comment">    Handler for the "examplePath" directive</code>
1459 <code class="sh_comment"> =======================================================================================================================</code>
1460 <code class="sh_comment"> */</code>
1461 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>example_set_path<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg<code class="sh_misc">)</code>
1462 <code class="sh_misc">{</code>
1463 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1464 example_config <code class="sh_misc">*</code>conf <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> cfg<code class="sh_misc">;</code>
1465 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1467 <code class="sh_declare">if</code><code class="sh_misc">(</code>conf<code class="sh_misc">)</code>
1468 <code class="sh_misc">{</code>
1469 <code class="sh_function">strcpy</code><code class="sh_misc">(</code>conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">,</code> arg<code class="sh_misc">)</code><code class="sh_misc">;</code>
1470 <code class="sh_misc">}</code>
1472 <code class="sh_declare">return</code> <code class="sh_constant">NULL</code><code class="sh_misc">;</code>
1473 <code class="sh_misc">}</code>
1475 <code class="sh_comment">/*</code>
1476 <code class="sh_comment"> =======================================================================================================================</code>
1477 <code class="sh_comment">    Handler for the "exampleAction" directive ;</code>
1478 <code class="sh_comment">    Let's pretend this one takes one argument (file or db), and a second (deny or allow), ;</code>
1479 <code class="sh_comment">    and we store it in a bit-wise manner.</code>
1480 <code class="sh_comment"> =======================================================================================================================</code>
1481 <code class="sh_comment"> */</code>
1482 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>example_set_action<code class="sh_misc">(</code>cmd_parms <code class="sh_misc">*</code>cmd<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>cfg<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg1<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>arg2<code class="sh_misc">)</code>
1483 <code class="sh_misc">{</code>
1484 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1485 example_config <code class="sh_misc">*</code>conf <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> cfg<code class="sh_misc">;</code>
1486 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1488 <code class="sh_declare">if</code><code class="sh_misc">(</code>conf<code class="sh_misc">)</code>
1489 <code class="sh_misc">{</code>
1490 <code class="sh_misc">{</code>
1491 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>arg1<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">file</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code>
1492 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">=</code> <code class="sh_reference">0x01</code><code class="sh_misc">;</code>
1493 <code class="sh_declare">else</code>
1494 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">=</code> <code class="sh_reference">0x02</code><code class="sh_misc">;</code>
1495 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code>strcasecmp<code class="sh_misc">(</code>arg2<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">deny</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">)</code>
1496 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">+</code><code class="sh_misc">=</code> <code class="sh_reference">0x10</code><code class="sh_misc">;</code>
1497 <code class="sh_declare">else</code>
1498 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">+</code><code class="sh_misc">=</code> <code class="sh_reference">0x20</code><code class="sh_misc">;</code>
1499 <code class="sh_misc">}</code>
1500 <code class="sh_misc">}</code>
1502 <code class="sh_declare">return</code> <code class="sh_constant">NULL</code><code class="sh_misc">;</code>
1503 <code class="sh_misc">}</code>
1505 <code class="sh_comment">/*</code>
1506 <code class="sh_comment"> =======================================================================================================================</code>
1507 <code class="sh_comment">    Function for creating new configurations for per-directory contexts</code>
1508 <code class="sh_comment"> =======================================================================================================================</code>
1509 <code class="sh_comment"> */</code>
1510 <code class="sh_declare">void</code> <code class="sh_misc">*</code>create_dir_conf<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">,</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>context<code class="sh_misc">)</code>
1511 <code class="sh_misc">{</code>
1512 context <code class="sh_misc">=</code> context <code class="sh_misc">?</code> context <code class="sh_misc">:</code> <code class="sh_character">"</code><code class="sh_value">Newly created configuration</code><code class="sh_character">"</code><code class="sh_misc">;</code>
1514 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1515 example_config <code class="sh_misc">*</code>cfg <code class="sh_misc">=</code> apr_pcalloc<code class="sh_misc">(</code>pool<code class="sh_misc">,</code> <code class="sh_declare">sizeof</code><code class="sh_misc">(</code>example_config<code class="sh_misc">)</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1516 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1518 <code class="sh_declare">if</code><code class="sh_misc">(</code>cfg<code class="sh_misc">)</code>
1519 <code class="sh_misc">{</code>
1520 <code class="sh_misc">{</code>
1521 <code class="sh_comment">/* Set some default values */</code>
1522 <code class="sh_function">strcpy</code><code class="sh_misc">(</code>cfg<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">context</code><code class="sh_misc">,</code> context<code class="sh_misc">)</code><code class="sh_misc">;</code>
1523 cfg<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code>
1524 <code class="sh_function">memset</code><code class="sh_misc">(</code>cfg<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">,</code> <code class="sh_reference">0</code><code class="sh_misc">,</code> <code class="sh_reference">256</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1525 cfg<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">=</code> <code class="sh_reference">0x00</code><code class="sh_misc">;</code>
1526 <code class="sh_misc">}</code>
1527 <code class="sh_misc">}</code>
1529 <code class="sh_declare">return</code> cfg<code class="sh_misc">;</code>
1530 <code class="sh_misc">}</code>
1532 <code class="sh_comment">/*</code>
1533 <code class="sh_comment"> =======================================================================================================================</code>
1534 <code class="sh_comment">    Merging function for configurations</code>
1535 <code class="sh_comment"> =======================================================================================================================</code>
1536 <code class="sh_comment"> */</code>
1537 <code class="sh_declare">void</code> <code class="sh_misc">*</code>merge_dir_conf<code class="sh_misc">(</code>apr_pool_t <code class="sh_misc">*</code>pool<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>BASE<code class="sh_misc">,</code> <code class="sh_declare">void</code> <code class="sh_misc">*</code>ADD<code class="sh_misc">)</code>
1538 <code class="sh_misc">{</code>
1539 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1540 example_config <code class="sh_misc">*</code>base <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> BASE<code class="sh_misc">;</code>
1541 example_config <code class="sh_misc">*</code>add <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> ADD<code class="sh_misc">;</code>
1542 example_config <code class="sh_misc">*</code>conf <code class="sh_misc">=</code> <code class="sh_misc">(</code>example_config <code class="sh_misc">*</code><code class="sh_misc">)</code> create_dir_conf<code class="sh_misc">(</code>pool<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">Merged configuration</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1543 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1545 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">=</code> <code class="sh_misc">(</code>add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">=</code><code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">)</code> <code class="sh_misc">?</code> base<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code> <code class="sh_misc">:</code> add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">enabled</code><code class="sh_misc">;</code>
1546 conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">=</code> add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">?</code> add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code> <code class="sh_misc">:</code> base<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">typeOfAction</code><code class="sh_misc">;</code>
1547 <code class="sh_function">strcpy</code><code class="sh_misc">(</code>conf<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">,</code> <code class="sh_function">strlen</code><code class="sh_misc">(</code>add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">)</code> <code class="sh_misc">?</code> add<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code> <code class="sh_misc">:</code> base<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">path</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1548 <code class="sh_declare">return</code> conf<code class="sh_misc">;</code>
1549 <code class="sh_misc">}</code>
1551 <!-- END EXAMPLE CODE -->
1559 <section id="summary"><title>Summing up</title>
1561 We have now looked at how to create simple modules for Apache HTTP Server 2.4 and
1562 configuring them. What you do next is entirely up to you, but it is my
1563 hope that something valuable has come out of reading this documentation.
1564 If you have questions on how to further develop modules, you are welcome
1565 to join our <a href="http://httpd.apache.org/lists.html">mailing lists</a>
1566 or check out the rest of our documentation for further tips.
1570 <section id="snippets"><title>Some useful snippets of code</title>
1572 <section id="get_post"><title>Retrieve a variable from POST form data</title>
1575 <!-- BEGIN EXAMPLE CODE -->
1577 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>read_post_value<code class="sh_misc">(</code><code class="sh_declare">const</code> apr_array_header_t <code class="sh_misc">*</code>fields<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>key<code class="sh_misc">)</code>
1578 <code class="sh_misc">{</code>
1579 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1580 <code class="sh_declare">int</code> i<code class="sh_misc">;</code>
1581 apr_table_entry_t <code class="sh_misc">*</code>e <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code>
1582 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1583 e <code class="sh_misc">=</code> <code class="sh_misc">(</code>apr_table_entry_t <code class="sh_misc">*</code><code class="sh_misc">)</code> fields<code class="sh_misc">-</code><code class="sh_misc">></code>elts<code class="sh_misc">;</code>
1584 <code class="sh_declare">for</code><code class="sh_misc">(</code>i <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code> i <code class="sh_misc"><</code> fields<code class="sh_misc">-</code><code class="sh_misc">></code>nelts<code class="sh_misc">;</code> i<code class="sh_misc">+</code><code class="sh_misc">+</code><code class="sh_misc">)</code> <code class="sh_misc">{</code>
1585 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">!</code><code class="sh_function">strcmp</code><code class="sh_misc">(</code>e<code class="sh_misc">[</code>i<code class="sh_misc">]</code><code class="sh_misc">.</code>key<code class="sh_misc">,</code> key<code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_declare">return</code> e<code class="sh_misc">[</code>i<code class="sh_misc">]</code><code class="sh_misc">.</code>val<code class="sh_misc">;</code>
1586 <code class="sh_misc">}</code>
1587 <code class="sh_declare">return</code> <code class="sh_reference">0</code><code class="sh_misc">;</code>
1588 <code class="sh_misc">}</code>
1589 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_req <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
1590 <code class="sh_misc">{</code>
1591 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~*/</code>
1592 apr_array_header_t <code class="sh_misc">*</code>POST<code class="sh_misc">;</code>
1593 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>value<code class="sh_misc">;</code>
1594 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~*/</code>
1595 ap_parse_form_data<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_constant">NULL</code><code class="sh_misc">,</code> <code class="sh_misc">&</code>POST<code class="sh_misc">,</code> <code class="sh_misc">-</code><code class="sh_reference">1</code><code class="sh_misc">,</code> <code class="sh_reference">8192</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1597 value <code class="sh_misc">=</code> read_post_value<code class="sh_misc">(</code>POST<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">valueA</code><code class="sh_character">"</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1598 <code class="sh_declare">if</code> <code class="sh_misc">(</code><code class="sh_misc">!</code>value<code class="sh_misc">)</code> value <code class="sh_misc">=</code> <code class="sh_character">"</code><code class="sh_value">(undefined)</code><code class="sh_character">"</code><code class="sh_misc">;</code>
1599 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value">The value of valueA is: </code><code class="sh_reference">%s</code><code class="sh_character">"</code><code class="sh_misc">,</code> value<code class="sh_misc">)</code><code class="sh_misc">;</code>
1600 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
1601 <code class="sh_misc">}</code>
1603 <!-- END EXAMPLE CODE -->
1608 <section id="headers_out"><title>Printing out every HTTP header received</title>
1611 <!-- BEGIN EXAMPLE CODE -->
1613 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_req <code class="sh_misc">*</code>r<code class="sh_misc">)</code>
1614 <code class="sh_misc">{</code>
1615 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1616 <code class="sh_declare">const</code> apr_array_header_t <code class="sh_misc">*</code>fields<code class="sh_misc">;</code>
1617 <code class="sh_declare">int</code> i<code class="sh_misc">;</code>
1618 apr_table_entry_t <code class="sh_misc">*</code>e <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code>
1619 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1621 fields <code class="sh_misc">=</code> <a href="http://apr.apache.org/docs/apr/1.4/group__apr__tables.html#gaea3005541cce67481f48ab201b5c0cf3">apr_table_elts</a><code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code>headers_in<code class="sh_misc">)</code><code class="sh_misc">;</code>
1622 e <code class="sh_misc">=</code> <code class="sh_misc">(</code>apr_table_entry_t <code class="sh_misc">*</code><code class="sh_misc">)</code> fields<code class="sh_misc">-</code><code class="sh_misc">></code>elts<code class="sh_misc">;</code>
1623 <code class="sh_declare">for</code><code class="sh_misc">(</code>i <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code> i <code class="sh_misc"><</code> fields<code class="sh_misc">-</code><code class="sh_misc">></code>nelts<code class="sh_misc">;</code> i<code class="sh_misc">+</code><code class="sh_misc">+</code><code class="sh_misc">)</code> <code class="sh_misc">{</code>
1624 ap_rprintf<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_character">"</code><code class="sh_value"><b></code><code class="sh_reference">%s</code><code class="sh_value"></b>: </code><code class="sh_reference">%s</code><code class="sh_value"><br/></code><code class="sh_character">"</code><code class="sh_misc">,</code> e<code class="sh_misc">[</code>i<code class="sh_misc">]</code><code class="sh_misc">.</code>key<code class="sh_misc">,</code> e<code class="sh_misc">[</code>i<code class="sh_misc">]</code><code class="sh_misc">.</code>val<code class="sh_misc">)</code><code class="sh_misc">;</code>
1625 <code class="sh_misc">}</code>
1626 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
1627 <code class="sh_misc">}</code>
1629 <!-- END EXAMPLE CODE -->
1634 <section id="request_body"><title>Reading the request body into memory</title>
1637 <!-- BEGIN EXAMPLE CODE -->
1639 <code class="sh_declare">static</code> <code class="sh_declare">int</code> util_read<code class="sh_misc">(</code>request_rec <code class="sh_misc">*</code>r<code class="sh_misc">,</code> <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code><code class="sh_misc">*</code>rbuf<code class="sh_misc">,</code> apr_off_t <code class="sh_misc">*</code>size<code class="sh_misc">)</code>
1640 <code class="sh_misc">{</code>
1641 <code class="sh_comment">/*~~~~~~~~*/</code>
1642 <code class="sh_declare">int</code> rc <code class="sh_misc">=</code> OK<code class="sh_misc">;</code>
1643 <code class="sh_comment">/*~~~~~~~~*/</code>
1645 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">(</code>rc <code class="sh_misc">=</code> ap_setup_client_block<code class="sh_misc">(</code>r<code class="sh_misc">,</code> REQUEST_CHUNKED_ERROR<code class="sh_misc">)</code><code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_misc">{</code>
1646 <code class="sh_declare">return</code><code class="sh_misc">(</code>rc<code class="sh_misc">)</code><code class="sh_misc">;</code>
1647 <code class="sh_misc">}</code>
1649 <code class="sh_declare">if</code><code class="sh_misc">(</code>ap_should_client_block<code class="sh_misc">(</code>r<code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_misc">{</code>
1651 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1652 <code class="sh_declare">char</code> argsbuffer<code class="sh_misc">[</code>HUGE_STRING_LEN<code class="sh_misc">]</code><code class="sh_misc">;</code>
1653 apr_off_t rsize<code class="sh_misc">,</code> len_read<code class="sh_misc">,</code> rpos <code class="sh_misc">=</code> <code class="sh_reference">0</code><code class="sh_misc">;</code>
1654 apr_off_t length <code class="sh_misc">=</code> r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">remaining</code><code class="sh_misc">;</code>
1655 <code class="sh_comment">/*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/</code>
1657 <code class="sh_misc">*</code>rbuf <code class="sh_misc">=</code> <code class="sh_misc">(</code><code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code><code class="sh_misc">)</code> apr_pcalloc<code class="sh_misc">(</code>r<code class="sh_misc">-</code><code class="sh_misc">></code><code class="sh_subobject">pool</code><code class="sh_misc">,</code> <code class="sh_misc">(</code>apr_size_t<code class="sh_misc">)</code> <code class="sh_misc">(</code>length <code class="sh_misc">+</code> <code class="sh_reference">1</code><code class="sh_misc">)</code><code class="sh_misc">)</code><code class="sh_misc">;</code>
1658 <code class="sh_misc">*</code>size <code class="sh_misc">=</code> length<code class="sh_misc">;</code>
1659 <code class="sh_declare">while</code><code class="sh_misc">(</code><code class="sh_misc">(</code>len_read <code class="sh_misc">=</code> ap_get_client_block<code class="sh_misc">(</code>r<code class="sh_misc">,</code> argsbuffer<code class="sh_misc">,</code> <code class="sh_declare">sizeof</code><code class="sh_misc">(</code>argsbuffer<code class="sh_misc">)</code><code class="sh_misc">)</code><code class="sh_misc">)</code> <code class="sh_misc">></code> <code class="sh_reference">0</code><code class="sh_misc">)</code> <code class="sh_misc">{</code>
1660 <code class="sh_declare">if</code><code class="sh_misc">(</code><code class="sh_misc">(</code>rpos <code class="sh_misc">+</code> len_read<code class="sh_misc">)</code> <code class="sh_misc">></code> length<code class="sh_misc">)</code> <code class="sh_misc">{</code>
1661 rsize <code class="sh_misc">=</code> length <code class="sh_misc">-</code> rpos<code class="sh_misc">;</code>
1662 <code class="sh_misc">}</code>
1663 <code class="sh_declare">else</code> <code class="sh_misc">{</code>
1664 rsize <code class="sh_misc">=</code> len_read<code class="sh_misc">;</code>
1665 <code class="sh_misc">}</code>
1667 <code class="sh_function">memcpy</code><code class="sh_misc">(</code><code class="sh_misc">(</code><code class="sh_declare">char</code> <code class="sh_misc">*</code><code class="sh_misc">)</code> <code class="sh_misc">*</code>rbuf <code class="sh_misc">+</code> rpos<code class="sh_misc">,</code> argsbuffer<code class="sh_misc">,</code> <code class="sh_misc">(</code><code class="sh_function">size_t</code><code class="sh_misc">)</code> rsize<code class="sh_misc">)</code><code class="sh_misc">;</code>
1668 rpos <code class="sh_misc">+</code><code class="sh_misc">=</code> rsize<code class="sh_misc">;</code>
1669 <code class="sh_misc">}</code>
1670 <code class="sh_misc">}</code>
1671 <code class="sh_declare">return</code><code class="sh_misc">(</code>rc<code class="sh_misc">)</code><code class="sh_misc">;</code>
1672 <code class="sh_misc">}</code>
1674 <code class="sh_declare">static</code> <code class="sh_declare">int</code> example_handler<code class="sh_misc">(</code>request_req<code class="sh_misc">*</code> r<code class="sh_misc">)</code>
1675 <code class="sh_misc">{</code>
1676 <code class="sh_comment">/*~~~~~~~~~~~~~~~~*/</code>
1677 apr_off_t size<code class="sh_misc">;</code>
1678 <code class="sh_declare">const</code> <code class="sh_declare">char</code> <code class="sh_misc">*</code>buffer<code class="sh_misc">;</code>
1679 <code class="sh_comment">/*~~~~~~~~~~~~~~~~*/</code>
1681 <code class="sh_declare">if</code><code class="sh_misc">(</code>util_read<code class="sh_misc">(</code>r<code class="sh_misc">,</code> <code class="sh_misc">&</code>data<code class="sh_misc">,</code> <code class="sh_misc">&</code>size<code class="sh_misc">)</code> <code class="sh_misc">=</code><code class="sh_misc">=</code> OK<code class="sh_misc">)</code> <code class="sh_misc">{</code>
1682 ap_rprintf<code class="sh_misc">(</code><code class="sh_character">"</code><code class="sh_value">We read a request body that was </code><code class="sh_reference">%u</code><code class="sh_value"> bytes long</code><code class="sh_character">"</code><code class="sh_misc">,</code> size<code class="sh_misc">)</code><code class="sh_misc">;</code>
1683 <code class="sh_misc">}</code>
1684 <code class="sh_declare">return</code> OK<code class="sh_misc">;</code>
1685 <code class="sh_misc">}</code>
1687 <!-- END EXAMPLE CODE -->