soc.2009.telepathy: 80d08346: Documented telepathy.c and added some TO...
sttwister at gmail.com
sttwister at gmail.com
Mon Dec 21 13:30:40 EST 2009
-----------------------------------------------------------------
Revision: 80d08346ceb8c29239415b6039eba621ff8a21c2
Ancestor: 4eeef180d160f80e8bc7776e9bb558ee6667cc41
Author: sttwister at gmail.com
Date: 2009-12-21T18:29:00
Branch: im.pidgin.soc.2009.telepathy
URL: http://d.pidgin.im/viewmtn/revision/info/80d08346ceb8c29239415b6039eba621ff8a21c2
Modified files:
libpurple/protocols/telepathy/telepathy.c
ChangeLog:
Documented telepathy.c and added some TODOs
-------------- next part --------------
============================================================
--- libpurple/protocols/telepathy/telepathy.c c7ea9a7a38c0092898f3c22a5747328491bead30
+++ libpurple/protocols/telepathy/telepathy.c 609938ac396e87907cd69e2239d35fee36caaf6a
@@ -52,18 +52,41 @@
#include "telepathy_contact.h"
#include "telepathy_utils.h"
+/**
+ * Do the necesarry initializations when loading the plugin.
+ *
+ * @param plugin The plugin to be loaded
+ *
+ * @return TRUE in case of success, FALSE otherwise
+ */
static gboolean
telepathy_plugin_load(PurplePlugin *plugin)
{
return TRUE;
}
+/**
+ * Return the base icon name, given an account and buddy.
+ *
+ * @param acct The account containing the buddy.
+ * @param buddy The buddy whose icon is to be returned.
+ *
+ * @return The icon name
+ */
+/* TODO: Perhaps try to return a proper protocol icon if available? */
static const char *
telepathy_list_icon(PurpleAccount *acct, PurpleBuddy *buddy)
{
return "telepathy";
}
+/**
+ * Attempts to return a human-readable description for a status.
+ *
+ * @param status The purple status to look for a description.
+ *
+ * @return A human-readable description if found, NULL otherwise.
+ */
static const gchar*
telepathy_get_status_string(PurpleStatus *status)
{
@@ -71,6 +94,7 @@ telepathy_get_status_string(PurpleStatus
int i;
+ /* Look in statuses for a match and return its description if found */
for (i = 0; statuses[i].id != NULL; ++i)
{
if (statuses[i].status_primitive != PURPLE_STATUS_AVAILABLE && g_strcmp0(id, statuses[i].id) == 0)
@@ -82,6 +106,13 @@ telepathy_get_status_string(PurpleStatus
return NULL;
}
+/**
+ * Return the status text for a buddy.
+ *
+ * @param buddy The buddy whose status text is to be returned.
+ *
+ * @return The buddy status text, or NULL if there isn't one.
+ */
static gchar*
telepathy_status_text(PurpleBuddy* buddy)
{
@@ -129,12 +160,21 @@ telepathy_status_text(PurpleBuddy* buddy
}
}
+/**
+ * Fills in user_info with information regarding a specific buddy.
+ *
+ * @param buddy The buddy whose information will be returned.
+ * @param user_info Must be filled with information pairs with
+ * purple_notify_user_info_add_pair.
+ * @param full TRUE if full information is to be returned.
+ *
+ * @return Nothing, provide the information via user_info.
+ */
static void
telepathy_tooltip_text (PurpleBuddy *buddy,
PurpleNotifyUserInfo *user_info,
- gboolean full)
+ gboolean full)
{
- //const gchar *name = purple_buddy_get_name(buddy);
const gchar *alias = purple_buddy_get_alias(buddy);
gchar *status = telepathy_status_text(buddy);
@@ -150,6 +190,13 @@ telepathy_tooltip_text (PurpleBuddy *bud
}
}
+/**
+ * Return a list of statuses provided by the prpl.
+ *
+ * @param acct The account for which the statuses will be returned.
+ *
+ * @return A GList of PurpleStatusType.
+ */
/* TODO: Do a proper query of the "status" property */
static GList *
telepathy_status_types(PurpleAccount *acct)
@@ -178,6 +225,14 @@ telepathy_status_types(PurpleAccount *ac
return g_list_reverse(types);
}
+/**
+ * Returns a list of information that must be filled by the user when joining a
+ * chat.
+ *
+ * @param gc The connection used when joining the chat.
+ *
+ * @return A GList of proto_chat_entry.
+ */
static GList *
telepathy_chat_info(PurpleConnection *gc)
{
@@ -193,11 +248,17 @@ telepathy_chat_info(PurpleConnection *gc
return m;
}
+/**
+ * Attemp to bring an account online.
+ *
+ * @param acct The account to bring online.
+ */
static void
telepathy_login(PurpleAccount *acct)
{
GValueArray *initial_presence;
+ /* TODO: account_data should be properly stored somehow in a PurpleAccount. */
PrplTpAccount *account_data = (PrplTpAccount*)purple_account_get_int(
acct, "tp_account_data", 0);
@@ -214,6 +275,8 @@ telepathy_login(PurpleAccount *acct)
return;
}
+ /* Change the account's Enabled and RequestedPresence properties in order
+ * to login. */
initial_presence = purple_status_to_telepathy_status(
purple_account_get_active_status(acct));
@@ -235,11 +298,17 @@ telepathy_login(PurpleAccount *acct)
tp_g_value_slice_free(requested_presence);
}
+/**
+ * Disconnect an existing connection.
+ *
+ * @param gc The connection to disconnect.
+ */
static void
telepathy_close(PurpleConnection *gc)
{
PurpleAccount *acct = purple_connection_get_account(gc);
+ /* TODO: Fix this... */
PrplTpAccount *account_data = (PrplTpAccount*)purple_account_get_int(
acct, "tp_account_data", 0);
@@ -255,6 +324,7 @@ telepathy_close(PurpleConnection *gc)
return;
}
+ /* Set the account's Enabled property to FALSE */
enabled = tp_g_value_slice_new_boolean(FALSE);
tp_cli_dbus_properties_call_set(account_data->tp_account, -1,
@@ -264,6 +334,16 @@ telepathy_close(PurpleConnection *gc)
tp_g_value_slice_free(enabled);
}
+/**
+ * Send a message to the buddy.
+ *
+ * @param gc The connection that will be used to send the message.
+ * @param who The name of the buddy to send the message to.
+ * @param message The message text.
+ * @param flags A bitwise OR of message flags.
+ *
+ * @return A positive value in case of success.
+ */
static int
telepathy_send_im (PurpleConnection *gc,
const char *who,
@@ -294,11 +374,13 @@ telepathy_send_im (PurpleConnection *gc,
TP_IFACE_CHANNEL ".TargetID", G_TYPE_STRING, who,
NULL);
+ /* Create a new channel struct and cache it. */
tp_channel = g_new0(PrplTpTextChannel, 1);
g_hash_table_insert(data->text_Channels, g_strdup(who), tp_channel);
purple_debug_info("telepathy", "Requesting text channel for %s\n", who);
+ /* Ensure the channel exists (create it). */
tp_cli_channel_dispatcher_call_ensure_channel(channel_Dispatcher, -1,
tp_account->obj_Path, map, time(NULL), "",
create_channel_cb, data, NULL, NULL);
@@ -324,6 +406,15 @@ telepathy_send_im (PurpleConnection *gc,
return 1;
}
+/**
+ * Send a typing notification to a buddy.
+ *
+ * @param gc The connection used to send the typing notification.
+ * @param name The name of the buddy to send the notification to.
+ * @param state The typing state to send to the buddy.
+ *
+ * @return TODO: What's the return value??
+ */
static unsigned int
telepathy_send_typing (PurpleConnection *gc, const char *name, PurpleTypingState state)
{
@@ -388,6 +479,14 @@ telepathy_send_typing (PurpleConnection
return 0;
}
+/**
+ * Arranges for purple_notify_userinfo() to be called with information about
+ * the buddy. Use purple_notify_user_info_new() and
+ * purple_notify_user_info_add_pair() for this purpose.
+ *
+ * @param gc The connection used to gather the data.
+ * @param who The name of the buddy whose info will be collected.
+ */
static void
telepathy_get_info (PurpleConnection *gc, const char *who)
{
@@ -412,6 +511,12 @@ telepathy_get_info (PurpleConnection *gc
purple_notify_userinfo(gc, who, user_info, NULL, NULL);
}
+/**
+ * Modify the status of an account.
+ *
+ * @param account The account whose status is modified.
+ * @param status The new status to use.
+ */
static void
telepathy_set_status (PurpleAccount *account, PurpleStatus *status)
{
@@ -421,17 +526,21 @@ telepathy_set_status (PurpleAccount *acc
GValueArray *initial_presence;
GValue *requested_presence;
+ /* Extract the information that will be passed on to Telepathy */
const gchar *presence_id = purple_status_get_id(status);
const gchar *presence_message = purple_status_get_attr_string(status, "message");
purple_debug_info("telepathy", "Setting status %s (%s) for %s\n",
presence_id, presence_message, purple_account_get_username(account));
+ /* Return the status in form of a value array */
initial_presence = purple_status_to_telepathy_status(
purple_account_get_active_status(account));
+ /* The array needs to be boxed before sending */
requested_presence = tp_g_value_slice_new_boxed(G_TYPE_VALUE_ARRAY, initial_presence);
+ /* Send the request to change the status */
tp_cli_dbus_properties_call_set(account_data->tp_account, -1,
TP_IFACE_ACCOUNT, "RequestedPresence",
requested_presence,
@@ -442,6 +551,13 @@ telepathy_set_status (PurpleAccount *acc
tp_g_value_slice_free(requested_presence);
}
+/**
+ * Add a new buddy to this account.
+ *
+ * @param gc The connection used to add the buddy.
+ * @param buddy Contains information about the buddy to be added.
+ * @param group The group in which the buddy is to be added.
+ */
static void
telepathy_add_buddy (PurpleConnection *gc, PurpleBuddy *buddy, PurpleGroup *group)
{
@@ -504,6 +620,13 @@ telepathy_add_buddy (PurpleConnection *g
}
}
+/**
+ * Remove a buddy from an account.
+ *
+ * @param gc The connection used to remove the buddy.
+ * @param buddy The buddy to be removed.
+ * @param group The buddy's group.
+ */
static void
telepathy_remove_buddy (PurpleConnection *gc, PurpleBuddy *buddy, PurpleGroup *group)
{
@@ -514,12 +637,22 @@ telepathy_remove_buddy (PurpleConnection
purple_debug_info("telepathy", "Removing buddy %s\n", buddy_name);
+ /* Request a handle using the buddy name and then remove the buddy using
+ * the handle. */
+ /* TODO: Perhaps the buddy handle could be cached into PurpleBuddy ? */
tp_connection_request_handles(connection_data->connection, -1,
TP_HANDLE_TYPE_CONTACT, ids,
remove_contact_cb, connection_data,
NULL, NULL);
}
+/**
+ * Join a chat using the information specified in components.
+ *
+ * @param gc The connection used to join the chat.
+ * @param components A hash-table containing information required to join the
+ * chat (i.e room name).
+ */
static void
telepathy_join_chat (PurpleConnection *gc, GHashTable *components)
{
@@ -648,6 +781,12 @@ telepathy_chat_invite (PurpleConnection
invite_contact_to_chatroom_cb, invitation, g_free, NULL);
}
+/**
+ * Leave a chat.
+ *
+ * @param gc The connection that was used to join the chat.
+ * @param id The id of the chat.
+ */
static void
telepathy_chat_leave (PurpleConnection *gc, int id)
{
@@ -666,6 +805,14 @@ telepathy_chat_leave (PurpleConnection *
tp_cli_channel_call_close(tp_channel->channel, -1, NULL, NULL, NULL, NULL);
}
+/**
+ * Send a message to a chat room.
+ *
+ * @param gc The connection that was used to join the chat.
+ * @param it The id of the chat.
+ * @param message The message text to be sent.
+ * @param flags A bitwise OR of message flags.
+ */
static int
telepathy_chat_send (PurpleConnection *gc, int id, const char *message, PurpleMessageFlags flags)
{
@@ -710,6 +857,12 @@ telepathy_chat_send (PurpleConnection *g
return 1;
}
+/**
+ * Sets the account's image to be displayed to buddies.
+ *
+ * @param gc The connection used to set the image.
+ * @param img The actual image to be set.
+ */
static void
telepathy_set_buddy_icon (PurpleConnection *gc, PurpleStoredImage *img)
{
@@ -745,6 +898,13 @@ telepathy_set_buddy_icon (PurpleConnecti
}
}
+/**
+ * Modifies a chat's topic.
+ *
+ * @param gc The connection used when joining the chat.
+ * @param id The chat's id.
+ * @param topic The text of the topic.
+ */
static void
telepathy_set_chat_topic (PurpleConnection *gc, int id, const char *topic)
{
@@ -812,6 +972,9 @@ telepathy_set_chat_topic (PurpleConnecti
g_ptr_array_free(arr, TRUE);
}
+/**
+ * Free any memory used by the plugin.
+ */
static void
telepathy_destroy(PurplePlugin *plugin)
{
@@ -828,6 +991,9 @@ telepathy_destroy(PurplePlugin *plugin)
}
}
+/**
+ * Contains information about the prpl.
+ */
static PurplePluginProtocolInfo telepathy_prpl_info =
{
OPT_PROTO_CHAT_TOPIC, /* options */
@@ -901,6 +1067,10 @@ static PurplePluginProtocolInfo telepath
NULL, /* get_media_caps */
};
+/**
+ * Contains information about the plugin (general information not related to a
+ * protocol).
+ */
static PurplePluginInfo telepathy_info =
{
PURPLE_PLUGIN_MAGIC,
@@ -937,6 +1107,15 @@ static PurplePluginInfo telepathy_info =
NULL
};
+/**
+ * Transforms a Telepathy option name to a human-readable format.
+ *
+ * @param telepathy_name The original Telepathy name.
+ * @param dbus_type The DBus type of the option.
+ * @param purple_type_out An output parameter containing the option type.
+ *
+ * @return The human-readable format of the option.
+ */
/* TODO: Handle "as" types */
static gchar *
get_human_name(const gchar *telepathy_name,
@@ -971,6 +1150,12 @@ get_human_name(const gchar *telepathy_na
return telepathy_transform_param_name(telepathy_name);
}
+/**
+ * Returns the integer value contained in a GValue.
+ *
+ * @param value The GValue containing the integer.
+ * @param signature The DBus signature of the integer contained in value.
+ */
static int
get_int_value(const GValue *value,
const gchar *signature)
@@ -983,7 +1168,12 @@ get_int_value(const GValue *value,
return 0;
}
-/* add parameters extracted from telepathy as libpurple options */
+/**
+ * Adds Telepathy protocol parameters to a plugin as libpurple options.
+ *
+ * @param plugin The plugin to add the options to.
+ * @param protocol The Telepathy protocol used to gather the parameters.
+ */
static void
add_protocol_options(PurplePlugin *plugin,
TpConnectionManagerProtocol *protocol)
@@ -1054,6 +1244,14 @@ add_protocol_options(PurplePlugin *plugi
}
}
+/**
+ * Fix libpurple accounts when initializing. This is required because libpurple
+ * initializes the accounts before the prpl is loaded (due to the DBus callback
+ * system), so some properties might be in an undefined state and need to be
+ * fixed.
+ *
+ * @param plugin The plugin to fix.
+ */
static void
fix_protocol_accounts(PurplePlugin* plugin)
{
@@ -1103,6 +1301,15 @@ fix_protocol_accounts(PurplePlugin* plug
}
+/**
+ * Export a libpurple plugin to match a Telepathy connection manager and
+ * protocol.
+ *
+ * @param cm The connection manager that will be used by the exported prpl.
+ * @param protocol The protocol that will be used by the exported prpl.
+ *
+ * @return TRUE in case of sucess, FALSE otherwise.
+ */
static gboolean
export_prpl(TpConnectionManager *cm,
TpConnectionManagerProtocol *protocol)
@@ -1149,12 +1356,20 @@ export_prpl(TpConnectionManager *cm,
return TRUE;
}
+/**
+ * Callback for the ListConnectionManagers DBus call.
+ *
+ * @param cms An array of connection managers.
+ * @param n_cms The number of connection managers in cms.
+ * @param error Points to a GError in case of failure, otherwise set to NULL.
+ * @param user_data Points to a PurplePlugin (the "master" Telepathy prpl).
+ */
static void
list_connection_managers_cb (TpConnectionManager * const *cms,
- gsize n_cms,
- const GError *error,
- gpointer user_data,
- GObject *weak_object)
+ gsize n_cms,
+ const GError *error,
+ gpointer user_data,
+ GObject *weak_object)
{
int i,j;
@@ -1185,6 +1400,15 @@ list_connection_managers_cb (TpConnectio
}
+/**
+ * Initializes the plugin. This plugin is the "master" prpl and is created by
+ * libpurple which will then export a prpl for each protocol supported by
+ * Telepathy.
+ *
+ * @param plugin The plugin created by libpurple.
+ *
+ * @return TRUE in case of sucess, FALSE otherwise.
+ */
/* TODO: Check for staticly linked module */
/* TODO: Get rid of the "Telepathy" prpl */
G_MODULE_EXPORT gboolean purple_init_plugin(PurplePlugin *plugin);
More information about the Commits
mailing list