Hooks

March 26, 2020 Contributors

About Hooks

This part documents Momentum’s hooking API. The most useful hook points are defined within the core of Momentum and are called "core hooks". These hooks are found at Hooks in the core scope . You can use these predefined hook points from custom modules. To do this, you must create a module and that module must define a function that is registered with the desired hook point. If you are familiar with using Lua with Momentum, the registerModule function performs registration for a Lua script.

Hook points are registered in a singleton module’s conf_setup function or, for non-singleton modules, in the ext_init function. “Module API” describes these functions in detail. As an example, if you are creating a singleton module and wanted to perform certain actions on shutdown, from within conf_setup call register_core_control_shutdown_hook_first (or last) passing in a function pointer and a closure. The referenced function must be defined within your module code and the closure is typically a reference to your custom module (a generic_module_infrastructure). The closure that you supply when registering a function will be passed as the first parameter when the hook point arrives.

All hook points have "has", "register" and "call" functions that are generated by the EC_DECLARE_VOID_HOOK or EC_DECLARE_HOOK macro described at EC_DECLARE_HOOK. Hook "has" and "call" routines also provide a _txn version. The "call" routine returns a "transactional" module infrastructure that is guaranteed to be valid for the life of the hook invocation allowing you to write custom module code such as the following:

ec_config_header *global_conf = ec_config_fetch_globalconf();
generic_module_infrastructure *self = call_mymodule_get_module_closure_txn(global_conf);
register_mymodule_get_module_closure_hook_first(get_closure, self);
...

Using the _txn hook consumer guarantees that the value returned will remain valid until the configuration is released. This is exactly the same idiom that the hooking infrastructure itself uses when calling hooks and that’s how it guarantees that the configuration and module infrastructure is valid for the life of the hook invocation.

To use an existing built-in Momentum hook point you must invoke the "register" function associated with it and you must know the following:

  • The hook name.

  • When the hook occurs.

  • Whether the hook has a return value.

  • Which thread the hook can be invoked from.

  • Any special circumstances related to that hook.

The hook API is discussed in detail at “Hooking API”. If you wish to create hooks for a custom module see EC_DECLARE_HOOK.

Note

All hooks related to SMPP and MM7 are documented in Mobile Momentum Developer Guide.

Some of the hooks documented here have been created manually and others have been generated automatically from source code. Automatic documentation is noted as such.