Mercurial > pidgin
annotate HACKING @ 1092:a930439f29b1
[gaim-migrate @ 1102]
fun fun
committer: Tailor Script <tailor@pidgin.im>
author | Eric Warmenhoven <eric@warmenhoven.org> |
---|---|
date | Mon, 13 Nov 2000 04:29:41 +0000 |
parents | e1408fb04c36 |
children | 4416ead31db7 |
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 | |
3 soon, so to help all you would-be hackers help out gaim, here's a brief | |
4 tutorial on how gaim works. I'll quickly describe the logical flow of | |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
5 things, then what you'll find in each of the source files. As an added |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
6 bonus, I'll try and describe as best I can how multiple connections and |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
7 multiple protocols work. Hopefully that's enough to get most of you going. |
639 | 8 |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
9 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
|
10 against the absolute latest CVS. I get really annoyed when I get patches |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
11 against the last released version, especially since I don't usually have |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
12 a copy of it on my computer, and gaim tends to change a lot between |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
13 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
|
14 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
|
15 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
|
16 run the following commands: |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
17 |
774
b61607d6c2af
[gaim-migrate @ 784]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
749
diff
changeset
|
18 $ export CVSROOT=:pserver:anonymous@cvs.gaim.sourceforge.net:/cvsroot/gaim |
708
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
19 $ cvs login |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
20 (hit enter as the password) |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
21 $ cvs co gaim |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
22 (you'll see it getting all of the files) |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
23 $ cd gaim |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
24 $ ./gen |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
25 |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
26 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
|
27 want to make your life really simple, learn how CVS works. CVS is your |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
28 friend.) |
3ff8b997cd37
[gaim-migrate @ 718]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
706
diff
changeset
|
29 |
639 | 30 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
|
31 In ./configure there's an --enable-debug option. This does two things: |
639 | 32 compiles with -Wall, and prints debugging information to stdout. The |
33 debugging information is printed to the debug window (which can be turned | |
34 on in the preferences) whether or not --enable-debug was selected. Most | |
35 of the information that's printed is useless anyway though; so the | |
36 --enable-debug option really doesn't do a whole lot. | |
37 | |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
38 This file was last modified by $Author: warmenhoven $ on $Date: 2000-11-03 22:08:54 -0500 (Fri, 03 Nov 2000) $. |
684
b29c92be568b
[gaim-migrate @ 694]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
639
diff
changeset
|
39 |
639 | 40 |
41 PROGRAM FLOW | |
42 ============ | |
43 | |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
44 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
|
45 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
|
46 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
|
47 show_login, and waits for input. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
48 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
49 At the login window, when "Accounts" is clicked, account_editor() is |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
50 called. This then displays all of the users and various information about |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
51 them. If the user clicks the "Signon" button instead, serv_login is called. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
52 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
53 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
|
54 username and the password for the account. If the password length is |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
55 zero (the password field is a character array rather than pointer so |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
56 it will not be NULL) then the Signon callback will prompt for the |
980
82c5865f7cfe
[gaim-migrate @ 990]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
979
diff
changeset
|
57 password before calling serv_login. serv_login then signs in the user |
82c5865f7cfe
[gaim-migrate @ 990]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
979
diff
changeset
|
58 using the appropriate protocol. We'll assume TOC for the rest of this |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
59 discussion; Oscar has a lot of bad hacks to get it working that I don't |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
60 even want to think about. |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
61 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
62 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
|
63 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
|
64 PROTOCOL), Gaim draws the buddy list by calling show_buddy_list, and |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
65 waits for input from two places: the server and the user. The first place |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
66 it gets input from after signon is usually the server, when the server |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
67 tells Gaim which buddies are signed on. |
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 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
|
70 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
|
71 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
|
72 conversation windows of the update if need be; notifying the plugins; |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
73 and finally, calling set_buddy. |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
74 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
75 New connections happen the exact same way as described above. Each aim_user |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
76 can have one gaim_connection associated with it. aim_user and gaim_connection |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
77 both have a protocol field; gaim_connection's should be constant once it is |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
78 set in the appropriate (protocol)_login function. There are lots of details |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
79 that are connected with multiple connections that are best explained by |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
80 reading the code. |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
81 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
82 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
|
83 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
|
84 open (checked by calling find_conversation), show_conv is called to |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
85 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
|
86 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
|
87 |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
88 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
|
89 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
|
90 involved. Most of the back-end stuff is pretty basic; most of gaim is GTK. |
639 | 91 |
92 | |
93 SOURCE FILES | |
94 ============ | |
95 | |
96 about.c: | |
97 Not much to say here, just a few basic functions. | |
98 | |
99 aim.c: | |
100 This is where the main() function is. It takes care of a lot of the | |
101 initialization stuff, and showing the login window. It's pretty tiny | |
102 and there's not really much to edit in it. Watch out for bad Oscar | |
103 sign in hacks. | |
104 | |
105 away.c: | |
106 This takes care of most of the away stuff: setting the away message | |
107 (do_im_away); coming back (do_im_back); drawing the away window; | |
108 etc. To be honest I haven't looked at this file in months. | |
109 | |
110 browser.c: | |
111 Code for opening a browser window. Most of the code is trying to deal | |
112 with Netscape. The most important function here is open_url. Have fun. | |
113 | |
114 buddy.c: | |
115 This takes care of not only nearly everything buddy-related (the buddy | |
116 list, the permit/deny lists, and the window), but also a lot of the | |
117 code flow and util functions. Look for good things like find_buddy, | |
118 set_buddy, and signoff() here. | |
119 | |
120 buddy_chat.c: | |
121 This takes care of the buddy chat stuff. This used to be a lot bigger | |
122 until the chat and IM windows got merged in the code. Now it mostly | |
123 just takes care of chat-specific stuff, like ignoring people and | |
124 keeping track of who's in the room. This is also where the chat window | |
125 is created. | |
126 | |
127 conversation.c: | |
128 This is where most of the functions dealing with the IM and chat windows | |
129 are hidden. It tries to abstract things as much as possible, but doesn't | |
130 do a very good job. This is also where things like "Enter sends" and | |
131 "Ctrl-{B/I/U/S}" options get carried out (look for send_callback). The | |
132 chat and IM toolbar (with the B/I/U/S buttons) are both built from the | |
133 same function, build_conv_toolbar. | |
134 | |
135 dialogs.c: | |
136 A massive file with a lot of little utility functions. This is where | |
137 all of those little dialog windows are created. Things like the warn | |
138 dialog and the add buddy dialog are here. Not all of the dialogs in | |
139 gaim are in this file, though. But most of them are. This is also | |
140 where do_import is housed, to import buddy lists. | |
141 | |
142 gaimrc.c: | |
143 This controls everything about the .gaimrc file. There's not really much | |
144 to say about it; this is probably one of the better designed and easier | |
145 to follow files in gaim. The important functions are towards the bottom. | |
146 | |
147 gnome_applet_mgr.c: | |
148 A hideous creation from the days before I started working on gaim. Most | |
149 of it works, but it has functionsLikeThis. I hate looking at this | |
150 file, but I'm too lazy to change the functions. The best functions | |
151 are things like set_applet_draw_open, whose sole purpose is to set a | |
749
94edd99b7302
[gaim-migrate @ 759]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
708
diff
changeset
|
152 global variable to TRUE. [ note 8/22/00 - I finally changed this file. ] |
639 | 153 |
154 gtkhtml.c: | |
155 This is really just one big hack. It started off as an HTML widget that | |
156 was written for Gnome as far as I can tell. The current version is | |
157 huge, requires way too many libs, and is too hard to upgrade to. But | |
158 we've managed to hack this poor old version into basically what we | |
159 need it for. I recommend not looking at this file if you want to save | |
160 your sanity. | |
161 | |
162 gtkticker.c: | |
163 Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that | |
164 widget. It's cool, and it's tiny. | |
165 | |
166 html.c: | |
167 Don't ask my why this is called html.c. Most of it is just grab_url, | |
168 which does like the name says; it downloads a URL to show in the | |
169 GtkHTML widget. http.c would be a more appropriate name, but that's OK. | |
170 | |
171 idle.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
172 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
|
173 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
|
174 reporting idle time (imagine that). It's a pretty straight-forward file. |
639 | 175 |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
176 multi.c: |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
177 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
|
178 with multiple connections. The best function in here by far is the |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
179 account_editor(). auto_login() is also in here (I'm just reading |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
180 multi.h now...); auto_login has problems. Someone please fix it. |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
181 account_editor is really the only function that the UI needs to be |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
182 concerned with. If you want to remove multiconnectivity from gaim, |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
183 all you would really need to do is comment out any lines that make |
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
184 reference to this function (there are only two - one in aim.c and one |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
185 in buddy.c). Or you could just run ./configure --disable-multi. |
979
ae6d13c11570
[gaim-migrate @ 989]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
960
diff
changeset
|
186 |
639 | 187 network.c: |
188 This has two functions: get_address and connect_address, both of which | |
189 call proxy functions. If you want to see how these are used, look at | |
190 toc.c and/or rvous.c. These are really just front-ends to the proxy | |
191 stuff; use these instead of calling the proxy functions. | |
192 | |
193 oscar.c: | |
194 One big hack of copied code. This is supposed to be the libfaim tie-in | |
195 in gaim. Most of it is just copied straight from faimtest, the small | |
196 program that comes with libfaim. I'm not even sure how half of it works, | |
197 if that makes you feel any better. | |
198 | |
199 perl.c: | |
200 This was basically copied straight from X-Chat through the power of | |
201 the GPL. Perl is the biggest, most confusing piece of C code I've ever | |
202 seen in my life (and keep in mind I'm a gaim hacker). I have a basic | |
203 idea of what's going on in it, but I couldn't tell you exactly. The | |
204 top half sets up perl and tells it what's going on and the bottom half | |
205 implements the AIM module. | |
206 | |
207 plugins.c: | |
208 This is the "plugin plug", as the file states. This file is probably | |
209 the only file in all of gaim that at the top has all of the functions | |
210 and global and static variables named out for you. It makes reading | |
211 it a little easier, but not by much. A lot of the code in here deals | |
212 with the plugin window rather than the plugins themselves. | |
213 | |
214 prefs.c: | |
215 The important function in here is build_prefs, but the most useful | |
216 function is gaim_button. build_prefs draws the window, and calls | |
217 gaim_button probably 30 or 40 times. (I don't really wanna run grep | |
218 | wc to count.) This is where you add the toggle button for gaim | |
219 preferences. It's very simple, and if you look at a couple of the | |
220 calls to gaim_button you'll figure it out right away. | |
221 | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
222 prpl.c: |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
223 This file is what lets gaim dynamically load protocols, sort of. All of |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
224 the actual dlopen(), dlsym() stuff is in plugins.c. But this contains |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
225 all of the functions that the protocol plugin needs to call, and manages |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
226 all of the protocols. It's a pretty simple file actually. |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
227 |
639 | 228 proxy.c: |
229 This is where the bulk of the actual networking code is done. The big | |
230 function here is proxy_connect, which will connect through the proxy | |
231 setup you've chosen (most of which don't work...) or just regularly. | |
232 | |
233 rvous.c: | |
234 This was originally going to be the stuff for all of the Buddy Icon | |
235 and Voice Chat stuff, but I got really sick of protocol hacking really | |
236 quick. Now it only houses the file transfer stuff, which only works | |
237 for TOC. | |
238 | |
239 server.c: | |
240 This is where all of the differentiation between TOC and Oscar is | |
241 done. Nearly everything that's network related goes through here | |
242 at one point or another. This has good things like serv_send_im and | |
243 serv_got_update. Most of it should be pretty self-explanatory. | |
244 | |
245 sound.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
246 The main function in this file is play_sound, which plays one of 8 |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
247 (maybe 9?) sounds based on preferences. All that the rest of the |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
248 code should have to do is call play_sound(BUDDY_ARRIVE), for example, |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
249 and this file will take care of determining if a sound should be played |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
250 and which file should be played. |
639 | 251 |
252 ticker.c: | |
253 Syd is just so cool. I really can't get over it. He let me come | |
254 visit him at Netscape one day, and I got to see all of their toys | |
255 (don't worry, I'm under an NDA). Anyway, this file is for the buddy | |
256 ticker. This is also a damn cool file because it's got all of the | |
257 functions that you'd want right up at the top. Someday I want to be | |
258 as cool as Syd. | |
259 | |
260 toc.c: | |
261 This handles everything TOC-related, including parsing gaim's buddy | |
262 list. Most of this file is toc_callback, which parses the incoming | |
263 information from the server. I really don't like TOC though. | |
264 | |
265 util.c: | |
266 There's not really a lot of cohesion to this file; it's just a lot of | |
267 stuff that happened to be thrown into it for no apparent reason. None | |
268 of it is particularly tasty; it's all just utility functions. Just | |
269 like the name says. | |
270 | |
271 | |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
272 MULTIPLE CONNECTIONS AND PRPLS |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
273 ============================== |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
274 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
275 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
|
276 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
|
277 Each aim_user has certain features: a username, a password, and user_info. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
278 It also has certain options, and the protocol it uses to sign on (kept as |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
279 an int which is #define'd in prpl.h). The way the management of the users |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
280 works is, there will (hopefully) only be one user for a given screenname/ |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
281 protocol pair (i.e. you may have two user warmenhoven's, but they'll both |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
282 have a different protocol number). |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
283 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
284 Now then, there are protocols that gaim knows about. Each protocol is in |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
285 a prpl struct and kept track of in the protocols GSList. The way the |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
286 management of the protocols is, there will only ever be one prpl per numeric |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
287 protocol. Each prpl defines a basic set of functions: login, logout, send_im, |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
288 etc. The prpl is responsible not only for handling these functions, but also |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
289 for calling the appropriate serv_got functions (e.g. serv_got_update when a |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
290 buddy comes online/goes offline/goes idle/etc). It handles each of these on |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
291 a per-connection basis. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
292 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
293 So why's it called a PRPL? It stands for PRotocol PLugin. That means that |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
294 it's possible to dynamically add new protocols to gaim. However, all protocols |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
295 must be implemented the same way: by using a prpl struct and being loaded, |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
296 regardless of whether they are static or dynamic. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
297 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
298 Here's how struct gaim_connection fits into all of this. At some point the |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
299 User (capitalized to indicate a person and not a name) will try to sign on |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
300 one of Their users. serv_login is then called for that user. It searches for |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
301 the prpl that is assigned to that user, and calls that prpl's login function, |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
302 passing it the aim_user struct that is attempting to sign on. The prpl is then |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
303 responsible for seeing that the gaim_connection is created (by calling |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
304 new_gaim_connection), and registering it as being online (by calling |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
305 account_online and passing it the aim_user and gaim_connection structs). At |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
306 that point, the aim_user and gaim_connection structs have pointers to each |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
307 other, and the gaim_connection struct has a pointer to the prpl struct that |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
308 it is using. The gaim_connections are stored in the connections GSList. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
309 The way connection management works is, there will always only be one |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
310 gaim_connection per user, and the prpl that the gaim_connection uses will be |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
311 constant for the gaim_connection's life. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
312 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
313 So at certain points the User is going to want to do certain things, like |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
314 send a message. They must send the message on a connection. So the UI figures |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
315 out which gaim_connection the User want to send a message on (for our example), |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
316 and calls serv_send_im, telling it which gaim_connection to use, and the |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
317 necessary information (who to send it to, etc). The serv_ function then |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
318 calls the handler of the prpl of the connection for that event (that was way |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
319 too many prepositions). OK, each prpl has a send_im function. Each connection |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
320 has a prpl. so you call gc->prpl->send_im and pass it the connection and all |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
321 the necessary info. And that's how things get done. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
322 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
323 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
|
324 sense to me. Thank god I wrote the code; otherwise I'm sure I'd be lost. |