What is libpurple?

libpurple is intended to be the core of an IM program. When using libpurple, you'll basically be writing a UI for this core chunk of code. Pidgin is a GTK+ frontend to libpurple, Gaim-text is an ncurses frontend, and Adium is a Cocoa frontend.

Your program provides the int main() function. Your main function will call libpurple_core_init(), which initializes libpurple. Your main function will also register a whole bunch of "callback" functions that are called by libpurple any time there is something to tell the user. For example, when libpurple receives an IM it'll call your function for handling an incoming IM. When one of your buddies signs online libpurple will call your function to update the buddylist.

If your user fetches someones info then you'll call a libpurple function that sends the appropriate message across the network. Then libpurple will get a response and call your function for handling buddy info.

TODO: Combine the following text with the above

Applications that use libgaim provide the appropriate functions to perform the UI operations invoked by the core (libgaim). This is done by populating the uiops structures (eg. GaimAccountUiOps?, GaimBlistUiOps? etc.) and making them available to the core (by calling gaim_accounts_set_ui_ops, gaim_blist_set_ui_ops etc.). The functions in the uiops are triggered at specific events, eg. the buddylist-uiops are used to update the buddy list when a new buddy is added, or removed, or the status of a buddy is changed etc. The same happens for conversations, logging etc.

While the uiops are sufficient for most of the ui operations, it's likely that you will want to use the gaim-signals as well to fine-tune some stuff.

libgaim uses the glib mainloop to do all the things. The application wanting to use libgaim will [likely] have to do the same.

The application will first initialize the core (gaim_core_init), add plugin-search paths, load the saved plugins, prefs etc. If you have the source, I suggest you take a look at console/gntgaim.c:init_libgaim to get an idea of what's required to setup libgaim for your application.