Mercurial > pidgin
annotate PRPL @ 1047:ece2d1543b20
[gaim-migrate @ 1057]
Plugins now use GModule. Protocol plugins can be dynamically updated.
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Wed, 01 Nov 2000 22:30:36 +0000 |
parents | 38452403563b |
children | ce201056e7a6 |
rev | line source |
---|---|
981 | 1 Protocol Plugins. What EveryBuddy should have been. |
2 | |
3 Protocol Plugins are easier than GUI plugins. This is because there is necessarily a limited set | |
4 of server functions; protocols are limited. What a programmer can do with a UI is limitless. | |
5 | |
6 In order to design a framework for which Protocol Plugins can work, we must first think about | |
7 which protocols can be pluginized. (Henceforth PRPL will stand for both the Protocol Plugin | |
8 system and an individual Protocol Plugin.) | |
9 | |
10 Oscar. TOC. Yahoo. MSN. ICQ. FTP. IRC. | |
11 | |
12 There is a longer list. Note that FTP is in the list presented. FTP has basic functions similar | |
13 to those of the others. The basic functions that must be performed are: | |
14 | |
15 Sign on. (log in) | |
16 Sign off. | |
17 Send and receive messages. | |
18 | |
19 There really isn't much more to it than that. There are, then, additional functions that some | |
20 protocols implement: | |
21 | |
22 Chat. | |
23 File Transfer. | |
24 Away/Idle. (states) | |
25 Directory Info. | |
26 | |
27 Before PRPL there was a slight abstraction in the code. The UI simply needed to call serv_login, | |
28 and that function would decide between the protocols, which function to call. It did that with | |
29 an if-elseif-else series. | |
30 | |
31 With PRPL, each PRPL is stored in a struct. The structs are then kept in a GSList. The serv_ | |
32 functions then simply need to search the GSList for the correct protocol, and call the desired | |
33 function. The struct holds void * references to the desired functions. serv_* simply needs to | |
34 call that function. (Even better, each connection has a reference to the PRPL struct it uses; | |
35 this will reduce search time.) | |
36 | |
37 A new PRPL can be loaded at any time. They can be either static or dynamic code. When a new | |
38 protocol is loaded, gaim will call its protocol_init function, which is expected to return a | |
39 pointer to the aforementioned struct. If it returns NULL, the PRPL will not be loaded. (This is | |
40 not entirely true and needs to be modified in the code to work similarly to how it's decscribed | |
41 here.) | |
42 | |
43 Each PRPL needs to have a unique identifier. In the pre-PRPL system TOC was 0 and Oscar was 1. | |
44 This identifier can be found in prpl.h. They are pre-assigned. PROTO_TOC is still 0, PROTO_OSCAR | |
45 is still 1. The protocol_init function is expected to set the struct's protocol member to the | |
46 appropriate value. If you want to write a new PRPL for gaim, please email one of the maintainers | |
47 with the name of the protocol. We'll then reserve a number for it. Please do not use a number | |
48 that has not been assigned to your protocol, not even for testing purposes. | |
49 | |
50 The addition of PRPL to gaim means that gaim now supports multiple connections and multiple (and | |
51 dynamically loadable) protocols. | |
52 | |
53 ====== | |
54 | |
55 In order to test that PRPL was working with as little work as possible I made Oscar a plugin. In | |
56 order to use Oscar as a plugin, first recompile gaim with the make variable DEBUG_CFLAGS set to | |
57 -DDYNAMIC_OSCAR, e.g. | |
58 | |
59 /usr/src/gaim $ make DEBUG_CFLAGS=-DDYNAMIC_OSCAR | |
60 | |
61 This will then remove Oscar support from the code (though it will still link with libfaim. However, | |
62 gaim does not need to link to libfaim itself). Making the Oscar plugin is straight-forward; simply | |
63 make oscar.so in the plugins directory, e.g. | |
64 | |
65 /usr/src/gaim/plugins $ make oscar.so | |
66 | |
67 You will then be presented with a gaim binary in src/gaim and the Oscar plugin in plugins/oscar.so. | |
68 Simply load the oscar.so file from the normal plugin window. This will set up everything necessary. | |
69 You may unload the plugin at any time, but the protocol will still be loaded. This may or may not | |
70 be a problem and may or may not be fixed at a later point in time. | |
1030
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
71 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
72 ====== |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
73 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
74 I guess I should document how to write a PRPL. |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
75 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
76 The first thing to do is to write your init function. It should be delcared |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
77 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
78 void my_proto_init(struct prpl *p); |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
79 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
80 You then fill in the members of the struct. See prpl.h for what they are. |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
81 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
82 If you're going to load your protocol dynamically, put the function gaim_plugin_init(void *) in the |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
83 file, and have it call |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
84 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
85 load_protocol(my_proto_init); |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
86 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
87 and return a non-negative int. Then compile as a plugin, load the .so file, and you're set. If you're |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
88 going to load it dynamically, extern the my_proto_init function, and in prpl.c, call load_protocol. |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
89 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
90 Your PRPL needs to have a login function, which ideally should set up a gdk_input watcher. When you |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
91 want to indicate that the account is online, simply call account_online(struct gaim_connection *). |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
92 When there is information from the server, you should call the appropriate serv_got function (see |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
93 gaim.h for a (partial?) list). |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
94 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
95 When the UI wants to send something via the server, it will call the appropriate function that you set |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
96 in your PRPL, if it's non-NULL. |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
97 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
98 There's currently no way to unload a PRPL, even if compiled dynamically and the plugin is removed. If |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
99 you do remove a dynamic PRPL and try to load a new version of it, you will still be using the old |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
100 version. Hopefully I can figure out how to fix this. Maybe it's not that important. |