Disconnection reasons that the UI can understand

[Will Thompson]

Hi,

So over in Telepathy land, connections to a server can be in one of
three states — connecting, connected or disconnected — and transitions
between them are signalled along with a reason, taken from an
enumeration of possible reasons[0].  Implementing this in telepathy-haze
is fine for moving to connecting (Reason_Requested, i.e. "you asked for
it") and to connected (Reason_None_Specified), but reporting
disconnections is problematic.  libpurple lets the UI distinguish
between connection errors and normal disconnections by whether
report_disconnect has been called or not, but the UI has no way of
knowing the reason in any more detail (other than by examining a
localized, prpl-specific string).

[0] http://telepathy.freedesktop.org/spec.html#org.freedesktop.Telepathy.Connection.Connection_Status_Reason

From my point of view, combining PurpleConnectionUiOps.disconnected and
PurpleConnectionUiOps.report_disconnect into a single function with a
reason seems reasonable.  Create a PurpleDisconnectReason enum, similar
to the Telepathy one (although an Unknown reason would be handy, and I
need to take a look at the new certificate stuff for reporting SSL
errors).  Then this hypothetical UiOp, called something like
report_disconnect_reason until 3.0, would have three arguments: the
PurpleConnection, the PurpleDisconnectReason, and the localized string
that report_disconnect currently gets, giving more details.

purple_connection_error would (until 3.0) become a stub calling a new
function, purple_connection_error_reason, with UnknownError.
purple_connection_error_reason calls the new UiOp if present, and
otherwise calls the old one.  _set_state also checks whether the new
UiOp is present: if so, if disconnect_timeout is unset (meaning the
disconnection was not an error) it calls the new op with reason
Requested; otherwise, it calls the old disconnected op.

Come 3.0 all the cruft gets blown away, connection_error goes away,
_set_state gains a reason parameter.

(All these names are just names that came to mind.)

I don't think that this is too haze-specific; Pidgin and Finch (and
presumably Adium) could benefit from knowing more about disconnections.
On username/passwords errors, for example, the error dialog could prompt
for them, or give you the account dialog with a nice red message saying
"one of these is allegedly wrong", or something.

Am I missing anything?  Am I over- or under-engineering?  Any
suggestions for better names for functions?  Can anyone see a way I can
implement the Telepathy disconnection reasons without some change like
this?  (I figured I'd ask before I dive in and implement this.)

This was longer than I hoped.  Oh well.

Will
-- 
River:  My food is problematic.
-------------- 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/20070912/ffed0737/attachment.sig>