Modules

	Introduction
	CGI and SSI
	<pike> tag
	Pike script
	Modules

	Module types
	create()
	defvar()
	query()
	set()
	query_internal_location()
	check_variable()
	info()
	query_name()
	register_module()
	start()
	status()
	stop()
	find_internal()

	Parser modules
	Location modules
	Other module types
	Request information object
	Responses
	Library methods

Modules

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.

A module is a .pike file, with appropriate methods implementing the module API. It must contain contain a register_module() 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.

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

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

#include <module.h>

inherit "module";
inherit "roxenlib";

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

If you have created or installed a new module you will need to do a reload on the Add Module 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 Event Log or the debug log file.

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.

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 Reload Module button on the appropriate module in the configuration interface.

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.

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

defvar(): is used to register a configuration variable. It is usually called from the constructor (create() method).
query(): returns the value of a configuration variable.
set(): sets the value of a configuration variable.
query_internal_location(): gives the path to this modules own unique internal mount path.

API methods that the module can implements are:

checkvar(): 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.
info(): shall return a the description of the module, which then overrides the description given in the register_module module.
query_name(): shall return the name of the module, which then overrides the name given in the register_module module.
register_module(): returns information about the module, such as which type of module it is. register_module must be implemented in all modules.
start(): is called when the module is started, each time a configuration variable is changed as well as when the module is unloaded.
status(): returns a status message that will be displayed in the configuration interface.
stop(): is called when the module is disabled or reloaded as well as when the server is restarted or shut down.
find_internal(): is called when a file is requested from this modules internal mount path.

Errors
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.

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 Global Variables/Show the internals variable to No.