Mercurial > pidgin
annotate plugins/HOWTO @ 11853:65b6f52c2696
[gaim-migrate @ 14144]
log that
committer: Tailor Script <tailor@pidgin.im>
author | Stu Tomlinson <stu@nosnilmot.com> |
---|---|
date | Thu, 27 Oct 2005 18:38:52 +0000 |
parents | 258c19be6d84 |
children |
rev | line source |
---|---|
7327 | 1 Everything in this file should be considered old and potentially out of |
2 date. For more reliable information, install doxygen and graphiz dot, | |
3 then run | |
4 make docs | |
5 in the gaim source tree. This will produce html docs in gaim/docs/html | |
6 that will provide an api reference and in the related pages section, | |
7 information on perl and c plugins. | |
8 | |
9 | |
93 | 10 Ok, this howto is going to be really short and sweet and to the point. |
11 | |
12 First off, before you do anything else, in all of the files for your plugin, | |
13 put the lines | |
14 | |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
15 #define GAIM_PLUGINS |
93 | 16 #include "gaim.h" |
17 | |
18 I mean this. Without this, all kinds of things will not work correctly. If you | |
19 really want to know exactly what this does, read ../src/gaim.h and learn. But | |
20 if you don't want to do that, just know that it's important. | |
21 | |
22 Now that you've put that there, make sure gaim.h is in your include path. | |
23 | |
24 Ok, now you're ready to write the plugin. | |
25 | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
26 The only function that is required is gaim_plugin_init(GModule *). This gets |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
27 called as soon as it gets loaded (sort of - man dlopen for more details). If |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
28 your function never returns, it will crash gaim! If your plugin uses up all |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
29 the memory in the system, it will crash gaim! Once your plugin gets loaded, |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
30 it effectively becomes a part of gaim, and anything that goes wrong will look |
93 | 31 like it is a problem with gaim itself. I write bugfree code! :) Therefore, it |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
32 is your problem, not mine. (I'm usually nice and willing to help you with your |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
33 problems though.) |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
34 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
35 The GModule* that gets passed to gaim_plugin_init is the handle for the plugin. |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
36 DO NOT CHANGE THIS POINTER! Bad things will happen. You've been warned. It's |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
37 needed for connecting to signals and things. It's a good idea to remember it |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
38 somehow. |
93 | 39 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
40 gaim_plugin_init should return a char*. If the char* returned is not NULL, it |
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
41 is interpreted as an error, and used as an error message. See the ChangeLog |
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
42 file in this directory for more details. |
391
be408b41c172
[gaim-migrate @ 401]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
144
diff
changeset
|
43 |
93 | 44 You can basically do anything you want in the plugin. You can make function |
45 calls, change public widgets, display new widgets, things like that. But the | |
95
19cffb5bd129
[gaim-migrate @ 105]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
94
diff
changeset
|
46 really neat thing is you can do things at events. For example, when one of |
93 | 47 your buddies signs on, you can instantly send them a message. You can modify |
48 the incoming and outgoing text. You can do all kinds of crazy things. Whatever | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
49 you want. Check out SIGNALS for more information. |
93 | 50 |
51 Plugins can share globals with gaim, but will not share with other plugins. | |
52 This is so if you have a global variable GtkWidget *window in your plugin and | |
53 J. Random Hacker also has the same name on a global variable, you won't be | |
54 constantly overwriting each others' variables. Unfortunately, this also means | |
55 that plugins will have difficulty working together. But then again, that's | |
56 what shared memory is for. | |
57 | |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
58 Plugins can be configured. This makes it so they don't have to be recompiled |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
59 in order to change things internal to them, and it's also just a cool feature |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
60 to have :). It's optional; to allow your plugin to be configured, add a |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
61 function called gaim_plugin_config(). The advised course of action is to have |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
62 it pop up a dialog window; but it's your plugin. |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
63 |
93 | 64 When your plugin gets unloaded, gaim will try to call gaim_plugin_remove(). It |
65 doesn't have to be there, but it's nice if, say, you create a window, and when | |
98
c2d22261e281
[gaim-migrate @ 108]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
95
diff
changeset
|
66 the plugin gets unloaded, it removes the window. Also, all the callbacks you |
c2d22261e281
[gaim-migrate @ 108]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
95
diff
changeset
|
67 have attached to gaim signals will be removed. |
93 | 68 |
2327
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
69 Plugins can also unload themselves. To do this, call gaim_plugin_unload(GModule *) |
f74eefb55a78
[gaim-migrate @ 2337]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
445
diff
changeset
|
70 (the GModule* is the handle passed to gaim_plugin_init). When your plugin gets |
445
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
71 unloaded, gaim will remove all of your callbacks. It will not call your |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
72 gaim_plugin_remove function, however, since it will assume you have already |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
73 done the necessary cleanup. |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
74 |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
75 Compilation of the plugins is fairly straight-forward; there is a Makefile in |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
76 this directory that has a rule for making the .so file from a .c file. No |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
77 modification of the Makefile should be necessary, unless if you simply want |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
78 to type 'make' to have it made; otherwise, 'make filename.so' will take |
445
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
79 filename.c and make the .so plugin from it. If you need to link in with extra |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
80 libraries, you can set the environment variable PLUGIN_LIBS to be the libraries |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
81 you want to link with. |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
82 |
93 | 83 There are a few examples in this directory. Enjoy. |