annotate PRPL @ 1342:84aef77f0add

[gaim-migrate @ 1352] Umm, I forgot this :-). committer: Tailor Script <tailor@pidgin.im>
author Rob Flynn <gaim@robflynn.com>
date Thu, 21 Dec 2000 02:11:56 +0000
parents b332d8f46b84
children a7bfb5dfab25
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
981
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
1 Protocol Plugins. What EveryBuddy should have been.
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
14
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
15 ======
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
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.