Plugins are executable code that expand the functionality of the server.
Examples of plugins include the user authentication plugin (see The User Authentication Plugins) and the server status plugin, which you can use to help implement customization of existing functionality, such as High Availability (see How to Implement Manager HA with the Generic Plugin).
Unlike UDFs, plugins are called by the server rather than called from yourCCL statements.
Every plugin must have at least three functions:
An "initialize" function.
An "execute" function.
A "shutdown" function.
The initialize function performs any initial setup that is required. This may involve allocating memory or looking up information outside the server. If no setup is required you must still have an initialize function; however, you may leave it empty.
The execute function is called each time there is a reason for the plugin to do something. For example, in a user authentication plugin, the function would be called each time the server needs to verify that a user's ID and password are valid. In a Manager HA plugin, the execute function might be called each time a manager fails and needs to be replaced with a standby manager.
The shutdown function allows the plugin to do any necessary cleanup, such as deallocating memory. If no cleanup code is required, you must still have a shutdown function even if it is empty.
To call these functions, the server must know the names of the functions and the name of the linkable library file (typically a .dll or .so file) that contains the functions. The name of this file, as well as the names of the initialize(), execute(), and shutdown() functions, must be specified in the server configuration file (c8-server.conf). An example of part of a configuration file is shown below.
<section name="ManagerFailoverDDNSPlugin">
<preference name="LibraryName"
value="c8_server_plugins_lib"/>
<preference name="InitializeFunction"
value="c8_command_line_plugin_initialize"/>
<preference name="ExecuteFunction"
value="c8_command_line_plugin_execute"/>
<preference name="ShutdownFunction"
value="c8_command_line_plugin_shutdown"/>
...
</section>
The plugin may be very small (just big enough to run an external program and pass it appropriate parameters), or the plugin may be large if that is necessary to handle the work required.
For some plugins, the timing of the call to the plugin's execute() function may be determined by an event in a stream. For example, when an HA manager dies, an event is published to a status stream. The server monitors this stream and calls an HA-related plugin when the stream contains a message indicating that the HA manager died. For other plugins, such as the user authentication plugin, the activity (such as a user trying to access a restricted resource) may not show up as an event in a stream.
If the plugin is invoked based upon the arrival of a message in a status stream, then you will also need to specify which message should cause the server to invoke the plugin. An example of a c8-server.conf file section specifying the message is below:
<section name="ManagerFailoverDDNSPlugin">
...
<preference name="MessageGroup"
value="ManagerInfo"/>
<preference name="MessageName"
value="ManagerHAPromotedToPrimary"/>
...
</section>
For a more complete example and lists of valid MessageGroups and MessageNames, see Message-Driven Plugins shows