Mercurial > pidgin
annotate doc/C-HOWTO.dox @ 28482:da5f35ec5785
This feels hacky to me, so if someone has a better idea, go for it. This change
makes it so the global "Use remote DNS with SOCKS4 proxies" pref checkbox stays
visible when the proxy type pref changes. Etan, Paul, and I noticed this the
other day when discussing the previous changes.
author | John Bailey <rekkanoryo@rekkanoryo.org> |
---|---|
date | Mon, 02 Nov 2009 02:58:17 +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 |