<html>
<head>
<title>Modules</title>
<meta name="keywords" content="">
</head>

<body bgcolor=#113377 text=#000000 vlink=#551a8b alink=#00c0ff link=#0000ee>




















































<table width=100% border=0>
<tr>
  <td valign=top>
  <table width=100% cellpadding=5 cellspacing=0 border=0>
    <tr><td bgcolor="#ffffff" align=center>
       <img height=40 border=0 src="../../img/logga.gif" alt="" width=102>
    </td></tr>
    <tr><td valign=top>
      <img src=internal-roxen-unit width=1 height=3 alt="">
    </td></tr>
    <tr valign=top>
      <td bgcolor="#ffffff">




        <table cellpadding=0 cellspacing=0 border=0>
          
       <!--a1  Introduction manual.tmpl-->
    
            <tr><td><a href="../introduction/index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="../introduction/index.html">Introduction</a></td>
	    </tr>
    
          
       <!--a1  CGI and SSI manual.tmpl-->
    
            <tr><td><a href="../cgi/index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="../cgi/index.html">CGI and SSI</a></td>
	    </tr>
    
          
       <!--a1  &lt;pike&gt; tag manual.tmpl-->
    
            <tr><td><a href="../pike-tag/index.html"><img src="../../img/chapter.gif" border=0></a>&nbsp;</td>
	      <td><a href="../pike-tag/index.html">&lt;pike&gt; tag</a></td>
	    </tr>
    
          
       <!--a1  Pike script manual.tmpl-->
    
            <tr><td><a href="../pike-scripts/index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="../pike-scripts/index.html">Pike script</a></td>
	    </tr>
    
          
       <!--a1  Modules manual.tmpl-->
    
            <tr><td><a href="index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="index.html"><b>Modules</b></a></td>
	    </tr>
    
          
	</table>
	
        <table cellpadding=0 cellspacing=0 border=0>
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="types.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="types.html">Module types</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="create.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="create.html">create()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="defvar.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="defvar.html">defvar()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="query.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="query.html">query()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="set.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="set.html">set()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="query_internal_location.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="query_internal_location.html">query_internal_location()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="check_variable.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="check_variable.html">check_variable()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="info.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="info.html">info()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="query_name.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="query_name.html">query_name()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="register_module.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="register_module.html">register_module()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="start.html"><img src="../../img/page.gif" border=0></a>&nbsp;</td>
	      <td><a href="start.html">start()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="status.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="status.html">status()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="stop.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="stop.html">stop()</a></td>
	    </tr>
    
	  
      <!--b1  -->
    
	    <tr><td>&nbsp;&nbsp;<a href="find_internal.html"><img border=0 src="../../img/page.gif"></a>&nbsp;</td>
	      <td><a href="find_internal.html">find_internal()</a></td>
	    </tr>
    
	  
        </table>

        <table cellpadding=0 cellspacing=0 border=0>
          
      <!--c1  -->
    
            <tr><td><a href="../tag-modules/index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="../tag-modules/index.html">Parser modules</a></td>
	    </tr>
    
          
      <!--c1  -->
    
            <tr><td><a href="../location-modules/index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="../location-modules/index.html">Location modules</a></td>
	    </tr>
    
          
      <!--c1  -->
    
            <tr><td><a href="../other-modules/index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="../other-modules/index.html">Other module types</a></td>
	    </tr>
    
          
      <!--c1  -->
    
            <tr><td><a href="../id/index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="../id/index.html">Request information object</a></td>
	    </tr>
    
          
      <!--c1  -->
    
            <tr><td><a href="../responses/index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="../responses/index.html">Responses</a></td>
	    </tr>
    
          
      <!--c1  -->
    
            <tr><td><a href="../library-methods/index.html"><img border=0 src="../../img/chapter.gif"></a>&nbsp;</td>
	      <td><a href="../library-methods/index.html">Library methods</a></td>
	    </tr>
    
          
	</table>

      </td>
    </tr>
    <tr><td height=100%>&nbsp;</td></tr>
  </table>
  </td>
  <td>
    <img src=internal-roxen-unit width=3 height=1 alt="">
  </td>

  <td valign=top>
    <table cellspacing=0 cellpadding=5 width=100% height=100% border=0>
    <tr>
      <td bgcolor="#ffffff">
       <b><font size=+2>Modules</font></b>

	<p>The functionality of the Roxen Challenger web server is implemented as
