head	1.42;
access;
symbols
	v2_0_0beta3:1.42
	v2_0_0beta2:1.42
	v2_0_0beta1:1.42
	v1_5_0:1.38
	v1_4_0:1.38
	gaim-doodle:1.41.0.2
	v1_3_1:1.38
	v1_3_0:1.38
	v1_2_1:1.38
	v1_2_0:1.38
	v1_1_4:1.38
	v1_1_3:1.38
	v1_1_2:1.38
	v1_1_1:1.38
	v1_1_0:1.38
	v1_0_3:1.38
	v1_0_2:1.38
	v1_0_1:1.38
	v1_0_0:1.38
	oldstatus:1.38.0.2
	v0_82:1.38
	v0_81:1.36
	v0_80:1.35
	v0_79:1.35
	v0_78:1.34
	v0_77:1.34
	v0_76:1.33
	v0_75:1.33
	v0_74:1.33
	v0_74-branch:1.33.0.2
	v0_73:1.33
	v0_72:1.31
	v0_71:1.31
	v0_70:1.31
	v0_69:1.31
	v0_68:1.29
	v0_67:1.29
	v0_65:1.29
	v0_64:1.29
	v0_63:1.29
	v0_62:1.29
	gaim_0_60:1.29
	v0_60:1.29
	ZERO_DOT_FUCKING_SIXTY:1.29
	v0_59_9:1.27
	v0_59_8:1.27
	gaim_0_59_7:1.27
	v0_60alpha3:1.27
	v0_59_6:1.27
	v0_59_5:1.27
	v0_59_4:1.27
	v0_59_3:1.27
	v0_59_2:1.27
	gtk1-stable:1.27.0.2
	v059:1.27
	v058:1.27
	v057:1.27
	v056:1.27
	v055:1.27
	v0_54:1.27;
locks; strict;
comment	@# @;


1.42
date	2005.08.22.21.59.10;	author thekingant;	state Exp;
branches;
next	1.41;

1.41
date	2005.04.11.12.21.10;	author lschiere;	state Exp;
branches;
next	1.40;

1.40
date	2004.12.05.21.05.50;	author thekingant;	state Exp;
branches;
next	1.39;

1.39
date	2004.09.11.03.37.15;	author thekingant;	state Exp;
branches;
next	1.38;

1.38
date	2004.08.08.05.37.58;	author thekingant;	state Exp;
branches
	1.38.2.1;
next	1.37;

1.37
date	2004.08.08.00.47.57;	author thekingant;	state Exp;
branches;
next	1.36;

1.36
date	2004.07.31.20.48.03;	author thekingant;	state Exp;
branches;
next	1.35;

1.35
date	2004.06.08.23.32.08;	author eblanton;	state Exp;
branches;
next	1.34;

1.34
date	2004.04.09.02.49.30;	author thekingant;	state Exp;
branches;
next	1.33;

1.33
date	2003.11.16.15.44.30;	author lschiere;	state Exp;
branches;
next	1.32;

1.32
date	2003.11.16.06.00.53;	author lschiere;	state Exp;
branches;
next	1.31;

1.31
date	2003.09.10.20.10.20;	author lschiere;	state Exp;
branches;
next	1.30;

1.30
date	2003.09.09.14.35.07;	author lschiere;	state Exp;
branches;
next	1.29;

1.29
date	2003.02.18.14.36.12;	author lschiere;	state Exp;
branches;
next	1.28;

1.28
date	2003.01.31.13.03.41;	author faceprint;	state Exp;
branches;
next	1.27;

1.27
date	2001.12.09.14.06.36;	author warmenhoven;	state Exp;
branches;
next	1.26;

1.26
date	2001.11.01.18.50.39;	author warmenhoven;	state Exp;
branches;
next	1.25;

1.25
date	2001.10.16.23.37.11;	author warmenhoven;	state Exp;
branches;
next	1.24;

1.24
date	2001.10.16.23.34.26;	author warmenhoven;	state Exp;
branches;
next	1.23;

1.23
date	2001.09.20.08.20.32;	author warmenhoven;	state Exp;
branches;
next	1.22;

1.22
date	2001.08.26.19.18.38;	author warmenhoven;	state Exp;
branches;
next	1.21;

1.21
date	2001.08.20.20.39.28;	author warmenhoven;	state Exp;
branches;
next	1.20;

1.20
date	2001.08.15.18.09.48;	author warmenhoven;	state Exp;
branches;
next	1.19;

1.19
date	2001.05.20.00.01.55;	author warmenhoven;	state Exp;
branches;
next	1.18;

