annotate libfaim/README.gaim @ 247:f6e8ea29b24f

[gaim-migrate @ 257] OSCAR: getting a user's info now displays in the dialog window as opposed to the debug window you can add people to your permit/deny list (but be warned - you will get a lot of noise if you do) 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 haven't even gotten it to sign on, but theoretically it can receive
IMs.

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 other users' info
Telling the server who's on your permit/deny lists (buggy)

CURRENTLY UNSUPPORTED FEATURES
==============================
Warning users (libfaim's problem)
Chat (gaim's problem)
Getting users' away messages (libfaim's problem? doesn't work with TOC either)
Getting/setting dir info (libfaim's problem?)
Changing your password (gaim's problem?)
File transfer/IM images/voice chat/etc. (gaim's problem?)

(If I assigned problems incorrectly, sorry.)

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.