modules. There are no difference between a module delivered with Roxen
Challenger and a module made by a third-party. All parts of the Roxen
API are available to any module.

<p>A module is a <tt>.pike</tt> file, with appropriate methods
implementing the module API. It must contain contain a
<tt>register_module()</tt> method, that returns information
about the module such as what type of module it is. The module type
determines all further interactions between Challenger and the module.

<p>Almost all modules contain configuration variables, that can be
changed in Challenger's configuration interface. These variables are
defined by calling the <tt>defvar()</tt> method, usually from
the constructor (the <tt>create()</tt> method).

<p>In order to get the necessary prototypes and methods for the Roxen
API, modules needs to include <tt>module.h</tt> and inherit
<tt>module</tt>. Most modules also inherit <tt>roxenlib</tt> to get
access to the library methods. Thus most modules begin with:

<pre>
#include &lt;module.h&gt;

inherit "module";
inherit "roxenlib";
</pre>



<p><a name="Loading and reloading">
<b><font size=+2>Loading and reloading</font></b></a>
<br>

Modules are loaded by adding them to a virtual server, with the
<i>Add Module</i> button in the configuration interface. Once a
module has been enabled and configured it will by loaded automatically
when the server restarts.

<p>If you have created or installed a new module you will need to do a
reload on the <i>Add Module</i> page, in order to get it to show
up. If there are any compilation errors the module will not show up,
and the errors will be reported in the <i>Event Log</i> or the
debug log file.

<p>Modules are identified by their file name only. Thus you may not
call your module the same as an existing module, even if it is placed
in a different directory.

<p>If you have changed the a module and want to try the new version
you need to reload it. This is done by pressing the <i>Reload
Module</i> button on the appropriate module in the configuration
interface. 

<p>In case there were any compilation errors they will show up
directly when you try to reload the module. The reload will fail and
the old version of the module will keep running while you fix the
errors in the new version.



<p><a name="API methods">
<b><font size=+2>API methods</font></b></a>
<br>

The API methods that are available to be called from the module are:

<dl>
<dt><b>defvar()</b><dd>



is used to register a configuration variable. It is usually called
from the constructor (<tt>create()</tt> method).

<p>
<dt><b>query()</b><dd>



returns the value of a configuration variable.

<p>
<dt><b>set()</b><dd>



sets the value of a configuration variable.

<p>
<dt><b>query_internal_location()</b><dd>



gives the path to this modules own unique internal mount path.
</dl>

API methods that the module can implements are:

<dl>

<dt><b>checkvar()</b><dd>



checks the intended value of a configuration variable when the user
changes it. If the value is not valid an error message can be returned.

<p>
<dt><b>info()</b><dd>



shall return a the description of the module, which then overrides the
description given in the <i>register_module</i> module.

<p>
<dt><b>query_name()</b><dd>



shall return the name of the module, which then overrides the name
given in the <i>register_module</i> module.

<p>
<dt><b>register_module()</b><dd>



returns information about the module, such as which type of module it
is. <i>register_module</i> must be implemented in all
modules.

<p>
<dt><b>start()</b><dd>



is called when the module is started, each time a configuration
variable is changed as well as when the module is unloaded.

<p>
<dt><b>status()</b><dd>



returns a status message that will be displayed in the configuration
interface.

<p>
<dt><b>stop()</b><dd>



is called when the module is disabled or reloaded as well as when the
server is restarted or shut down.

<p>
<dt><b>find_internal()</b><dd>



is called when a file is requested from this modules internal mount
path.
</dl>



<p><a name="Errors">
<b><font size=+2>Errors</font></b></a>
<br>

Since Pike is an interpreted language a programming error cannot crash
the program. Instead the Pike interpreter catches and handles
errors. Challenger takes advantage of this by providing error messages
with a full Pike backtrace, making it easy to pinpoint the
problem. The error will be reported sent to the browser as well as
being written in the debug and event log.

<p>That error messages, complete with a Pike backtrace, are written to
the browser is great for programmers debugging their applications. It
might however scare rather than help the average user of a web
site. Therefore it is recommended to turn of such error messages on
production servers, by setting the <i>Global Variables/Show the internals</i>
variable to <i>No</i>. 


      </td>
    </tr>
    </table>
  </td>
</tr>
<tr>
</table>
</body>
</html>