1.18
date	2001.04.13.10.50.32;	author warmenhoven;	state Exp;
branches;
next	1.17;

1.17
date	2001.03.27.21.01.29;	author warmenhoven;	state Exp;
branches;
next	1.16;

1.16
date	2001.03.19.22.40.07;	author warmenhoven;	state Exp;
branches;
next	1.15;

1.15
date	2001.03.10.09.34.31;	author warmenhoven;	state Exp;
branches;
next	1.14;

1.14
date	2000.12.12.12.56.53;	author warmenhoven;	state Exp;
branches;
next	1.13;

1.13
date	2000.11.16.07.35.58;	author warmenhoven;	state Exp;
branches;
next	1.12;

1.12
date	2000.11.04.03.08.53;	author warmenhoven;	state Exp;
branches;
next	1.11;

1.11
date	2000.10.31.10.49.52;	author warmenhoven;	state Exp;
branches;
next	1.10;

1.10
date	2000.10.12.18.59.36;	author warmenhoven;	state Exp;
branches;
next	1.9;

1.9
date	2000.10.12.09.02.56;	author warmenhoven;	state Exp;
branches;
next	1.8;

1.8
date	2000.10.10.00.01.34;	author warmenhoven;	state Exp;
branches;
next	1.7;

1.7
date	2000.10.09.09.18.19;	author warmenhoven;	state Exp;
branches;
next	1.6;

1.6
date	2000.08.28.18.49.17;	author warmenhoven;	state Exp;
branches;
next	1.5;

1.5
date	2000.08.23.19.43.07;	author warmenhoven;	state Exp;
branches;
next	1.4;

1.4
date	2000.08.17.08.35.34;	author warmenhoven;	state Exp;
branches;
next	1.3;

1.3
date	2000.08.17.07.27.45;	author warmenhoven;	state Exp;
branches;
next	1.2;

1.2
date	2000.08.15.17.02.00;	author warmenhoven;	state Exp;
branches;
next	1.1;

1.1
date	2000.08.08.20.55.17;	author warmenhoven;	state Exp;
branches;
next	;

1.38.2.1
date	2005.08.22.21.59.14;	author thekingant;	state Exp;
branches;
next	;


desc
@@


