diff HACKING @ 16178:d73ee2690376

merge of '3ae1c2f29b72682bad3542b9c0175438dd3309c0' and '60672db63b751e0cdc4ab40d5251c9479d3c0c79'

--- a/HACKING	Sun Apr 15 23:54:55 2007 +0000
+++ b/HACKING	Mon Apr 16 00:46:39 2007 +0000
@@ -1,448 +1,2 @@
-Lots of this is pretty grossly out of date...
-Some of it might still be useful.  For coding style, your
-best bet is to browse through some of the files in src and
-emulate what you see there.
---Mark
-
-
-The majority of the below was written by Eric Warmenhoven way back in
-antiquity. I have taken the liberty of attempting to PARTIALLY update
-it. I still think its helpful, but use it at your own risk.
---Luke
-
-
-A lot of people have tried to hack gaim, but haven't been able to because
-the code is just so horrid. Well, the code isn't getting better anytime
-soon (I hate GNU indent), so to help all you would-be hackers help out
-gaim, here's a brief tutorial on how gaim works. I'll quickly describe
-the logical flow of things, then what you'll find in each of the source
-files. As an added bonus, I'll try and describe as best I can how multiple
-connections and multiple protocols work. Depending on how much I want to
-avoid my final tomorrow I may even describe other parts of gaim that I
-particularly want to brag about. Hopefully that's enough to get most of
-you going.
-
-If you don't know how event-driven programs work, stop right now. Gaim
-uses GTK+'s main loop (actually GLib's but I won't talk about how GTK
-works) and uses GLib functions for timeouts and socket notification. If
-you don't know GTK+ you should go learn that first.
-
-If you're going to hack gaim, PLEASE, PLEASE PLEASE PLEASE send patches
-against the absolute latest SVN. I get really annoyed when I get patches
-against the last released version, especially since I don't usually have
-a copy of it on my computer, and gaim tends to change a lot between
-versions. (I sometimes get annoyed when they're against SVN from 3 days
-ago, but can't complain because it's usually my fault that I haven't
-looked at the patch yet.) To get gaim from SVN (if you haven't already),
-run the following commands:
-
-$ svn co https://svn.sourceforge.net/svnroot/gaim/trunk gaim
-$ cd gaim
-$ ./autogen.sh
-
-You'll now have your normal gaim tree with ./configure and all (which
-./autogen.sh takes the liberty of running for you). (If you want to make
-your life really simple, learn how SVN works. SVN is your friend.) To make
-a patch, just edit the files right there in that tree (don't bother with
-two trees, or even two copies of the same file). Then when you're ready to
-make your patch, simply run 'svn diff > my.patch' and post it on
-sf.net/projects/gaim in the patches section.
-
-Some Documentation is available on the Gaim api if you run the command 
-$make docs
-after running ./configure (or ./autogen.sh). You will need doxygen and
-graphiz dot to generate these docs. 
-
-CODING STYLE
-============
-
-Coding styles are like assholes, everyone has one and no one likes anyone
-elses. This is mine and if you want me to accept a patch from you without
-getting annoyed you'll follow this coding style. :)
-
-It would probably just be easier for me to include CodingStyle from the
-linux kernel source.
-
-Tab indents. I *HATE* 2-space indents, and I strongly dislike 8-space
-indents. Use a tab character. I'm likely to refuse a patch if it has
-2-space indents.
-
-K&R style for braces. Braces always go on the same line as the if, etc.
-that they're associated with; the only exception is functions. Braces
-for else statements should have both braces on the same line as the else
-(i.e. "} else {").
-
-No functionOrVariableNamesLikeThis. Save it for Java. Underscores are your
-friend. "tmp" is an excellent variable name. Hungarian style will not be
-tolerated. Go back to Microsoft.
-
-I have a 105-char wide Eterm. Deal with it.
-
-NO goto. I'm very likely to refuse a patch if it makes use of goto. If you
-feel the need to use goto, you need to rethink your design and flow.
-
-
-PROGRAM FLOW  (just about every function name from here on down is wrong.
-============   but many of the ideas still apply under different names.)
-
-Before gaim does anything you can see, it initializes itself, which is
-mostly just reading ~/.gaim/*.xml (handled by the functions in prefs.[ch])
-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. (Don't ask about what happens when "Sign On" is called. It's
-quite hackish. The only reason the login window is there anymore is to
-make it more palatable to people so used to WinAIM that they can't accept
-anything else.)
-
-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 password
-before calling serv_login. serv_login then signs in the user using the
-appropriate protocol.
-
-After you're signed in, Gaim draws the buddy list by calling
-show_buddy_list. Assuming the user has a buddy list (all buddy list
-functions are controlled by list.c; when you sign on do_import is called
-and that loads the locally saved list), the protocol calls
-gaim_prpl_got functions, which set the information in the appropriate 
-struct buddy and then passes it off to set_buddy.
-
-set_buddy is responsible for a lot of stuff, but most of it is done
-implicitly. It's responsible for the sounds (which is just a call to
-play_sound), but the biggest thing it does is call new_group_show and
-new_buddy_show if necessary. There's only one group_show per group name,
-even between connections, and only one buddy_show per group_show per
-buddy name, even between connections. (If that's not confusing enough,
-wait until I really start describing how the buddy list works.)
-
-New connections happen the exact same way as described above. Each
-gaim_account can have one gaim_connection associated with it. gaim_account
-and gaim_connection both have a protocol field. This is kind of confusing:
-gaim, except for the account editor screen and when the user signs on,
-ignores the user's protocl field, and only uses the connection's protocol
-field. You can change the connection's protocol field once it's created
-and been assigned a PRPL to use to change certain behavior (Oscar does
-this because it handles both AIM and ICQ). I'll talk about the
-gaim_connection struct more later.
-
-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+.
-
-
-SOURCE FILES  (this should probly be utterly removed)
-============
-
-about.c:
-  Not much to say here, just a few basic functions.
-
-account.[ch]:
-	This controls the GaimAccount struct, which stores information
-	on each account a user registers with gaim. Usernames, pass-
-	words, user info, alias, user specific options, and everything
-	else controlled from within the account editor (and then some)
-	are handled via this code.
-
-accountopt.[ch]:
-	Api and implemenation for account options. I'm not precisely
-	sure how this meshes with account.[ch]
-
-away.c:
-  This takes care of most of the away stuff: setting the away message
-  (do_away_message); coming back (do_im_back); drawing the away window;
-  etc. Away messages work really oddly due to multiple connections and
-  multiple protocols; I think there are really only two or three people
-  who know how it works and I don't think any of us know why it works
-  that way.
-
-blist.[ch]:
-	This takes care of the buddy list backend, the blist.xml file,
-	importing old buddy list files, and related things like
-	finding buddies and groups. buddies, contacts, and groups
-	are controlled from these files.
-
-buddy_chat.c:
-  This takes care of the buddy chat stuff. This used to be a lot bigger
-  until the chat and IM windows got merged in the code. Now it mostly
-  just takes care of chat-specific stuff, like ignoring people and
-  keeping track of who's in the room. This is also where the chat window
-  is created.
-
-conversation.c:
-  This is where most of the functions dealing with the IM and chat windows
-  are hidden. It tries to abstract things as much as possible, but doesn't
-  do a very good job. This is also where things like "Enter sends" and
-  "Ctrl-{B/I/U/S}" options get carried out (look for send_callback). The
-  chat and IM toolbar (with the B/I/U/S buttons) are both built from
-  the same function, build_conv_toolbar.
-
-core.c:
-  This is the start of what will become the main() for gaim-core.
-
-gtkdialogs.c:
-  A massive file with a lot of little utility functions. This is where all
-  of those little dialog windows are created. Things like the warn dialog
-  and the add buddy dialog are here. Not all of the dialogs in gaim are in
-  this file, though. But most of them are. This is also where do_import
-  is housed, to import buddy lists. (The actual buddy list parsing code
-  is in util.c for winaim lists and buddy.c for gaim's own lists.)
-
-gtkimhtml.c:
-  This is gaim's HTML widget. It replaced the old widget, GtkHtml (which
-  was different than GNOME's GtkHTML). It's self-contained (it doesn't
-  use any of gaim's code) and is actually a separate project from gaim
-  (but is maintained by Eric).
-
-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.
-  This also takes care of the auto-away stuff.
-
-gtkmain.c:
-  This is where the main() function is. It takes care of a lot of the
-  initialization stuff, and showing the buddy list or account editor.
-
-md5.c:
-  Oscar, Yahoo, and MSN all require md5 hashing, so better to put it in
-  the core than have the same thing in three different places.
-
-module.c:
-  This contains all of the plugin code, except for the UI. This is what
-  actually loads the plugins, makes sure they're valid, has the code for
-  setting up plugin event handlers, and contains the plugin_event method
-  that gaim calls on events.
-
-prefs.c:
-	Read the documentation on this file. This handles the backend
-	side of prefs.
-
-proxy.c:
-  Adam (of libfaim glory) got bored one day and rewrote this file, so
-  now everything actually works. The main function is proxy_connect,
-  which figures out which proxy you want to use (if you want to use one
-  at all) and passes off the data to the appropriate function. This file
-  should be pretty straight-forward.
- 	Except I STRONGLY suspect that time has broken this file.
-
-prpl.c:
-  This file is what lets gaim dynamically load protocols, sort of. All
-  of the actual dlopen(), dlsym() stuff is in module.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.
-
-server.c:
-  This is where all of the differentiation between the different protocols
-  is done.  Nearly everything that's network related goes through here
-  at one point or another. This has good things like serv_send_im. 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.
-
-util.c:
-  There's not really a lot of cohesion to this file; it's just a lot of
-  stuff that happened to be thrown into it for no apparent reason. None
-  of it is particularly tasty; it's all just utility functions. Just
-  like the name says.
-
-plugins/ticker/gtkticker.c:
-  Syd, our resident GTK+ God, wrote a GtkWidget, GtkTicker. This is that
-  widget. It's cool, and it's tiny. This is actually a really good example
-  widget for those of you looking to write your own.
-
-plugins/ticker/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
-  ticker. This is also a damn cool file because it's got all of the
-  functions that you'd want right up at the top. Someday I want to be
-  as cool as Syd.
-
-For the PRPLs, the only protocol whose "main" gaim file isn't the same as
-the name of the protocol is ICQ; for that it's gaim_icq.c. But ICQ is
-deprecated and you should be using Oscar for ICQ anyway.
-
-PLUGINS (read the plugins howto, this is really out of date)
-=======
-
-OK, so you want to load a plugin. You go through whatever UI (you
-can read all about the UI in plugins.c or whereever). You finally get
-to load_plugin, the meat of the plugins stuff (plugins can actually
-call load_plugin themselves to load other plugins). load_plugin
-is passed the full path to the plugin you want to load
-(e.g. /usr/local/lib/gaim/irc.so).
-
-load_plugin does a few things with that filename. The first is to see
-if you've already loaded that plugin. If you have, load_plugin unloads
-the one that is currently loaded. You might wonder why; it's because
-the same plugin can't be loaded twice. If you call g_module_open on a
-filename twice, both times it will return the same pointer, and both times
-increment the reference count on the GModule * that it returns. This
-means you really do have the same plugin twice, which fucks up the
-callback system to no end.  So it's better that you can only have it
-loaded once at any given time.
-
-Now that we're assured that we don't have this particular plugin loaded
-yet, we better load it. g_module_open, baby. Much more portable than
-dlopen().  In fact, for Linux it actually is the equivalent of dlopen()
-(you can read the gmodule source and see for yourself). There's only one
-quirk. It always logically ORs the options you pass with RTLD_GLOBAL,
-which means that plugins share symbols. I haven't figured out yet if
-this means just functions or variables too; but in either case make every
-function and variable in your plugin static except for gaim_plugin_*(),
-name(), and description().  It's good coding practice anyway.
-
-So, assuming we didn't get NULL back from g_module_open, we then make sure
-it's a valid gaim plugin by looking for and calling gaim_plugin_init,
-courtesy g_module_symbol (g_module_symbol is actually what's portable
-about gmodule as opposed to dl*; some BSD's require '_' prepended to
-symbol names and g_module_symbol guarantees we do The Right Thing).
-
-Assuming we've found gaim_plugin_init and it hasn't returned non-NULL
-to us, we then add it to our list of plugins and go merrily about our way.
-
-So when do the callbacks happen?! plugin_event, baby, plugin_event. Any
-time you want to trigger a plugin event simply call plugin_even with the
-parameters to be passed to any event handlers and you're set. plugin_event
-then makes sure that any plugins waiting for the event get passed the
-arguments properly and passes it on to perl.
-
-Speaking of perl. If you really want to know how this works, you're
-better off reading X-Chat's documentation of it, because it's better
-than what I could provide.
-
-
-MULTIPLE CONNECTIONS AND PRPLS
-==============================
-
-OK, let's start with the basics. There are users. Each user is contained
-in an gaim_account struct, and kept track of in the gaim_accounts GSList.
-Each gaim_account has certain features: a username, a password, and
-user_info.  It also has certain options, and the protocol it uses to sign
-on (kept as an int which is #define'd in prpl.h).
-
-Now then, there are protocols that gaim knows about. Each protocol is
-in a prpl struct and kept track of in the protocols GSList. The way the
-management of the protocols is, there will only ever be one prpl per
-numeric protocol. Each prpl defines a basic set of functions: login,
-logout, send_im, etc. The prpl is responsible not only for handling
-these functions, but also for calling the appropriate prpl_got functions
-It handles each of these on a per-account basis.
-
-So why's it called a PRPL? It stands for PRotocol PLugin. That means
-that it's possible to dynamically add new protocols to gaim. However,
-all protocols must be implemented the same way: by using a prpl struct
-and being loaded, regardless of whether they are static or dynamic.
-
-Here's how struct gaim_connection fits into all of this. At some point
-the User (capitalized to indicate a person and not a name) will try to
-sign on one of Their users. serv_login is then called for that user. It
-searches for the prpl that is assigned to that user, and calls that prpl's
-login function, passing it the gaim_account struct that is attempting to
-sign on. The prpl is then responsible for seeing that the gaim_connection
-is created (by calling new_gaim_connection), and registering it as
-being online (by calling account_online and passing it the gaim_account and
-gaim_connection structs). At that point, the gaim_account and gaim_connection
-structs have pointers to each other, and the gaim_connection struct has
-a pointer to the prpl struct that it is using. The gaim_connections are
-stored in the connections GSList.  The way connection management works is,
-there will always only be one gaim_connection per user, and the prpl that
-the gaim_connection uses will be constant for the gaim_connection's life.
-
-So at certain points the User is going to want to do certain things,
-like send a message. They must send the message on a connection. So the UI
-figures out which gaim_connection the User want to send a message on (for
-our example), and calls serv_send_im, telling it which gaim_connection to
-use, and the necessary information (who to send it to, etc). The serv_
-function then calls the handler of the prpl of the connection for that
-event (that was way too many prepositions). OK, each prpl has a send_im
-function. Each connection has a prpl. so you call gc->prpl->send_im and
-pass it the connection and all the necessary info. And that's how things
-get done.
-
-I hope some of that made sense. Looking back at it it makes absolutely no
-sense to me. Thank god I wrote the code; otherwise I'm sure I'd be lost.
-
-
-WRITING PRPLS
-=============
-
-Start off with a protocol that you want to implement; make sure it has a
-number defined in prpl.h. If it doesn't, talk to Rob or Eric about adding
-it. *NEVER* use an unassigned number, not even for testing or personal
-use. It's possible that number will be used later by something else and
-that would cause quite a few head-scratchers.
-
-Start off with the following boiler plate:
-
-static struct prpl *my_protocol = NULL;
-
-void newproto_init(struct prpl *ret) {
-	ret->protocol = PROTO_NEWPROTO;
-
-	my_protocol = ret;
-}
-
-#ifndef STATIC
-
-char *gaim_plugin_init(GModule *handle)
-{
-        load_protocol(newproto_init, sizeof(struct prpl));
-        return NULL;
-}
-
-void gaim_plugin_remove()
-{
-        struct prpl *p = find_prpl(PROTO_NEWPROTO);
-        if (p == my_protocol)
-                unload_protocol(p);
-}
-
-char *name()
-{
-        return "New Protocol";
-}
-
-char *description()
-{
-        return PRPL_DESC("New Protocol");
-}
-
-#endif
-
-Replace all NEWPROTO things with your protocol name (e.g. PROTO_OSCAR
-instead of PROTO_NEWPROTO, oscar_init instead of newproto_init). Then
-populate your struct prpl; the most important function is actually name(),
-because without it, Gaim will most likely segfault. The second most
-important function is login(). Not all functions need to be implemented.
-
-There should be absolutely *ZERO* GTK+ in the PRPLs. PRPLs should *NEVER*
-say what the UI *looks* like, only what information needs to be there.
-There's currently an effort to get the GTK+ that is contained in the PRPLs
-directory out of there. If you submit a patch that adds GTK+ to those
-directories it's very likely to be refused, unless if I'm in a good mood
-and decide to relocate things for you. That's not likely.
-
-You're probably wondering how you can do certain things without GTK+. Well,
-you're just going to have to make do. Rely on the UI, that's why it's
-there.  A PRPL should have absolutely ZERO interaction with the user, it
-should all be handled by the UI.
-
-Don't use the _options variables at all. The core should take care of all
-of that. There are several proto_opt fields that you can use on a per-user
-basis. Check out existing protocols for more details.
+For information on hacking on Pidgin, Finch, or libpurple, see:
+	http://developer.pidgin.im