annotate PRPL @ 1106:5bc8fdacd2cb

[gaim-migrate @ 1116] lots of changes. buddy.c: just in general tried to get things to work better. moving things in the edit list window and signing off should be handled better in the main buddy list window (watch out for flashes). gaim.h: removed toc-specific things and moved them to toc.c and rvous.c as needed. gtkhtml.c: possible fix for AOL 6.0 problems (I wasn't able to reproduce the problem before or after the fix, but i fixed what i think might have been causing the problem). multi.c: moved LOGIN_STEPS from gaim.h here and actually use it now oscar.c: moved an oscar-specific struct definition from gaim.h here and also handle problems better perl.c: fix for stupid problem rvous.c: first pass at attempt to be able to remove toc.c and rvous.c (though this will never happen; gaim will support toc as long as aol does) without cruft. gaim is now only dependent on toc.c and rvous.c for toc_build_config and parse_toc_buddy_list, which gaim needs to save and read its buddy list. toc.c: rewrote the signin process so that the read()'s won't block. it's not actually a non-blocking read; it's just that it won't ever get to the read until there's data to be read (thanks to the gdk_input watcher). this means the cancel button should work after it's connected, but it's still not a non-blocking connect. 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 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.