annotate doc/C-HOWTO.dox @ 13517:fe065eb51c2e

[gaim-migrate @ 15893] GG PRPL: Free the search form also when no users were found. committer: Tailor Script <tailor@pidgin.im>
author Bartoz Oler <bartosz@pidgin.im>
date Wed, 15 Mar 2006 12:37:43 +0000
parents 51b87da4e9f0
children 8f910263b4bb
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
1 /** @page c-howto C Plugin HOWTO
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
2
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
3 @section Introduction
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
4 C plugins are native plugins. They have complete access to all of the api,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
5 and can do basically whatever they want. All of the protocol plugins, as
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
6 well as the perl and tcl loader plugins are written in C.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
7
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
8 @section getting_started Getting Started
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
9 To develop a plugin you need to have the Gaim source code. It is generally a
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
10 good idea to compile against the same version of Gaim that you are running.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
11 You may also want to develop against CVS. While we do NOT recomend this for
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
12 normal users, it makes sense for plugin developers to use CVS to ensure their
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
13 plugins works with the most recent changes in Gaim. A lot tends to
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
14 change between versions and it's much easier to fix your plugin as things
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
15 change rather than waiting until the release. But please do not abuse CVS.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
16 Gaim puts a lot of strain on Source Forge's servers, and we do not need to
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
17 add anymore to it.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
18
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
19 If you choose not to head my warnings and develop against a version of Gaim
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
20 that is different from what you're running, then your Gaim source must at
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
21 the very least be configured. Note that just running configure will
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
22 generally set the prefix to /usr/local. This shouldn't be a problem, except
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
23 that most packages compile and install Gaim with /usr as the prefix.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
24
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
25 All plugins must have @c GAIM_PLUGINS defined. You can choose to include
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
26 @c internal.h to do this, but if you choose to do it this way it must be
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
27 included before any other Gaim files. Likewise, if you choose to manually
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
28 define @c GAIM_PLUGINS, the definition must be before including any Gaim
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
29 files. Failure to do so will produce the 'plugin foo could not be loaded for
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
30 an unknown reason'. This is one of the hardest unknown reasons to track
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
31 down, so let's try to avoid it at all costs ;)
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
32
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
33 @section hello_world Hello World!
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
34 I know every tutorial has a hello world, so why should Gaim be any different?
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
35
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
36 @code
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
37 #define GAIM_PLUGINS
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
38
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
39 #include <glib.h>
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
40
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
41 #include "notify.h"
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
42 #include "plugin.h"
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
43 #include "version.h"
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
44
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
45 static gboolean
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
46 plugin_load(GaimPlugin *plugin) {
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
47 gaim_notify_message(plugin, GAIM_NOTIFY_MSG_INFO, "Hello World!",
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
48 "This is the Hello World! plugin :)", NULL, NULL, NULL);
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
49
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
50 return TRUE;
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
51 }
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
52
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
53 static GaimPluginInfo info = {
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
54 GAIM_PLUGIN_MAGIC,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
55 GAIM_MAJOR_VERSION,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
56 GAIM_MINOR_VERSION,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
57 GAIM_PLUGIN_STANDARD,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
58 NULL,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
59 0,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
60 NULL,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
61 GAIM_PRIORITY_DEFAULT,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
62
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
63 "core-hello_world",
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
64 "Hello World!",
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
65 VERSION,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
66
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
67 "Hello World Plugin",
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
68 "Hello World Plugin",
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
69 NULL,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
70 GAIM_WEBSITE,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
71
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
72 plugin_load,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
73 NULL,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
74 NULL,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
75
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
76 NULL,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
77 NULL,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
78 NULL,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
79 NULL
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
80 };
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
81
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
82 static void
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
83 init_plugin(GaimPlugin *plugin) {
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
84 }
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
85
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
86 GAIM_INIT_PLUGIN(hello_world, init_plugin, info);
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
87
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
88 @endcode
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
89
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
90 Okay, so what does all this mean? We start off by defining @c GAIM_PLUGINS
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
91 like described before. Next we include glib.h, mainly for gboolean and the
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
92 glib wrappers of the standard c types. We could just use stdio and use
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
93 an int for the gboolean but since Gaim uses glib internally, we might as
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
94 well do the same.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
95
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
96 Next, we include plugin.h which has all the plugin specific stuff that we
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
97 need. For example @c GaimPlugin, @c GaimPluginInfo, @c GAIM_PLUGIN_MAGIC,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
98 and @c GAIM_INIT_PLUGIN().
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
99
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
100 Our last include is version.h which defines @c GAIM_MAJOR_VERSION, and
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
101 @c GAIM_MINOR_VERSION. There is not much you need to know about these,
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
102 except that they are required and will stop your plugin from crashing Gaim
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
103 when something has changed that you plugin does not know about yet.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
104
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
105 plugin_load is not required. It is called when the plugin is loaded so that
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
106 you can initialize any variables and so on. But in this plugin we'll just
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
107 use it to display a message.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
108
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
109 Next we have the @c GaimPluginInfo structure. Every plugin MUST have one of
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
110 these. Below is a code snipet of the same struct used in @c hello_world with
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
111 comments describing what each is.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
112
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
113 @code
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
114 static GaimPluginInfo info = {
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
115 GAIM_PLUGIN_MAGIC, /* Plugin magic, this should always be
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
116 GAIM_PLUGIN_MAGIC. This value gets
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
117 incremented inside of Gaim so that plugins
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
118 that haven't been updated yet will fail to
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
119 load and avoid potential crashes while
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
120 loading old plugins.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
121 */
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
122 GAIM_MAJOR_VERSION, /* This is also defined in Gaim. It helps
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
123 Gaim's plugin system determine what version
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
124 of Gaim this plugin was compiled for, and
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
125 whether loading it will cause problems.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
126 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
127 GAIM_MINOR_VERSION, /* See previous */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
128 GAIM_PLUGIN_STANDARD, /* GaimPluginType, there are 4 different values
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
129 for this field. The first is
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
130 GAIM_PLUGIN_UNKNOWN, which should not be
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
131 used. The second is GAIM_PLUGIN_STANDARD,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
132 this is the value most plugins will use.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
133 Next we have GAIM_PLUGIN_LOADER, this is
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
134 the type you want to load if your plugin
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
135 is going to make it possible to load non-
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
136 native plugins. For example, perl and tcl.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
137 Last, we have GAIM_PLUGIN_PROTOCOL. If
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
138 your plugin is going to allow the user to
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
139 connect to another network, this is the
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
140 type you'd want to use.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
141 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
142 NULL, /* This field is the ui requirement. This
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
143 value should be a string. If you're
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
144 writing a core plugin, this should be NULL
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
145 and the plugin should not contain any ui
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
146 specific code. If you're writing a gtk
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
147 plugin, you can use the
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
148 GAIM_GTK_PLUGIN_TYPE macro. All other ui
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
149 plugins are dependent on their ui
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
150 implementation, and is outside the scope of
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
151 this howto.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
152 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
153 0, /* This field is for plugin flags. Currently,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
154 the only flag available to plugins is
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
155 invisible (GAIM_PLUGIN_FLAG_INVISIBLE).
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
156 This plugin is currently used by the ssl
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
157 plugin, the tcl loader, and the perl
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
158 loaded. It causes the plugin to NOT
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
159 appear in the list of plugins in Gaim's
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
160 preferences window.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
161 */
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
162 NULL, /* This is a GList of plugin dependencies. In
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
163 other words, a GList of plugin id's that
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
164 your plugin depends on. If your plugin
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
165 does not have any dependencies, set this
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
166 value to NULL.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
167 */
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
168 GAIM_PRIORITY_DEFAULT, /* This is the priority Gaim with give your
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
169 plugin. There are three possible values
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
170 for this field, GAIM_PRIORITY_DEFAULT,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
171 GAIM_PRIORITY_HIGHEST, and
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
172 GAIM_PRIORITY_LOWEST
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
173 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
174
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
175 "core-hello_world", /* This is your plugin's id. There is a whole
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
176 page dedicated to this in the
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
177 'related-pages' section of Gaim's API docs.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
178 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
179 "Hello World!", /* This is your plugin name. This is what
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
180 will be displayed for your plugin in the ui.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
181 */
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
182 1.1, /* This is the version of your plugin. For
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
183 the sake of simplicity, I'm using the Gaim
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
184 version.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
185 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
186
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
187 "Hello World Plugin", /* This is the summary of your plugin. It
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
188 should be a short little blurb. The ui
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
189 determines where, if at all, to display
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
190 this.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
191 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
192 "Hello World Plugin", /* This is the description of your plugin. It
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
193 can be as long and as descriptive as you
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
194 like. And like the summary, it's up to the
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
195 ui where, if at all, to display this.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
196 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
197 NULL, /* This is where you can put your name and
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
198 email address. (You are the author right?)
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
199 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
200 GAIM_WEBSITE, /* This is the website for the plugin. This
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
201 is helpful if users find bugs in your
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
202 plugin so they can help to bring them to
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
203 your attention.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
204 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
205
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
206 plugin_load, /* This is a pointer to a function for Gaim to
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
207 call when it is loading your plugin. It
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
208 should be in the form of:
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
209
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
210 gboolean function_name(GaimPlugin *plugin)
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
211
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
212 Returning TRUE will tell Gaim to continue
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
213 loading your plugin, while FALSE will tell
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
214 Gaim to stop trying to load it.
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
215 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
216 NULL, /* Same as above except it is called when
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
217 Gaim tries to unload your plugin. It
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
218 should be in the form of:
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
219
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
220 gboolean function_name(GaimPlugin *plugin)
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
221
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
222 Where returning TRUE will tell Gaim to
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
223 continue unloading and false to not continue
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
224 unloading your plugin.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
225 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
226 NULL, /* Similar to the two above members, except
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
227 this is called when Gaim tries to destory
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
228 the plugin. This is generally only called
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
229 when for some reason or another the plugin
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
230 fails to probe correctly. It should be in
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
231 the form of:
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
232
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
233 void function_name(GaimPlugin *plugin)
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
234 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
235
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
236 NULL, /* This is a pointer to a ui specific struct.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
237 For a gtk plugin it will be a pointer to a
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
238 GaimGtkPluginUiInfo struct.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
239 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
240 NULL, /* This is a pointer to either a
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
241 GaimPluginLoaderInfo struct or a
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
242 GaimPluginProtocolInfo struct, and is
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
243 beyond the scope of this document.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
244 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
245 NULL, /* This is a pointer to a GaimPluginUiInfo
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
246 struct. It is a core/ui split way for
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
247 core plugins to have a ui configuration
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
248 frame. You can find an example of this
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
249 code in plugins/pluginpref_example.c
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
250 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
251 NULL /* Finally the last member of the structure,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
252 is a function pointer where you can define
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
253 menu entries for 'Tools->Plugin Actions'.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
254 It should be in the form of:
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
255
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
256 GList *function_name(GaimPlugin *plugin,
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
257 gpointer context)
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
258
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
259 It should return a GList of
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
260 GaimPluginActions.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
261 */
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
262 };
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
263 @endcode
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
264
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
265 Finally we have @c init_plugin and @c GAIM_INIT_PLUGIN. @c init_plugin is a
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
266 function that gets called when Gaim probes the plugin. Most plugins will
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
267 add their preferences to the pref tree here, more about that later.
10469
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
268 @c GAIM_INIT_PLUGIN is a macro that EVERY plugin MUST have. @c GAIM_INIT_PLUGIN
51b87da4e9f0 [gaim-migrate @ 11751]
Mark Doliner <mark@kingant.net>
parents: 10468
diff changeset
269 tells Gaim some very basic things about your plugin, like what name to use
10468
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
270 if the plugin is compiled staticly, the @c init_plugin function, and
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
271 the name of the @c GaimPluginInfo structure. As you may have guess this
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
272 also gets read when Gaim is probing your plugin. If this is missing you
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
273 will get the infamous "plugin unloadable for unknown reasons", so do not
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
274 forget it.
87d2f1a7f984 [gaim-migrate @ 11750]
Luke Schierer <lschiere@pidgin.im>
parents:
diff changeset
275 */