1BitlBee post-1.x "architecture" 2 3DISCLAIMER: The messy architecture is being cleaned up. Although lots of 4progress was made already, this is still a work in progress, and possibly 5parts of this document aren't entirely accurate anymore by the time you 6read this. 7 8It's been a while since BitlBee started, as a semi-fork of Gaim (version 90.58 at the time). Some people believe nothing changed, but fortunately, 10many things have. 11 12The API is gone for a while already - which wasn't incredibly intrusive, 13just a few functions renamed for slightly better consistency, added some 14calls and arguments where that seemed useful, etc. 15 16However, up to late in the 1.2 series, the IRC core was still spread across 17several files, mostly irc.c + irc_commands.c and pieces and bits in 18nogaim.c. If you're looking for a textbook example of layer violation, start 19there. 20 21This was all finally redone. Most of the IRC protocol code was rewritten, 22as was most of the glue between that and the IM modules. 23 24The core of BitlBee is now protocols/bee*. Some pieces are still left in 25protocols/nogaim*. Most stuff in the "root" directory belongs to the IRC 26UI, which should be considered "a" frontend (although currently, and 27possibly forever, the only one). Every subdirectory of protocols/ is another 28IM protocol backend (including purple/ which uses libpurple to define 29many different protocols). 30 31 32/ 33 34The IRC core has code to show an IRC interface to a user, with contacts, 35channels, etc. To make channels and contacts do something, you add event 36handlers (that translate a message sent to a nick into an instant message 37to an IM contact, or translates joining a channel into joining an IM 38chatroom). 39 40To get events back from the BitlBee core, the bee_t object has a bunch of 41functions (struct bee_ui_funcs) that catch them and convert them back to 42IRC. 43 44Short description of what all irc*.c files (and some related ones) do: 45 46bitlbee.c: BitlBee bootstrap code, doing bits of I/O as well. 47ipc.c: For inter-process communication - communication between BitlBee 48 sessions. Also used in daemon mode (in which it's not so much inter- 49 process). 50irc.c: The main core, with bits of I/O handling, parsing, etc. 51irc_channel.c: Most things related to standard channels (also defines some 52 of the control channel behaviour). 53irc_commands.c: Defines all IRC commands (JOIN, NICK, PRIVMSG, etc.). 54irc_im.c: Most of the glue between IRC and the IM core live here. This is 55 where instant messages are converted to IRC and vice versa, contacts 56 coming online is translated to one or more joins and/or mode changes. 57irc_send.c: Simple functions that send pieces of IRC output. Somewhat 58 random, but if an IRC response is slightly more complicated than just a 59 simple line, make it a function here. 60irc_user.c: Defines all IRC user details. Mostly defines the user "object". 61irc_util.c: Misc. stuff. Not much ATM. 62nick.c: Handling of nicknames: compare, ucase/lcase, generating and storing 63 nicks for IM contacts. 64set.c: Settings management, used for user-changeable global/account/channel 65 settings. Should really be considered part of the core. 66storage*.c: Storing user accounts. (The stuff you normally find in 67 /var/lib/bitlbee) 68 69 70/protocols 71 72The IM core lives in protocols/. Whenever you write code there, try to avoid 73using any IRCisms there. 74 75Most header files in there have some of their details explained in comments. 76bee*.c and nogaim.c are the layer between the IM modules and the IRC 77frontend. They keep track of IM accounts, contacts and their status, 78groupchats, etc. 79 80You can control them by calling functions in there if available, and 81otherwise by just calling the functions exported via the prpl struct. Most 82of these functions are briefly explained in the header files, otherwise the 83best documentation is sadly in irc_im.c and root_commands.c. 84 85Events from the IM module go back to the core + frontend via imcb_* 86functions defined in bee*.c and nogaim.c. They're all described in the 87header files. 88 89 90/lib 91 92BitlBee uses GLib, which is a pretty nifty library adding a bunch of things 93that make life of a C coder better. Please try to not use features from 94recent GLib versions as whenever this happens, some people get cranky. :> 95 96There's also a whole bunch of nice stuff in lib/ that you can use: 97 98arc.c: ARC4 encryption, mostly used for encrypting IM passwords in the XML 99 storage module. 100base64.c 101events_*.c: Event handling, using either GLib (default) or libevent (may 102 make non-forking daemon mode with many users a little bit more efficient). 103ftutil.c: Some small utility functions currently just used for file transfers. 104http_client.c: A simple (but asynchronous) HTTP(S) client, used by the MSN, 105 Yahoo! and Twitter module by now. 106ini.c: Simple INI file parser, used to parse bitlbee.conf. 107md5.c 108misc.c: What the name says, really. 109oauth.c: What the name says. If you don't know what OAuth is, ask Google. 110 Currently only used by the Twitter module. Implements just version 1a ATM. 111proxy.c: Used together with events_*.c for asynchronous I/O directly or via 112 proxies. 113sha1.c 114ssl_*.c: SSL client stuff, using GnuTLS (preferred) or OpenSSL. Other modules 115 aren't working well ATM. 116url.c: URL parser. 117xmltree.c: Uses the GLib stream parser to build XML parse trees from a stream 118 and convert the same structs back into XML. Good enough to do Jabber but 119 not very aware of stuff like XML namespaces. Used for Jabber and Twitter. 120 121This, together with the headerfile comments, is most of the documentation we 122have right now. If you're trying to make some changes to BitlBee, do feel 123free to join #bitlbee on irc.oftc.net to ask any question you have. 124Suggestions for specific parts to document a little bit more are also 125welcome. 126