Gaim: The Pimpin' Penguin IM Clone Thats Good For The Soul 1 The Basics 1.1 What does 'gaim' stand for? 1.2 Where are my log files stored? 1.3 What are GtkHTML and GtkIMHtml, and why not just use GNOME's GtkHTML? 1.4 How do I load plugins/perl scripts? 1.5 I'm not a native English speaker and I would like a translated version of gaim. 1.6 Why can I import my buddylist but not export it? 2 Multiple Connections 2.1 What do you mean by "multiple connections"? 2.2 How do I sign on more than one account? 2.3 How do buddy lists work for multiple connections? 2.4 What's a PRPL? 2.5 How do I use a different protocol? 3 About the Protocols (what they support, and how to do things with them) 3.0 Introduction 3.1 TOC 3.2 Oscar 3.3 Yahoo! 3.4 IRC 3.5 ICQ 3.6 MSN 3.7 Jabber 3.8 Napster 4 Problems 4.1 Sound doesn't work 4.2 Clicking on URLs doesn't open Netscape 4.3 I don't use Netscape 4.4 I have a bug not described here 5 Programming 5.1 I have a patch for gaim! 5.2 I have a plugin/perl script for gaim! 5.3 Can you teach me how to program GTK? 6 Miscellaneous 6.1 Can I talk to you on IM? 6.2 I want to write an IM client. Will you help me? 6.3 I have money. I need software written. Can you help? 6.4 I have hardware here that's not being used. Can you use it? 6.5 I would like to send you beer. 6.6 Are you going to port this to Windows? 6.7 Why no AOL logo? 6.8 Why the GPL? 6.9 What is a wagii? 6.10 What window manager/distribution/other crap do you use? 6.11 Is XX a good hard drive, YY a good monitor and ZZ a good CPU? 6.12 I want to contribute to the effort. Where can I send beer to? --- 1 The Basics 1.1 What does 'gaim' stand for? It's basically the letter 'g' tacked on to the beginning of 'AIM' (which is fairly obvious). G stands for all sorts of good things. Girls, Godzilla, GTK, graham crackers, whatever. 1.2 Where are my log files stored? Your logs are stored in $HOME/.gaim/logs/. They had previously been stored in $HOME/.gaim/YourScreenName/ (e.g. $HOME/.gaim/EWarmenhoven). 1.3 What are GtkHTML and GtkIMHtml, and why not just use GNOME's GtkHTML? The widget Gaim had previously used to display HTML was called GtkHTML, and was written by Mark and Jim specifically for Gaim. Over time, Rob and Eric hacked at it (read: broke it) and it's gotten to be very fragile and fairly buggy. One day Eric got pissed off at GtkHTML and decided to rewrite it, and called it GtkIMHtml (IM to indicate that it should be used in IM clients). He made it its own separate project, so that other IM clients (like Jabber clients) could use it. He based it somewhat off of the old GtkHTML and GNOME's GtkHTML. GNOME's GtkHTML is a very powerful HTML viewer. Because of this, it isn't well-suited for Gaim. It wouldn't be very good if we let you have IFrames in your conversation, for example. Also, GNOME's GtkHTML depends on a lot of GNOME libraries that we don't want to force people to use in Gaim. (There is a strip-down version, CSCHTML, which doesn't use the GNOME libraries; but the first objection (that it supports too many tags) still applies.) 1.4 How do I load plugins/perl scripts? Plugins you had loaded when you quit gaim are loaded again when you start gaim. To load a new plugin, either click 'Plugins' on the login screen, or select 'Plugins' from the 'Tools' menu in the buddy list. From there, you can load and unload plugins, and configure certain ones. If you click on the 'Load Plugin' button, it will present you with a file dialog, asking which file you want to load; it will default to looking for a .so file in the directory plugins get installed to, though you don't have to load a .so file, and you don't have to load it from that directory. When you start gaim, all the .pl files in ~/.gaim will be loaded automatically. You can also load new scripts from the 'Perl' menu in 'Tools'. From that menu, you can load a new script (similarly to how you loaded a plugin above), unload all your loaded scripts, and list which scripts you have loaded. 1.5 I'm not a native English speaker and I would like a translated version of gaim. Gaim currently has a few translations (French, Spanish, Korean, and Simplified Chinese); however, most of them are out of date. If you would like to update or add a translation of gaim, email or IM either Rob or Eric and they can tell you how to go about it. 1.6 Why can I import my buddylist but not export it? Because you don't have to. Gaim, out of the kindness of its sweet little heart, automagically exports your buddylist for you. You can find a copy of your list in ~/.gaim/YOURNAME.PROTO.BLIST. For example, if you're using AIM, and your name is JoeUser, then your buddy list could be found in: ~/.gaim/JOEUSER.0.blist. 2 Multiple Connections 2.1 What do you mean by "multiple connections"? Multiple Connections means that it's possible to connect to the AOL servers using more than one screenname at a time. It's just a way of not having to run three copies of gaim for each of your screennames. 2.2 How do I sign on more than one account? The Account Editor controls all of your accounts, and lets you add, delete, modify, and sign on/off accounts. It is accessible from the login window or from the 'Tools' menu in the buddy list as 'Accounts'. Simply highlight the account you want to sign on, and click the 'Sign On/Off' button. To sign on another account, highlight it and click the 'Sign On/Off' button. There is a column labeled 'Currently Online' to let you know if the account is online or not. 2.3 How do buddy lists work for multiple connections? "The same as they did before" is the simple answer. Each account you have will have its own buddy list, which you can add buddies to and remove from. In the 'Edit Buddies' tab of your buddy list, you'll see the name of each of your online accounts (unless if you only have one), with its buddy list nested underneath it. 2.4 What's a PRPL? PRPL stands for Protocol Plugin. It's a way to dynamically add new protocols to gaim. This allows you to use gaim as your AIM, ICQ, Yahoo, and even IRC client, all at the same time. Loading a PRPL is just like loading any other plugin - simply load the .so file from the plugins dialog. 2.5 How do I use a different protocol? In the Account Editor, click the 'Add' button to add a new account. Below the password entry, you should see a menu labeled 'Protocol', with a list of the protocols available for you to use. (If you don't see the protocol you want to use, make sure you have the proper PRPL loaded.) Enter in your username (for ICQ this should be your UIN) and password, and you're set. You can then sign the account on by clicking the 'Sign On/Off' button when the account is highlighted. 3 About the Protocols (what they support, and how to do things with them) 3.0 Introduction This really only describes the protocol, and how gaim is able to use it. For a listing of what gaim has implemented with each protocol, please read the STATUS file. 3.1 TOC TOC is an open protocol (meaning that there's open documentation from the people who developed it), developed by AOL, for clients to use to connect to the AIM server. It has stopped being supported by AOL (though they do still make changes to the TOC server). It is a strip-down and simplified version of their "real" protocol, Oscar. TOC is a TCP protocol, and will only ever make one TCP connection (unless if you accept a file transfer request). Your buddy list is stored on the server, and gaim keeps a locally cached copy as well. When you sign on the server and local lists are merged. 3.2 Oscar Oscar is the protocol that the Windows version of AIM uses (and actually, ICQ2000 uses it too). It's a closed protocol, meaning that in order for gaim to use it, someone had to reverse-engineer it. For gaim, the libfaim authors did this, and wrote a library so that we could use it. Oscar is a TCP protocol, but it makes several connections: the authorizor (the initial connection, who you send your screenname/password to), the BOS (which is the "main" connection, through which all your messages go), ChatNav (which lets you join chat rooms), as well as one for each chat room you join. Oscar does let you store your buddy list on the server, but libfaim hasn't added that functionality yet. 3.3 Yahoo! Yahoo! uses a closed protocol; the authors of libyahoo reverse-engineered it and gaim uses that library. It is a TCP protocol, and makes several connections, though I'm not entirely sure at which points. It stores your buddy list on the server, and gaim keeps a locally cached copy. When you sign on the server and local lists are merged. 3.4 IRC IRC is an open protocol (though I've heard that some servers deviate slightly from it). It's a TCP protocol, and will only ever make one connection (outside of DCC connections). 3.5 ICQ ICQ is a closed protocol, though there have been several groups of people who have reverse-engineered it, and there are several libraries available. Gaim uses icqlib (which supports multiple connections, as opposed to libicq, which does not). It is a mix of UDP and TCP: the connection to the server is UDP, and conversations are TCP unless if they are sent through the server. This means you'll make one UDP connection, and possibly very many TCP connections. 3.6 MSN MSN is a weird TCP protocol written by Microsoft. It requires multiple connections and is a real headache :). 3.7 Jabber Jabber is an open protocol, developed by the Jabber team, and is XML-encoded. It is a TCP protocol, and you will only ever make one TCP connection. Jabber has a feature it calls 'transports', where the server tells you which services it has available (such as AIM or ICQ), and you tell it which service you would like to use. This way you can have only one connection, but be connected to AIM and ICQ (among others) several times. Anyone who gives a damn about Open Source, especially open messaging, should use Jabber. They have the only Open Source IM server. 3.8 Napster Napster is, as you know, the protocol used by that wonderful little program called napster. You know the one! It's what millions of college kids across america are using to sastisfy their longing for music :-D. Anyways, gaim supports it. It's kind of fiunky, though. Napster is a TCP protocol and only requires one connection to the server. All file transfers, however, are explicitly client to client. The plugin currently only supports one way file transfer (downloading) from people who are _not_ firewalled. You can also send private messages to each other, join chat rooms, browse a user's files, and search. More implementation coming soon. 4 Problems 4.1 Sound doesn't work ./configure should autodetect whether or not you have ESD libraries. If you have them it will compile with them; if not it won't. If it compiles with them you don't need to be running the ESD daemon; it'll automatically fall back to using /dev/dsp. Make sure gaim has the proper permissions to talk to /dev/dsp and /dev/audio though! 4.2 Clicking on URLs doesn't open Netscape Netscape either needs to be running on the current display (though gaim should handle remote netscape windows OK), or 'netscape' needs to be in your path. 4.3 I don't use Netscape There's the option to manually enter which browser you'd like to use. We're interested in supporting browsers other than Netscape though; send us some information about how to send a URL to your browser (source is nice :) ). 4.4 I have a bug not described here We have a page at http://sourceforge.net/projects/gaim/, and from there you can report your bug. 5 Programming 5.1 I have a patch for gaim! Great! Send it over to the Patches section on our sourceforge page, http://sourceforge.net/projects/gaim/. From there we'll take a look at it (no promises that it'll get in, but we'll at least take a look at it). 5.2 I have a plugin/perl script for gaim! Great! Post it to the Patches section on our sourceforge page, and mark it as a plugin. Then other people will be able to see it and use it. (Make sure that you understand that your plugin is necessarily GPL'd, and you must provide source to your plugin.) 5.3 Can you teach me how to program GTK? Actually, I can't. I'm a very bad teacher. I'm much too impatient. There is a really great tutorial and API reference on the GTK website though, http://www.gtk.org/. That's how I learned, anyway. 6 Miscellaneous 6.1 Can I talk to you on IM? Sure. Our IM names can be found in the AUTHORS file. Keep in mind though that we're busy people. We use those screennames as our main screen names, not just to talk to gaim users. So please, don't IM us for us to answer questions about Linux. We'd like to be able to answer everyone's questions, but we just don't have the time. We aren't paid to hack gaim; we do have other jobs. Also, please don't waste our time with a simple "hi" or "hello." Don't ask if you can ask a question, just ask it. We'll usually respond. 6.2 I want to write an IM client. Will you help me? I'll give you advice, but other than that, no (unless you'd like to pay me). 6.3 I have money. I need software written. Can you help? Oh yes. Our email addresses are bj91704@binghamtom.edu (SeanEgn) and rob@marko.net (RobFlynn). 6.4 I have hardware here that's not being used. Can you use it? Most certainly. IM me or email me and I'll tell you where you can ship it to (I might be able to scratch together shipping money even). 6.5 I would like to send you beer. OK. 6.6 Are you going to port this to Windows? No. If you'd like to work on a port help yourself; but I really really dislike Windows (in all its closed-source evilness). 6.7 Why no AOL logo? AOL's legal staff told us no-no. 6.8 Why the GPL? I like the GPL. 6.9 What is a wagii? Interesting question that you ask, there. 'Wagii' is the official celebratory cry of gaim. Anytime you are feeling happy or excited, just remember all of the hard work that we have done to provide you with this wonderful, free piece of software -- as the pure, raw, emotion flows through you, maybe you too will let out the cry of -- Wagii. It is also the sound a Penguin Samurai makes :) 6.10 What window manager/distribution/other crap do you use? Rob uses Red Hat, with Ximian GNOME on top. I dont really like Ximian but I like Gnome. On top of my Ximian Gnome is Sawfish. Eric hates saw fish. I kinda of like it even though it makes me mad. Eric uses debian woody. He uses Enlightenment as his window manager; though the only reason it would seem that Eric uses X at all is to support having his 20 Eterms and 4 Mozilla windows open. Oh yeah, and gaim_applet. 6.11 Is XX a good hard drive, YY a good monitor and ZZ a good CPU? You could send us one and we could tell you... :) 6.12 I want to contribute to the effort. Where can I send beer to? IM RobFlynn or email him at rob@marko.net.