[Bug 29531] high-level API for text channels

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=29531

--- Comment #3 from Guillaume Desmottes <guillaume.desmottes at collabora.co.uk> 2010-09-14 05:36:39 PDT ---
Let's start the API brainstorming. I'll focus on the Text and Messages features
for now.

For the record the tp-qt4 equivalent of this API is
http://telepathy.freedesktop.org/doc/telepathy-qt4/classTp_1_1TextChannel.html

How should we call this object? TpTextChannel?

I guess we are going to re-use TpMessage.

Would it be ok to make Message mandatory in order to use it? I'd say yes as we
want to make it mandatory anyway (bug #29376).

The constructor would follow the usual channel pattern:

TpTextChannel *tp_text_channel_new (TpConnection *conn,
    const gchar *object_path,
    const GHashTable *immutable_properties,
    GError **error);


Properties and accessors
------------------------

const gchar * const * tp_text_channel_get_supported_content_types (
    TpTextChannel *self);

TpMessagePartSupportFlags tp_text_channel_get_message_part_support_flags (
    TpTextChannel *self);

TpDeliveryReportingSupportFlags tp_text_channel_get_delivery_reporting_support
(
    TpTextChannel *self);

/* Return a list of TpMessage */
GList * tp_text_channel_get_pending_messages (TpTextChannel *self);

Methods
-------

const gchar * tp_text_channel_send_message (TpTextChannel *self,
    TpMessage *message,
    TpMessageSendingFlags flags);

Or should we have an _async function completing when the message has actually
be sent (or sending failed)? Then we could have something like:

const gchar * tp_text_channel_send_message_async (TpTextChannel *self,
    TpMessage *message,
    TpMessageSendingFlags flags,
    GAsyncReadyCallback callback,
    gpointer user_data);

gboolean tp_text_channel_send_message_finish (TpTextChannel *self,
    TpMessageSendingFlags *flags,
    GAsyncResult *result,
    GError **error);

void tp_text_channel_ack_messages_async (TpTextChannel *self,
    GList *messages, /* list of TpMessage */
    GAsyncReadyCallback callback,
    gpointer user_data);

gboolean tp_text_channel_ack_messages_finish (TpTextChannel *self,
    GAsyncResult *result,
    GError **error);

+ probably a _ack_message_{async.finish} as an helper for the single message
case

void tp_text_channel_forget (TpTextChannel *self,
    GList *messages, /* list of TpMessage */);

and maybe a forget_all() ?

Signals
-------

"message-received" (TpMessage *message)

"message-sent" (TpMessage *message, TpMessageSendingFlags flags, const gchar
*token)

"pending-messages-removed" (GList *list of TpMessage)

Do we want to bind the "LostMessage" signal? We can't do much with it.

Features
--------

TP_TEXT_CHANNEL_FEATURE_PENDING : used to retrive pending messages

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.