Mercurial > pidgin
annotate doc/C-HOWTO.dox @ 17745:8d3c28521112
I think this fixes #532.
author | Sadrul Habib Chowdhury <imadil@gmail.com> |
---|---|
date | Wed, 23 May 2007 06:23:01 +0000 |
parents | 17e8b8805688 |
children | 52f3e904a250 |
rev | line source |
---|---|
10468 | 1 /** @page c-howto C Plugin HOWTO |
2 | |
3 @section Introduction | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
4 C plugins are native plugins. They have complete access to all of the API, |
10468 | 5 and can do basically whatever they want. All of the protocol plugins, as |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
6 well as the Mono, Perl, and Tcl loader plugins are written in C. |
10468 | 7 |
8 @section getting_started Getting Started | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
9 To develop a plugin you need to have the libpurple and (for UI plugins) the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
10 Pidgin/Finch source code or development headers. It is generally a good idea |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
11 to compile against the same version of Pidgin that you are running. You may |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
12 also want to develop against the code in our Monotone repository if you need |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
13 to use a new feature. Please do not abuse our Monotone repository, however. |
10468 | 14 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
15 All plugins must have @c PURPLE_PLUGINS defined and the definition must be |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
16 before including any libpurple, Pidgin, or Finch header files. Failure to do |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
17 so can lead to strange errors that are hard to diagnose. Just don't forget! |
10468 | 18 |
19 @section hello_world Hello World! | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
20 I know every tutorial has a hello world, so why should libpurple be any |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
21 different? |
10468 | 22 |
23 @code | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
24 #define PURPLE_PLUGINS |
10468 | 25 |
26 #include <glib.h> | |
27 | |
28 #include "notify.h" | |
29 #include "plugin.h" | |
30 #include "version.h" | |
31 | |
32 static gboolean | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
33 plugin_load(PurplePlugin *plugin) { |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
34 purple_notify_message(plugin, PURPLE_NOTIFY_MSG_INFO, "Hello World!", |
10468 | 35 "This is the Hello World! plugin :)", NULL, NULL, NULL); |
36 | |
37 return TRUE; | |
38 } | |
39 | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
40 static PurplePluginInfo info = { |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
41 PURPLE_PLUGIN_MAGIC, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
42 PURPLE_MAJOR_VERSION, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
43 PURPLE_MINOR_VERSION, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
44 PURPLE_PLUGIN_STANDARD, |
10468 | 45 NULL, |
46 0, | |
47 NULL, | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
48 PURPLE_PRIORITY_DEFAULT, |
10468 | 49 |
50 "core-hello_world", | |
51 "Hello World!", | |
52 VERSION, | |
53 | |
54 "Hello World Plugin", | |
55 "Hello World Plugin", | |
56 NULL, | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
57 "http://helloworld.tld", |
10468 | 58 |
59 plugin_load, | |
60 NULL, | |
61 NULL, | |
62 | |
63 NULL, | |
64 NULL, | |
65 NULL, | |
66 NULL | |
67 }; | |
68 | |
69 static void | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
70 init_plugin(PurplePlugin *plugin) |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
71 { |
10468 | 72 } |
73 | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
74 PURPLE_INIT_PLUGIN(hello_world, init_plugin, info); |
10468 | 75 |
76 @endcode | |
77 | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
78 Okay, so what does all this mean? We start off by defining @c PURPLE_PLUGINS |
10468 | 79 like described before. Next we include glib.h, mainly for gboolean and the |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
80 glib wrappers of the standard C types. |
10468 | 81 |
82 Next, we include plugin.h which has all the plugin specific stuff that we | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
83 need. For example: @c PurplePlugin, @c PurplePluginInfo, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
84 @c PURPLE_PLUGIN_MAGIC, and @c PURPLE_INIT_PLUGIN(). |
10468 | 85 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
86 Our last include is version.h which defines @c PURPLE_MAJOR_VERSION, and |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
87 @c PURPLE_MINOR_VERSION. There is not much you need to know about these, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
88 except that they are required and will stop your plugin from crashing Pidgin |
10469 | 89 when something has changed that you plugin does not know about yet. |
10468 | 90 |
10469 | 91 plugin_load is not required. It is called when the plugin is loaded so that |
92 you can initialize any variables and so on. But in this plugin we'll just | |
93 use it to display a message. | |
10468 | 94 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
95 Next we have the @c PurplePluginInfo structure. Every plugin MUST have one of |
10468 | 96 these. Below is a code snipet of the same struct used in @c hello_world with |
97 comments describing what each is. | |
98 | |
99 @code | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
100 static PurplePluginInfo info = { |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
101 PURPLE_PLUGIN_MAGIC, /* Plugin magic, this must always be |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
102 PURPLE_PLUGIN_MAGIC. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
103 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
104 PURPLE_MAJOR_VERSION, /* This is also defined in libpurple. It helps |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
105 libpurple's plugin system determine which |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
106 version of libpurple this plugin was |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
107 compiled for, and whether loading it will |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
108 cause problems. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
109 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
110 PURPLE_MINOR_VERSION, /* See previous */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
111 PURPLE_PLUGIN_STANDARD, /* PurplePluginType: There are 4 different |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
112 values for this field. The first is |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
113 PURPLE_PLUGIN_UNKNOWN, which should not be |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
114 used. The second is PURPLE_PLUGIN_STANDARD; |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
115 this is the value most plugins will use. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
116 Next, we have PURPLE_PLUGIN_LOADER; this is |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
117 the type you want to load if your plugin |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
118 is going to make it possible to load non- |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
119 native plugins. For example, the Perl and |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
120 Tcl loader plugins are of this type. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
121 Last, we have PURPLE_PLUGIN_PROTOCOL. If |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
122 your plugin is going to allow the user to |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
123 connect to another network, this is the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
124 type you'd want to use. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
125 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
126 NULL, /* This field is the UI requirement. If you're |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
127 writing a core plugin, this must be NULL |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
128 and the plugin must not contain any UI |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
129 code. If you're writing a Pidgin plugin, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
130 you need to use PIDGIN_PLUGIN_TYPE. If you |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
131 are writing a Finch plugin, you would use |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
132 FINCH_PLUGIN_TYPE. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
133 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
134 0, /* This field is for plugin flags. Currently, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
135 the only flag available to plugins is |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
136 invisible (PURPLE_PLUGIN_FLAG_INVISIBLE). |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
137 It causes the plugin to NOT appear in the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
138 list of plugins. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
139 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
140 NULL, /* This is a GList of plugin dependencies. In |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
141 other words, a GList of plugin id's that |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
142 your plugin depends on. Set this value to |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
143 NULL no matter what. If your plugin has |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
144 dependencies, set them at run-time in the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
145 plugin_init function. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
146 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
147 PURPLE_PRIORITY_DEFAULT,/* This is the priority libpurple with give your |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
148 plugin. There are three possible values |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
149 for this field, PURPLE_PRIORITY_DEFAULT, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
150 PURPLE_PRIORITY_HIGHEST, and |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
151 PURPLE_PRIORITY_LOWEST |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
152 */ |
10468 | 153 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
154 "core-hello_world", /* This is your plugin's id. There is a whole |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
155 page dedicated to this in the Related Pages |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
156 section of the API docs. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
157 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
158 "Hello World!", /* This is your plugin's name. This is what |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
159 will be displayed for your plugin in the UI. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
160 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
161 1.1, /* This is the version of your plugin. */ |
10468 | 162 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
163 "Hello World Plugin", /* This is the summary of your plugin. It |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
164 should be a short little blurb. The UI |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
165 determines where, if at all, to display |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
166 this. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
167 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
168 "Hello World Plugin", /* This is the description of your plugin. It |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
169 can be as long and as descriptive as you |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
170 like. And like the summary, it's up to the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
171 UI where, if at all, to display this (and |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
172 how much to display). |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
173 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
174 NULL, /* This is where you can put your name and |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
175 e-mail address. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
176 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
177 "http://helloworld.tld",/* This is the website for the plugin. This |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
178 tells users where to find new versions, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
179 report bugs, etc. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
180 */ |
10468 | 181 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
182 plugin_load, /* This is a pointer to a function for |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
183 libpurple to call when it is loading the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
184 plugin. It should be of the type: |
10468 | 185 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
186 gboolean plugin_load(PurplePlugin *plugin) |
10468 | 187 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
188 Returning FALSE will stop the loading of the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
189 plugin. Anything else would evaluate as |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
190 TRUE and the plugin will continue to load. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
191 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
192 NULL, /* Same as above except it is called when |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
193 libpurple tries to unload your plugin. It |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
194 should be of the type: |
10468 | 195 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
196 gboolean plugin_unload(PurplePlugin *plugin) |
10468 | 197 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
198 Returning TRUE will tell libpurple to |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
199 continue unloading while FALSE will stop |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
200 the unloading of your plugin. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
201 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
202 NULL, /* Similar to the two above members, except |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
203 this is called when libpurple tries to |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
204 destory the plugin. This is generally only |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
205 called when for some reason or another the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
206 plugin fails to probe correctly. It should |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
207 be of the type: |
10468 | 208 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
209 void plugin_destroy(PurplePlugin *plugin) |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
210 */ |
10468 | 211 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
212 NULL, /* This is a pointer to a UI-specific struct. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
213 For a Pidgin plugin it will be a pointer to a |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
214 PidginPluginUiInfo struct, for example. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
215 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
216 NULL, /* This is a pointer to either a |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
217 PurplePluginLoaderInfo struct or a |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
218 PurplePluginProtocolInfo struct, and is |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
219 beyond the scope of this document. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
220 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
221 NULL, /* This is a pointer to a PurplePluginUiInfo |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
222 struct. It is a core/ui split way for |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
223 core plugins to have a UI configuration |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
224 frame. You can find an example of this |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
225 code in: |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
226 libpurple/plugins/pluginpref_example.c |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
227 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
228 NULL /* Finally, the last member of the structure |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
229 is a function pointer where you can define |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
230 "plugin actions". The UI controls how |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
231 they're displayed. It should be of the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
232 type: |
10468 | 233 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
234 GList *function_name(PurplePlugin *plugin, |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
235 gpointer context) |
10468 | 236 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
237 It must return a GList of |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
238 PurplePluginActions. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
239 */ |
10468 | 240 }; |
241 @endcode | |
242 | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
243 Finally we have @c init_plugin and @c PURPLE_INIT_PLUGIN. @c init_plugin is |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
244 a function that gets called when libpurple probes the plugin. Most plugins |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
245 will add their preferences to the pref tree here--more about that later. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
246 @c PURPLE_INIT_PLUGIN is a macro that EVERY plugin MUST have. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
247 @c PURPLE_INIT_PLUGIN tells libpurple some very basic things about your |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
248 plugin, like what name to use if the plugin is compiled staticly, the |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
249 @c init_plugin function, and the name of the PurplePluginInfo structure. As |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
250 you may have guessed, this also gets read when libpurple is probing your |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
251 plugin. If this is missing, the plugin will not load. |
10468 | 252 */ |