annotate libfaim/README.gaim @ 249:810c595258c8

[gaim-migrate @ 259] You can now get users' away messages. committer: Tailor Script <[e-mail]>

Hello, your good friend EW here with a nice little notice that I'm sure will
affect the ten of you who actually read this.

I'm going to start trying to get gaim to use Oscar through libfaim. As far as I
can tell, the only thing it used to be able to do is sign on and receive IMs. I
updated libfaim to what's currently in the libfaim CVS on sourceforge. As of
right now, I've been able to implement most of the features libfaim offers.

I'm going to try to make as few modifications as possible to the libfaim code.
The only two modifications I'll probably ever make to it are 1) to make my life
easier (like putting all the .h files in the same directory as the .c files) or
2) to fix a compilation error that I happen to be able to fix very easily (like
with a typo or something). That means that what you're getting when you enable
oscar is basically faimtest (the very instructional program included with the
libfaim source on sourceforge) with the Gaim GTK front-end. I'll put any changes
I make into a file, but so far, I haven't made any changes other than moving the
.h files down a directory.

CURRENTLY SUPPORTED FEATURES
============================
Signing on
Sending IMs
Receiving IMs
Being away/coming back
Being idle
Setting your info
Getting users' info
Getting users' away messages (PLEASE do not use oscar/libfaim just because of
	this, gaim with libfaim still really buggy, none of you will listen to
	me anyway)
Telling the server who's on your permit/deny lists (buggy)
Chat:
 - joining rooms
 - leaving rooms
 - talking

CURRENTLY UNSUPPORTED FEATURES
==============================
Warning users/getting warned
Chat:
 - whispering
 - refreshing the chatlist in the preferences dialog
 - invitations (both to and from you)
Getting/setting dir info
Changing your password
File transfer/IM images/voice chat/etc.

KNOWN ISSUES
============
- libfaim apparently has a problem with receiving messages to fast (sort of). If
someone sends you a message "too fast", the server says "slow down" basically,
and lets you know that a message was dropped. The time interval between messages
seems to be much longer with libfaim than with TOC (i.e. you can receive more
messages in less time with TOC than with libfaim). The outgoing limit seems to
be about the same. So if all your friends are slow typists, this shouldn't be a
problem.

- Signing on every once in a while acts really bizarrely for me. Maybe it's just
me.

- Adding or removing people to your permit/deny lists causes the server to tell
you everyone on your buddy list signed off and then immediately signed in again.
While you won't ever see that it happens (other than everyone will suddenly have
the guy-in-the-door icon), you'll hear it. Be warned.

HOW TO HELP
===========
So here's what you can do in order to help gaim use libfaim. There are basically
3 steps:

1) In server.c, find an #ifndef USE_OSCAR tag that doesn't have a corresponding
#else. Find it in a good fun function that you want to implement. Basically
copy the code from the TOC side for the Oscar side. For example:

void serv_send_im(char *name, char *message, int away)
{
	char buf[MSG_LEN - 7];

#ifndef USE_OSCAR
	g_snprintf(buf, MSG_LEN - 8, "toc_send_im %s \"%s\"%s", normalize(name),		   message, ((away) ? " auto" : ""));
	sflap_send(buf, strlen(buf), TYPE_DATA);
#endif
	if (!away)
		serv_touch_idle();
}

becomes:

void serv_send_im(char *name, char *message, int away)
{
        char buf[MSG_LEN - 7];

#ifndef USE_OSCAR
        g_snprintf(buf, MSG_LEN - 8, "toc_send_im %s \"%s\"%s", normalize(name),
	           message, ((away) ? " auto" : ""));
	sflap_send(buf, strlen(buf), TYPE_DATA);
#else
	oscar_send_im(name, message, away);
#endif
	if (!away)
		serv_touch_idle();
}

2) Edit gaim.h to add the new function (you'll see a list of them in there)

3) Edit oscar.c to implement the new function

Most of the functions you're going to need to call use a session and connection
structure. These are kept (globally) in oscar.c as gaim_sess and gaim_conn. For
example, from above:

void oscar_send_im(char *name, char *msg, int away) {
	if (away)
		aim_send_im(gaim_sess, gaim_conn, name, AIM_IMFLAGS_AWAY, msg);
	else
		aim_send_im(gaim_sess, gaim_conn, name, 0, msg);
}

That should be all that's needed. And that's that. Happy hacking.