1.42
log
@A blurb.
@
text
@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 CVS. 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 CVS 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 CVS (if you haven't already),
run the following commands:

$ export CVSROOT=:pserver:anonymous@@cvs.sourceforge.net:/cvsroot/gaim
$ cvs login (hit enter as the password)
$ cvs co gaim (you'll see it getting all of the files)
$ 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 CVS works. CVS 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 'cvs diff -u >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.
@


1.41
log
@same thing here, changing to consistently using GTK+, by rlaager
@
text
@d1 8
a8 1
The majority of the below was written by Eric Warmenhoven way back in 
d10 1
a10 1
it. I still think its helpful, but use it at your own risk. 
@


1.40
log
@A little code cleanup here and there.  And I removed gaim_setup() from
gtkmain.c and put it in gtksound.c
@
text
@d21 1
a21 1
you don't know GTK you should go learn that first.
d134 2
a135 2
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.
d259 1
a259 1
  Syd, our resident GTK God, wrote a GtkWidget, GtkTicker. This is that
d429 1
a429 1
There should be absolutely *ZERO* GTK in the PRPLs. PRPLs should *NEVER*
d431 2
a432 2
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
d436 1
a436 1
You're probably wondering how you can do certain things without GTK. Well,
@


1.39
log
@More deprecation of serv_got_update or whatever it's called.

Is all the sound and logging stuff done in the new code?  I didn't
actually check.
@
text
@d207 1
a207 1
main.c:
d209 1
a209 4
  initialization stuff, and showing the login window. It's pretty tiny
  and there's not really much to edit in it. This has some of the most
  pointless functions, like gaim_setup, which optionally turns off sounds
  on signon. A lot of this file should actually be part of other files.
@


1.38
log
@Remove multi.h
@
text
@d106 2
a107 2
serv_got_update, which sets the information in the appropriate struct
buddy and then passes it off to set_buddy.
d245 2
a246 2
  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.
d342 2
a343 3
these functions, but also for calling the appropriate serv_got functions
(e.g. serv_got_update when a buddy comes online/goes offline/goes
idle/etc). It handles each of these on a per-connection basis.
@


1.38.2.1
log
@A blurb.
@
text
@d1 1
a1 8
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
d3 1
a3 1
it. I still think its helpful, but use it at your own risk.
d43 1
a43 1
make your patch, simply run 'cvs diff -u >my.patch' and post it on
d46 1
a46 1
Some Documentation is available on the Gaim api if you run the command
d49 1
a49 1
graphiz dot to generate these docs.
@


1.37
log
@This patch is freaking massive.
Renamed ui.h to gtkdialogs.h
Renamed dialogs.c to gtkdialogs.c
sed'ed the hell out of the .po files

These files are similar to gtkutil.c/.h.  They are meant to contain
dialogs such as the "New Instant Message" window, which does not
belong in gtkblist.c or gtkconv.c, and is called from both places.

Eventually the functions in gtkdialogs.c/.h should be changed to
conform to Gaim's naming convention.
@
text
@a223 7
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...). account_editor is really the only function that the UI needs
  to be concerned with.

@


1.36
log
@Odds n ends.
@
text
@d187 1
a187 1
dialogs.c:
@


1.35
log
@Apparently SF changed this on us.
@
text
@a194 8
gaimrc.c:
  This controls everything about the .gaimrc file. There's not really much
  to say about it; this is probably one of the better designed and easier
  to follow files in gaim. The important functions are towards the bottom.
	This file is also utterly deprecated. It is used only for importing
	on upgrade. the prefs.c and prefs.h files replace the control,
	and gtkprefs.c replaces the gui component.

@


1.34
log
@Any objections to this?
@
text
@d32 1
a32 1
$ export CVSROOT=:pserver:anonymous@@cvs.gaim.sourceforge.net:/cvsroot/gaim
@


1.33
log
@i hate spelling
@
text
@d43 2
a44 3
make your patch, simply run 'cvs diff -u >my.patch' and send it off;
either post it on sf.net/projects/gaim in the patches section, or email it
to gaim@@marko.net.
@


1.32
log
@didn't notice my commits weren't happening, now i did, but you all miss out
on having on-topic commit log this time around
@
text
@d149 1
a149 1
	else controled from within the account editor (and then some)
d168 1
a168 1
	are controled from these files.
@


1.31
log
@a second partial update
@
text
@d155 1
a155 1
	
a163 4
browser.c:
  Code for opening a browser window. Most of the code is trying to deal
  with Netscape. The most important function here is open_url. Have fun.

d168 2
a169 2
	are controled from these files. 
	
d200 1
a200 1
  	This file is also utterly deprecated. It is used only for importing
a209 5
html.c:
  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.

d242 1
a242 1
	side of prefs. 
d249 2
a250 2
  should be pretty straight-forward.	
  	Except I STRONGLY suspect that time has broken this file.
@


1.30
log
@Okay, our text files are REALLY OLD. they need massively updated, HACKING
especially is like 2/3rds wrong. but there is more wrong than i care to
deal with right now. over the next few days you will hopefully see some
updates, BUT IT WON'T BE ENOUGH. someone had better decide to help out
:-)
@
text
@d145 11
d168 1
a168 1
blist.c:
d171 2
a172 1
	finding buddies and groups.
@


1.29
log
@Matthew Smith (smigs) writes:
"- Some more i18n _() added. (ticker.c, timestamp.c)
- A couple of dialogs given titles (instead of
"Unnamed"). (dialogs.c)
- Lots more files added to POTFILES.in
- I cleaned up the file list in HACKING, removing files
that no longer exist, and changing names/locations for others."
@
text
@d1 6
d47 4
a50 11
This file was last modified by $Author: faceprint $ on
$Date: 2003/01/31 13:03:41 $. Do not expect any information contained
within to be current or correct.

Here's something new. Someone requested that I comment the code. No. I'm a
lazy bastard, and I understand most of the code, so I don't need the
comments. I understand that some of you do though. So give me the names of
specific functions that you'd like commented and I'll see what I can do.
It's more likely that those comments will be updated with the code than
this file is, though even that is still unlikely.

d81 2
a82 2
PROGRAM FLOW
============
d85 3
a87 3
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.
d139 1
a139 1
SOURCE FILES
d157 5
a161 4
buddy.c:
  This takes care of the buddy list window and most things related to it.
  It still has some functions that manage the list, but not many.

d192 3
a212 5
list.c:
  This file contains all of the routines for managing buddy lists,
  including importing them from a file, saving them, adding and removing
  buddies and groups, etc.

