Dev:Module API

From UnrealIRCd documentation wiki
Jump to: navigation, search

In Dev:Module you could read how a module is structured. In this article you can read about the various API's available to modules by which they can provide their functionality.

Plugging-in

UnrealIRCd provides two ways to "plug-in" or "override" existing functionality:

Hooks

By using the Dev:Hook API you can tell UnrealIRCd that your function needs to be called when a specific event happens, such as a user connecting, joining a channel, trying to change the topic, etc. UnrealIRCd has 80+ hooks available so in many cases if you want to be notified about some kind of event, this is the place to be.

Hooks are also relatively easy to use, as your function will receive exactly the information it needs (and expects).

Command overrides

Dev:Command Overrides are more complex, though very powerful. They allow your function to be called before or after the actual function for a command is called. For example: you can override "LINKS" and do some custom action and decide whether the original "LINKS" function may still be called or not. It also allows you to replace a command altogether, though this is uncommon / generally not recommended.

In general, though, you should look at Hooks first as they are less of a hassle / easier to use. Note that even if there's no Hook available for you and thus you resort to Command Override's it may still be useful to request a new hook on http://bugs.unrealircd.org/ for future versions of your module.

New functionality

Commands

The Dev:Command API allows you to add any new command.

User Modes

The Dev:User Mode API allows you to add new user modes.

Channel Modes

The Dev:Channel Mode API allows you to add new channel modes.

Extended Bans

The Dev:Extended Bans API allows you to introduce new extended ban types.

Callback functions

The Dev:Callback API is used to register callbacks which are invoked when a particular event occurs. This sounds a lot like Hooks but callbacks are slightly different: while hooks can be chained (the same event may be hooked by multiple modules), callbacks on the other hand only have 1 callback per callback type.

Currently callbacks are only used for cloaking. So if you want to provide some custom cloaking algorithm, read about the Dev:Callback API.

Configuration

Your module may want to have some options that the user can configure in the configuration file, like a something { } block or just a simple set { some-nice-variable 1234; };. This is done by using 3 Hooks, see Dev:Configuration API for all details.

Functions and helper API's

  • Dev:Send API - Used to leverage pre-written efficient implementations of various "send" logic in the core, e.g. send to a channel
  • Dev:Find API - Includes a number of methods to locate clients, servers, channels, and other objects.
  • Dev:Module Storage - Used to store metadata from a module with a particular user, channel, or other object - useful if you need to store more detailed information about a given object in the core than simply a single character (a mode) and are fine with it being local to the module only.