Disconnection reasons that the UI can understand

[Will Thompson]

I've implemented pretty much what I proposed to the list a while back.
To summarise:

 * prpls now call purple_connection_error_reason, which is like
   purple_connection_error except with an extra 'reason' parameter,
   which is an element of the PurpleDisconnectReason enum (loosely based
   on the Telepathy Connection_Status_Reason enum).
 * ConnectionUiOps.report_disconnect is replaced by
   .report_disconnect_reason, again with an extra reason parameter.
   (report_disconnect is still called at the appropriate moment if it is
   implemented.)
 * UIs can use the purple_connection_reason_is_fatal() function to
   discover whether an error is fatal, or whether auto-reconnection
   should be attempted.  For instance,
   PURPLE_REASON_AUTHENTICATION_FAILED is fatal because the user needs
   to fix up their password.  This is meant to replace checking
   gc->wants_to_die to see whether to auto-reconnect.
 * wants_to_die is set by purple_connection_error_reason; prpls should
   not set it any more.
 * purple_connection_error is a stub calling
   purple_connection_error_reason with a fatal reason if
   gc->wants_to_die is true and a non-fatal reason otherwise, for
   backward-compatibility.

Right now there's a bit of namespace confusion:

 * the enum is called PurpleDisconnectReason;
 * the elements are PURPLE_REASON_* (although the #define for "one more than
 * the last reason" is PURPLE_NUM_REASONS;
   grim points out that it should be PURPLE_REASON_NUM_REASONS.
 * purple_connection_reason_is_fatal();

I'm thinking they should either all be prefixed with the appropriate
casing/underscoring of something like “purple disconnect[ion?] reason”,
or possibly “purple connection error”.  purple_reason is probably a bad
prefix: there might well be other things that reasons are needed for in
the future.  Any opinions on what the prefix should be?  I notice that
PURPLE_CONNECTION_ERROR_CERT_FINGERPRINT_MISMATCH is a really long word.

Also, I'm pretty sure my changes to the prpls are correct, but I haven't
tested them all, not being a Gadu-Gadu user...  Let me know if I've
messed anything up.

Finally, should PURPLE_NUM_REASONS exist at all?  If so, should it be
the last element of PurpleDisconnectReasons (but not actually a valid
reason) or a #define?  It exists mostly so that we can say

    g_return_if_fail (reason < PURPLE_NUM_REASONS)

which guards against people passing random integers as reasons by
casting them; if that's a sensible thing to do, then it seems sensible
for it not to be a valid value of reason, but then the #define has to be
updated if new elements are added to the enum.  (Actually, in any case
its value would change if new reasons were added, which breaks the
ABI...)  Without it, some functions would have a default: branch of a
switch which uses g_warning or similar to cry about the reason being
invalid before doing some default thing instead, and others would just
pass on busted reason parameters.  Maybe that's not so bad.

Any opinions?

Thanks,

Will
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://pidgin.im/pipermail/devel/attachments/20071013/1c840756/attachment.sig>