Mercurial > pidgin.yaz
annotate PRPL @ 1492:638b57b1801d
[gaim-migrate @ 1502]
bah.
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Sat, 17 Feb 2001 00:08:45 +0000 |
parents | b332d8f46b84 |
children | a7bfb5dfab25 |
rev | line source |
---|---|
981 | 1 Protocol Plugins. What EveryBuddy should have been. |
2 | |
1333
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
3 Each PRPL needs to have a unique identifier. In the pre-PRPL system TOC |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
4 was 0 and Oscar was 1. This identifier can be found in prpl.h. They |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
5 are pre-assigned. PROTO_TOC is still 0, PROTO_OSCAR is still 1. The |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
6 protocol_init function is expected to set the struct's protocol member to |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
7 the appropriate value. If you want to write a new PRPL for gaim, please |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
8 email one of the maintainers with the name of the protocol. We'll then |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
9 reserve a number for it. Please do not use a number that has not been |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
10 assigned to your protocol. |
981 | 11 |
1333
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
12 The addition of PRPL to gaim means that gaim now supports multiple |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
13 connections and multiple (and dynamically loadable) protocols. |
981 | 14 |
15 ====== | |
16 | |
1030
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
17 I guess I should document how to write a PRPL. |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
18 |
1333
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
19 The first thing to do is to write your init function. It should be |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
20 delcared |
1030
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
21 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
22 void my_proto_init(struct prpl *p); |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
23 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
24 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
|
25 |
1333
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
26 If you're going to load your protocol dynamically, put the function |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
27 gaim_plugin_init(void *) in the file, and have it call |
1030
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
28 |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
29 load_protocol(my_proto_init); |
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
30 |
1333
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
31 and return NULL. Then compile as a plugin, load the .so file, and you're |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
32 set. If you're going to load it statically, extern the my_proto_init |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
33 function, and in prpl.c, call load_protocol. |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
34 |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
35 Your PRPL needs to have a login function, which ideally should set up a |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
36 gdk_input watcher. When you want to indicate that the account is online, |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
37 simply call account_online(struct gaim_connection *). When there is |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
38 information from the server, you should call the appropriate serv_got |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
39 function (see gaim.h for a (partial?) list). |
1030
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
40 |
1333
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
41 When the UI wants to send something via the server, it will call the |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
42 appropriate function that you set in your PRPL, if it's non-NULL. The |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
43 only function that is absolutely critical is name. Without name gaim |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
44 will probably crash. You don't even need login, just name. (You need |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
45 login to do anything useful though.) |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
46 |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
47 ====== |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
48 |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
49 Erg. Now the fun part. The part that you would have never guessed if you |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
50 weren't me. (I know that you wouldn't have guessed this stuff because |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
51 it isn't painfully obvious to me. Use the Source, Luke.) |
1030
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
52 |
1333
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
53 Let's start with the basics. PRPLs shouldn't use GTK at all. That said, |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
54 they have to in no fewer than three functions: action_menu, user_opts, and |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
55 draw_new_user (probably do_new_user too). Fortunately, all of these are |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
56 optional. Unfortunatly, all of these are so incredibly useful that they |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
57 probably aren't optional. If you use GTK (other than gdk_input_add/remove |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
58 for the connections) in any function other than these three I will hunt |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
59 you down like the dog you are and kill you. (Oscar and TOC are excused |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
60 temporarily because they existed long before all the other PRPLs.) |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
61 |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
62 You're probably wondering how you can do certain things without GTK. Well, |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
63 you're just going to have to make do. Rely on the UI, that's why it's |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
64 there. A PRPL should have absolutely ZERO interaction with the user, |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
65 it should all be handled by the UI. So far, about the only thing that's |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
66 been added to gaim to aid in this goal is do_ask_dialog. But at least |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
67 it's a start. |
1030
38452403563b
[gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
981
diff
changeset
|
68 |
1333
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
69 do_ask_dialogs is one of the worst creations ever to come from my ass. It |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
70 must have been very late in the morning, just before I went to sleep, |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
71 when I coded it. That's my excuse. |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
72 |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
73 You pass it the question you want to ask, what to do on Yes, what to |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
74 do on No, and optional data. The logic actually isn't like that at |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
75 all. Given you call do_ask_dialog("Wanna?", mydata, yes_func, no_func), |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
76 the logic is: |
1086
ce201056e7a6
[gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1030
diff
changeset
|
77 |
1333
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
78 if (clicked_yes) |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
79 yes_func(); |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
80 no_func(); |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
81 |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
82 i.e. no_func() gets called regardless of what's clicked. So |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
83 it's best to use it for freeing mydata, and not freeing mydata in |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
84 yes_func. To be quite honest, I'm not sure no_func is needed. (I |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
85 also seem to think that yes_func isn't entirely necessary either, |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
86 except for the little part about it being the point of do_ask_dialog.) |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
87 |
b332d8f46b84
[gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1224
diff
changeset
|
88 Um. So that was interesting. |