annotate PRPL @ 2690:5a207e155c15

[gaim-migrate @ 2703] Sean Egan wrote this. committer: Tailor Script <tailor@pidgin.im>
author Eric Warmenhoven <eric@warmenhoven.org>
date Wed, 07 Nov 2001 21:02:06 +0000
parents a7bfb5dfab25
children
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
2318
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
53 Let's start with the basics. PRPLs shouldn't use GTK at all. If you use
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
54 GTK I will hunt you down like the dog you are and kill you.
1333
b332d8f46b84 [gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1224
diff changeset
55
b332d8f46b84 [gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1224
diff changeset
56 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
57 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
58 there. A PRPL should have absolutely ZERO interaction with the user,
2318
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
59 it should all be handled by the UI.
1333
b332d8f46b84 [gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1224
diff changeset
60
2318
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
61 So let's talk about what that means in a practical way. Have a socket that
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
62 you want notification on? Use gaim_input functions; they work just like
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
63 the gdk_input functions. Want to add a timeout? g_timeout_add and
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
64 g_source_remove. Want to ask a question? do_ask_dialog. Etc.
1086
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
65
2318
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
66 Don't use the _options variables at all. The core should take care of all
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
67 of that.
1333
b332d8f46b84 [gaim-migrate @ 1343]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1224
diff changeset
68
2318
a7bfb5dfab25 [gaim-migrate @ 2328]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1333
diff changeset
69 Um. I'm sure there's more.