When you write a module, it can be thought as a subclass of
pa_module, if you're familiar with the object oriented programming concepts.
pa_module with its associated functions define some basic functionality that all the different modules include and refine. Let's see if there's any useful stuff in that basic functionality.
I'll walk you through the interface, see pulsecore/module.h for a more compact reference, and also for the complete definitions, as I won't repeat the field and function types here.
* Here you have a pointer to the core that the module is connected to.
* The name that was used when loading the module, i.e. the first argument to the "load-module" command.
* The whole argument string that was given with the "load-module" command. You could parse this yourself, but it's better to use the available helper functions. See [[Software/PulseAudio/Documentation/Developer/ModuleArgumentsAPI]].
* Every loaded module is assigned an index in the core that is used as an unique identifier. If you're ever going to need the index for any purpose, note that it is set only after
pa__init returns, so its value is undefined during the initialization.
* Handle through which the module's symbols are loaded. You can probably ignore this.
* Pointer to the
* Pointer to the
* This is initially NULL. This field belongs completely to you, you store a pointer to your custom data in this variable and you take care of freeing it too.
The next three fields are part of the
n_used), and you can ignore that too, if you don't want to support the functionality.
* Number of current "users". If you allow automatic unloading, value 0 is a precondition for automatic unloading to happen. Initialized to -1. Don't change this directly, use
* This is managed by the autoload system, don't modify. 0 means that automatic unloading is off and 1 means on.
* This gets updated whenever you change
n_used to 0 with
pa_module_set_used. Not initialized until the first zeroing of
* This is set to 1 when someone (might be you) wants to unload the module. Initialized to 0. Don't change this directly, use
Functions and macros
Loading and unloading functions are primarily for the daemon, except
pa_module_unload_request, but if you want to do some module management, feel free.
* Loads a module and returns a pointer to it. If module loading is disallowed in the core or loading otherwise fails, NULL is returned.
* Unloads one module instance.
* Same as
pa_module_unload, but uses an index for identification instead of a
* Unloads all modules.
* Unloads those modules that allow automatic unloading and have been unused at least for the time specified in
* Ask the core to unload a module instance. The actual unloading doesn't happen immediately. If you'd like to call this outside the mainloop thread, don't do that, but instead send a
PA_CORE_MESSAGE_UNLOAD_MODULE message to the core, see [[Software/PulseAudio/Documentation/Developer/CoreAPI]].
* Updates the number of module users.
* See Writing Modules#Optionalfunctions.
Automatic unloading is part of the autoload feature of PulseAudio. The modules that the user has told the system to load automatically are also unloaded automatically, if they support it.
If you want your module to support automatic unloading, keep the
n_used field updated by calling
pa_module_set_used in right places. What are the "right places", is fully up to you. Setting the user count to zero causes an unload if the counter isn't reset to some other value quickly.