annotate HACKING @ 1686:73be09912842

[gaim-migrate @ 1696] good fixes. committer: Tailor Script <[e-mail]>

  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 (I hate GNU indent), so to help all you would-be hackers help out
  4 gaim, here's a brief tutorial on how gaim works. I'll quickly describe
  5 the logical flow of things, then what you'll find in each of the source
  6 files. As an added bonus, I'll try and describe as best I can how multiple
  7 connections and multiple protocols work. Depending on how much I want
  8 to avoid my final tomorrow I may even describe other parts of gaim that
  9 I particularly want to brag about. Hopefully that's enough to get most
 10 of you going.
 11 
 12 If you're going to hack gaim, PLEASE, PLEASE PLEASE PLEASE send patches
 13 against the absolute latest CVS. I get really annoyed when I get patches
 14 against the last released version, especially since I don't usually
 15 have a copy of it on my computer, and gaim tends to change a lot between
 16 versions. (I sometimes get annoyed when they're against CVS from 3 days
 17 ago, but can't complain because it's usually my fault that I haven't
 18 looked at the patch yet.) To get gaim from CVS (if you haven't already),
 19 run the following commands:
 20 
 21 $ export CVSROOT=:pserver:[e-mail]:/cvsroot/gaim
 22 $ cvs login (hit enter as the password)
 23 $ cvs co gaim
 24 (you'll see it getting all of the files)
 25 $ cd gaim
 26 $ ./gen
 27 
 28 You'll now have your normal gaim tree with ./configure and all. (If you
 29 want to make your life really simple, learn how CVS works. CVS is your
 30 friend.) To make a patch, just edit the files right there in that tree
 31 (don't bother with two trees, or even two copies of the same file). Then
 32 when you're ready to make your patch, simply run 'cvs diff -u >my.patch'
 33 and send it off.
 34 
 35 This file was last modified by $Author: warmenhoven $ on
 36 $Date: 2001-03-27 16:01:29 -0500 (Tue, 27 Mar 2001) $.
 37 
 38 
 39 PROGRAM FLOW
 40 ============
 41 
 42 Before gaim does anything you can see, it initializes itself, which is
 43 mostly just reading .gaimrc (handled by the functions in gaimrc.c) and
 44 parsing command-line options. It then draws the login window by calling
 45 show_login, and waits for input.
 46 
 47 At the login window, when "Accounts" is clicked, account_editor() is
 48 called. This then displays all of the users and various information
 49 about them. If the user clicks the "Signon" button instead, serv_login
 50 is called.
 51 
 52 When the "Sign on/off" button is clicked, serv_login is passed the
 53 username and the password for the account. If the password length is
 54 zero (the password field is a character array rather than pointer so it
 55 will not be NULL) then the Signon callback will prompt for the password
 56 before calling serv_login. serv_login then signs in the user using the
 57 appropriate protocol. We'll assume TOC for the rest of this discussion;
 58 even the libfaim guys get scared by oscar.c, and I'll talk about the
 59 PRPLs later.
 60 
 61 After you're signed in (I'll skip that discussion - I doubt many people
 62 are going to change the login process, since it pretty much just follows
 63 PROTOCOL), Gaim draws the buddy list by calling show_buddy_list, and
 64 waits for input from two places: the server and the user. The first
 65 place it gets input from after signon is usually the server, when the
 66 server tells Gaim which buddies are signed on.
 67 
 68 When there is information ready to be read from the server, toc_callback
 69 is called (by GDK) to parse the incoming information. On an UPDATE,
 70 serv_got_update is called, which takes care of things like notifying
 71 conversation windows of the update if need be; notifying the plugins;
 72 and finally, calling set_buddy.
 73 
 74 set_buddy is responsible for a lot of stuff, but most of it is done
 75 implicitly. It's responsible for the sounds (which is just a call to
 76 play_sound), but the biggest thing it does is call new_group_show and
 77 new_buddy_show if necessary. There's only one group_show per group name,
 78 even between connections, and only one buddy_show per group_show per
 79 buddy name, even between connections. (If that's not confusing enough,
 80 wait until I really start describing how the buddy list works.)
 81 
 82 New connections happen the exact same way as described above. Each
 83 aim_user can have one gaim_connection associated with it. aim_user and
 84 gaim_connection both have a protocol field; gaim_connection's should
 85 be constant once it is set. (I'll talk about the gaim_connection struct
 86 more later.)
 87 
 88 When the user opens a new conversation window, new_conversation is called.
 89 That's easy enough. If there isn't a conversation with the person already
 90 open (checked by calling find_conversation), show_conv is called to
 91 create the new window. All sorts of neat things happen there, but it's
 92 mostly drawing the window. show_conv is the best place to edit the UI.
 93 
 94 That's pretty much it for the quick tutorial. I know it wasn't much but
 95 it's enough to get you started. Make sure you know GTK before you get too
 96 involved. Most of the back-end stuff is pretty basic; most of gaim is GTK.
 97 
 98 
 99 SOURCE FILES
