Tip of the day: If you still have users on plaintext port 6667, consider enabling Strict Transport Security to gently move users to SSL/TLS on port 6697.

Dev:Module API

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

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

The module API is currently documented at two places:

  • The wiki (such as this page): for a high level overview, with examples etc. to get you started
  • The Module API Doxygen docs: this contains all the details. All the struct definitions, most functions, etc.

The wiki is easy to read and is the best starting point for anyone new. The doxygen docs are more detailed, auto-generated from the source code, however they are not so easy to read since not everything is grouped well together yet, don't contain examples, etc. Both the wiki and the doxygen docs will always be "work in progress" and never finished.

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 more than 100(!) 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.

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. And even if there is no Hook available for your purpose, and you end up using overrides, it may be a good idea to request a new Hook at https://bugs.unrealircd.org/ for future versions of your module, to make things simpler for you but also for future module coders.

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

All the rest is documented in the doxygen pages. Such as send functions.