annotate PRPL @ 1103:7aabbbaae829

[gaim-migrate @ 1113] lalala committer: Tailor Script <tailor@pidgin.im>
author Eric Warmenhoven <eric@warmenhoven.org>
date Fri, 17 Nov 2000 22:45:31 +0000
parents ce201056e7a6
children 0bbe3aaa6a3e
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
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
3 Each PRPL needs to have a unique identifier. In the pre-PRPL system TOC was 0 and Oscar was 1.
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
4 This identifier can be found in prpl.h. They are pre-assigned. PROTO_TOC is still 0, PROTO_OSCAR
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
5 is still 1. The protocol_init function is expected to set the struct's protocol member to the
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
6 appropriate value. If you want to write a new PRPL for gaim, please email one of the maintainers
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
7 with the name of the protocol. We'll then reserve a number for it. Please do not use a number
1103
7aabbbaae829 [gaim-migrate @ 1113]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1086
diff changeset
8 that has not been assigned to your protocol.
981
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
9
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
10 The addition of PRPL to gaim means that gaim now supports multiple connections and multiple (and
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
11 dynamically loadable) protocols.
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
12
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
13 ======
7e231bc0018a [gaim-migrate @ 991]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
14
1030
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
15 I guess I should document how to write a PRPL.
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
16
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
17 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
18
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
19 void my_proto_init(struct prpl *p);
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
20
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
21 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
22
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
23 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
24 file, and have it call
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
25
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
26 load_protocol(my_proto_init);
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
27
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
28 and return a non-negative int. Then compile as a plugin, load the .so file, and you're set. If you're
1086
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
29 going to load it statically, extern the my_proto_init function, and in prpl.c, call load_protocol.
1030
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
30
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
31 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
32 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
33 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
34 gaim.h for a (partial?) list).
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
35
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
36 When the UI wants to send something via the server, it will call the appropriate function that you set
1086
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
37 in your PRPL, if it's non-NULL. The only function that is absolutely critical is name. Without name
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
38 gaim will probably crash. You don't even need login, just name. (You need login to do anything useful
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
39 though.)
1030
38452403563b [gaim-migrate @ 1040]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 981
diff changeset
40
1086
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
41 The best example to copy is probably Rob's IRC plugin, in plugins/irc.c. The most important functions
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
42 for gaim interaction are at the bottom (irc_init, gaim_plugin_init, and gaim_plugin_remove). The
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
43 rest of it is the protocol implementation.
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
44
ce201056e7a6 [gaim-migrate @ 1096]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1030
diff changeset
45 Sorry for the formatting. My Eterm is 105 characters wide.