comparison HACKING @ 1038:daad2440a642

[gaim-migrate @ 1048] i have homework i need to be doing. it's due in less than 7 hours, and i haven't started and i need to sleep. committer: Tailor Script <[e-mail]>

1037:1c663beef29d

debugging information is printed to the debug window (which can be turned
on in the preferences) whether or not --enable-debug was selected. Most
of the information that's printed is useless anyway though; so the
--enable-debug option really doesn't do a whole lot.

This file was last modified by $Author: warmenhoven $ on $Date: 2000-10-12 14:59:36 -0400 (Thu, 12 Oct 2000) $.


PROGRAM FLOW
============

Before gaim does anything you can see, it initializes itself, which is
mostly just reading .gaimrc (handled by the functions in gaimrc.c). It
then draws the login window by calling show_login, and waits for input.

At the login window, when "Accounts" is clicked, account_editor() is
called. (NOTE: the login window will probably be changed soon.) This
then displays all of the users and various information about them.

When the "Sign on/off" button is clicked, serv_login is passed the
username and the password for the account. If the password length is
zero (the password field is a character array rather than pointer so
it will not be NULL) then the Signon callback will prompt for the

After you're signed in (I'll skip that discussion - I doubt many people
are going to change the login process, since it pretty much just follows
PROTOCOL), Gaim draws the buddy list by calling show_buddy_list, and
waits for input from two places: the server and the user. The first place
it gets input from after signon is invariably the server, when the server
tells Gaim which buddies are signed on.

When there is information ready to be read from the server, toc_callback
is called (by GDK) to parse the incoming information. On an UPDATE,
serv_got_update is called, which takes care of things like notifying
conversation windows of the update if need be; notifying the plugins;
and finally, calling set_buddy.

set_buddy is one of the most frequently called functions in gaim, one of
the largest functions in gaim, and probably one of the buggiest functions
in gaim. It is responsible for updating the pixmaps in the buddy list;
notifying plugins of various events; updating the tooltips for buddies;
making sounds; and updating the ticker. It's also called once per online
buddy every 20 seconds per connection (by GTK through update_all_buddies).

New connections happen the exact same way as described above. Each aim_user
can have one gaim_connection associated with it. aim_user and gaim_connection
both have a protocol field; gaim_connection's should be constant once it is
set in the appropriate (protocol)_login function. There are lots of details

When the user opens a new conversation window, new_conversation is called.
That's easy enough. If there isn't a conversation with the person already
open (checked by calling find_conversation), show_conv is called to
create the new window. All sorts of neat things happen there, but it's
mostly drawing the window. show_conv is the best place to edit the UI. Be
prepared for some incredibly bad GTK programming. (Rob's fixing this as
we speak no doubt.)

That's pretty much it for the quick tutorial. I know it wasn't much but
it's enough to get you started. Make sure you know GTK before you get too
involved. Most of the back-end stuff is pretty basic; most of gaim is GTK.

  Don't ask my why this is called html.c. Most of it is just grab_url,
  which does like the name says; it downloads a URL to show in the
  GtkHTML widget.  http.c would be a more appropriate name, but that's OK.

idle.c:
  There is a very good reason why this file is still on version 1.1
  in CVS.  The entire thing is #if 0'd out. I haven't ever really taken
  a good look at it, but I think what it was supposed to have done is
  set you as being away when a screensaver came on.

multi.c:
  This is the file that tries to take care of most of the major issues
  with multiple connections. The best function in here by far is the
  account_editor(). auto_login() is also in here (I'm just reading
  multi.h now...); auto_login has problems. Someone please fix it.
  account_editor is really the only function that the UI needs to be
  concerned with. If you want to remove multiconnectivity from gaim,
  all you would really need to do is comment out any lines that make
  reference to this function (there are only two - one in aim.c and one
  in buddy.c). The login window UI would have to be changed but it would
  be simple to take an old version of gaim and copy code (it won't drop-in
  because there were other changes, but it should be simple to hand-edit).

network.c:
  This has two functions: get_address and connect_address, both of which
  call proxy functions. If you want to see how these are used, look at
  toc.c and/or rvous.c. These are really just front-ends to the proxy

  gaim_button probably 30 or 40 times. (I don't really wanna run grep
  | wc to count.) This is where you add the toggle button for gaim
  preferences. It's very simple, and if you look at a couple of the
  calls to gaim_button you'll figure it out right away.

proxy.c:
  This is where the bulk of the actual networking code is done. The big
  function here is proxy_connect, which will connect through the proxy
  setup you've chosen (most of which don't work...) or just regularly.

  done.  Nearly everything that's network related goes through here
  at one point or another. This has good things like serv_send_im and
  serv_got_update. Most of it should be pretty self-explanatory.

sound.c:
  The big important function is play_sound, which plays one of 4 (actually
  6) sounds. One of the sounds is called in 3 different events, which
  is why there are actually 6 sounds. This then calls play which then
  checks for esd, then nas if that's not available, then falls back
  to /dev/audio.

