Mercurial > pidgin.yaz
annotate HACKING @ 1170:16d748023b2b
[gaim-migrate @ 1180]
You can now choose the sound(s) you want to hear for various events.
It doesnt update the preferences wnidow but it really does save them,
honest!
I'll fix the rest tomrrow. I'm sleepy.
All Work and No play Makes Timmy TIIMMY TIimmMYY GOBBLES!
committer: Tailor Script <tailor@pidgin.im>
author | Rob Flynn <gaim@robflynn.com> |
---|---|
date | Wed, 29 Nov 2000 10:30:56 +0000 |
parents | 4416ead31db7 |
children | 72692c70317e |
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 | |
1099
4416ead31db7
[gaim-migrate @ 1109]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1063
diff
changeset
|
38 This file was last modified by $Author: warmenhoven $ on $Date: 2000-11-16 02:35:58 -0500 (Thu, 16 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 oscar.c: |
188 One big hack of copied code. This is supposed to be the libfaim tie-in | |
189 in gaim. Most of it is just copied straight from faimtest, the small | |
190 program that comes with libfaim. I'm not even sure how half of it works, | |
191 if that makes you feel any better. | |
192 | |
193 perl.c: | |
194 This was basically copied straight from X-Chat through the power of | |
195 the GPL. Perl is the biggest, most confusing piece of C code I've ever | |
196 seen in my life (and keep in mind I'm a gaim hacker). I have a basic | |
197 idea of what's going on in it, but I couldn't tell you exactly. The | |
198 top half sets up perl and tells it what's going on and the bottom half | |
199 implements the AIM module. | |
200 | |
201 plugins.c: | |
202 This is the "plugin plug", as the file states. This file is probably | |
203 the only file in all of gaim that at the top has all of the functions | |
204 and global and static variables named out for you. It makes reading | |
205 it a little easier, but not by much. A lot of the code in here deals | |
206 with the plugin window rather than the plugins themselves. | |
207 | |
208 prefs.c: | |
209 The important function in here is build_prefs, but the most useful | |
210 function is gaim_button. build_prefs draws the window, and calls | |
211 gaim_button probably 30 or 40 times. (I don't really wanna run grep | |
212 | wc to count.) This is where you add the toggle button for gaim | |
213 preferences. It's very simple, and if you look at a couple of the | |
214 calls to gaim_button you'll figure it out right away. | |
215 | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
216 prpl.c: |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
217 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
|
218 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
|
219 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
|
220 all of the protocols. It's a pretty simple file actually. |
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
221 |
639 | 222 proxy.c: |
1099
4416ead31db7
[gaim-migrate @ 1109]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1063
diff
changeset
|
223 Adam (of libfaim glory) got bored one day and rewrote this file, so now |
4416ead31db7
[gaim-migrate @ 1109]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1063
diff
changeset
|
224 everything actually works. The main function is proxy_connect, which |
4416ead31db7
[gaim-migrate @ 1109]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1063
diff
changeset
|
225 figures out which proxy you want to use (if you want to use one at all) |
4416ead31db7
[gaim-migrate @ 1109]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1063
diff
changeset
|
226 and passes off the data to the appropriate function. This file should be |
4416ead31db7
[gaim-migrate @ 1109]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1063
diff
changeset
|
227 pretty straight-forward. |
639 | 228 |
229 rvous.c: | |
230 This was originally going to be the stuff for all of the Buddy Icon | |
231 and Voice Chat stuff, but I got really sick of protocol hacking really | |
232 quick. Now it only houses the file transfer stuff, which only works | |
233 for TOC. | |
234 | |
235 server.c: | |
236 This is where all of the differentiation between TOC and Oscar is | |
237 done. Nearly everything that's network related goes through here | |
238 at one point or another. This has good things like serv_send_im and | |
239 serv_got_update. Most of it should be pretty self-explanatory. | |
240 | |
241 sound.c: | |
1038
daad2440a642
[gaim-migrate @ 1048]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
980
diff
changeset
|
242 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
|
243 (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
|
244 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
|
245 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
|
246 and which file should be played. |
639 | 247 |
248 ticker.c: | |
249 Syd is just so cool. I really can't get over it. He let me come | |
250 visit him at Netscape one day, and I got to see all of their toys | |
251 (don't worry, I'm under an NDA). Anyway, this file is for the buddy | |
252 ticker. This is also a damn cool file because it's got all of the | |
253 functions that you'd want right up at the top. Someday I want to be | |
254 as cool as Syd. | |
255 | |
256 toc.c: | |
257 This handles everything TOC-related, including parsing gaim's buddy | |
258 list. Most of this file is toc_callback, which parses the incoming | |
259 information from the server. I really don't like TOC though. | |
260 | |
261 util.c: | |
262 There's not really a lot of cohesion to this file; it's just a lot of | |
263 stuff that happened to be thrown into it for no apparent reason. None | |
264 of it is particularly tasty; it's all just utility functions. Just | |
265 like the name says. | |
266 | |
267 | |
1063
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
268 MULTIPLE CONNECTIONS AND PRPLS |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
269 ============================== |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
270 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
271 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
|
272 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
|
273 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
|
274 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
|
275 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
|
276 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
|
277 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
|
278 have a different protocol number). |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
279 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
280 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
|
281 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
|
282 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
|
283 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
|
284 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
|
285 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
|
286 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
|
287 a per-connection basis. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
288 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
289 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
|
290 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
|
291 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
|
292 regardless of whether they are static or dynamic. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
293 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
294 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
|
295 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
|
296 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
|
297 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
|
298 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
|
299 responsible for seeing that the gaim_connection is created (by calling |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
300 new_gaim_connection), and registering it as being online (by calling |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
301 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
|
302 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
|
303 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
|
304 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
|
305 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
|
306 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
|
307 constant for the gaim_connection's life. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
308 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
309 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
|
310 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
|
311 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
|
312 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
|
313 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
|
314 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
|
315 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
|
316 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
|
317 the necessary info. And that's how things get done. |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
318 |
e1408fb04c36
[gaim-migrate @ 1073]
Eric Warmenhoven <eric@warmenhoven.org>
parents:
1038
diff
changeset
|
319 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
|
320 sense to me. Thank god I wrote the code; otherwise I'm sure I'd be lost. |