Mercurial > pidgin
annotate doc/C-HOWTO.dox @ 24392:d1211d64c825
Didn't mean to check this assert in. I mean, it's probably bad if it
happens. I think it'll lead to a crash later on. Or at least some
invalid memory accesses.
author | Mark Doliner <mark@kingant.net> |
---|---|
date | Thu, 13 Nov 2008 06:30:33 +0000 |
parents | e0bcb8cfda74 |
children |
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, | |
18537
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
66 NULL, |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
67 NULL, |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
68 NULL, |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
69 NULL, |
10468 | 70 NULL |
71 }; | |
72 | |
73 static void | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
74 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
|
75 { |
10468 | 76 } |
77 | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
78 PURPLE_INIT_PLUGIN(hello_world, init_plugin, info); |
10468 | 79 |
80 @endcode | |
81 | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
82 Okay, so what does all this mean? We start off by defining @c PURPLE_PLUGINS |
10468 | 83 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
|
84 glib wrappers of the standard C types. |
10468 | 85 |
86 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
|
87 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
|
88 @c PURPLE_PLUGIN_MAGIC, and @c PURPLE_INIT_PLUGIN(). |
10468 | 89 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
90 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
|
91 @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
|
92 except that they are required and will stop your plugin from crashing Pidgin |
18537
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
93 when something has changed that your plugin does not know about yet. |
10468 | 94 |
18537
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
95 @c plugin_load is not required. It is called when the plugin is loaded so |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
96 that you can initialize any variables and so on. In this plugin we'll just |
10469 | 97 use it to display a message. |
10468 | 98 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
99 Next we have the @c PurplePluginInfo structure. Every plugin MUST have one of |
10468 | 100 these. Below is a code snipet of the same struct used in @c hello_world with |
101 comments describing what each is. | |
102 | |
103 @code | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
104 static PurplePluginInfo info = { |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
105 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
|
106 PURPLE_PLUGIN_MAGIC. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
107 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
108 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
|
109 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
|
110 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
|
111 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
|
112 cause problems. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
113 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
114 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
|
115 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
|
116 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
|
117 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
|
118 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
|
119 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
|
120 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
|
121 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
|
122 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
|
123 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
|
124 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
|
125 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
|
126 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
|
127 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
|
128 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
|
129 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
130 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
|
131 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
|
132 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
|
133 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
|
134 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
|
135 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
|
136 FINCH_PLUGIN_TYPE. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
137 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
138 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
|
139 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
|
140 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
|
141 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
|
142 list of plugins. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
143 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
144 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
|
145 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
|
146 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
|
147 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
|
148 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
|
149 plugin_init function. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
150 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
151 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
|
152 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
|
153 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
|
154 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
|
155 PURPLE_PRIORITY_LOWEST |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
156 */ |
10468 | 157 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
158 "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
|
159 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
|
160 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
|
161 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
162 "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
|
163 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
|
164 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
165 1.1, /* This is the version of your plugin. */ |
10468 | 166 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
167 "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
|
168 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
|
169 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
|
170 this. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
171 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
172 "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
|
173 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
|
174 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
|
175 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
|
176 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
|
177 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
178 NULL, /* This is where you can put your name and |
23180
e0bcb8cfda74
Use "email" and "Email" consistently. This is potentially controversial,
Richard Laager <rlaager@wiktel.com>
parents:
20807
diff
changeset
|
179 email address. |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
180 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
181 "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
|
182 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
|
183 report bugs, etc. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
184 */ |
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 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
|
187 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
|
188 plugin. It should be of the type: |
10468 | 189 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
190 gboolean plugin_load(PurplePlugin *plugin) |
10468 | 191 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
192 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
|
193 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
|
194 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
|
195 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
196 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
|
197 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
|
198 should be of the type: |
10468 | 199 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
200 gboolean plugin_unload(PurplePlugin *plugin) |
10468 | 201 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
202 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
|
203 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
|
204 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
|
205 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
206 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
|
207 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
|
208 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
|
209 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
|
210 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
|
211 be of the type: |
10468 | 212 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
213 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
|
214 */ |
10468 | 215 |
16199
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 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
|
217 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
|
218 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
|
219 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
220 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
|
221 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
|
222 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
|
223 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
|
224 */ |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
225 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
|
226 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
|
227 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
|
228 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
|
229 code in: |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
230 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
|
231 */ |
18537
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
232 NULL, /* This is a function pointer where you can define |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
233 "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
|
234 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
|
235 type: |
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 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
|
238 gpointer context) |
10468 | 239 |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
240 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
|
241 PurplePluginActions. |
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
242 */ |
18537
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
243 NULL, /* This is a pointer reserved for future use. |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
244 We set it to NULL to indicate we don't |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
245 need it. |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
246 */ |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
247 NULL, /* This is a pointer reserved for future use. |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
248 We set it to NULL to indicate we don't |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
249 need it. |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
250 */ |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
251 NULL, /* This is a pointer reserved for future use. |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
252 We set it to NULL to indicate we don't |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
253 need it. |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
254 */ |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
255 NULL /* This is a pointer reserved for future use. |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
256 We set it to NULL to indicate we don't |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
257 need it. |
52f3e904a250
Patch from John Bailey (rekkanoryo) to update the C Howto.
John Bailey <rekkanoryo@rekkanoryo.org>
parents:
16199
diff
changeset
|
258 */ |
10468 | 259 }; |
260 @endcode | |
261 | |
16199
17e8b8805688
Effect the rename in the C-HOWTO and clean it up.
Richard Laager <rlaager@wiktel.com>
parents:
15802
diff
changeset
|
262 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
|
263 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
|
264 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
|
265 @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
|
266 @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
|
267 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
|
268 @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
|
269 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
|
270 plugin. If this is missing, the plugin will not load. |
10468 | 271 */ |
20807
e0613cf8c493
Add some links from signal documentation back to the documentation for the
Will Thompson <will.thompson@collabora.co.uk>
parents:
18537
diff
changeset
|
272 // vim: syntax=c.doxygen |