soc.2009.telepathy: 50a52709: Documented telepathy_channel_text.*
sttwister at gmail.com
sttwister at gmail.com
Mon Feb 1 21:15:52 EST 2010
-----------------------------------------------------------------
Revision: 50a52709f1fa1d3dddb33f49c5576065d5b71aa3
Ancestor: 5f74503b62e2e86878d805b68fbe0afed372f381
Author: sttwister at gmail.com
Date: 2010-02-02T02:08:08
Branch: im.pidgin.soc.2009.telepathy
URL: http://d.pidgin.im/viewmtn/revision/info/50a52709f1fa1d3dddb33f49c5576065d5b71aa3
Modified files:
libpurple/protocols/telepathy/telepathy_channel_text.c
libpurple/protocols/telepathy/telepathy_channel_text.h
ChangeLog:
Documented telepathy_channel_text.*
-------------- next part --------------
============================================================
--- libpurple/protocols/telepathy/telepathy_channel_text.c a559b63a2d2344d38cdcf3d4c7b9c67c840744e9
+++ libpurple/protocols/telepathy/telepathy_channel_text.c 1e4d7d549bcb9f68b403c6d2a4ef085bdfcbe207
@@ -63,8 +63,8 @@ write_message_to_chatroom (int id,
write_message_to_chatroom (int id,
const gchar *from,
guint timestamp,
- const gchar *msg,
- gpointer user_data)
+ const gchar *msg,
+ gpointer user_data)
{
PrplTpConnection *data = user_data;
@@ -86,6 +86,17 @@ write_message_to_chatroom (int id,
g_free(final_message);
}
+/**
+ * Called when a message has been received in a chatroom.
+ *
+ * @param tp_channel The channel in which the message was received.
+ * @param arg_ID The ID of the message.
+ * @param arg_Timestamp The time the message was received.
+ * @param arg_Sender The handle of the sender contact.
+ * @param arg_Type The message type.
+ * @param arg_Flags A bitwise OR of message flags.
+ * @param arg_Text The message contents.
+ */
static void
chat_got_message (PrplTpRoomChannel *tp_channel,
guint arg_ID,
@@ -134,6 +145,16 @@ chat_got_message (PrplTpRoomChannel *tp_
}
+/**
+ * Callback for querying contacts for scrollback messages.
+ *
+ * @param connection Connection-specific data.
+ * @param n_contacts The number of contacts successfuly fetched.
+ * @param contacts An array of contact proxy objects.
+ * @param n_failed The number of contacts that were not fetched.
+ * @param failed An array of contact handles that were not fetched.
+ * @param error Points to a GError in case of failure, NULL otherwise.
+ */
static void
get_contacts_for_scrollback_cb (TpConnection *connection,
guint n_contacts,
@@ -208,6 +229,14 @@ get_contacts_for_scrollback_cb (TpConnec
g_free(tp_messages);
}
+/**
+ * Called when scrollback messages have been received in a text channel.
+ *
+ * Checks to see if there's any contact that is not cached.
+ *
+ * @param data Connection-specific data.
+ * @param tp_messages An array of scrollback messages.
+ */
static void
chat_got_scrollback_messages (PrplTpConnection *data,
PrplTpScrollbackMessages *tp_messages)
@@ -240,6 +269,11 @@ chat_got_scrollback_messages (PrplTpConn
}
}
+/**
+ * Callback for ListPendingMessages DBus method for chatrooms.
+ *
+ * @see list_pending_messages_cb
+ */
static void
chat_list_pending_messages_cb (TpChannel *proxy,
const GPtrArray *out_Pending_Messages,
@@ -335,6 +369,11 @@ chat_list_pending_messages_cb (TpChanne
}
}
+/**
+ * Callback for the Received DBus signal for chatrooms.
+ *
+ * @see received_cb
+ */
static void
chat_received_cb (TpChannel *proxy,
guint arg_ID,
@@ -385,6 +424,11 @@ chat_received_cb (TpChannel *proxy,
}
}
+/**
+ * Callback for the SendError DBus signal for chatrooms.
+ *
+ * @see send_error_cb
+ */
static void
chat_send_error_cb (TpChannel *proxy,
guint arg_Error,
@@ -494,6 +538,17 @@ chat_send_cb (TpChannel *proxy,
}
}
+/**
+ * Callback for querying the contacts of a chatroom.
+ *
+ * @param connection The Telepathy connection proxy.
+ * @param n_contacts The number of contacts successfully fetched.
+ * @param contacts An array of contacts succesfully fetched.
+ * @param n_failed The number of contacts that were not fetched.
+ * @param failed An array of contact handles that were not fetched.
+ * @param error Points to a GError in case of failure, NULL otherwise.
+ * @param user_data Points to a #PrplTpRoomChannel.
+ */
static void
chat_get_contacts_cb (TpConnection *connection,
guint n_contacts,
@@ -552,6 +607,19 @@ chat_get_contacts_cb (TpConnection *conn
}
+/**
+ * Callback for getting all member handles for a channel.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param out_Members An array of contact handles.
+ * @param out_Local_Pending An array of contact handles pending local
+ * approval..
+ * @param out_Remote_Pending An array of contact handles pending remote
+ * approval.
+ * @param error Points to a GError in case of failure, NULL
+ * otherwise.
+ * @param user_data Points to a #PrplTpRoomChannel.
+ */
static void
chat_get_all_members_cb (TpChannel *proxy,
const GArray *out_Members,
@@ -656,6 +724,11 @@ room_channel_invalidated_cb (TpProxy *se
g_hash_table_remove(connection_data->room_Channels, (gpointer)handle);
}
+/**
+ * Callback for querying details of contacts that joined a chatroom.
+ *
+ * @see chat_get_contacts_cb
+ */
static void
chat_members_joined (TpConnection *connection,
guint n_contacts,
@@ -714,7 +787,20 @@ chat_members_joined (TpConnection *conne
}
}
-
+/**
+ * Callback for the MembersChanged DBus signal for chatrooms.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param arg_Message An optional message regarding the change.
+ * @param arg_Added A list of contact handles added to the room.
+ * @param arg_Removed A list of contact handles removed from the room.
+ * @param arg_Local_Pending A list of contact handles pending local approval.
+ * @param arg_Remote_Pending A list of contact handles pending remote approval.
+ * @param arg_Actor The contact handle of the member who requested the
+ * change.
+ * @param arg_Reason A reason for the change.
+ * @param user_data Points to a #PrplTpRoomChannel.
+ */
static void
chat_members_changed_cb (TpChannel *proxy,
const gchar *arg_Message,
@@ -791,6 +877,12 @@ chat_members_changed_cb (TpChannel *prox
}
}
+/**
+ * Called when a chatroom property has been updated.
+ *
+ * @param tp_channel The channel whose property was updated.
+ * @param tp_property The property that was updated.
+ */
static void
room_property_updated (PrplTpRoomChannel *tp_channel,
PrplTpProperty *tp_property)
@@ -884,6 +976,14 @@ room_property_updated (PrplTpRoomChannel
}
}
+/**
+ * Callback for requesting a channel's Telepathy properties.
+ *
+ * @param proxy A Telepathy channel proxy.
+ * @param out_Values An array of Telepathy properties.
+ * @param error Points to a GError in case of failure, NULL otherwise.
+ * @param user_data Points to a #PrplTpRoomChanel.
+ */
static void
get_properties_cb (TpProxy *proxy,
const GPtrArray *out_Values,
@@ -927,6 +1027,14 @@ get_properties_cb (TpProxy *proxy,
}
}
+/**
+ * Callback for the ListProperties DBus method.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param out_Available_Properties An array of availble properties.
+ * @param error Points to a GError in case of failure, NULL otherwise.
+ * @param user_data Points to a #PrplTpRoomChannel.
+ */
static void
list_properties_cb (TpProxy *proxy,
const GPtrArray *out_Available_Properties,
@@ -996,6 +1104,13 @@ list_properties_cb (TpProxy *proxy,
g_array_free(properties, TRUE);
}
+/**
+ * Callback for the PropertyFlagsChanged DBus signal.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param arg_Properties An array of properties whose flags were changed.
+ * @param user_data Points to a #PrplTpRoomChannel.
+ */
static void
property_flags_changed_cb (TpProxy *proxy,
const GPtrArray *arg_Properties,
@@ -1027,6 +1142,13 @@ property_flags_changed_cb (TpProxy *prox
}
}
+/**
+ * Callback for the PropertiesChanged DBus signal.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param arg_Properties An array of properties that were changed.
+ * @param user_data Points to a #PrplTpRoomChannel.
+ */
static void
properties_changed_cb (TpProxy *proxy,
const GPtrArray *arg_Properties,
@@ -1244,8 +1366,8 @@ write_message_to_conversation (const gch
void
write_message_to_conversation (const gchar *from,
guint timestamp,
- const gchar *msg,
- gpointer user_data)
+ const gchar *msg,
+ gpointer user_data)
{
PrplTpConnection *data = user_data;
@@ -1579,6 +1701,12 @@ chat_state_changed_cb (TpChannel *proxy,
}
}
+/**
+ * Handles the creation of a new Telepathy one-to-one text channel.
+ *
+ * @param channel The Telepathy proxy object representing the channel.
+ * @param data Data about the connection which created the channel.
+ */
static void
handle_im_text_channel (TpChannel *channel,
PrplTpConnection *data)
============================================================
--- libpurple/protocols/telepathy/telepathy_channel_text.h a0221a2a2a704309afc4ac529780c678bfb8fd5e
+++ libpurple/protocols/telepathy/telepathy_channel_text.h 625874a087e86bebfd8770e37501f877bc4de2ec
@@ -44,6 +44,11 @@ typedef struct
} PrplTpProperty;
+/**
+ * Free the memory of a #PrplTpProperty.
+ *
+ * @param tp_property The struct to clean up.
+ */
void
destroy_property(PrplTpProperty *tp_property);
@@ -62,6 +67,11 @@ typedef struct
GHashTable *properties_by_name; /**< Maps property names to PrplTpProperty structs. */
} PrplTpRoomChannel;
+/**
+ * Free the memory of a #PrplTpRoomChannel.
+ *
+ * @param tp_channel The struct to clean up.
+ */
void
destroy_room_channel(PrplTpRoomChannel *tp_channel);
@@ -130,32 +140,78 @@ typedef struct
gboolean received_Pending_Messages;
} PrplTpTextChannel;
+/**
+ * Free the memory of a #PrplTpTextChannel.
+ *
+ * @param tp_channel The struct to clean up.
+ */
void
destroy_text_channel(PrplTpTextChannel *tp_channel);
+/**
+ * Handles the creation of a new Telepathy room text channel.
+ *
+ * @param channel The Telepathy proxy object representing the channel.
+ * @param data Data about the connection which created the channel.
+ * @param invitation TRUE if the channel was created as a result of an
+ * invitation.
+ */
void
handle_room_text_channel (TpChannel *channel,
PrplTpConnection *data,
gboolean invitation);
+/**
+ * Callback for the Send DBus method when called on a room text chanel.
+ *
+ * @param proxy The Telepathy channel proxy used to send the message.
+ * @param error Points to a GError in case of failure, NULL otherwise.
+ * @param user_data Points to a #PrplTpConnection holding connection data.
+ */
void
chat_send_cb (TpChannel *proxy,
const GError *error,
gpointer user_data,
GObject *weak_object);
+/**
+ * Forward a received message to the conversation window.
+ *
+ * @param from The handle of the message sender.
+ * @param timestamp A timestamp represnting when the message was received.
+ * @param msg The message contents.
+ * @param user_data Points to a #PrplTpConnection holding connection data.
+ */
void
write_message_to_conversation (const gchar *from,
guint timestamp,
- const gchar *msg,
- gpointer user_data);
+ const gchar *msg,
+ gpointer user_data);
+/**
+ * Callback for the AcknowledgePendingMessages Dbus method.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param error Points to a GError in case of failure, NULL otherwise.
+ * @param user_data Points to a #PrplTpConnection holding connection data.
+ */
void
acknowledge_pending_messages_cb (TpChannel *proxy,
const GError *error,
- gpointer user_data,
- GObject *weak_object);
+ gpointer user_data,
+ GObject *weak_object);
+/**
+ * Callback for the ListPendingMessage DBus method.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param out_Pending_Messages An array of messages having DBus signature
+ * a(uuuuus). Represented as a GPtrArray of
+ * GValueArray's.
+ * @param error Points to a GError in case of failure, NULL
+ * otherwise.
+ * @param user_data Points to a #PrplTpConnection.
+ */
void
list_pending_messages_cb (TpChannel *proxy,
const GPtrArray *out_Pending_Messages,
@@ -163,6 +219,18 @@ list_pending_messages_cb (TpChannel *pr
gpointer user_data,
GObject *weak_object);
+/**
+ * Callback for the Received DBus signal.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param arg_ID The message ID.
+ * @param arg_Timestamp The time the message was received.
+ * @param arg_Sender The handle of the message sender.
+ * @param arg_Type The type of the message.
+ * @param arg_Flags A bitwise OR of flags.
+ * @param arg_Text The message contents.
+ * @param user_data Points to a #PrplTpConnection.
+ */
void
received_cb (TpChannel *proxy,
guint arg_ID,
@@ -174,6 +242,16 @@ received_cb (TpChannel *proxy,
gpointer user_data,
GObject *weak_object);
+/**
+ * Callback for the SendError DBus signal.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param arg_Error The id of the error that occured.
+ * @param arg_Timestamp The time the message was sent.
+ * @param arg_Type The message type.
+ * @param arg_Text The message contents.
+ * @param user_data Points to a #PrplTpConnection.
+ */
void
send_error_cb (TpChannel *proxy,
guint arg_Error,
@@ -183,12 +261,24 @@ send_error_cb (TpChannel *proxy,
gpointer user_data,
GObject *weak_object);
+/**
+ * Callback for the Send DBus method.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param error Points to a GError in case of failure, NULL otherwise.
+ * @param user_data Points to a #PrplTpConnection.
+ */
void
send_cb (TpChannel *proxy,
const GError *error,
gpointer user_data,
GObject *weak_object);
+/**
+ * Callback for TpChannel's "invalidated" signal.
+ *
+ * @param self The channel that got invalidated.
+ */
void
text_channel_invalidated_cb (TpProxy *self,
guint domain,
@@ -196,6 +286,14 @@ text_channel_invalidated_cb (TpProxy *se
gchar *message,
gpointer user_data);
+/**
+ * Callback for the ChatStateChanged DBus method.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param arg_Contact The handle of the contacts whose state changed.
+ * @param arg_State The new chat state of the contact.
+ * @param user_data Points to a #PrplTpConnection.
+ */
void
chat_state_changed_cb (TpChannel *proxy,
guint arg_Contact,
@@ -203,10 +301,24 @@ chat_state_changed_cb (TpChannel *proxy,
gpointer user_data,
GObject *weak_object);
+/**
+ * Handle the creation of a new Telepathy text channel (either one-to-one or
+ * chatroom channel).
+ *
+ * @param channel The newly created channel.
+ * @param data Connection-specific data
+ */
void
handle_text_channel (TpChannel *channel,
PrplTpConnection *data);
+/**
+ * Callb ack for the SetChatState DBus method.
+ *
+ * @param proxy The Telepathy channel proxy.
+ * @param error Points to a GError on failure, NULL otherwise.
+ * @param user_data Points to a #PrplTpConnection.
+ */
void
set_chat_state_cb (TpChannel *proxy,
const GError *error,
More information about the Commits
mailing list