====== Developing Prosody modules ====== Creating modules for Prosody is a piece of cake. If you are new to Lua then take a look at the online [[http://lua.org/pil/|Programming in Lua]] book for an introduction to the language, and [[http://lua.org/manual/5.1/|the Lua manual]] for later reference. If you are already familiar with programming then Lua will hardly need learning at all. A module consists of a single Lua script, which will get loaded by the server whenever necessary. When loaded into the server, there will be available a global object 'module' through which you can interact with the module manager and the rest of the server. The methods of the module API object are described on this page. ===== Reference ===== ==== Logging ==== === module:log(level, message, ...) === Logs the specified message at the specified level. ''message'' may contain format specifiers, like printf and string.format. ==== Module specifics ==== === module:get_host() === Returns the host that the current module is loaded for, or "*" if it is a global module (not associated with a particular host). === module:set_global() === Sets the current module as a 'global' module, that is one which is not associated with a particular host and may only be loaded once per running server. ==== Events ==== === module:hook(event, callback, priority) === Calls the specified callback when the specified ''event'' occurs. The optional ''priority'' allows order to be given in which callbacks are called. Higher priority callbacks are called before lower priority callbacks. [[doc:developers:events|Here's a list of events.]] === module:fire_event(event, data) === Fires the given event on the current host, with the supplied data being passed to all registered event handlers. If any handler returns a value other than nil then the firing of the event is stopped (i.e. no more handlers are called) and that value is returned. Otherwise this function returns nil. ==== Configuration options ==== === module:get_option(option_name, default_value) === Retrieve the specified option from the config. Automatically looks for the option for the module's host before checking global options. If no value is found then default_value is returned (nil if missing). There are a number of variants of this function for getting specific types. If the user supplied a type different to the expected then it is automatically converted, or an error logged and default_value returned as above. === module:get_option_string(option_name, default_value) === Returns the option as a string. === module:get_option_number(option_name, default_value) === Returns the option as a number. === module:get_option_boolean(option_name, default_value) === Returns the option as a boolean (true or false). === module:get_option_array(option_name, default_value) === Returns the option as an array. If the user has set a single value in the config then the array contains that as a single element. See [[:doc:developers:util:array|util.array documentation]] for working with Prosody arrays. === module:get_option_set(option_name, default_value) === Returns the option as a set. Like array, but the values provided by the user are collected into a set (e.g. duplicates removed). See [[:doc:developers:util:set|util.set documentation]] for working with Prosody sets. ==== XMPP service discovery (disco) ==== === module:add_feature(feature) === Add the given disco feature to the current host. This is to signal to a client that Prosody supports a certain XMPP extension for example. These features are usually given in the "Discovering support" section of the relavent XEPs. A full list of all official features in specs published by the XSF can be found at http://xmpp.org/registrar/disco-features.html If making your own extension, use a URL of a site that you own. e.g. for Prosody we use URLs of the form http://prosody.im/protocol/* . === module:add_identity(category, type, name) === Add the given identity to the current host. This is similar to features, but rather than telling clients what the host //supports// it says what the host //is//. XEPs inform you when a host needs to have a certain identity. A full list of all official identities published by the XSF can be found at http://xmpp.org/registrar/disco-categories.html ==== Items ==== Prosody has a registry of "items" for each host. This is a generic API for modules to dynamically add/remove things such as authentication and storage providers. === module:add_item(type, item) === Add an item of the given type. Items are automatically removed on module unload. === module:remove_item(type, item) === Remove an item of the given type. === module:get_host_items(type) === Returns an array of items of a given type.