a236 8
perl.c:
  This was basically copied straight from X-Chat through the power of
  the GPL.  Perl is the biggest, most confusing piece of C code I've ever
  seen in my life (and keep in mind I'm a gaim hacker). I have a basic
  idea of what's going on in it, but I couldn't tell you exactly. The
  top half sets up perl and tells it what's going on and the bottom half
  implements the AIM module.

d238 2
a239 8
  The important function in here is build_prefs, but the most useful
  function is gaim_button. build_prefs draws the window, and calls
  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. The new prefs
  window uses a CList instead of a Notebook, and there's a pretty bad
  hack to get it to work. I won't tell you what though.
d246 2
a247 1
  should be pretty straight-forward.
d291 1
a291 64
HOW BUDDY LISTS WORK
====================

The buddy list is a pain in the ass. Let me start off by saying that. The
most difficult part about getting gaim to do multiple connections was
the buddy list. In its current state it's very much like the UI for
0.10.x and earlier, which is what I was aiming for. However, the code
is completely different. And not much better.

There are two parts to the buddy list: the lists for the connections and
the Buddy List window. list.c contains code to manage the lists themselves
and buddy.c contains the code for the Buddy List window.

Each buddy needs to belong to a connection, it cannot belong to a
"protocol" like in EveryBuddy. The reason is because when you are adding
buddies, you tell the server who is on your buddy list so it can tell you
about them; in order to tell the server, it needs to go out over a
connection. Going out over all connections would not be good, so you need
to specify which connection they go out on.

Managing lists is therefore fairly easy, each group and buddy has an
associated connection. Management functions like add_buddy/remove_buddy
and add_group/remove_group all take a gaim_connection. These are all in
list.c. They're boring.

The window is a lot more fun. There's really only one function that
does anything interesting, and that's set_buddy. (There's also things
like build_edit_tree, but that's boring.) set_buddy is called by
serv_got_update (and should only be called by that function) any time
a user signs on, signs off, goes away, comes back, goes idle, etc, etc,
etc. Various things happen depending on the new state of the buddy.

struct buddy has a member, present, which is set to either 0, 1, or
2. You can check if the buddy is online with "if (b->present)". This
becomes important. present is set to either 0 or 1 by serv_got_update,
or is not set at all. When the buddy is passed to set_buddy, if present
is 1 then set_buddy plays the BUDDY_ARRIVE sound, and sets present to 2,
to indicate it has already received notification of arrival. It then
does other signin-related stuff: setting the pixmap to the login icon;
updating the conversation windows; etc.

The most important thing it does though, if a buddy is present, is it
checks for the existance of the appropriate group_show and buddy_show for
that buddy.  Each buddy must belong to a group. group_shows are based on
name; there can only be one group_show for each group name. buddy_shows
are based both on name and on group_show; there can only be one buddy_show
in a group_show for each name. However, there can be two buddy_shows
with the same name as long as they have different group_shows.

Each buddy_show has a GList of connections that has registered its related
buddy as being online. set_buddy makes sure that the connection that it's
being passed is part of the connlist for the buddy_show associated with
the struct buddy that it's passed (it helps to know your data structures).

If a buddy logs off (b->present == 0), and a buddy_show exists for
that buddy, then set_buddy will play the logoff sound, change the icon,
remove the connection from the connlist for the buddy_show, etc.

And that's how that works. For the buddy lists, connections own buddies;
for the window, the buddies own the connections. When the buddy_show
connlist count drops to zero it disappears from existance.


PLUGINS
@


1.28
log
@aim_user is dead.  long live gaim_account.
@
text
@d41 2
a42 2
This file was last modified by $Author: warmenhoven $ on
$Date: 2001/12/09 14:06:36 $. Do not expect any information contained
a145 14
aim.c:
  This is where the main() function is. It takes care of a lot of the
  initialization stuff, and showing the login window. It's pretty tiny
  and there's not really much to edit in it. This has some of the most
  pointless functions, like gaim_setup, which optionally turns off sounds
  on signon. A lot of this file should actually be part of other files.

applet.c:
  This controls most things that are related to the applet. I don't like
  looking at this file because it still has functionsLikeThis. But at
  least it doesn't have many of them anymore. Anyway, this file isn't
  very big because there's really not much difference between the panel
  version and the app version.

a198 11
gtkspell.c:
  This controls spell checking. It's not a widget per se but it does have
  some influence over the GtkText widget. It's a separate project from
  gaim; if you have a patch for this file send it to the author (the
  contact info is in the file).

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.

d215 7
a246 3
plugins.c:
  This contains the UI for the plugins dialog. It's mostly GTK.

d283 12
a294 1
ticker.c:
a300 6

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.
@


1.27
log
@bye bye my love bye bye
@
text
@d42 1
a42 1
$Date: 2001/11/01 18:50:39 $. Do not expect any information contained
d120 2
a121 2
aim_user can have one gaim_connection associated with it. aim_user and
gaim_connection both have a protocol field. This is kind of confusing:
d439 4
a442 4
in an aim_user struct, and kept track of in the aim_users GList (GSList?).
Each aim_user 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).
d462 2
a463 2
login function, passing it the aim_user struct that is attempting to sign
on. The prpl is then responsible for seeing that the gaim_connection
d465 2
a466 2
being online (by calling account_online and passing it the aim_user and
gaim_connection structs). At that point, the aim_user and gaim_connection
@


