[Telepathy] tp-qt4 high level channel API sketch

[Andre Moreira Magalhaes]

Hi,

Simon McVittie wrote:
> I think Channel could benefit from having accessors for targetID(),
> isRequested() and initiator() (a nullable Contact object) too.
>
> Requested is a little tricky because it has to be a tri-state - on old
> connection managers, we can't know whether the channel was requested or
> not!
>
>   
Hmm, I will add the extra methods, there will probably be more methods 
there that we are missing here.
The idea of this sketch was just to see if the idea of splitting 
channels in specialized classes was acceptable, which I think it is.
 
> On Fri, 30 Jan 2009 at 11:37:47 -0300, Andre Moreira Magalhaes wrote:
>   
>> class GroupChannel : Channel:
>>     
>
> Many channels are (at least potentially) a Group so I think this is
> unnecessary - just fold it into the Channel class and have it not always
> be relevant.
>
>   
Yes, actually the first version I wrote here, was like this with the 
group functionality inside the Channel class itself, but then I changed 
it to be a separate class to make it more user-friendly IMHO, but I can 
revert that if you prefer.

> I think we agreed earlier that channels whose TargetHandleType is Contact
> should fake being a Group with two members ("us" and "them"), even if at
> the D-Bus level they're not.
>
>   
Yes, that will be done, I just didn't wrote it. The group will always 
have at least 2 members.

> The Group API should be based on Contact objects, not handles (at least
> as a Feature, but probably as a core thing).
>
>   

>> signals:
>>   void membersChanged(Contact[] current, Contact[] local, Contact[] remote);
>>     
>
> This should resemble the new MembersChangedDetailed instead, and fake the
> detailed signal from MembersChanged if necessary. (General principle:
> make the C/C++ API look like the modern version of the D-Bus API rather
> than the old version, wherever possible.)
>
> It is very necessary to expose information about the change, like the actor
> (who it was that made the change), reason, etc. - these are important
> for chatrooms and StreamedMedia calls.
>
>   
Hmm I missed the  MembersChangedDetailed in the spec, but yeah, I will 
change this to use it.

>> class TextChannel : GroupChannel
>> {
>> public:
>>   UintList allowedMessageTypes();
>>
>>   PendingOperation *acknowledgePendingMessages(UintList messagesIds)
>>   PendingMessages *pendingMessages();
>>   PendingMessageToken *sendMessage(uint type, string message)
>>     
>
> No, please leave TextChannel as a stub (no extra functionality over
> Channel) for now, and design the Message sending and receiving as a separate
> task, later. It's going to be a significant amount of work to construct a
> good API (as opposed to a simple binding of the Text interface - anyone
> who wanted that could just use the generated code).
>
> When you do, the C++ API should be based on the combination of the Text and
> Messages D-Bus interfaces, with a queue of Message objects that represent the
> messages. (General principle, as above: Text can be viewed as a trivial
> case of Text+Messages.)
>
>   
I agree that we should  merge the Messages and  Text interface here, I 
just didn't wrote it as I wanted it to be done first this way, so we 
have something to show, and then extend/change it later to support the 
Messages Interface
>> class ContactListChannel : GroupChannel
>> {
>> }
>>     
>
> I don't think exposing the Contact List channels to library users is useful.
> Adding "roster" functionality to Contact objects is already in the outline in
> my "sketches" branch - that seems a much better API for the same thing.
>
>   
I really prefer having a ContactList channel that in reality is just a 
Group Channel, or if we change a Channel itself. It's easier for users 
IMHO to understand, They will add/remove contacts using addContact, 
removeContact, get all contacts using local/pendin/...Members

But that's your call.

The thing is, it seems the basic idea is approved, the idea to split it 
in several specialized channels and then return them to the users.
I will start working on this, I just would like to set first if we are 
going to join Channel and GroupChannel, I am really not sure which one 
is more friendly.

BR
Andrunko