Mercurial > pidgin.yaz
annotate HACKING @ 1333:b332d8f46b84
[gaim-migrate @ 1343]
oo, a fun new register button. oh yeah, and the buddy list stuff got moved back from toc.c to buddy.c. isn't that nice. now you can remove toc.c and rvous.c, comment out one line in prpl.c, and get rid of toc altogether. but you won't do that.
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Wed, 20 Dec 2000 13:24:48 +0000 |
parents | 72692c70317e |
children | ab5dd2c7e7f8 |
rev | line source |
---|---|
639 | 1 A lot of people have tried to hack gaim, but haven't been able to because |
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 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
7 connections and multiple protocols work. Depending on how much I want |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
8 to avoid my final tomorrow I may even describe other parts of gaim that |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
9 I particularly want to brag about. Hopefully that's enough to get most |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
10 of you going. |
639 | 11 |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
12 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
|
13 against the absolute latest CVS. I get really annoyed when I get patches |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
14 against the last released version, especially since I don't usually |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
15 have 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
|
16 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
|
17 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
|
18 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
|
19 run the following commands: |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
20 |
774
b61607d6c2af
[gaim-migrate @ 784]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
749
diff
changeset
|
21 $ export CVSROOT=:pserver:anonymous@cvs.gaim.sourceforge.net:/cvsroot/gaim |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
22 $ cvs login (hit enter as the password) |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
23 $ cvs co gaim |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
24 (you'll see it getting all of the files) |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
25 $ cd gaim |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
26 $ ./gen |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
27 |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
28 You'll now have your normal gaim tree with ./configure and all. (If you |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
29 want to make your life really simple, learn how CVS works. CVS is your |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
30 friend.) To make a patch, just edit the files right there in that tree |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
31 (don't bother with two trees, or even two copies of the same file). Then |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
32 when you're ready to make your patch, simply run 'cvs diff -u >my.patch' |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
33 and send it off. |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
34 |
639 | 35 There's one little thing that's just a pet peeve, and it's really stupid. |
706
a9758452f3c4
[gaim-migrate @ 716]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
684
diff
changeset
|
36 In ./configure there's an --enable-debug option. This does two things: |
639 | 37 compiles with -Wall, and prints debugging information to stdout. The |
38 debugging information is printed to the debug window (which can be turned | |
39 on in the preferences) whether or not --enable-debug was selected. Most | |
40 of the information that's printed is useless anyway though; so the | |
41 --enable-debug option really doesn't do a whole lot. | |
42 | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
43 This file was last modified by $Author: warmenhoven $ on |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
44 $Date: 2000-12-12 07:56:53 -0500 (Tue, 12 Dec 2000) $. |
684
b29c92be568b
[gaim-migrate @ 694]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
639
diff
changeset
|
45 |
639 | 46 |
47 PROGRAM FLOW | |
48 ============ | |
49 | |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
50 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
|
51 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
|
52 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
|
53 show_login, and waits for input. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
54 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
55 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
|
56 called. This then displays all of the users and various information |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
57 about them. If the user clicks the "Signon" button instead, serv_login |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
58 is called. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
59 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
60 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
|
61 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
|
62 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
|
63 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
|
64 before calling serv_login. serv_login then signs in the user using the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
65 appropriate protocol. We'll assume TOC for the rest of this discussion; |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
66 even the libfaim guys get scared by oscar.c, and I'll talk about the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
67 PRPLs later. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
68 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
69 After you're signed in (I'll skip that discussion - I doubt many people |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
70 are going to change the login process, since it pretty much just follows |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
71 PROTOCOL), Gaim draws the buddy list by calling show_buddy_list, and |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
72 waits for input from two places: the server and the user. The first |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
73 place it gets input from after signon is usually the server, when the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
74 server tells Gaim which buddies are signed on. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
75 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
76 When there is information ready to be read from the server, toc_callback |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
77 is called (by GDK) to parse the incoming information. On an UPDATE, |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
78 serv_got_update is called, which takes care of things like notifying |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
79 conversation windows of the update if need be; notifying the plugins; |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
80 and finally, calling set_buddy. |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
81 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
82 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
|
83 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
|
84 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
|
85 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
|
86 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
|
87 buddy name, even between connections. (If that's not confusing enough, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
88 wait until I really start describing how the buddy list works.) |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
89 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
90 New connections happen the exact same way as described above. Each |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
91 aim_user can have one gaim_connection associated with it. aim_user and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
92 gaim_connection both have a protocol field; gaim_connection's should |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
93 be constant once it is set. (I'll talk about the gaim_connection struct |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
94 more later.) |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
95 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
96 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
|
97 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
|
98 open (checked by calling find_conversation), show_conv is called to |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
99 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
|
100 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
|
101 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
102 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
|
103 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
|
104 involved. Most of the back-end stuff is pretty basic; most of gaim is GTK. |
639 | 105 |
106 | |
107 SOURCE FILES | |
108 ============ | |
109 | |
110 about.c: | |
111 Not much to say here, just a few basic functions. | |
112 | |
113 aim.c: | |
114 This is where the main() function is. It takes care of a lot of the | |
115 initialization stuff, and showing the login window. It's pretty tiny | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
116 and there's not really much to edit in it. This has some of the most |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
117 pointless functions, like gaim_setup, which optionally turns off sounds |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
118 on signon. A lot of this file should actually be part of other files. |
639 | 119 |
120 away.c: | |
121 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
|
122 (do_away_message); coming back (do_im_back); drawing the away window; |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
123 etc. |
639 | 124 |
125 browser.c: | |
126 Code for opening a browser window. Most of the code is trying to deal | |
127 with Netscape. The most important function here is open_url. Have fun. | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
128 (This file may give you problems with GTK 2.0, because it uses parts |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
129 of GDK that it's not supposed to know about.) |
639 | 130 |
131 buddy.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
132 This takes care of not only nearly everything buddy-related (the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
133 buddy lists, the window, etc.), but also a lot of the code flow and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
134 util functions. Look for good things like find_buddy, set_buddy, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
135 and signoff here. |
639 | 136 |
137 buddy_chat.c: | |
138 This takes care of the buddy chat stuff. This used to be a lot bigger | |
139 until the chat and IM windows got merged in the code. Now it mostly | |
140 just takes care of chat-specific stuff, like ignoring people and | |
141 keeping track of who's in the room. This is also where the chat window | |
142 is created. | |
143 | |
144 conversation.c: | |
145 This is where most of the functions dealing with the IM and chat windows | |
146 are hidden. It tries to abstract things as much as possible, but doesn't | |
147 do a very good job. This is also where things like "Enter sends" and | |
148 "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
|
149 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
|
150 the same function, build_conv_toolbar. |
639 | 151 |
152 dialogs.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
153 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
|
154 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
|
155 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
|
156 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
|
157 is housed, to import buddy lists. (The actual buddy list parsing code |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
158 is in util.c for winaim lists and toc.c for gaim's own lists.) |
639 | 159 |
160 gaimrc.c: | |
161 This controls everything about the .gaimrc file. There's not really much | |
162 to say about it; this is probably one of the better designed and easier | |
163 to follow files in gaim. The important functions are towards the bottom. | |
164 | |
165 gnome_applet_mgr.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
166 This controls most things that are related to the applet. I don't like |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
167 looking at this file because it still has functionsLikeThis. But at |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
168 least it doesn't have many of them anymore. Anyway, this file isn't |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
169 very big because there's really not much difference between the panel |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
170 version and the app version. |
639 | 171 |
172 gtkhtml.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
173 This is really just one big hack. I recommend not looking at this |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
174 file if you want to save your sanity. (It's going to be replaced |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
175 eventually anyway.) People have asked why we don't replace this with |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
176 GNOME's GtkHTML, or embed mozilla (yes, they were serious). There |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
177 are two reasons. The first is that doing that would cause gaim to |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
178 require 6 extra libraries that nobody needs or wants or has. The |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
179 second is that we really don't need, or even want, a full-fledged |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
180 HTML viewer. We don't even want a normal HTML viewer because the text |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
181 that gets sent gets parsed and displayed different than normal HTML. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
182 (Try inserting a newline and you'll see what I mean.) We should only |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
183 support about 12 tags, not the 50 that normal HTML supports. |
639 | 184 |
185 gtkticker.c: | |
186 Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that | |
187 widget. It's cool, and it's tiny. | |
188 | |
189 html.c: | |
190 Don't ask my why this is called html.c. Most of it is just grab_url, | |
191 which does like the name says; it downloads a URL to show in the | |
192 GtkHTML widget. http.c would be a more appropriate name, but that's OK. | |
193 | |
194 idle.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
195 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
|
196 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
|
197 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
|
198 This also takes care of the auto-away stuff. |
639 | 199 |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
200 multi.c: |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
201 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
|
202 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
|
203 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
|
204 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
|
205 to be concerned with. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
206 |
639 | 207 oscar.c: |
208 One big hack of copied code. This is supposed to be the libfaim tie-in | |
209 in gaim. Most of it is just copied straight from faimtest, the small | |
210 program that comes with libfaim. I'm not even sure how half of it works, | |
211 if that makes you feel any better. | |
212 | |
213 perl.c: | |
214 This was basically copied straight from X-Chat through the power of | |
215 the GPL. Perl is the biggest, most confusing piece of C code I've ever | |
216 seen in my life (and keep in mind I'm a gaim hacker). I have a basic | |
217 idea of what's going on in it, but I couldn't tell you exactly. The | |
218 top half sets up perl and tells it what's going on and the bottom half | |
219 implements the AIM module. | |
220 | |
221 plugins.c: | |
222 This is the "plugin plug", as the file states. This file is probably | |
223 the only file in all of gaim that at the top has all of the functions | |
224 and global and static variables named out for you. It makes reading | |
225 it a little easier, but not by much. A lot of the code in here deals | |
226 with the plugin window rather than the plugins themselves. | |
227 | |
228 prefs.c: | |
229 The important function in here is build_prefs, but the most useful | |
230 function is gaim_button. build_prefs draws the window, and calls | |
231 gaim_button probably 30 or 40 times. (I don't really wanna run grep | |
232 | wc to count.) This is where you add the toggle button for gaim | |
233 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
|
234 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
|
235 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
|
236 hack to get it to work. I won't tell you what though. |
639 | 237 |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
238 prpl.c: |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
239 This file is what lets gaim dynamically load protocols, sort of. All |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
240 of the actual dlopen(), dlsym() stuff is in plugins.c. But this |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
241 contains all of the functions that the protocol plugin needs to call, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
242 and manages all of the protocols. It's a pretty simple file actually. |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
243 |
639 | 244 proxy.c: |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
245 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
|
246 now everything actually works. The main function is proxy_connect, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
247 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
|
248 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
|
249 should be pretty straight-forward. |
639 | 250 |
251 rvous.c: | |
252 This was originally going to be the stuff for all of the Buddy Icon | |
253 and Voice Chat stuff, but I got really sick of protocol hacking really | |
254 quick. Now it only houses the file transfer stuff, which only works | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
255 for TOC. ("Works" being a very subjective statement. This file needs |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
256 to be rewritten.) |
639 | 257 |
258 server.c: | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
259 This is where all of the differentiation between the different protocols |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
260 is done. Nearly everything that's network related goes through here |
639 | 261 at one point or another. This has good things like serv_send_im and |
262 serv_got_update. Most of it should be pretty self-explanatory. | |
263 | |
264 sound.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
265 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
|
266 (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
|
267 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
|
268 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
|
269 and which file should be played. |
639 | 270 |
271 ticker.c: | |
272 Syd is just so cool. I really can't get over it. He let me come | |
273 visit him at Netscape one day, and I got to see all of their toys | |
274 (don't worry, I'm under an NDA). Anyway, this file is for the buddy | |
275 ticker. This is also a damn cool file because it's got all of the | |
276 functions that you'd want right up at the top. Someday I want to be | |
277 as cool as Syd. | |
278 | |
279 toc.c: | |
280 This handles everything TOC-related, including parsing gaim's buddy | |
281 list. Most of this file is toc_callback, which parses the incoming | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
282 information from the server. I really don't like TOC though. (I've spent |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
283 waaayyyy too much time with TOC. I rewrote the signon process for this |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
284 file at one point, so that read was only called when data was pending. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
285 Since then the TOC server has been blocking my IP (probably my own |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
286 stupid fault, sending bad strings or some such).) |
639 | 287 |
288 util.c: | |
289 There's not really a lot of cohesion to this file; it's just a lot of | |
290 stuff that happened to be thrown into it for no apparent reason. None | |
291 of it is particularly tasty; it's all just utility functions. Just | |
292 like the name says. | |
293 | |
294 | |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
295 HOW THE BUDDY LIST WORKS |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
296 ======================== |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
297 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
298 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
|
299 most difficult part about getting gaim to do multiple connections was |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
300 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
|
301 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
|
302 is completely different. And not much better. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
303 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
304 All of the buddy list stuff is in buddy.c, so you'll only have to have |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
305 that one file open (and possibly gaim.h for the struct definitions). There |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
306 are two sets of functions: those that deal with the buddy lists, and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
307 those that deal with the window. (I say lists because each connection |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
308 has their own buddy list, independent of the others, even though the UI |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
309 merges them.) |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
310 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
311 The buddy list functions work pretty much the same way they did before; |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
312 except now that each buddy and group belongs to a connection, things |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
313 like find_buddy take an additional argument, the connection you want to |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
314 search for the buddy in. Read gaim.h for a good list of them: find_buddy, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
315 find_group, add_buddy, remove_buddy, remove_group. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
316 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
317 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
|
318 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
|
319 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
|
320 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
|
321 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
|
322 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
|
323 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
324 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
|
325 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
|
326 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
|
327 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
|
328 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
|
329 to indicate it has already received notification of arrival. It then |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
330 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
|
331 updating the conversation windows; etc. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
332 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
333 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
|
334 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
|
335 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
|
336 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
|
337 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
|
338 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
|
339 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
|
340 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
341 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
|
342 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
|
343 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
|
344 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
|
345 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
346 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
|
347 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
|
348 remove the connection from the connlist for the buddy_show, etc. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
349 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
350 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
|
351 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
|
352 connlist count drops to zero it disappears from existance. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
353 |
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 PLUGINS |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
356 ======= |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
357 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
358 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
|
359 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
|
360 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
|
361 call load_plugin themselves to load other plugins). load_plugin |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
362 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
|
363 (e.g. /usr/local/lib/gaim/irc.so). |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
364 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
365 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
|
366 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
|
367 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
|
368 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
|
369 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
|
370 increment the reference count on the GModule * that it returns. This |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
371 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
|
372 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
|
373 loaded once at any given time. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
374 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
375 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
|
376 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
|
377 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
|
378 (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
|
379 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
|
380 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
|
381 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
|
382 function and variable in your plugin static except for gaim_plugin_*(), |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
383 name(), and description(). It's good coding practice anyway. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
384 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
385 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
|
386 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
|
387 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
|
388 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
|
389 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
|
390 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
391 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
|
392 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
|
393 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
394 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
|
395 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
|
396 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
|
397 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
|
398 arguments properly and passes it on to perl. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
399 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
400 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
|
401 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
|
402 than what I could provide. |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
403 |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
404 |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
405 MULTIPLE CONNECTIONS AND PRPLS |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
406 ============================== |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
407 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
408 OK, let's start with the basics. There are users. Each user is contained |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
409 in an aim_user struct, and kept track of in the aim_users GList (GSList?). |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
410 Each aim_user has certain features: a username, a password, and user_info. |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
411 It also has certain options, and the protocol it uses to sign on (kept |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
412 as an int which is #define'd in prpl.h). The way the management of the |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
413 users works is, there will (hopefully) only be one user for a given |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
414 screenname/ protocol pair (i.e. you may have two user warmenhoven's, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
415 but they'll both have a different protocol number). |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
416 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
417 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
|
418 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
|
419 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
|
420 numeric protocol. Each prpl defines a basic set of functions: login, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
421 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
|
422 these functions, but also for calling the appropriate serv_got functions |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
423 (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
|
424 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
|
425 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
426 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
|
427 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
|
428 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
|
429 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
|
430 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
431 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
|
432 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
|
433 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
|
434 searches for the prpl that is assigned to that user, and calls that prpl's |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
435 login function, passing it the aim_user struct that is attempting to sign |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
436 on. The prpl is then responsible for seeing that the gaim_connection |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
437 is created (by calling new_gaim_connection), and registering it as |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
438 being online (by calling account_online and passing it the aim_user and |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
439 gaim_connection structs). At that point, the aim_user and gaim_connection |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
440 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
|
441 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
|
442 stored in the connections GSList. The way connection management works is, |
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
443 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
|
444 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
|
445 |
1237
72692c70317e
[gaim-migrate @ 1247]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1099
diff
changeset
|
446 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
|
447 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
|
448 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
|
449 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
|
450 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
|
451 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
|
452 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
|
453 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
|
454 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
|
455 get done. |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
456 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
457 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
|
458 sense to me. Thank god I wrote the code; otherwise I'm sure I'd be lost. |