annotate PRPL @ 2695:d4be9f5b8d58

[gaim-migrate @ 2708] remove the #undef's for things that aren't #define'd as well committer: Tailor Script <[e-mail]>

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.

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.

The first thing to do is to write your init function. It should be
delcared

void my_proto_init(struct prpl *p);

You then fill in the members of the struct. See prpl.h for what they are.

If you're going to load your protocol dynamically, put the function
gaim_plugin_init(void *) in the file, and have it call

	load_protocol(my_proto_init);

and return NULL. 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.)

======

Erg. Now the fun part. The part that you would have never guessed if you
weren't me. (I know that you wouldn't have guessed this stuff because
it isn't painfully obvious to me. Use the Source, Luke.)

Let's start with the basics. PRPLs shouldn't use GTK at all. If you use
GTK I will hunt you down like the dog you are and kill you.

You're probably wondering how you can do certain things without GTK. Well,
you're just going to have to make do. Rely on the UI, that's why it's
there.	A PRPL should have absolutely ZERO interaction with the user,
it should all be handled by the UI.

So let's talk about what that means in a practical way. Have a socket that
you want notification on? Use gaim_input functions; they work just like
the gdk_input functions. Want to add a timeout? g_timeout_add and
g_source_remove. Want to ask a question? do_ask_dialog. Etc.

Don't use the _options variables at all. The core should take care of all
of that.

Um. I'm sure there's more.