annotate HACKING @ 6179:16e384bb7fbf

[gaim-migrate @ 6664] Core/UI split the core initialization and shutdown. I think I got all the bugs worked out. It's looking nice and stable here, but if it causes CVS to go to hell for everyone.. er, try to fix it or let me know :) I don't have this in patch form. committer: Tailor Script <tailor@pidgin.im>
author Christian Hammond <chipx86@chipx86.com>
date Thu, 17 Jul 2003 10:35:43 +0000
parents c7986b4d182a
children 053b577e08f2
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
1 A lot of people have tried to hack gaim, but haven't been able to because
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
2 the code is just so horrid. Well, the code isn't getting better anytime
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
3 soon (I hate GNU indent), so to help all you would-be hackers help out
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
4 gaim, here's a brief tutorial on how gaim works. I'll quickly describe
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
5 the logical flow of things, then what you'll find in each of the source
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
6 files. As an added bonus, I'll try and describe as best I can how multiple
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
7 connections and multiple protocols work. Depending on how much I want to
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
8 avoid my final tomorrow I may even describe other parts of gaim that I
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
9 particularly want to brag about. Hopefully that's enough to get most of
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
10 you going.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
11
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
12 If you don't know how event-driven programs work, stop right now. Gaim
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
13 uses GTK+'s main loop (actually GLib's but I won't talk about how GTK
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
14 works) and uses GLib functions for timeouts and socket notification. If
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
15 you don't know GTK you should go learn that first.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
16
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
17 If you're going to hack gaim, PLEASE, PLEASE PLEASE PLEASE send patches
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
18 against the absolute latest CVS. I get really annoyed when I get patches
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
19 against the last released version, especially since I don't usually have
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
20 a copy of it on my computer, and gaim tends to change a lot between
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
21 versions. (I sometimes get annoyed when they're against CVS from 3 days
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
22 ago, but can't complain because it's usually my fault that I haven't
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
23 looked at the patch yet.) To get gaim from CVS (if you haven't already),
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
24 run the following commands:
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
25
774
b61607d6c2af [gaim-migrate @ 784]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 749
diff changeset
26 $ export CVSROOT=:pserver:anonymous@cvs.gaim.sourceforge.net:/cvsroot/gaim
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
27 $ cvs login (hit enter as the password)
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
28 $ cvs co gaim (you'll see it getting all of the files)
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
29 $ cd gaim
1863
bf2434d36e54 [gaim-migrate @ 1873]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1710
diff changeset
30 $ ./autogen.sh
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
31
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
32 You'll now have your normal gaim tree with ./configure and all (which
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
33 ./autogen.sh takes the liberty of running for you). (If you want to make
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
34 your life really simple, learn how CVS works. CVS is your friend.) To make
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
35 a patch, just edit the files right there in that tree (don't bother with
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
36 two trees, or even two copies of the same file). Then when you're ready to
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
37 make your patch, simply run 'cvs diff -u >my.patch' and send it off;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
38 either post it on sf.net/projects/gaim in the patches section, or email it
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
39 to gaim@marko.net.
708
3ff8b997cd37 [gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 706
diff changeset
40
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
41 This file was last modified by $Author: lschiere $ on
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
42 $Date: 2003-02-18 09:36:15 -0500 (Tue, 18 Feb 2003) $. Do not expect any information contained
2520
e9faa7435b2a [gaim-migrate @ 2533]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2519
diff changeset
43 within to be current or correct.
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
44
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
45 Here's something new. Someone requested that I comment the code. No. I'm a
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
46 lazy bastard, and I understand most of the code, so I don't need the
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
47 comments. I understand that some of you do though. So give me the names of
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
48 specific functions that you'd like commented and I'll see what I can do.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
49 It's more likely that those comments will be updated with the code than
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
50 this file is, though even that is still unlikely.
2655
c4ad36781d1b [gaim-migrate @ 2668]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2520
diff changeset
51
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
52
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
53 CODING STYLE
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
54 ============
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
55
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
56 Coding styles are like assholes, everyone has one and no one likes anyone
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
57 elses. This is mine and if you want me to accept a patch from you without
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
58 getting annoyed you'll follow this coding style. :)
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
59
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
60 It would probably just be easier for me to include CodingStyle from the
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
61 linux kernel source.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
62
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
63 Tab indents. I *HATE* 2-space indents, and I strongly dislike 8-space
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
64 indents. Use a tab character. I'm likely to refuse a patch if it has
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
65 2-space indents.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
66
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
67 K&R style for braces. Braces always go on the same line as the if, etc.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
68 that they're associated with; the only exception is functions. Braces
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
69 for else statements should have both braces on the same line as the else
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
70 (i.e. "} else {").
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
71
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
72 No functionOrVariableNamesLikeThis. Save it for Java. Underscores are your
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
73 friend. "tmp" is an excellent variable name. Hungarian style will not be
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
74 tolerated. Go back to Microsoft.
2144
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
75
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
76 I have a 105-char wide Eterm. Deal with it.
a9940cdb86ee [gaim-migrate @ 2154]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1863
diff changeset
77
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
78 NO goto. I'm very likely to refuse a patch if it makes use of goto. If you
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
79 feel the need to use goto, you need to rethink your design and flow.
684
b29c92be568b [gaim-migrate @ 694]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 639
diff changeset
80
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
81
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
82 PROGRAM FLOW
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
83 ============
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
84
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
85 Before gaim does anything you can see, it initializes itself, which is
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
86 mostly just reading .gaimrc (handled by the functions in gaimrc.c) and
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
87 parsing command-line options. It then draws the login window by calling
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
88 show_login, and waits for input.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
89
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
90 At the login window, when "Accounts" is clicked, account_editor() is
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
91 called. This then displays all of the users and various information
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
92 about them. (Don't ask about what happens when "Sign On" is called. It's
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
93 quite hackish. The only reason the login window is there anymore is to
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
94 make it more palatable to people so used to WinAIM that they can't accept
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
95 anything else.)
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
96
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
97 When the "Sign on/off" button is clicked, serv_login is passed the
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
98 username and the password for the account. If the password length is
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
99 zero (the password field is a character array rather than pointer so it
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
100 will not be NULL) then the Signon callback will prompt for the password
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
101 before calling serv_login. serv_login then signs in the user using the
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
102 appropriate protocol.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
103
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
104 After you're signed in, Gaim draws the buddy list by calling
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
105 show_buddy_list. Assuming the user has a buddy list (all buddy list
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
106 functions are controlled by list.c; when you sign on do_import is called
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
107 and that loads the locally saved list), the protocol calls
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
108 serv_got_update, which sets the information in the appropriate struct
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
109 buddy and then passes it off to set_buddy.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
110
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
111 set_buddy is responsible for a lot of stuff, but most of it is done
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
112 implicitly. It's responsible for the sounds (which is just a call to
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
113 play_sound), but the biggest thing it does is call new_group_show and
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
114 new_buddy_show if necessary. There's only one group_show per group name,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
115 even between connections, and only one buddy_show per group_show per
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
116 buddy name, even between connections. (If that's not confusing enough,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
117 wait until I really start describing how the buddy list works.)
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
118
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
119 New connections happen the exact same way as described above. Each
4491
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
120 gaim_account can have one gaim_connection associated with it. gaim_account
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
121 and gaim_connection both have a protocol field. This is kind of confusing:
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
122 gaim, except for the account editor screen and when the user signs on,
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
123 ignores the user's protocl field, and only uses the connection's protocol
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
124 field. You can change the connection's protocol field once it's created
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
125 and been assigned a PRPL to use to change certain behavior (Oscar does
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
126 this because it handles both AIM and ICQ). I'll talk about the
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
127 gaim_connection struct more later.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
128
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
129 When the user opens a new conversation window, new_conversation is called.
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
130 That's easy enough. If there isn't a conversation with the person already
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
131 open (checked by calling find_conversation), show_conv is called to
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
132 create the new window. All sorts of neat things happen there, but it's
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
133 mostly drawing the window. show_conv is the best place to edit the UI.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
134
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
135 That's pretty much it for the quick tutorial. I know it wasn't much but
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
136 it's enough to get you started. Make sure you know GTK before you get too
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
137 involved. Most of the back-end stuff is pretty basic; most of gaim is GTK.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
138
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
139
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
140 SOURCE FILES
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
141 ============
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
142
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
143 about.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
144 Not much to say here, just a few basic functions.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
145
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
146 away.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
147 This takes care of most of the away stuff: setting the away message
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
148 (do_away_message); coming back (do_im_back); drawing the away window;
1558
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
149 etc. Away messages work really oddly due to multiple connections and
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
150 multiple protocols; I think there are really only two or three people
1619
0bdc891164ad [gaim-migrate @ 1629]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1558
diff changeset
151 who know how it works and I don't think any of us know why it works
1558
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
152 that way.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
153
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
154 browser.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
155 Code for opening a browser window. Most of the code is trying to deal
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
156 with Netscape. The most important function here is open_url. Have fun.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
157
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
158 buddy.c:
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
159 This takes care of the buddy list window and most things related to it.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
160 It still has some functions that manage the list, but not many.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
161
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
162 buddy_chat.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
163 This takes care of the buddy chat stuff. This used to be a lot bigger
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
164 until the chat and IM windows got merged in the code. Now it mostly
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
165 just takes care of chat-specific stuff, like ignoring people and
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
166 keeping track of who's in the room. This is also where the chat window
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
167 is created.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
168
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
169 conversation.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
170 This is where most of the functions dealing with the IM and chat windows
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
171 are hidden. It tries to abstract things as much as possible, but doesn't
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
172 do a very good job. This is also where things like "Enter sends" and
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
173 "Ctrl-{B/I/U/S}" options get carried out (look for send_callback). The
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
174 chat and IM toolbar (with the B/I/U/S buttons) are both built from
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
175 the same function, build_conv_toolbar.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
176
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
177 core.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
178 This is the start of what will become the main() for gaim-core.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
179
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
180 dialogs.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
181 A massive file with a lot of little utility functions. This is where all
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
182 of those little dialog windows are created. Things like the warn dialog
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
183 and the add buddy dialog are here. Not all of the dialogs in gaim are in
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
184 this file, though. But most of them are. This is also where do_import
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
185 is housed, to import buddy lists. (The actual buddy list parsing code
2166
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
186 is in util.c for winaim lists and buddy.c for gaim's own lists.)
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
187
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
188 gaimrc.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
189 This controls everything about the .gaimrc file. There's not really much
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
190 to say about it; this is probably one of the better designed and easier
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
191 to follow files in gaim. The important functions are towards the bottom.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
192
1558
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
193 gtkimhtml.c:
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
194 This is gaim's HTML widget. It replaced the old widget, GtkHtml (which
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
195 was different than GNOME's GtkHTML). It's self-contained (it doesn't
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
196 use any of gaim's code) and is actually a separate project from gaim
ab5dd2c7e7f8 [gaim-migrate @ 1568]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1237
diff changeset
197 (but is maintained by Eric).
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
198
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
199 html.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
200 Don't ask my why this is called html.c. Most of it is just grab_url,
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
201 which does like the name says; it downloads a URL to show in the
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
202 GtkHTML widget. http.c would be a more appropriate name, but that's OK.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
203
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
204 idle.c:
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
205 This file used to be entirely #if 0'd out of existance. However, thanks
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
206 to some very generous people who submitted patches, this takes care of
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
207 reporting idle time (imagine that). It's a pretty straight-forward file.
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
208 This also takes care of the auto-away stuff.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
209
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
210 list.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
211 This file contains all of the routines for managing buddy lists,
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
212 including importing them from a file, saving them, adding and removing
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
213 buddies and groups, etc.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
214
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
215 main.c:
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
216 This is where the main() function is. It takes care of a lot of the
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
217 initialization stuff, and showing the login window. It's pretty tiny
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
218 and there's not really much to edit in it. This has some of the most
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
219 pointless functions, like gaim_setup, which optionally turns off sounds
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
220 on signon. A lot of this file should actually be part of other files.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
221
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
222 md5.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
223 Oscar, Yahoo, and MSN all require md5 hashing, so better to put it in
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
224 the core than have the same thing in three different places.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
225
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
226 module.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
227 This contains all of the plugin code, except for the UI. This is what
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
228 actually loads the plugins, makes sure they're valid, has the code for
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
229 setting up plugin event handlers, and contains the plugin_event method
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
230 that gaim calls on events.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
231
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
232 multi.c:
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
233 This is the file that tries to take care of most of the major issues
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
234 with multiple connections. The best function in here by far is the
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
235 account_editor(). auto_login() is also in here (I'm just reading multi.h
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
236 now...). account_editor is really the only function that the UI needs
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
237 to be concerned with.
979
ae6d13c11570 [gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 960
diff changeset
238
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
239 perl.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
240 This was basically copied straight from X-Chat through the power of
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
241 the GPL. Perl is the biggest, most confusing piece of C code I've ever
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
242 seen in my life (and keep in mind I'm a gaim hacker). I have a basic
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
243 idea of what's going on in it, but I couldn't tell you exactly. The
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
244 top half sets up perl and tells it what's going on and the bottom half
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
245 implements the AIM module.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
246
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
247 prefs.c:
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
248 The important function in here is build_prefs, but the most useful
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
249 function is gaim_button. build_prefs draws the window, and calls
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
250 gaim_button probably 30 or 40 times. (I don't really wanna run grep
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
251 | wc to count.) This is where you add the toggle button for gaim
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
252 preferences. It's very simple, and if you look at a couple of the
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
253 calls to gaim_button you'll figure it out right away. The new prefs
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
254 window uses a CList instead of a Notebook, and there's a pretty bad
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
255 hack to get it to work. I won't tell you what though.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
256
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
257 proxy.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
258 Adam (of libfaim glory) got bored one day and rewrote this file, so
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
259 now everything actually works. The main function is proxy_connect,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
260 which figures out which proxy you want to use (if you want to use one
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
261 at all) and passes off the data to the appropriate function. This file
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
262 should be pretty straight-forward.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
263
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
264 prpl.c:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
265 This file is what lets gaim dynamically load protocols, sort of. All
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
266 of the actual dlopen(), dlsym() stuff is in module.c. But this contains
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
267 all of the functions that the protocol plugin needs to call, and manages
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
268 all of the protocols. It's a pretty simple file actually.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
269
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
270 server.c:
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
271 This is where all of the differentiation between the different protocols
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
272 is done. Nearly everything that's network related goes through here
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
273 at one point or another. This has good things like serv_send_im and
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
274 serv_got_update. Most of it should be pretty self-explanatory.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
275
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
276 sound.c:
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
277 The main function in this file is play_sound, which plays one of 8
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
278 (maybe 9?) sounds based on preferences. All that the rest of the code
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
279 should have to do is call play_sound(BUDDY_ARRIVE), for example, and
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
280 this file will take care of determining if a sound should be played
1038
daad2440a642 [gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 980
diff changeset
281 and which file should be played.
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
282
4586
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
283 util.c:
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
284 There's not really a lot of cohesion to this file; it's just a lot of
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
285 stuff that happened to be thrown into it for no apparent reason. None
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
286 of it is particularly tasty; it's all just utility functions. Just
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
287 like the name says.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
288
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
289 plugins/ticker/gtkticker.c:
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
290 Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
291 widget. It's cool, and it's tiny. This is actually a really good example
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
292 widget for those of you looking to write your own.
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
293
c7986b4d182a [gaim-migrate @ 4870]
Luke Schierer <lschiere@pidgin.im>
parents: 4491
diff changeset
294 plugins/ticker/ticker.c:
639
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
295 Syd is just so cool. I really can't get over it. He let me come
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
296 visit him at Netscape one day, and I got to see all of their toys
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
297 (don't worry, I'm under an NDA). Anyway, this file is for the buddy
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
298 ticker. This is also a damn cool file because it's got all of the
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
299 functions that you'd want right up at the top. Someday I want to be
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
300 as cool as Syd.
9a01b3fb1a9d [gaim-migrate @ 649]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
diff changeset
301
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
302 For the PRPLs, the only protocol whose "main" gaim file isn't the same as
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
303 the name of the protocol is ICQ; for that it's gaim_icq.c. But ICQ is
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
304 deprecated and you should be using Oscar for ICQ anyway.
1653
7fc1a25e567b [gaim-migrate @ 1663]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1619
diff changeset
305
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
306 HOW BUDDY LISTS WORK
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
307 ====================
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
308
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
309 The buddy list is a pain in the ass. Let me start off by saying that. The
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
310 most difficult part about getting gaim to do multiple connections was
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
311 the buddy list. In its current state it's very much like the UI for
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
312 0.10.x and earlier, which is what I was aiming for. However, the code
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
313 is completely different. And not much better.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
314
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
315 There are two parts to the buddy list: the lists for the connections and
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
316 the Buddy List window. list.c contains code to manage the lists themselves
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
317 and buddy.c contains the code for the Buddy List window.
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
318
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
319 Each buddy needs to belong to a connection, it cannot belong to a
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
320 "protocol" like in EveryBuddy. The reason is because when you are adding
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
321 buddies, you tell the server who is on your buddy list so it can tell you
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
322 about them; in order to tell the server, it needs to go out over a
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
323 connection. Going out over all connections would not be good, so you need
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
324 to specify which connection they go out on.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
325
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
326 Managing lists is therefore fairly easy, each group and buddy has an
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
327 associated connection. Management functions like add_buddy/remove_buddy
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
328 and add_group/remove_group all take a gaim_connection. These are all in
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
329 list.c. They're boring.
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
330
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
331 The window is a lot more fun. There's really only one function that
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
332 does anything interesting, and that's set_buddy. (There's also things
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
333 like build_edit_tree, but that's boring.) set_buddy is called by
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
334 serv_got_update (and should only be called by that function) any time
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
335 a user signs on, signs off, goes away, comes back, goes idle, etc, etc,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
336 etc. Various things happen depending on the new state of the buddy.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
337
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
338 struct buddy has a member, present, which is set to either 0, 1, or
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
339 2. You can check if the buddy is online with "if (b->present)". This
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
340 becomes important. present is set to either 0 or 1 by serv_got_update,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
341 or is not set at all. When the buddy is passed to set_buddy, if present
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
342 is 1 then set_buddy plays the BUDDY_ARRIVE sound, and sets present to 2,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
343 to indicate it has already received notification of arrival. It then
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
344 does other signin-related stuff: setting the pixmap to the login icon;
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
345 updating the conversation windows; etc.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
346
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
347 The most important thing it does though, if a buddy is present, is it
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
348 checks for the existance of the appropriate group_show and buddy_show for
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
349 that buddy. Each buddy must belong to a group. group_shows are based on
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
350 name; there can only be one group_show for each group name. buddy_shows
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
351 are based both on name and on group_show; there can only be one buddy_show
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
352 in a group_show for each name. However, there can be two buddy_shows
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
353 with the same name as long as they have different group_shows.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
354
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
355 Each buddy_show has a GList of connections that has registered its related
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
356 buddy as being online. set_buddy makes sure that the connection that it's
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
357 being passed is part of the connlist for the buddy_show associated with
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
358 the struct buddy that it's passed (it helps to know your data structures).
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
359
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
360 If a buddy logs off (b->present == 0), and a buddy_show exists for
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
361 that buddy, then set_buddy will play the logoff sound, change the icon,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
362 remove the connection from the connlist for the buddy_show, etc.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
363
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
364 And that's how that works. For the buddy lists, connections own buddies;
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
365 for the window, the buddies own the connections. When the buddy_show
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
366 connlist count drops to zero it disappears from existance.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
367
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
368
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
369 PLUGINS
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
370 =======
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
371
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
372 OK, so you want to load a plugin. You go through whatever UI (you
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
373 can read all about the UI in plugins.c or whereever). You finally get
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
374 to load_plugin, the meat of the plugins stuff (plugins can actually
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
375 call load_plugin themselves to load other plugins). load_plugin
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
376 is passed the full path to the plugin you want to load
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
377 (e.g. /usr/local/lib/gaim/irc.so).
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
378
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
379 load_plugin does a few things with that filename. The first is to see
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
380 if you've already loaded that plugin. If you have, load_plugin unloads
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
381 the one that is currently loaded. You might wonder why; it's because
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
382 the same plugin can't be loaded twice. If you call g_module_open on a
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
383 filename twice, both times it will return the same pointer, and both times
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
384 increment the reference count on the GModule * that it returns. This
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
385 means you really do have the same plugin twice, which fucks up the
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
386 callback system to no end. So it's better that you can only have it
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
387 loaded once at any given time.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
388
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
389 Now that we're assured that we don't have this particular plugin loaded
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
390 yet, we better load it. g_module_open, baby. Much more portable than
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
391 dlopen(). In fact, for Linux it actually is the equivalent of dlopen()
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
392 (you can read the gmodule source and see for yourself). There's only one
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
393 quirk. It always logically ORs the options you pass with RTLD_GLOBAL,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
394 which means that plugins share symbols. I haven't figured out yet if
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
395 this means just functions or variables too; but in either case make every
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
396 function and variable in your plugin static except for gaim_plugin_*(),
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
397 name(), and description(). It's good coding practice anyway.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
398
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
399 So, assuming we didn't get NULL back from g_module_open, we then make sure
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
400 it's a valid gaim plugin by looking for and calling gaim_plugin_init,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
401 courtesy g_module_symbol (g_module_symbol is actually what's portable
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
402 about gmodule as opposed to dl*; some BSD's require '_' prepended to
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
403 symbol names and g_module_symbol guarantees we do The Right Thing).
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
404
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
405 Assuming we've found gaim_plugin_init and it hasn't returned non-NULL
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
406 to us, we then add it to our list of plugins and go merrily about our way.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
407
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
408 So when do the callbacks happen?! plugin_event, baby, plugin_event. Any
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
409 time you want to trigger a plugin event simply call plugin_even with the
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
410 parameters to be passed to any event handlers and you're set. plugin_event
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
411 then makes sure that any plugins waiting for the event get passed the
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
412 arguments properly and passes it on to perl.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
413
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
414 Speaking of perl. If you really want to know how this works, you're
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
415 better off reading X-Chat's documentation of it, because it's better
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
416 than what I could provide.
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
417
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
418
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
419 MULTIPLE CONNECTIONS AND PRPLS
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
420 ==============================
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
421
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
422 OK, let's start with the basics. There are users. Each user is contained
4491
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
423 in an gaim_account struct, and kept track of in the gaim_accounts GSList.
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
424 Each gaim_account has certain features: a username, a password, and
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
425 user_info. It also has certain options, and the protocol it uses to sign
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
426 on (kept as an int which is #define'd in prpl.h).
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
427
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
428 Now then, there are protocols that gaim knows about. Each protocol is
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
429 in a prpl struct and kept track of in the protocols GSList. The way the
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
430 management of the protocols is, there will only ever be one prpl per
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
431 numeric protocol. Each prpl defines a basic set of functions: login,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
432 logout, send_im, etc. The prpl is responsible not only for handling
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
433 these functions, but also for calling the appropriate serv_got functions
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
434 (e.g. serv_got_update when a buddy comes online/goes offline/goes
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
435 idle/etc). It handles each of these on a per-connection basis.
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
436
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
437 So why's it called a PRPL? It stands for PRotocol PLugin. That means
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
438 that it's possible to dynamically add new protocols to gaim. However,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
439 all protocols must be implemented the same way: by using a prpl struct
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
440 and being loaded, regardless of whether they are static or dynamic.
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
441
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
442 Here's how struct gaim_connection fits into all of this. At some point
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
443 the User (capitalized to indicate a person and not a name) will try to
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
444 sign on one of Their users. serv_login is then called for that user. It
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
445 searches for the prpl that is assigned to that user, and calls that prpl's
4491
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
446 login function, passing it the gaim_account struct that is attempting to
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
447 sign on. The prpl is then responsible for seeing that the gaim_connection
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
448 is created (by calling new_gaim_connection), and registering it as
4491
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
449 being online (by calling account_online and passing it the gaim_account and
3196d9044a45 [gaim-migrate @ 4766]
Nathan Walp <nwalp@pidgin.im>
parents: 2863
diff changeset
450 gaim_connection structs). At that point, the gaim_account and gaim_connection
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
451 structs have pointers to each other, and the gaim_connection struct has
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
452 a pointer to the prpl struct that it is using. The gaim_connections are
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
453 stored in the connections GSList. The way connection management works is,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
454 there will always only be one gaim_connection per user, and the prpl that
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
455 the gaim_connection uses will be constant for the gaim_connection's life.
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
456
1237
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
457 So at certain points the User is going to want to do certain things,
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
458 like send a message. They must send the message on a connection. So the UI
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
459 figures out which gaim_connection the User want to send a message on (for
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
460 our example), and calls serv_send_im, telling it which gaim_connection to
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
461 use, and the necessary information (who to send it to, etc). The serv_
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
462 function then calls the handler of the prpl of the connection for that
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
463 event (that was way too many prepositions). OK, each prpl has a send_im
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
464 function. Each connection has a prpl. so you call gc->prpl->send_im and
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
465 pass it the connection and all the necessary info. And that's how things
72692c70317e [gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1099
diff changeset
466 get done.
1063
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
467
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
468 I hope some of that made sense. Looking back at it it makes absolutely no
e1408fb04c36 [gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 1038
diff changeset
469 sense to me. Thank god I wrote the code; otherwise I'm sure I'd be lost.
2166
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
470
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
471
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
472 WRITING PRPLS
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
473 =============
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
474
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
475 Start off with a protocol that you want to implement; make sure it has a
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
476 number defined in prpl.h. If it doesn't, talk to Rob or Eric about adding
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
477 it. *NEVER* use an unassigned number, not even for testing or personal
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
478 use. It's possible that number will be used later by something else and
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
479 that would cause quite a few head-scratchers.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
480
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
481 Start off with the following boiler plate:
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
482
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
483 static struct prpl *my_protocol = NULL;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
484
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
485 void newproto_init(struct prpl *ret) {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
486 ret->protocol = PROTO_NEWPROTO;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
487
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
488 my_protocol = ret;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
489 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
490
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
491 #ifndef STATIC
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
492
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
493 char *gaim_plugin_init(GModule *handle)
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
494 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
495 load_protocol(newproto_init, sizeof(struct prpl));
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
496 return NULL;
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
497 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
498
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
499 void gaim_plugin_remove()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
500 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
501 struct prpl *p = find_prpl(PROTO_NEWPROTO);
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
502 if (p == my_protocol)
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
503 unload_protocol(p);
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
504 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
505
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
506 char *name()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
507 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
508 return "New Protocol";
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
509 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
510
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
511 char *description()
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
512 {
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
513 return PRPL_DESC("New Protocol");
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
514 }
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
515
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
516 #endif
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
517
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
518 Replace all NEWPROTO things with your protocol name (e.g. PROTO_OSCAR
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
519 instead of PROTO_NEWPROTO, oscar_init instead of newproto_init). Then
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
520 populate your struct prpl; the most important function is actually name(),
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
521 because without it, Gaim will most likely segfault. The second most
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
522 important function is login(). Not all functions need to be implemented.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
523
2166
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
524 There should be absolutely *ZERO* GTK in the PRPLs. PRPLs should *NEVER*
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
525 say what the UI *looks* like, only what information needs to be there.
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
526 There's currently an effort to get the GTK that is contained in the PRPLs
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
527 directory out of there. If you submit a patch that adds GTK to those
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
528 directories it's very likely to be refused, unless if I'm in a good mood
dbd74f49dabb [gaim-migrate @ 2176]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2150
diff changeset
529 and decide to relocate things for you. That's not likely.
2863
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
530
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
531 You're probably wondering how you can do certain things without GTK. Well,
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
532 you're just going to have to make do. Rely on the UI, that's why it's
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
533 there. A PRPL should have absolutely ZERO interaction with the user, it
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
534 should all be handled by the UI.
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
535
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
536 Don't use the _options variables at all. The core should take care of all
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
537 of that. There are several proto_opt fields that you can use on a per-user
0e70fe072ab4 [gaim-migrate @ 2876]
Eric Warmenhoven <eric@warmenhoven.org>
parents: 2655
diff changeset
538 basis. Check out existing protocols for more details.