annotate plugins/HOWTO @ 19799:88b0c434259a

[gaim-migrate @ 16733] change the BL process method continue to debug This is an in progress version,continue to add support for send Yahoo Message committed by Ma Yuan <mayuan2006@gmail.com> committer: Ethan Blanton <elb@pidgin.im>
author Ma Yuan <mayuan2006@gmail.com>
date Sun, 13 Aug 2006 06:09:48 +0000
parents 258c19be6d84
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7327
258c19be6d84 [gaim-migrate @ 7913]
Luke Schierer <lschiere@pidgin.im>
parents: 2327
diff changeset
1 Everything in this file should be considered old and potentially out of
258c19be6d84 [gaim-migrate @ 7913]
Luke Schierer <lschiere@pidgin.im>
parents: 2327
diff changeset
2 date. For more reliable information, install doxygen and graphiz dot,
258c19be6d84 [gaim-migrate @ 7913]
Luke Schierer <lschiere@pidgin.im>
parents: 2327
diff changeset
3 then run
258c19be6d84 [gaim-migrate @ 7913]
Luke Schierer <lschiere@pidgin.im>
parents: 2327
diff changeset
4 make docs
258c19be6d84 [gaim-migrate @ 7913]
Luke Schierer <lschiere@pidgin.im>
parents: 2327
diff changeset
5 in the gaim source tree. This will produce html docs in gaim/docs/html
258c19be6d84 [gaim-migrate @ 7913]
Luke Schierer <lschiere@pidgin.im>
parents: 2327
diff changeset
6 that will provide an api reference and in the related pages section,
258c19be6d84 [gaim-migrate @ 7913]
Luke Schierer <lschiere@pidgin.im>
parents: 2327
diff changeset
7 information on perl and c plugins.
258c19be6d84 [gaim-migrate @ 7913]
Luke Schierer <lschiere@pidgin.im>
parents: 2327
diff changeset
8
258c19be6d84 [gaim-migrate @ 7913]
Luke Schierer <lschiere@pidgin.im>
parents: 2327
diff changeset
9
93
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
10 Ok, this howto is going to be really short and sweet and to the point.
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
11
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
12 First off, before you do anything else, in all of the files for your plugin,
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
13 put the lines
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
14
94
9f6ce50ffb78 [gaim-migrate @ 104]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 93
diff changeset
15 #define GAIM_PLUGINS
93
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
16 #include "gaim.h"
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
17
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
18 I mean this. Without this, all kinds of things will not work correctly. If you
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
19 really want to know exactly what this does, read ../src/gaim.h and learn. But
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
20 if you don't want to do that, just know that it's important.
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
21
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
22 Now that you've put that there, make sure gaim.h is in your include path.
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
23
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
24 Ok, now you're ready to write the plugin.
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
44 You can basically do anything you want in the plugin. You can make function
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
47 your buddies signs on, you can instantly send them a message. You can modify
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
50
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
51 Plugins can share globals with gaim, but will not share with other plugins.
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
52 This is so if you have a global variable GtkWidget *window in your plugin and
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
53 J. Random Hacker also has the same name on a global variable, you won't be
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
54 constantly overwriting each others' variables. Unfortunately, this also means
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
55 that plugins will have difficulty working together. But then again, that's
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
56 what shared memory is for.
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
64 When your plugin gets unloaded, gaim will try to call gaim_plugin_remove(). It
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
5ca21b68eb29 [gaim-migrate @ 103]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
83 There are a few examples in this directory. Enjoy.