1.26
log
@it's 10:50
@
text
@d7 9
a15 4
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.
d19 2
a20 2
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
d28 1
a28 2
$ cvs co gaim
(you'll see it getting all of the files)
d32 8
a39 7
You'll now have your normal gaim tree with ./configure and all. (If you
want to make your life really simple, learn how CVS works. CVS 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 'cvs diff -u >my.patch'
and send it off; either post it on sf.net/projects/gaim in the patches
section, or email it to gaim@@marko.net.
d42 1
a42 1
$Date: 2001/10/16 23:37:11 $. Do not expect any information contained
d45 6
a50 6
Here's something new. Someone requested that I comment the code. No. I'm
a lazy bastard, and I understand most of the code, so I don't need the
comments. I understand that some of you do though. So give me the names
of specific functions that you'd like commented and I'll see what I can
do. It's more likely that those comments will be updated with the code
than this file is, though even that is still unlikely.
d56 3
a58 3
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. :)
d72 3
a74 3
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.
d78 2
a79 2
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.
d92 4
a95 2
about them. If the user clicks the "Signon" button instead, serv_login
is called.
d102 8
a109 16
appropriate protocol. We'll assume TOC for the rest of this discussion;
even the libfaim guys get scared by oscar.c, and I'll talk about the
PRPLs later.

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.
d121 7
a127 3
gaim_connection both have a protocol field; gaim_connection's should
be constant once it is set. (I'll talk about the gaim_connection struct
more later.)
a170 2
  (This file may give you problems with GTK 2.0, because it uses parts
  of GDK that it's not supposed to know about.)
d173 2
a174 4
  This takes care of not only nearly everything buddy-related (the
  buddy lists, the window, etc.), but also a lot of the code flow and
  util functions. Look for good things like find_buddy, set_buddy,
  and signoff here.
d191 3
d221 2
a222 1
  widget. It's cool, and it's tiny.
d235 15
d266 1
a266 5
  This is the "plugin plug", as the file states. This file is probably
  the only file in all of gaim that at the top has all of the functions
  and global and static variables named out for you. It makes reading
  it a little easier, but not by much. A lot of the code in here deals
  with the plugin window rather than the plugins themselves.
a277 6
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.

d285 6
d318 3
a320 55
PRPL sources:
-------------

ICQ (UDP v5)
  All of the .c and .h files in here, with the exception of gaim_icq.c,
  are part of ICQLib, by Bill Soudan and others. gaim_icq.c is what
  interacts with gaim, and Eric wrote it. ICQLib is a fairly complete
  implementation of the ICQ protocol, so if you want to add a new
  feature you're probably going to be adding it to gaim_icq.c and not
  to ICQLib.

ICQ (2000)
  This protocol doesn't exist yet. If you get really bored one day,
  you can write it. It shouldn't be that hard since ICQ2000 uses Oscar,
  so it should just be copying everything from oscar/ to here, and then
  making small modifications to deal with various things. Have fun.

IRC
  Rob wrote irc.c, and since it is only one file it stands by itself.
  All of the networking code is contained inside this file, as well as
  the parts that interact with gaim.

Jabber
  jabber.c was written by Adam Fritzler (the guy that wrote libfaim),
  and is maintained by Eric. The other .c and .h files belong to
  libxode and libjabber, which were written by the Jabber developers.

MSN
  Rob wrote msn.c, and md5.c is a standard file. MSN doesn't use its
  own library; all of the networking code is included inside of msn.c.

Napster
  Rob wrote napster.c, and since it is only one file it stands by
  itself.

Oscar
  Most of these files are libfaim; the only one that's written by a Gaim
  developer is oscar.c, and even that's questionable. oscar.c is mostly
  copied straight from faimtest, the small program that comes with
  libfaim.

TOC
  Everything TOC-related, more or less. All of it is in one big file, so
  depending on your style that either makes things a lot easier or a lot
  harder. Have fun with it. This protocol seems to break more easily
  than any of the others, which seems odd to me. But oh well.

Yahoo
  All of the files in here were written by Eric. All of the .c and .h
  files except yay.c are part of a library that Eric wrote, libyay.
  yay.c is what interacts with gaim.

Zephyr
  zephyr.c is the only file in this directory by Eric; all the other
  files are part of the Zephyr library from MIT.
d322 2
a323 3

HOW THE BUDDY LIST WORKS
========================
d331 15
a345 12
All of the buddy list stuff is in buddy.c, so you'll only have to have
that one file open (and possibly gaim.h for the struct definitions). There
are two sets of functions: those that deal with the buddy lists, and
those that deal with the window. (I say lists because each connection
has their own buddy list, independent of the others, even though the UI
merges them.)

The buddy list functions work pretty much the same way they did before;
except now that each buddy and group belongs to a connection, things
like find_buddy take an additional argument, the connection you want to
search for the buddy in.  Read gaim.h for a good list of them: find_buddy,
find_group, add_buddy, remove_buddy, remove_group.
d442 1
a442 4
as an int which is #define'd in prpl.h). The way the management of the
users works is, there will (hopefully) only be one user for a given
screenname/ protocol pair (i.e. you may have two user warmenhoven's,
but they'll both have a different protocol number).
d487 53
d546 9
@


1.25
log
@hi again
@
text
@d37 1
a37 1
$Date: 2001/10/16 23:34:26 $. Do not expect any information contained
d39 7
@


1.24
log
@hi.
@
text
@d37 2
a38 1
$Date: 2001/09/20 08:20:32 $.
@


1.23
log
@no rvous.c
@
text
@d33 2
a34 1
and send it off.
d37 1
a37 1
$Date: 2001/08/26 19:18:38 $.
@


1.22
log
@updated hacking and todo slightly. sebfrance sent in an updated french translation. thanks :)
@
text
@d36 1
a36 1
$Date: 2001/08/20 20:39:28 $.
a266 7

rvous.c:
  This was originally going to be the stuff for all of the Buddy Icon
  and Voice Chat stuff, but I got really sick of protocol hacking really
  quick.  Now it only houses the file transfer stuff, which only works
  for TOC. ("Works" being a very subjective statement. This file needs
  to be rewritten.)
@


1.21
log
@wee
@
text
@d36 1
a36 1
$Date: 2001/08/15 18:09:48 $.
d189 1
a189 1
  is in util.c for winaim lists and toc.c for gaim's own lists.)
d523 7
@


1.20
log
@coding style. mmm. Also got rid of po/ChangeLog, it's autogenerated and we don't use it.
@
text
@d36 1
a36 1
$Date: 2001/05/20 00:01:55 $.
a229 6
oscar.c:
  One big hack of copied code. This is supposed to be the libfaim tie-in
  in gaim. Most of it is just copied straight from faimtest, the small
  program that comes with libfaim. I'm not even sure how half of it works,
  if that makes you feel any better.

a295 9
toc.c:
  This handles everything TOC-related, including parsing gaim's buddy
  list.  Most of this file is toc_callback, which parses the incoming
  information from the server. I really don't like TOC though. (I've spent
  waaayyyy too much time with TOC. I rewrote the signon process for this
  file at one point, so that read was only called when data was pending.
  Since then the TOC server has been blocking my IP (probably my own
  stupid fault, sending bad strings or some such).)