ticker.c:
  Syd is just so cool. I really can't get over it. He let me come
  visit him at Netscape one day, and I got to see all of their toys
  (don't worry, I'm under an NDA). Anyway, this file is for the buddy

1038:daad2440a642

debugging information is printed to the debug window (which can be turned
on in the preferences) whether or not --enable-debug was selected. Most
of the information that's printed is useless anyway though; so the
--enable-debug option really doesn't do a whole lot.

This file was last modified by $Author: warmenhoven $ on $Date: 2000-10-31 05:49:53 -0500 (Tue, 31 Oct 2000) $.


PROGRAM FLOW
============

Before gaim does anything you can see, it initializes itself, which is
mostly just reading .gaimrc (handled by the functions in gaimrc.c) and
parsing command-line options. It then draws the login window by calling
show_login, and waits for input.

At the login window, when "Accounts" is clicked, account_editor() is
called. This then displays all of the users and various information about
them. If the user clicks the "Signon" button instead, serv_login is called.

When the "Sign on/off" button is clicked, serv_login is passed the
username and the password for the account. If the password length is
zero (the password field is a character array rather than pointer so
it will not be NULL) then the Signon callback will prompt for the

After you're signed in (I'll skip that discussion - I doubt many people
are going to change the login process, since it pretty much just follows
PROTOCOL), Gaim draws the buddy list by calling show_buddy_list, and
waits for input from two places: the server and the user. The first place
it gets input from after signon is usually the server, when the server
tells Gaim which buddies are signed on.

When there is information ready to be read from the server, toc_callback
is called (by GDK) to parse the incoming information. On an UPDATE,
serv_got_update is called, which takes care of things like notifying
conversation windows of the update if need be; notifying the plugins;
and finally, calling set_buddy.

New connections happen the exact same way as described above. Each aim_user
can have one gaim_connection associated with it. aim_user and gaim_connection
both have a protocol field; gaim_connection's should be constant once it is
set in the appropriate (protocol)_login function. There are lots of details

When the user opens a new conversation window, new_conversation is called.
That's easy enough. If there isn't a conversation with the person already
open (checked by calling find_conversation), show_conv is called to
create the new window. All sorts of neat things happen there, but it's
mostly drawing the window. show_conv is the best place to edit the UI.

That's pretty much it for the quick tutorial. I know it wasn't much but
it's enough to get you started. Make sure you know GTK before you get too
involved. Most of the back-end stuff is pretty basic; most of gaim is GTK.

  Don't ask my why this is called html.c. Most of it is just grab_url,
  which does like the name says; it downloads a URL to show in the
  GtkHTML widget.  http.c would be a more appropriate name, but that's OK.

idle.c:
  This file used to be entirely #if 0'd out of existance. However, thanks
  to some very generous people who submitted patches, this takes care of
  reporting idle time (imagine that). It's a pretty straight-forward file.

multi.c:
  This is the file that tries to take care of most of the major issues
  with multiple connections. The best function in here by far is the
  account_editor(). auto_login() is also in here (I'm just reading
  multi.h now...); auto_login has problems. Someone please fix it.
  account_editor is really the only function that the UI needs to be
  concerned with. If you want to remove multiconnectivity from gaim,
  all you would really need to do is comment out any lines that make
  reference to this function (there are only two - one in aim.c and one
  in buddy.c). Or you could just run ./configure --disable-multi.

network.c:
  This has two functions: get_address and connect_address, both of which
  call proxy functions. If you want to see how these are used, look at
  toc.c and/or rvous.c. These are really just front-ends to the proxy

  gaim_button probably 30 or 40 times. (I don't really wanna run grep
  | wc to count.) This is where you add the toggle button for gaim
  preferences. It's very simple, and if you look at a couple of the
  calls to gaim_button you'll figure it out right away.

prpl.c:
  This file is what lets gaim dynamically load protocols, sort of. All of
  the actual dlopen(), dlsym() stuff is in plugins.c. But this contains
  all of the functions that the protocol plugin needs to call, and manages
  all of the protocols. It's a pretty simple file actually.

proxy.c:
  This is where the bulk of the actual networking code is done. The big
  function here is proxy_connect, which will connect through the proxy
  setup you've chosen (most of which don't work...) or just regularly.

  done.  Nearly everything that's network related goes through here
  at one point or another. This has good things like serv_send_im and
  serv_got_update. Most of it should be pretty self-explanatory.

sound.c:
  The main function in this file is play_sound, which plays one of 8
  (maybe 9?) sounds based on preferences. All that the rest of the
  code should have to do is call play_sound(BUDDY_ARRIVE), for example,
  and this file will take care of determining if a sound should be played
  and which file should be played.

ticker.c:
  Syd is just so cool. I really can't get over it. He let me come
  visit him at Netscape one day, and I got to see all of their toys
  (don't worry, I'm under an NDA). Anyway, this file is for the buddy