grim/testing

Update the C plugin tutorial to use the gplugin macros

2021-06-07, Gary Kramlich
60f4b2a6d66a
Parents f0a12e3048a4
Children 2405744f8193
Update the C plugin tutorial to use the gplugin macros

Testing Done:
Built and reviewed the docs.

Reviewed at https://reviews.imfreedom.org/r/686/
1 files changed, 37 insertions(+), 25 deletions(-)
  • +37 -25
    doc/reference/libpurple/tut_c_plugins.xml
    • --- a/doc/reference/libpurple/tut_c_plugins.xml Sun May 30 20:34:04 2021 -0500
    +++ b/doc/reference/libpurple/tut_c_plugins.xml Mon Jun 07 22:15:46 2021 -0500
    @@ -36,8 +36,8 @@
    <programlisting>
    #include &lt;purple.h&gt;
    -static PurplePluginInfo *
    -plugin_query(GError **error)
    +static GPluginPluginInfo *
    +hello_world_query(GError **error)
    {
    const gchar * const authors[] = {
    "Author Name &lt;e@mail&gt;",
    @@ -60,7 +60,7 @@
    }
    static gboolean
    -plugin_load(PurplePlugin *plugin, GError **error)
    +hello_world_load(GPluginPlugin *plugin, GError **error)
    {
    purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!",
    "This is the Hello World! plugin :)",
    @@ -70,12 +70,12 @@
    }
    static gboolean
    -plugin_unload(PurplePlugin *plugin, GError **error)
    +hello_world_unload(GPluginPlugin *plugin, GError **error)
    {
    return TRUE;
    }
    -PURPLE_PLUGIN_INIT(hello_world, plugin_query, plugin_load, plugin_unload);
    +GPLUGIN_NATIVE_PLUGIN_DECLARE(hello_world)
    </programlisting>
    </example>
    </para>
    @@ -86,40 +86,52 @@
    </para>
    <para>
    - <literal>plugin_query</literal>, <literal>plugin_load</literal> and
    - <literal>plugin_unload</literal> must be implemented in every plugin. Each of
    - these functions can return an error on failure by using
    - <function>g_set_error()</function> on the <literal>error</literal> argument.
    + <literal>hello_world_query</literal>, <literal>hello_world_load</literal> and
    + <literal>hello_world_unload</literal> are functions that must be implemented
    + in every plugin. These functions are named according to the value passed
    + to <literal>GPLUGIN_NATIVE_PLUGIN_DECLARE</literal> which is described below.
    </para>
    <para>
    - <literal>plugin_query</literal> is called when the plugin is probed by the
    - plugin system, and returns various information about the plugin in form of a
    - newly created <literal>PurplePluginInfo</literal> instance. For a list of all
    - available properties, see
    + <literal>hello_world_query</literal> is called when the plugin is queried by
    + the plugin system, and returns various information about the plugin in form
    + of a newly created instance of <literal>GPluginPluginInfo</literal> or a
    + subclass. For a list of all available properties, see
    <link linkend="purple-plugin-info-new"><function>purple_plugin_info_new()</function></link>.
    </para>
    <para>
    - <literal>plugin_load</literal> is called when the plugin is loaded so that you
    - can initialize any variables, register dynamic types, and so on. Plugins may
    - also want to add their preferences to the pref tree--more about that later.
    - In this plugin we'll just use it to display a message.
    + If anything should go wrong during the query you can return an error by using
    + <function>g_set_error()</function> on the <literal>error</literal> argument.
    </para>
    <para>
    - <literal>plugin_unload</literal> is called when the plugin is unloaded, and we
    - can use it to wrap up everything, and free our variables.
    + <literal>hello_world_load</literal> is called when the plugin is loaded. That
    + is the user has enabled the plugin or libpurple is loading a plugin that was
    + previously loaded. You can initialize any variables, register dynamic types,
    + and so on in this function. Plugins may also want to add their preferences
    + to the pref tree--more about that later. In this plugin we'll just use it to
    + display a message. Just like
    + <literal>hello_world_query</literal> if there are any errors that arise, you
    + can call <function>g_set_error()</function> on the <literal>error</literal>
    + agument and return <literal>FALSE</literal>.
    + </para>
    +
    + <para>
    + <literal>hello_world_unload</literal> is called when the plugin is unloaded.
    + That is, when the user has manually unloaded the plugin or the program is
    + shutting down. We can use it to wrap up everything, and free our variables.
    + Again, if there are any errors, you can call
    + <function>g_set_error()</function> on the <literal>error</literal> argument
    + and return <literal>FALSE</literal>.
    </para>
    <para>
    Finally we have
    - <link linkend="PURPLE-PLUGIN-INIT:CAPS"><function>PURPLE_PLUGIN_INIT()</function></link>.
    - It is a macro that every plugin MUST have. It tells libpurple some basic
    - things about your plugin, like what name to use if the plugin is compiled
    - statically, along with the <literal>plugin_query</literal>,
    - <literal>plugin_load</literal>, and <literal>plugin_unload</literal>
    - functions.
    + <link linkend="GPLUGIN_NATIVE_PLUGIN_DECLARE:CAPS"><function>GPLUGIN_NATIVE_PLUGIN_DECLARE()</function></link>.
    + It is a helper macro that makes creating plugins easier. It has a single
    + argument which is the prefix used for the <literal>_query</literal>,
    + <literal>_load</literal>, and <literal>_unload</literal> functions.
    </para>
    </sect2>
    </chapter>