Mercurial > pidgin
annotate plugins/HOWTO @ 1191:4fd0d35826fe
[gaim-migrate @ 1201]
thanks to decklin for this patch.
for some reason the logic in strcpy_withhtml looks funny to me. i'm sure it's just me though.
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Sun, 03 Dec 2000 09:50:39 +0000 |
parents | e4c34ca88d9b |
children | f74eefb55a78 |
rev | line source |
---|---|
93 | 1 Ok, this howto is going to be really short and sweet and to the point. |
2 | |
3 First off, before you do anything else, in all of the files for your plugin, | |
4 put the lines | |
5 | |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
6 #define GAIM_PLUGINS |
93 | 7 #include "gaim.h" |
8 | |
9 I mean this. Without this, all kinds of things will not work correctly. If you | |
10 really want to know exactly what this does, read ../src/gaim.h and learn. But | |
11 if you don't want to do that, just know that it's important. | |
12 | |
13 Now that you've put that there, make sure gaim.h is in your include path. | |
14 | |
15 Ok, now you're ready to write the plugin. | |
16 | |
94
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
17 The only function that is required is gaim_plugin_init(void *). This gets |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
18 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
|
19 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
|
20 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
|
21 it effectively becomes a part of gaim, and anything that goes wrong will look |
93 | 22 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
|
23 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
|
24 problems though.) |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
25 |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
26 The void * that gets passed to gaim_plugin_init is the handle for the plugin. |
9f6ce50ffb78
[gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
93
diff
changeset
|
27 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
|
28 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
|
29 somehow. |
93 | 30 |
398
59d97cd251ff
[gaim-migrate @ 408]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
393
diff
changeset
|
31 gaim_plugin_init should return an int. If the int returned is less than 0, it |
59d97cd251ff
[gaim-migrate @ 408]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
393
diff
changeset
|
32 is interpreted as an error, and gaim_plugin_error is called. See the ChangeLog |
59d97cd251ff
[gaim-migrate @ 408]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
393
diff
changeset
|
33 file in this directory for more details, and error.c for an example. |
391
be408b41c172
[gaim-migrate @ 401]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
144
diff
changeset
|
34 |
93 | 35 You can basically do anything you want in the plugin. You can make function |
36 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
|
37 really neat thing is you can do things at events. For example, when one of |
93 | 38 your buddies signs on, you can instantly send them a message. You can modify |
39 the incoming and outgoing text. You can do all kinds of crazy things. Whatever | |
40 you want. Check out SIGNALS and CRAZY for more information and ideas. | |
41 | |
42 Plugins can share globals with gaim, but will not share with other plugins. | |
43 This is so if you have a global variable GtkWidget *window in your plugin and | |
44 J. Random Hacker also has the same name on a global variable, you won't be | |
45 constantly overwriting each others' variables. Unfortunately, this also means | |
46 that plugins will have difficulty working together. But then again, that's | |
47 what shared memory is for. | |
48 | |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
49 Plugins can be configured. This makes is so they don't have to be recompiled |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
50 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
|
51 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
|
52 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
|
53 it pop up a dialog window; but it's your plugin. |
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
54 |
93 | 55 When your plugin gets unloaded, gaim will try to call gaim_plugin_remove(). It |
56 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
|
57 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
|
58 have attached to gaim signals will be removed. |
93 | 59 |
445
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
60 Plugins can also unload themselves. To do this, call gaim_plugin_unload(void *) |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
61 (the void* is the handle passed to gaim_plugin_init). When your plugin gets |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
62 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
|
63 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
|
64 done the necessary cleanup. |
e4c34ca88d9b
[gaim-migrate @ 455]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
398
diff
changeset
|
65 |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
66 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
|
67 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
|
68 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
|
69 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
|
70 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
|
71 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
|
72 you want to link with. |
144
e8dae982b37c
[gaim-migrate @ 154]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
98
diff
changeset
|
73 |
93 | 74 There are a few examples in this directory. Enjoy. |