Mercurial > pidgin.yaz
annotate PRPL @ 2740:68ad186943e0
[gaim-migrate @ 2753]
one more
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Sat, 17 Nov 2001 21:59:59 +0000 |
parents | a7bfb5dfab25 |
children |
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 |
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. |