Hooks are a way to connect the core of an application, such as UnrealIRCd, with modules that you want to add to it. They are like events in that they are triggered when certain things happen and allow other code to react to them. This can be very useful for module developers who want to add something that can’t be done in a standard way through a module.
In the UnrealIRCd codebase there are more than 100 hooks that can be called by a module. These hooks are the way that UnrealIRCd tells a module what function it should call when a specific event occurs. The first step to using these is to implement a function that will call the hook. This can be as simple as calling ap_hook_function(name, arguments) in your module file or more complicated.
Depending on how you implemented the hook, it will return different values (e.g., OK or DECLINED). If you don’t return a value when you call ap_hook_function, the call will be aborted.
If you do return a value, the call to ap_hook_function is executed until one of the registered functions is called that does not return either OK or DECLINED. This is a great way to test your code and make sure that it works as expected.
The first argument to ap_hook_function is the function that the module wants to be called when it is hooked. It can be a function in a module or a function exported from another module. It should be a function that returns either a standard type or an object.
There are two other arguments to ap_hook_function: a list of the names of other module files that should be called before and after this function. The order of these other modules should be based on their system weight, which is the number of function calls that they will get in the first execution of the hook.
It is also possible to use a dictionary that contains module and package names together with their corresponding collection mode strings. This can be used to control the order of the module and subpackage collections when multiple hooks are implemented for a particular module name.
A custom hook module can be added to any step in the Data Hub (ingestion, mapping, matching, merging, or mastering). The steps execute the custom module in its own environment, separated from Data Hub processes and other modules. If a process in the custom hook module conflicts with a process in a step’s core module or functionality, the core module or functionality overrides the conflicting process.
Logic hooks are a great way to extend the functionality of your module. They can be created in a module file with a logic hook action method. These methods can be created with a namespace or without one. The namespace can be used for the name of the hook action method or to define the names of the other methods in the same logic hook.