comparison PRPL @ 1086:ce201056e7a6

[gaim-migrate @ 1096] adam is obviously very bored; he hacked gaim. other good prpl-related stuff. committer: Tailor Script <[e-mail]>

1085:8da0bf36fb99

Protocol Plugins. What EveryBuddy should have been.

Protocol Plugins are easier than GUI plugins. This is because there is necessarily a limited set
of server functions; protocols are limited. What a programmer can do with a UI is limitless.

In order to design a framework for which Protocol Plugins can work, we must first think about
which protocols can be pluginized. (Henceforth PRPL will stand for both the Protocol Plugin
system and an individual Protocol Plugin.)

Oscar. TOC. Yahoo. MSN. ICQ. FTP. IRC.

There is a longer list. Note that FTP is in the list presented. FTP has basic functions similar
to those of the others. The basic functions that must be performed are:

Sign on. (log in)
Sign off.
Send and receive messages.

There really isn't much more to it than that. There are, then, additional functions that some
protocols implement:

Chat.
File Transfer.
Away/Idle. (states)
Directory Info.

Before PRPL there was a slight abstraction in the code. The UI simply needed to call serv_login,
and that function would decide between the protocols, which function to call. It did that with
an if-elseif-else series.

With PRPL, each PRPL is stored in a struct. The structs are then kept in a GSList. The serv_
functions then simply need to search the GSList for the correct protocol, and call the desired
function. The struct holds void * references to the desired functions. serv_* simply needs to
call that function. (Even better, each connection has a reference to the PRPL struct it uses;
this will reduce search time.)

A new PRPL can be loaded at any time. They can be either static or dynamic code. When a new
protocol is loaded, gaim will call its protocol_init function, which is expected to return a
pointer to the aforementioned struct. If it returns NULL, the PRPL will not be loaded. (This is
not entirely true and needs to be modified in the code to work similarly to how it's decscribed
here.)

Each PRPL needs to have a unique identifier. In the pre-PRPL system TOC was 0 and Oscar was 1.
This identifier can be found in prpl.h. They are pre-assigned. PROTO_TOC is still 0, PROTO_OSCAR
is still 1. The protocol_init function is expected to set the struct's protocol member to the
appropriate value. If you want to write a new PRPL for gaim, please email one of the maintainers
with the name of the protocol. We'll then reserve a number for it. Please do not use a number
that has not been assigned to your protocol, not even for testing purposes.

The addition of PRPL to gaim means that gaim now supports multiple connections and multiple (and
dynamically loadable) protocols.

======

In order to test that PRPL was working with as little work as possible I made Oscar a plugin. In
order to use Oscar as a plugin, first recompile gaim with the make variable DEBUG_CFLAGS set to
-DDYNAMIC_OSCAR, e.g.

/usr/src/gaim $ make DEBUG_CFLAGS=-DDYNAMIC_OSCAR

This will then remove Oscar support from the code (though it will still link with libfaim. However,
gaim does not need to link to libfaim itself). Making the Oscar plugin is straight-forward; simply
make oscar.so in the plugins directory, e.g.

/usr/src/gaim/plugins $ make oscar.so

You will then be presented with a gaim binary in src/gaim and the Oscar plugin in plugins/oscar.so.
Simply load the oscar.so file from the normal plugin window. This will set up everything necessary.
You may unload the plugin at any time, but the protocol will still be loaded. This may or may not
be a problem and may or may not be fixed at a later point in time.

======

I guess I should document how to write a PRPL.

file, and have it call

	load_protocol(my_proto_init);

and return a non-negative int. Then compile as a plugin, load the .so file, and you're set. If you're
going to load it dynamically, extern the my_proto_init function, and in prpl.c, call load_protocol.

Your PRPL needs to have a login function, which ideally should set up a gdk_input watcher. When you
want to indicate that the account is online, simply call account_online(struct gaim_connection *).
When there is information from the server, you should call the appropriate serv_got function (see
gaim.h for a (partial?) list).

When the UI wants to send something via the server, it will call the appropriate function that you set
in your PRPL, if it's non-NULL.

There's currently no way to unload a PRPL, even if compiled dynamically and the plugin is removed. If
you do remove a dynamic PRPL and try to load a new version of it, you will still be using the old
version. Hopefully I can figure out how to fix this. Maybe it's not that important.

1086:ce201056e7a6

Protocol Plugins. What EveryBuddy should have been.

Each PRPL needs to have a unique identifier. In the pre-PRPL system TOC was 0 and Oscar was 1.
This identifier can be found in prpl.h. They are pre-assigned. PROTO_TOC is still 0, PROTO_OSCAR
is still 1. The protocol_init function is expected to set the struct's protocol member to the
appropriate value. If you want to write a new PRPL for gaim, please email one of the maintainers
with the name of the protocol. We'll then reserve a number for it. Please do not use a number
that has not been assigned to your protocol, not even for testing purposes.

The addition of PRPL to gaim means that gaim now supports multiple connections and multiple (and
dynamically loadable) protocols.

======

I guess I should document how to write a PRPL.

file, and have it call

	load_protocol(my_proto_init);

and return a non-negative int. Then compile as a plugin, load the .so file, and you're set. If you're
going to load it statically, extern the my_proto_init function, and in prpl.c, call load_protocol.

Your PRPL needs to have a login function, which ideally should set up a gdk_input watcher. When you
want to indicate that the account is online, simply call account_online(struct gaim_connection *).
When there is information from the server, you should call the appropriate serv_got function (see
gaim.h for a (partial?) list).

When the UI wants to send something via the server, it will call the appropriate function that you set
in your PRPL, if it's non-NULL. The only function that is absolutely critical is name. Without name
gaim will probably crash. You don't even need login, just name. (You need login to do anything useful
though.)

The best example to copy is probably Rob's IRC plugin, in plugins/irc.c. The most important functions
for gaim interaction are at the bottom (irc_init, gaim_plugin_init, and gaim_plugin_remove). The
rest of it is the protocol implementation.

Sorry for the formatting. My Eterm is 105 characters wide.