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