d305 1
a305 6
plugins/yay: Yahoo
  All of the files in here were written by Eric. All of the .c and .h
  files except yay.c are part of a library that Eric wrote, libyay.
  yay.c is what interacts with gaim.

plugins/icq: ICQ (UDP v5)
d313 5
a317 3
plugins/msn: MSN
  Rob wrote msn.c, and md5.c is a standard file. MSN doesn't use its
  own library; all of the networking code is included inside of msn.c.
d319 1
a319 1
plugins/irc.c: IRC
d324 1
a324 1
plugins/jabber: Jabber
d329 5
a333 1
plugins/napster.c: Napster
d337 18
a354 1
plugins/zephyr: Zephyr
@


1.19
log
@removing lots of auto-generated files. this should help when things like gettext and libtool are upgraded (like they are in debian). remember, don't run ./gen anymore, run ./autogen.sh. it'll also run ./configure for you with any options you pass it.
@
text
@d35 31
a65 2
This file was last modified by $Author: eric $ on
$Date: 2001/05/19 22:49:48 $.
@


1.18
log
@various fixes (for plugins especially), other updates. made WEBSITE macro so it's easy to change (not that i think it'll be changing again), updated some files to reflect that change.
@
text
@d26 1
a26 1
$ ./gen
d35 2
a36 2
This file was last modified by $Author: warmenhoven $ on
$Date: 2001/03/27 21:01:29 $.
@


