Proposals for 3.0.0 API changes

[Will Thompson]

Sorry for the delay in replying: uni vacation work took over.
(Amusingly, now that lectures have started again I have more time.
Hmm.)

On Mon, Dec 31, 2007 at 03:24:34PM -0500, Sadrul Habib Chowdhury wrote:
> * Will Thompson had this to say on [31 Dec 2007, 17:09:08 +0000]:
> > So when the request_action UiOp is called, Haze has no way to figure out
> > what it's being asked without a massive lookup table looking something
> > like:
> > 
> >     if (strcmp (primary, _("Accept chat invitation?"))
> >     {
> >         // * create a new muc
> >         // * add self to local_pending
> >         // * hook up accepting to the first callback (which we happen to
> >         //   know from reading server.c is "accept").
> >         // * hook up declining to the second.
> >     }
> >     else if (strcmp (primary, _("SSL Certificate Verification")))
> >     {
> >         ...
> > 
> 
> What happens for an unhandled request?

To clarify, this isn't what Haze actually does. The massive,
doing-it-wrong chain of localized string comparisons was meant to
illustrate why the request API is a problem in Haze-land. "What does
Haze actually do?", I hear you ask. Well: nothing. The request UiOps are
not implemented (modulo a compile-time flag that enables implementations
that just dump the message text to the debug stream and then return).
But if Haze did do this, for unhandled requests it would have to either
drop it on the floor, or call the default callback. However, a quick
survey revealed that most requests pass NO_DEFAULT (although I think
Mark started fixing this the other day?), and in any case I'd eventually
like to support both accepting and rejecting chats. :-)

> > First, some Telepathy background!  Channels are pretty much the
> > fundamental objects in the API.  Multi-user chats are represented as
> > text channels implementing the Group interface.  When you are
> > invited to a chat, a channel is created for that chat and you are added
> > to the list of locally-pending members of that channel.  Moving yourself
> > from the pending list to the current member list serves to accept the
> > invitation, and removing yourself serves to decline it.
> [snip]
> Now, what happens if you reject the invitation? Does the conversation
> ('channel') get closed?

Yes.

> Would it be 'reasonable' to create the channel
> and add yourself to the 'current member list' on creation if the
> invitation is accepted (which I believe the callback would do anyway)?

I'm not sure what you're saying here. Are you saying only to create the
channel if the invitation is accepted? If so, that's not even possible
--- invitations are represented by channels with you on the
local-pending list.

> Or are there other benifits in doing it the way you describe (e.g., does
> the list of active members in the chat show up before you accept the
> invitation? etc).

Well, on protocols where that's possible, yes, the member list could be
populated before you accept, and the UI could choose to show it to the
user in some way.

But the real benefit to doing it the way I described is that that's what
the Telepathy specification says to do, so doing it this way means the
connection manager works. :-) I'm not suggesting this just as *a*
possible way to represent invitations --- creating a channel and adding
you to the local-pending list is how MUC invitations are represented in
the Telepathy API.

> [snip]
> > The point is that Haze doesn't know what
> > question is being asked.
> 
> I guess what I am trying to figure out is: why is it necessary to
> know what the question is, or specifically categorize every request?

Because different requests need to be presented in different ways in the
Telepathy API. There's no org.freedesktop.Telepathy.MakeADialogBox()
method.

> I think the callback functions take care of whatever actions are
> required to do something (e.g., the callback function for accepting a
> chat-invite would end up creating the conversation

[NB. The MUC channel doesn't have the same lifetime as the
PurpleConvChat --- it must be created before the callback is called, as
described above.]

> and fetching the
> list of users in the chat), in which case, the UI shouldn't, in
> theory, need to care what the question is.
> 
> I see the benifit of handling certain requests differently. For example,
> using 'request_authorization' (instead of 'request_action') for
> authorizing a buddy allows finch to include the user-info in the request
> dialog. I am sure there are other places where such special handling can
> be useful. But having a different signal for every different operation
> doesn't sound very appealing to me.

As far as I can tell, you just answered your own question about why the
Ui might need to know what the question is. I concede that Haze is a bit
of an extreme case, because it can't display a dialog box as a fallback.

(To recap, Haze is a daemon; the only way it can interact with the UI
(which might wind up being a traditional IM client like Empathy, or
could be some other random application which wants to use IM) is via
D-Bus, with the signals and methods defined by the Telepathy API. "Raise
a dialog box with these arbitrary strings as buttons" is not in the API,
partly because you don't know that the UI application(s) can do that,
and partly because the UI knowing what's going on is valuable.)

As for a signal for every current use of the request API: well, there
aren't actually all that many distinct uses of it right now, and many of
them already raise a signal beforehand (although most of these signals
require immediate responses rather than having async callbacks, so don't
actually solve the problem, but that's not the point here :-)).

Ideally, I would like the request API to go away. It's unimplementable
in Haze, and Colin Barrett mentioned (in a reply he forgot to CC to the
list) that it has been a problem for Adium. I understand that it's
convenient for Pidgin and Finch to map it to a dialog box rather than
handling each signal, but there's no reason there couldn't be a function
which sets up handlers for a bunch of signals and maps them to funptrs
in a RequestUiOps-style struct which basically implements dialog boxes,
or something. (Actually, given the relatively few uses of the API, I
think this benefit is probably more imagined than real, assuming that
the replacement signals keep their human-readable strings alongside the
machine-readable arguments.)

(Pretty much all of this applies to the notify API as well,
incidentally.)

Oh, and the problems with requests and notifications Gabriel's having on
Maemo would completely go away without any "let's guess the dialog's
parent!" code if Pidgin attached to a bunch of signals rather than
listening to the request API.
-- 
Will