docs.roxen.comBack to normal mode
DocsRoxenWebServer 4.5System Developer Manual PikeThe Roxen Module API
Copyright © 2012, Roxen Internet Software
Suggestions, comments & compliments
manuals@roxen.com

Callback Methods Common to All Modules

This page covers all callbacks that all module types may or are expected to implement in order to function as a proper roxen module. (Be sure to see the sections on common constants and API methods too.)
void create(Configuration|void conf)

In create(), you typically define your module's configurable variables (using the defvar() method) and set data about it using set_module_creator() and set_module_url(). The configuration object of the virtual server the module was initialized in is always passed, except for the one occasion when the file is compiled for the first time, when the `conf' argument passed is 0. Se also start().

string info(Configuration|void conf)

Implementing this function in your module is optional.

When present, it returns a string that describes the module. When absent, Roxen will use element module_doc. Unlike module_doc, though, this information is only shown when the module is present in a virtual server, so it won't show up when adding modules to a server.

void start(int occasion, Configuration conf)

Set up shop / perform some action when saving variables. (optional)

If occasion is 0, we're being called when starting up the module, to perform whatever actions necessary before we are able to service requests. This call is received when the virtual server the module belongs to gets initialized, just after the module is successfully added by the administrator or when reloading the module.

This method is also called with occasion set to 2 whenever the configuration is saved, as in when some module variable has changed and the administrator clicked "save" in the admin interface. This also happens just before calling stop() upon reloading the module.

void stop()

Close down shop. (optional)

Tidy up before the module is terminated. This method is called when the administrator drops the module, reloads the module or when the server is being shut down.

string status()

Tells some run-time status, statistics or similar to the curious administrator. Implementing this function is optional.

Returns a string of HTML that will be put in the admin interface on the module's settings page just below the documentation string.

mapping|int(-1..0)|Stdio.File find_internal(string file, RequestID id)

Internal magic location any module may use, similar to the find_file() method of all Location (Filesystem) Modules, but with a less civilized-looking URL (typically prefixed with the string "/internal/" prepended to your module identifier). This method is mostly used for background things where a URL doesn't show too much, such as when generating background images and the like. To get the internal mountpoint below which find_internal will handle requests, use query_internal_location().

May return

  • an http response

    (a normal response mapping)

  • a directory indicator

    (the integer value -1.)

  • an open file descriptor

    (an Stdio.File object)

  • file not found / request not handled

    signalled by the integer value 0.