1.17
log
@doc updates
@
text
@d36 1
a36 1
$Date: 2001/03/19 22:40:07 $.
d321 4
@


1.16
log
@I he good have a grammar good.
@
text
@a34 8
There's one little thing that's just a pet peeve, and it's really stupid.
In ./configure there's an --enable-debug option. This does two things:
compiles with -Wall, and prints debugging information to stdout. The
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.

d36 1
a36 1
$Date: 2001/03/10 09:34:31 $.
d287 34
@


1.15
log
@hi there
@
text
@d44 1
a44 1
$Date: 2000/12/12 12:56:53 $.
d132 1
a132 1
  who know it all they work and I don't think any of us know why it works
@


1.14
log
@woo! i have a 10-ish page paper due in 11 hours on a book i haven't read yet. i'm in a writing mood.
@
text
@d44 1
a44 1
$Date: 2000/11/16 07:35:58 $.
d120 7
d130 4
a133 1
  etc.
d175 11
a185 19
gnome_applet_mgr.c:
  This controls most things that are related to the applet. I don't like
  looking at this file because it still has functionsLikeThis. But at
  least it doesn't have many of them anymore. Anyway, this file isn't
  very big because there's really not much difference between the panel
  version and the app version.

gtkhtml.c:
  This is really just one big hack. I recommend not looking at this
  file if you want to save your sanity. (It's going to be replaced
  eventually anyway.)  People have asked why we don't replace this with
  GNOME's GtkHTML, or embed mozilla (yes, they were serious). There
  are two reasons. The first is that doing that would cause gaim to
  require 6 extra libraries that nobody needs or wants or has. The
  second is that we really don't need, or even want, a full-fledged
  HTML viewer. We don't even want a normal HTML viewer because the text
  that gets sent gets parsed and displayed different than normal HTML.
  (Try inserting a newline and you'll see what I mean.) We should only
  support about 12 tags, not the 50 that normal HTML supports.
@


1.13
log
@updated hacking to reflect mid's changes, and applied mid's libyahoo patch
@
text
@d3 8
a10 5
soon, 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. Hopefully that's enough to get most of you going.
d14 2
a15 2
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
d22 1
a22 2
$ cvs login
(hit enter as the password)
d30 4
a33 1
friend.)
d43 2
a44 1
This file was last modified by $Author: warmenhoven $ on $Date: 2000/11/04 03:08:53 $.
d56 3
a58 2
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.
d62 6
a67 6
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. We'll assume TOC for the rest of this
discussion; Oscar has a lot of bad hacks to get it working that I don't
even want to think about.
d72 3
a74 3
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.
d82 13
a94 6
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
that are connected with multiple connections that are best explained by
reading the code.
d116 3
a118 2
  and there's not really much to edit in it. Watch out for bad Oscar
  sign in hacks.
d122 2
a123 2
  (do_im_away); coming back (do_im_back); drawing the away window;
  etc. To be honest I haven't looked at this file in months.
d128 2
d132 4
a135 4
  This takes care of not only nearly everything buddy-related (the buddy
  list, the permit/deny lists, and the window), but also a lot of the
  code flow and util functions. Look for good things like find_buddy,
  set_buddy, and signoff() here.
d149 2
a150 2
  chat and IM toolbar (with the B/I/U/S buttons) are both built from the
  same function, build_conv_toolbar.
d153 6
a158 5
  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.
d166 5
a170 5
  A hideous creation from the days before I started working on gaim. Most
  of it works, but it has functionsLikeThis. I hate looking at this
  file, but I'm too lazy to change the functions. The best functions
  are things like set_applet_draw_open, whose sole purpose is to set a
  global variable to TRUE. [ note 8/22/00 - I finally changed this file. ]
d173 11
a183 6
  This is really just one big hack. It started off as an HTML widget that
  was written for Gnome as far as I can tell. The current version is
  huge, requires way too many libs, and is too hard to upgrade to. But
  we've managed to hack this poor old version into basically what we
  need it for. I recommend not looking at this file if you want to save
  your sanity.
d198 1
d203 3
a205 7
  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.
d234 3
a236 1
  calls to gaim_button you'll figure it out right away.
d239 4
a242 4
  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.
d245 5
a249 5
  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.
d255 2
a256 1
  for TOC.
d259 2
a260 2
  This is where all of the differentiation between TOC and Oscar is
  done.  Nearly everything that's network related goes through here
