diff options
author | Gary Kramlich <grim@reaperworld.com> | 2021-06-07 22:15:46 -0500 |
---|---|---|
committer | Gary Kramlich <grim@reaperworld.com> | 2021-06-07 22:15:46 -0500 |
commit | ad2a64cedcbcf7918a7536432d6c9ccdec3cc7b0 (patch) | |
tree | a5d9c3abb87e7c38085fb264804ff31f5e39d588 /doc | |
parent | 33eb700b2fa2d5fc215da2ebacd7f2929b83399f (diff) | |
download | pidgin-ad2a64cedcbcf7918a7536432d6c9ccdec3cc7b0.tar.gz |
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/
Diffstat (limited to 'doc')
-rw-r--r-- | doc/reference/libpurple/tut_c_plugins.xml | 62 |
1 files changed, 37 insertions, 25 deletions
diff --git a/doc/reference/libpurple/tut_c_plugins.xml b/doc/reference/libpurple/tut_c_plugins.xml index bac09aa47f..7756f18536 100644 --- a/doc/reference/libpurple/tut_c_plugins.xml +++ b/doc/reference/libpurple/tut_c_plugins.xml @@ -36,8 +36,8 @@ <programlisting> #include <purple.h> -static PurplePluginInfo * -plugin_query(GError **error) +static GPluginPluginInfo * +hello_world_query(GError **error) { const gchar * const authors[] = { "Author Name <e@mail>", @@ -60,7 +60,7 @@ plugin_query(GError **error) } 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 @@ plugin_load(PurplePlugin *plugin, GError **error) } 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 @@ PURPLE_PLUGIN_INIT(hello_world, plugin_query, plugin_load, plugin_unload); </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>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>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_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> |