doc/HACKING

   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
  16 However, up to late in the 1.2 series, the IRC core was still spread accross
  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.