d266 3
a268 3
  (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
d282 5
a286 1
  information from the server. I really don't like TOC though.
d295 110
d411 45
a455 44
It also has certain options, and the protocol it uses to sign on (kept as
an int which is #define'd in prpl.h). The way the management of the users
works is, there will (hopefully) only be one user for a given screenname/
protocol pair (i.e. you may have two user warmenhoven's, but they'll both
have a different protocol number).

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 serv_got functions (e.g. serv_got_update when a
buddy comes online/goes offline/goes idle/etc). It handles each of these on
a per-connection 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 aim_user 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 aim_user and gaim_connection structs). At
that point, the aim_user 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.
@


1.12
log
@updated HACKING to describe gaim_connection/aim_user/prpl.
updated FAQ to answer some questions about multiple connections.
made it so you're not able to send a message in a chat room that you're no longer in (i.e. when you were in the room but sign off)
free'd the buddy list when the connection is destroyed
tried to prevent set_buddy from being called before the buddy list is drawn
i think there was something else
@
text
@d38 1
a38 1
This file was last modified by $Author: warmenhoven $ on $Date: 2000/10/31 10:49:52 $.
a186 6
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
  stuff; use these instead of calling the proxy functions.

d223 5
a227 3
  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.
@


1.11
log
@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.
@
text
@d5 3
a7 2
things, then what you'll find in each of the source files. Hopefully
that's enough to get most of you going.
d38 1
a38 1
This file was last modified by $Author: warmenhoven $ on $Date: 2000/10/12 18:59:36 $.
d272 53
a324 3
So that's our little tour of the internals of Gaim. It's really not
difficult to figure out if you've spent any time with GTK. I'm looking
forward to getting all of your patches :)
@


1.10
log
@i hope this works
@
text
@d37 1
a37 1
This file was last modified by $Author: warmenhoven $ on $Date: 2000/10/12 09:02:56 $.
d44 3
a46 2
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.
d49 2
a50 2
called. (NOTE: the login window will probably be changed soon.) This
then displays all of the users and various information about them.
d65 1
a65 1
it gets input from after signon is invariably the server, when the server
a73 7
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).

d85 1
a85 3
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.)
d171 3
a173 4
  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.
d184 1
a184 3
  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).
d221 6
d245 5
a249 5
  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.
@


1.9
log
@More patches! More patches! :)
@
text
@d37 1
a37 1
This file was last modified by $Author: warmenhoven $ on $Date: 2000/10/10 00:01:34 $.
d55 2
a56 3
password before calling serv_login. serv_login then finds the user,
and signs in using the specified protocol. (This is a bad way of doing
things and should be fixed.) We'll assume TOC for the rest of this
@


1.8
log
@*** MULTIPLE-CONNECTIONS ***
@
text
@d37 1
a37 1
This file was last modified by $Author: warmenhoven $ on $Date: 2000/10/09 09:18:19 $.
d43 56
a98 4
This has completely changed since multiple connections were added. Please
be patient; as soon as the code starts to settle this will get rewritten.
Most of the source files stayed the same though; only the one that got
added (multi.c) isn't covered below.
d184 13
@


1.7
log
@This is mostly just a test.
@
text
@d37 1
a37 1
This file was last modified by $Author$ on $Date$.
d43 4
a46 41
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 "signon" is clicked, dologin() is called. This
in turn calls serv_login, which checks to see if you want to use Oscar or
TOC, and calls oscar_login or toc_login appropriately. We'll assume TOC
for the rest of this discussion; Oscar has a lot of bad hacks to get it
working that I don't even want to think about.

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 (by GTK through update_all_buddies).

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.
@


1.6
log
@save buddy chats, and better display of them (though they flash now, but they don't cause errors)
@
text
@d37 1
a37 2
This was written around August 8, 2000. It's now August 15, 2000, and I'm
sure a lot of it is already out of date.
@


1.5
log
@la la la. i suppose sooner or later i should document how to write a perl script.
@
text
@d17 1
a17 1
$ export CVSROOT=anonymous@@cvs.gaim.sourceforge.net:/cvsroot/gaim
@


1.4
log
@la la la
@
text
@d146 1
a146 1
  global variable to TRUE.
@


1.3
log
@just some doc updates
@
text
@d8 21
@


1.2
log
@bmiller translated perl to C so now gaim can import winaim lists. oh yeah,
the permit/deny stuff isn't quite working right. argh.
@
text
@d9 1
a9 1
In ./configure there's and --enable-debug option. This does two things:
d34 1
a34 1
are going to change the login process, since it pretty much just folows
@


1.1
log
@added a file to help people try to hack gaim
@
text
@d16 3
@

