Mercurial > pidgin3 / file comparison

comparison: doc/C-HOWTO.dox

doc/C-HOWTO.dox

branch
soc.2013.gobjectification.plugins
changeset 36796
ebb632962d4e
parent 36793
c220f2cdca01
child 36801
70047858a8fd
equal deleted inserted replaced
36795:ceb47557895a 36796:ebb632962d4e
25 25
26 #include <glib.h> 26 #include <glib.h>
27 27
28 #include "notify.h" 28 #include "notify.h"
29 #include "plugins.h" 29 #include "plugins.h"
30 #include "version.h" 30
31 static PurplePluginInfo *
32 plugin_query(GError **error)
33 {
34 const gchar * const authors[] = {
35 "Author Name <e@mail>",
36 NULL
37 };
38
39 /* For specific notes on the meanings of each of these members, consult the
40 C Plugin Howto on the website. */
41 return purple_plugin_info_new (
42 "name", "Hello World!",
43 "version", VERSION,
44 "category", "Example",
45 "summary", "Hello World Plugin",
46 "description", "Hello World Plugin",
47 "authors", authors,
48 "website", "http://helloworld.tld",
49 "abi-version", PURPLE_ABI_VERSION,
50 NULL
51 );
52 }
31 53
32 static gboolean 54 static gboolean
33 plugin_load(PurplePlugin *plugin) { 55 plugin_load(PurplePlugin *plugin, GError **error)
56 {
34 purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!", 57 purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!",
35 "This is the Hello World! plugin :)", 58 "This is the Hello World! plugin :)",
36 NULL, NULL, NULL, NULL); 59 NULL, NULL, NULL, NULL);
37 60
38 return TRUE; 61 return TRUE;
39 } 62 }
40 63
41 static PurplePluginInfo info = { 64 static gboolean
42 PURPLE_PLUGIN_MAGIC, 65 plugin_unload(PurplePlugin *plugin, GError **error)
43 PURPLE_MAJOR_VERSION,
44 PURPLE_MINOR_VERSION,
45 PURPLE_PLUGIN_STANDARD,
46 NULL,
47 0,
48 NULL,
49 PURPLE_PRIORITY_DEFAULT,
50
51 "core-hello_world",
52 "Hello World!",
53 VERSION,
54
55 "Hello World Plugin",
56 "Hello World Plugin",
57 NULL,
58 "http://helloworld.tld",
59
60 plugin_load,
61 NULL,
62 NULL,
63
64 NULL,
65 NULL,
66 NULL,
67 NULL,
68 NULL,
69 NULL,
70 NULL,
71 NULL
72 };
73
74 static void
75 init_plugin(PurplePlugin *plugin)
76 { 66 {
67 return TRUE;
77 } 68 }
78 69
79 PURPLE_INIT_PLUGIN(hello_world, init_plugin, info); 70 PURPLE_PLUGIN_INIT(hello_world, plugin_query, plugin_load, plugin_unload);
80 71
81 @endcode 72 @endcode
82 73
83 Okay, so what does all this mean? We start off by defining @c PURPLE_PLUGINS 74 Okay, so what does all this mean? We start off by defining @c PURPLE_PLUGINS
84 like described before. Next we include glib.h, mainly for gboolean and the 75 like described before. Next we include glib.h, mainly for gboolean and the
85 glib wrappers of the standard C types. 76 glib wrappers of the standard C types.
86 77
87 Next, we include plugins.h which has all the plugin specific stuff that we 78 Next, we include plugins.h which has all the plugin specific stuff that we
88 need. For example: @c PurplePlugin, @c PurplePluginInfo, 79 need. For example: @c #PurplePlugin, @c #PurplePluginInfo,
89 @c PURPLE_PLUGIN_MAGIC, and @c PURPLE_INIT_PLUGIN(). 80 and @c PURPLE_PLUGIN_INIT().
90 81
91 Our last include is version.h which defines @c PURPLE_MAJOR_VERSION, and 82 @c plugin_query, @c plugin_load and @c plugin_unload must be implemented in
92 @c PURPLE_MINOR_VERSION. There is not much you need to know about these, 83 every plugin. Each of these functions can return an error on failure by using
93 except that they are required and will stop your plugin from crashing Pidgin 84 @c g_set_error on the @c error argument.
94 when something has changed that your plugin does not know about yet.
95 85
96 @c plugin_load is not required. It is called when the plugin is loaded so 86 @c plugin_query is called when the plugin is probed by the plugin system, and
97 that you can initialize any variables and so on. In this plugin we'll just 87 returns various information about the plugin in form of a newly created
98 use it to display a message. 88 PurplePluginInfo instance. See plugins.h for a list of available properties
89 you can use in @c purple_plugin_info_new .
99 90
100 Next we have the @c PurplePluginInfo structure. Every plugin MUST have one of 91 @c plugin_load is called when the plugin is loaded so that you can initialize
101 these. Below is a code snipet of the same struct used in @c hello_world with 92 any variables, register dynamic types, and so on. Plugins may also want to
102 comments describing what each is. 93 add their preferences to the pref tree--more about that later. In this plugin
94 we'll just use it to display a message.
103 95
104 @code 96 @c plugin_unload is called when the plugin is unloaded, and we can use it to
105 static PurplePluginInfo info = { 97 wrap up everything, and free our variables.
106 PURPLE_PLUGIN_MAGIC, /* Plugin magic, this must always be
107 PURPLE_PLUGIN_MAGIC.
108 */
109 PURPLE_MAJOR_VERSION, /* This is also defined in libpurple. It helps
110 libpurple's plugin system determine which
111 version of libpurple this plugin was
112 compiled for, and whether loading it will
113 cause problems.
114 */
115 PURPLE_MINOR_VERSION, /* See previous */
116 PURPLE_PLUGIN_STANDARD, /* PurplePluginType: There are 4 different
117 values for this field. The first is
118 PURPLE_PLUGIN_UNKNOWN, which should not be
119 used. The second is PURPLE_PLUGIN_STANDARD;
120 this is the value most plugins will use.
121 Next, we have PURPLE_PLUGIN_LOADER; this is
122 the type you want to load if your plugin
123 is going to make it possible to load non-
124 native plugins. For example, the Perl and
125 Tcl loader plugins are of this type.
126 Last, we have PURPLE_PLUGIN_PROTOCOL. If
127 your plugin is going to allow the user to
128 connect to another network, this is the
129 type you'd want to use.
130 */
131 NULL, /* This field is the UI requirement. If you're
132 writing a core plugin, this must be NULL
133 and the plugin must not contain any UI
134 code. If you're writing a Pidgin plugin,
135 you need to use PIDGIN_PLUGIN_TYPE. If you
136 are writing a Finch plugin, you would use
137 FINCH_PLUGIN_TYPE.
138 */
139 0, /* This field is for plugin flags. Currently,
140 the only flag available to plugins is
141 invisible (PURPLE_PLUGIN_FLAG_INVISIBLE).
142 It causes the plugin to NOT appear in the
143 list of plugins.
144 */
145 NULL, /* This is a GList of plugin dependencies. In
146 other words, a GList of plugin id's that
147 your plugin depends on. Set this value to
148 NULL no matter what. If your plugin has
149 dependencies, set them at run-time in the
150 plugin_init function.
151 */
152 PURPLE_PRIORITY_DEFAULT,/* This is the priority libpurple with give your
153 plugin. There are three possible values
154 for this field, PURPLE_PRIORITY_DEFAULT,
155 PURPLE_PRIORITY_HIGHEST, and
156 PURPLE_PRIORITY_LOWEST
157 */
158 98
159 "core-hello_world", /* This is your plugin's id. There is a whole 99 Finally we have @c PURPLE_PLUGIN_INIT(). @c PURPLE_PLUGIN_INIT is a macro
160 page dedicated to this in the Related Pages 100 that every plugin MUST have. @c PURPLE_PLUGIN_INIT tells libpurple some
161 section of the API docs. 101 basic things about your plugin, like what name to use if the plugin is
162 */ 102 compiled statically, and the @c plugin_query, @c plugin_load, and
163 "Hello World!", /* This is your plugin's name. This is what 103 @c plugin_unload functions.
164 will be displayed for your plugin in the UI.
165 */
166 1.1, /* This is the version of your plugin. */
167
168 "Hello World Plugin", /* This is the summary of your plugin. It
169 should be a short little blurb. The UI
170 determines where, if at all, to display
171 this.
172 */
173 "Hello World Plugin", /* This is the description of your plugin. It
174 can be as long and as descriptive as you
175 like. And like the summary, it's up to the
176 UI where, if at all, to display this (and
177 how much to display).
178 */
179 NULL, /* This is where you can put your name and
180 email address.
181 */
182 "http://helloworld.tld",/* This is the website for the plugin. This
183 tells users where to find new versions,
184 report bugs, etc.
185 */
186
187 plugin_load, /* This is a pointer to a function for
188 libpurple to call when it is loading the
189 plugin. It should be of the type:
190
191 gboolean plugin_load(PurplePlugin *plugin)
192
193 Returning FALSE will stop the loading of the
194 plugin. Anything else would evaluate as
195 TRUE and the plugin will continue to load.
196 */
197 NULL, /* Same as above except it is called when
198 libpurple tries to unload your plugin. It
199 should be of the type:
200
201 gboolean plugin_unload(PurplePlugin *plugin)
202
203 Returning TRUE will tell libpurple to
204 continue unloading while FALSE will stop
205 the unloading of your plugin.
206 */
207 NULL, /* Similar to the two above members, except
208 this is called when libpurple tries to
209 destory the plugin. This is generally only
210 called when for some reason or another the
211 plugin fails to probe correctly. It should
212 be of the type:
213
214 void plugin_destroy(PurplePlugin *plugin)
215 */
216
217 NULL, /* This is a pointer to a UI-specific struct.
218 For a Pidgin plugin it will be a pointer to a
219 PidginPluginUiInfo struct, for example.
220 */
221 NULL, /* This is a pointer to either a
222 PurplePluginLoaderInfo struct or a
223 PurplePluginProtocolInfo struct, and is
224 beyond the scope of this document.
225 */
226 NULL, /* This is a pointer to a PurplePluginUiInfo
227 struct. It is a core/ui split way for
228 core plugins to have a UI configuration
229 frame. You can find an example of this
230 code in:
231 libpurple/plugins/pluginpref_example.c
232 */
233 NULL, /* This is a function pointer where you can define
234 "plugin actions". The UI controls how
235 they're displayed. It should be of the
236 type:
237
238 GList *function_name(PurplePlugin *plugin,
239 gpointer context)
240
241 It must return a GList of
242 PurplePluginActions.
243 */
244 NULL, /* This is a pointer reserved for future use.
245 We set it to NULL to indicate we don't
246 need it.
247 */
248 NULL, /* This is a pointer reserved for future use.
249 We set it to NULL to indicate we don't
250 need it.
251 */
252 NULL, /* This is a pointer reserved for future use.
253 We set it to NULL to indicate we don't
254 need it.
255 */
256 NULL /* This is a pointer reserved for future use.
257 We set it to NULL to indicate we don't
258 need it.
259 */
260 };
261 @endcode
262
263 Finally we have @c init_plugin and @c PURPLE_INIT_PLUGIN. @c init_plugin is
264 a function that gets called when libpurple probes the plugin. Most plugins
265 will add their preferences to the pref tree here--more about that later.
266 @c PURPLE_INIT_PLUGIN is a macro that EVERY plugin MUST have.
267 @c PURPLE_INIT_PLUGIN tells libpurple some very basic things about your
268 plugin, like what name to use if the plugin is compiled staticly, the
269 @c init_plugin function, and the name of the PurplePluginInfo structure. As
270 you may have guessed, this also gets read when libpurple is probing your
271 plugin. If this is missing, the plugin will not load.
272 */ 104 */
273 // vim: syntax=c.doxygen 105 // vim: syntax=c.doxygen

Mercurial Repository: pidgin3

mercurial