100 ============
101 
102 about.c:
103   Not much to say here, just a few basic functions.
104 
105 aim.c:
106   This is where the main() function is. It takes care of a lot of the
107   initialization stuff, and showing the login window. It's pretty tiny
108   and there's not really much to edit in it. This has some of the most
109   pointless functions, like gaim_setup, which optionally turns off sounds
110   on signon. A lot of this file should actually be part of other files.
111 
112 applet.c:
113   This controls most things that are related to the applet. I don't like
114   looking at this file because it still has functionsLikeThis. But at
115   least it doesn't have many of them anymore. Anyway, this file isn't
116   very big because there's really not much difference between the panel
117   version and the app version.
118 
119 away.c:
120   This takes care of most of the away stuff: setting the away message
121   (do_away_message); coming back (do_im_back); drawing the away window;
122   etc. Away messages work really oddly due to multiple connections and
123   multiple protocols; I think there are really only two or three people
124   who know how it works and I don't think any of us know why it works
125   that way.
126 
127 browser.c:
128   Code for opening a browser window. Most of the code is trying to deal
129   with Netscape. The most important function here is open_url. Have fun.
130   (This file may give you problems with GTK 2.0, because it uses parts
131   of GDK that it's not supposed to know about.)
132 
133 buddy.c:
134   This takes care of not only nearly everything buddy-related (the
135   buddy lists, the window, etc.), but also a lot of the code flow and
136   util functions. Look for good things like find_buddy, set_buddy,
137   and signoff here.
138 
139 buddy_chat.c:
140   This takes care of the buddy chat stuff. This used to be a lot bigger
141   until the chat and IM windows got merged in the code. Now it mostly
142   just takes care of chat-specific stuff, like ignoring people and
143   keeping track of who's in the room. This is also where the chat window
144   is created.
145 
146 conversation.c:
147   This is where most of the functions dealing with the IM and chat windows
148   are hidden. It tries to abstract things as much as possible, but doesn't
149   do a very good job. This is also where things like "Enter sends" and
150   "Ctrl-{B/I/U/S}" options get carried out (look for send_callback). The
151   chat and IM toolbar (with the B/I/U/S buttons) are both built from
152   the same function, build_conv_toolbar.
153 
154 dialogs.c:
155   A massive file with a lot of little utility functions. This is where all
156   of those little dialog windows are created. Things like the warn dialog
157   and the add buddy dialog are here. Not all of the dialogs in gaim are in
158   this file, though. But most of them are. This is also where do_import
159   is housed, to import buddy lists. (The actual buddy list parsing code
160   is in util.c for winaim lists and toc.c for gaim's own lists.)
161 
162 gaimrc.c:
163   This controls everything about the .gaimrc file. There's not really much
164   to say about it; this is probably one of the better designed and easier
165   to follow files in gaim. The important functions are towards the bottom.
166 
167 gtkimhtml.c:
168   This is gaim's HTML widget. It replaced the old widget, GtkHtml (which
169   was different than GNOME's GtkHTML). It's self-contained (it doesn't
170   use any of gaim's code) and is actually a separate project from gaim
171   (but is maintained by Eric).
172 
173 gtkspell.c:
174   This controls spell checking. It's not a widget per se but it does have
175   some influence over the GtkText widget. It's a separate project from
176   gaim; if you have a patch for this file send it to the author (the
177   contact info is in the file).
178 
179 gtkticker.c:
180   Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that
181   widget. It's cool, and it's tiny.
182 
183 html.c:
184   Don't ask my why this is called html.c. Most of it is just grab_url,
185   which does like the name says; it downloads a URL to show in the
186   GtkHTML widget.  http.c would be a more appropriate name, but that's OK.
187 
188 idle.c:
189   This file used to be entirely #if 0'd out of existance. However, thanks
190   to some very generous people who submitted patches, this takes care of
191   reporting idle time (imagine that). It's a pretty straight-forward file.
192   This also takes care of the auto-away stuff.
193 
194 multi.c:
195   This is the file that tries to take care of most of the major issues
196   with multiple connections. The best function in here by far is the
197   account_editor(). auto_login() is also in here (I'm just reading multi.h
198   now...). account_editor is really the only function that the UI needs
199   to be concerned with.
200 
201 oscar.c:
202   One big hack of copied code. This is supposed to be the libfaim tie-in
203   in gaim. Most of it is just copied straight from faimtest, the small
204   program that comes with libfaim. I'm not even sure how half of it works,
205   if that makes you feel any better.
206 
207 perl.c:
208   This was basically copied straight from X-Chat through the power of
209   the GPL.  Perl is the biggest, most confusing piece of C code I've ever
210   seen in my life (and keep in mind I'm a gaim hacker). I have a basic
211   idea of what's going on in it, but I couldn't tell you exactly. The
212   top half sets up perl and tells it what's going on and the bottom half
213   implements the AIM module.
214 
215 plugins.c:
216   This is the "plugin plug", as the file states. This file is probably
217   the only file in all of gaim that at the top has all of the functions
218   and global and static variables named out for you. It makes reading
219   it a little easier, but not by much. A lot of the code in here deals
220   with the plugin window rather than the plugins themselves.
221 
222 prefs.c:
223   The important function in here is build_prefs, but the most useful
224   function is gaim_button. build_prefs draws the window, and calls
225   gaim_button probably 30 or 40 times. (I don't really wanna run grep
226   | wc to count.) This is where you add the toggle button for gaim
227   preferences. It's very simple, and if you look at a couple of the
228   calls to gaim_button you'll figure it out right away. The new prefs
229   window uses a CList instead of a Notebook, and there's a pretty bad
230   hack to get it to work. I won't tell you what though.
231 
232 prpl.c:
233   This file is what lets gaim dynamically load protocols, sort of. All
234   of the actual dlopen(), dlsym() stuff is in plugins.c. But this
235   contains all of the functions that the protocol plugin needs to call,
236   and manages all of the protocols. It's a pretty simple file actually.
237 
238 proxy.c:
239   Adam (of libfaim glory) got bored one day and rewrote this file, so
240   now everything actually works. The main function is proxy_connect,
241   which figures out which proxy you want to use (if you want to use one
242   at all) and passes off the data to the appropriate function. This file
243   should be pretty straight-forward.
244 
245 rvous.c:
246   This was originally going to be the stuff for all of the Buddy Icon
247   and Voice Chat stuff, but I got really sick of protocol hacking really
248   quick.  Now it only houses the file transfer stuff, which only works
249   for TOC. ("Works" being a very subjective statement. This file needs
250   to be rewritten.)
251 
252 server.c:
253   This is where all of the differentiation between the different protocols
254   is done.  Nearly everything that's network related goes through here
255   at one point or another. This has good things like serv_send_im and
256   serv_got_update. Most of it should be pretty self-explanatory.
257 
258 sound.c:
259   The main function in this file is play_sound, which plays one of 8
260   (maybe 9?) sounds based on preferences. All that the rest of the code
261   should have to do is call play_sound(BUDDY_ARRIVE), for example, and
262   this file will take care of determining if a sound should be played
263   and which file should be played.
264 
265 ticker.c:
266   Syd is just so cool. I really can't get over it. He let me come
267   visit him at Netscape one day, and I got to see all of their toys
268   (don't worry, I'm under an NDA). Anyway, this file is for the buddy
269   ticker. This is also a damn cool file because it's got all of the
270   functions that you'd want right up at the top. Someday I want to be
271   as cool as Syd.
272 
273 toc.c:
274   This handles everything TOC-related, including parsing gaim's buddy
275   list.  Most of this file is toc_callback, which parses the incoming
276   information from the server. I really don't like TOC though. (I've spent
277   waaayyyy too much time with TOC. I rewrote the signon process for this
278   file at one point, so that read was only called when data was pending.
279   Since then the TOC server has been blocking my IP (probably my own
280   stupid fault, sending bad strings or some such).)
281 
282 util.c:
283   There's not really a lot of cohesion to this file; it's just a lot of
284   stuff that happened to be thrown into it for no apparent reason. None
285   of it is particularly tasty; it's all just utility functions. Just
286   like the name says.
287 
288 PRPL sources:
289 -------------
290 
291 plugins/yay: Yahoo
292   All of the files in here were written by Eric. All of the .c and .h
293   files except yay.c are part of a library that Eric wrote, libyay.
294   yay.c is what interacts with gaim.
295 
296 plugins/icq: ICQ (UDP v5)
297   All of the .c and .h files in here, with the exception of gaim_icq.c,
298   are part of ICQLib, by Bill Soudan and others. gaim_icq.c is what
299   interacts with gaim, and Eric wrote it. ICQLib is a fairly complete
300   implementation of the ICQ protocol, so if you want to add a new
301   feature you're probably going to be adding it to gaim_icq.c and not
302   to ICQLib.
303 
304 plugins/msn: MSN
305   Rob wrote msn.c, and md5.c is a standard file. MSN doesn't use its
306   own library; all of the networking code is included inside of msn.c.
307 
308 plugins/irc.c: IRC
309   Rob wrote irc.c, and since it is only one file it stands by itself.
310   All of the networking code is contained inside this file, as well as
311   the parts that interact with gaim.
312 
313 plugins/jabber: Jabber
314   jabber.c was written by Adam Fritzler (the guy that wrote libfaim),
315   and is maintained by Eric. The other .c and .h files belong to
316   libxode and libjabber, which were written by the Jabber developers.
317 
318 plugins/napster.c: Napster
319   Rob wrote napster.c, and since it is only one file it stands by
320   itself.
321 
322 
323 HOW THE BUDDY LIST WORKS
324 ========================
325 
326 The buddy list is a pain in the ass. Let me start off by saying that. The
327 most difficult part about getting gaim to do multiple connections was
328 the buddy list. In its current state it's very much like the UI for
329 0.10.x and earlier, which is what I was aiming for. However, the code
330 is completely different. And not much better.
331 
332 All of the buddy list stuff is in buddy.c, so you'll only have to have
333 that one file open (and possibly gaim.h for the struct definitions). There
334 are two sets of functions: those that deal with the buddy lists, and
335 those that deal with the window. (I say lists because each connection
336 has their own buddy list, independent of the others, even though the UI
337 merges them.)
338 
339 The buddy list functions work pretty much the same way they did before;
340 except now that each buddy and group belongs to a connection, things
341 like find_buddy take an additional argument, the connection you want to
342 search for the buddy in.  Read gaim.h for a good list of them: find_buddy,
343 find_group, add_buddy, remove_buddy, remove_group.
344 
345 The window is a lot more fun. There's really only one function that
346 does anything interesting, and that's set_buddy. (There's also things
347 like build_edit_tree, but that's boring.) set_buddy is called by
348 serv_got_update (and should only be called by that function) any time
349 a user signs on, signs off, goes away, comes back, goes idle, etc, etc,
350 etc. Various things happen depending on the new state of the buddy.
351 
352 struct buddy has a member, present, which is set to either 0, 1, or
353 2. You can check if the buddy is online with "if (b->present)". This
354 becomes important. present is set to either 0 or 1 by serv_got_update,
355 or is not set at all. When the buddy is passed to set_buddy, if present
356 is 1 then set_buddy plays the BUDDY_ARRIVE sound, and sets present to 2,
357 to indicate it has already received notification of arrival. It then
358 does other signin-related stuff: setting the pixmap to the login icon;
359 updating the conversation windows; etc.
360 
361 The most important thing it does though, if a buddy is present, is it
362 checks for the existance of the appropriate group_show and buddy_show for
363 that buddy.  Each buddy must belong to a group. group_shows are based on
364 name; there can only be one group_show for each group name. buddy_shows
365 are based both on name and on group_show; there can only be one buddy_show
366 in a group_show for each name. However, there can be two buddy_shows
367 with the same name as long as they have different group_shows.
368 
369 Each buddy_show has a GList of connections that has registered its related
370 buddy as being online. set_buddy makes sure that the connection that it's
371 being passed is part of the connlist for the buddy_show associated with
372 the struct buddy that it's passed (it helps to know your data structures).
373 
374 If a buddy logs off (b->present == 0), and a buddy_show exists for
375 that buddy, then set_buddy will play the logoff sound, change the icon,
376 remove the connection from the connlist for the buddy_show, etc.
377 
378 And that's how that works. For the buddy lists, connections own buddies;
379 for the window, the buddies own the connections. When the buddy_show
380 connlist count drops to zero it disappears from existance.
381 
382 
383 PLUGINS
384 =======
385 
386 OK, so you want to load a plugin. You go through whatever UI (you
387 can read all about the UI in plugins.c or whereever). You finally get
388 to load_plugin, the meat of the plugins stuff (plugins can actually
389 call load_plugin themselves to load other plugins). load_plugin
390 is passed the full path to the plugin you want to load
391 (e.g. /usr/local/lib/gaim/irc.so).
392 
393 load_plugin does a few things with that filename. The first is to see
394 if you've already loaded that plugin. If you have, load_plugin unloads
395 the one that is currently loaded. You might wonder why; it's because
396 the same plugin can't be loaded twice. If you call g_module_open on a
397 filename twice, both times it will return the same pointer, and both times
398 increment the reference count on the GModule * that it returns. This
399 means you really do have the same plugin twice, which fucks up the
400 callback system to no end.  So it's better that you can only have it
401 loaded once at any given time.
402 
403 Now that we're assured that we don't have this particular plugin loaded
404 yet, we better load it. g_module_open, baby. Much more portable than
405 dlopen().  In fact, for Linux it actually is the equivalent of dlopen()
406 (you can read the gmodule source and see for yourself). There's only one
407 quirk. It always logically ORs the options you pass with RTLD_GLOBAL,
408 which means that plugins share symbols. I haven't figured out yet if
409 this means just functions or variables too; but in either case make every
410 function and variable in your plugin static except for gaim_plugin_*(),
411 name(), and description().  It's good coding practice anyway.
412 
413 So, assuming we didn't get NULL back from g_module_open, we then make sure
414 it's a valid gaim plugin by looking for and calling gaim_plugin_init,
415 courtesy g_module_symbol (g_module_symbol is actually what's portable
416 about gmodule as opposed to dl*; some BSD's require '_' prepended to
417 symbol names and g_module_symbol guarantees we do The Right Thing).
418 
419 Assuming we've found gaim_plugin_init and it hasn't returned non-NULL
420 to us, we then add it to our list of plugins and go merrily about our way.
421 
422 So when do the callbacks happen?! plugin_event, baby, plugin_event. Any
423 time you want to trigger a plugin event simply call plugin_even with the
424 parameters to be passed to any event handlers and you're set. plugin_event
425 then makes sure that any plugins waiting for the event get passed the
426 arguments properly and passes it on to perl.
427 
428 Speaking of perl. If you really want to know how this works, you're
429 better off reading X-Chat's documentation of it, because it's better
430 than what I could provide.
431 
432 
433 MULTIPLE CONNECTIONS AND PRPLS
434 ==============================
435 
436 OK, let's start with the basics. There are users. Each user is contained
437 in an aim_user struct, and kept track of in the aim_users GList (GSList?).
438 Each aim_user has certain features: a username, a password, and user_info.
439 It also has certain options, and the protocol it uses to sign on (kept
440 as an int which is #define'd in prpl.h). The way the management of the
441 users works is, there will (hopefully) only be one user for a given
442 screenname/ protocol pair (i.e. you may have two user warmenhoven's,
443 but they'll both have a different protocol number).
444 
445 Now then, there are protocols that gaim knows about. Each protocol is
446 in a prpl struct and kept track of in the protocols GSList. The way the
447 management of the protocols is, there will only ever be one prpl per
448 numeric protocol. Each prpl defines a basic set of functions: login,
449 logout, send_im, etc. The prpl is responsible not only for handling
450 these functions, but also for calling the appropriate serv_got functions
451 (e.g. serv_got_update when a buddy comes online/goes offline/goes
452 idle/etc). It handles each of these on a per-connection basis.
453 
454 So why's it called a PRPL? It stands for PRotocol PLugin. That means
455 that it's possible to dynamically add new protocols to gaim. However,
456 all protocols must be implemented the same way: by using a prpl struct
457 and being loaded, regardless of whether they are static or dynamic.
458 
459 Here's how struct gaim_connection fits into all of this. At some point
460 the User (capitalized to indicate a person and not a name) will try to
461 sign on one of Their users. serv_login is then called for that user. It
462 searches for the prpl that is assigned to that user, and calls that prpl's
463 login function, passing it the aim_user struct that is attempting to sign
464 on. The prpl is then responsible for seeing that the gaim_connection
465 is created (by calling new_gaim_connection), and registering it as
466 being online (by calling account_online and passing it the aim_user and
467 gaim_connection structs). At that point, the aim_user and gaim_connection
468 structs have pointers to each other, and the gaim_connection struct has
469 a pointer to the prpl struct that it is using. The gaim_connections are
470 stored in the connections GSList.  The way connection management works is,
471 there will always only be one gaim_connection per user, and the prpl that
472 the gaim_connection uses will be constant for the gaim_connection's life.
473 
474 So at certain points the User is going to want to do certain things,
475 like send a message. They must send the message on a connection. So the UI
476 figures out which gaim_connection the User want to send a message on (for
477 our example), and calls serv_send_im, telling it which gaim_connection to
478 use, and the necessary information (who to send it to, etc). The serv_
479 function then calls the handler of the prpl of the connection for that
480 event (that was way too many prepositions). OK, each prpl has a send_im
481 function. Each connection has a prpl. so you call gc->prpl->send_im and
482 pass it the connection and all the necessary info. And that's how things
483 get done.
484 
485 I hope some of that made sense. Looking back at it it makes absolutely no
486 sense to me. Thank god I wrote the code; otherwise I'm sure I'd be lost.