comparison: plugins/HOWTO
plugins/HOWTO
- branch
- cpw.khc.msnp14
- changeset 20472
- 6a6d2ef151e6
- parent 13912
- 463b4fa9f067
- parent 20469
- b2836a24d81e
- child 20473
- 91e1b3a49d10
equal
deleted
inserted
replaced
| 13912:463b4fa9f067 | 20472:6a6d2ef151e6 |
|---|---|
| 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 | |
| 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 | |
| 15 #define GAIM_PLUGINS | |
| 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 | |
| 26 The only function that is required is gaim_plugin_init(GModule *). This gets | |
| 27 called as soon as it gets loaded (sort of - man dlopen for more details). If | |
| 28 your function never returns, it will crash gaim! If your plugin uses up all | |
| 29 the memory in the system, it will crash gaim! Once your plugin gets loaded, | |
| 30 it effectively becomes a part of gaim, and anything that goes wrong will look | |
| 31 like it is a problem with gaim itself. I write bugfree code! :) Therefore, it | |
| 32 is your problem, not mine. (I'm usually nice and willing to help you with your | |
| 33 problems though.) | |
| 34 | |
| 35 The GModule* that gets passed to gaim_plugin_init is the handle for the plugin. | |
| 36 DO NOT CHANGE THIS POINTER! Bad things will happen. You've been warned. It's | |
| 37 needed for connecting to signals and things. It's a good idea to remember it | |
| 38 somehow. | |
| 39 | |
| 40 gaim_plugin_init should return a char*. If the char* returned is not NULL, it | |
| 41 is interpreted as an error, and used as an error message. See the ChangeLog | |
| 42 file in this directory for more details. | |
| 43 | |
| 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 | |
| 46 really neat thing is you can do things at events. For example, when one of | |
| 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 | |
| 49 you want. Check out SIGNALS for more information. | |
| 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 | |
| 58 Plugins can be configured. This makes it so they don't have to be recompiled | |
| 59 in order to change things internal to them, and it's also just a cool feature | |
| 60 to have :). It's optional; to allow your plugin to be configured, add a | |
| 61 function called gaim_plugin_config(). The advised course of action is to have | |
| 62 it pop up a dialog window; but it's your plugin. | |
| 63 | |
| 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 | |
| 66 the plugin gets unloaded, it removes the window. Also, all the callbacks you | |
| 67 have attached to gaim signals will be removed. | |
| 68 | |
| 69 Plugins can also unload themselves. To do this, call gaim_plugin_unload(GModule *) | |
| 70 (the GModule* is the handle passed to gaim_plugin_init). When your plugin gets | |
| 71 unloaded, gaim will remove all of your callbacks. It will not call your | |
| 72 gaim_plugin_remove function, however, since it will assume you have already | |
| 73 done the necessary cleanup. | |
| 74 | |
| 75 Compilation of the plugins is fairly straight-forward; there is a Makefile in | |
| 76 this directory that has a rule for making the .so file from a .c file. No | |
| 77 modification of the Makefile should be necessary, unless if you simply want | |
| 78 to type 'make' to have it made; otherwise, 'make filename.so' will take | |
| 79 filename.c and make the .so plugin from it. If you need to link in with extra | |
| 80 libraries, you can set the environment variable PLUGIN_LIBS to be the libraries | |
| 81 you want to link with. | |
| 82 | |
| 83 There are a few examples in this directory. Enjoy. |
