soc.2009.telepathy: 4eeef180: Documented all PrplTp* structs.
sttwister at gmail.com
sttwister at gmail.com
Thu Dec 3 18:15:53 EST 2009
-----------------------------------------------------------------
Revision: 4eeef180d160f80e8bc7776e9bb558ee6667cc41
Ancestor: 2d36fc213fa74d6ef4c9ee0de6a2cd88a166bb44
Author: sttwister at gmail.com
Date: 2009-12-03T23:09:46
Branch: im.pidgin.soc.2009.telepathy
URL: http://d.pidgin.im/viewmtn/revision/info/4eeef180d160f80e8bc7776e9bb558ee6667cc41
Modified files:
libpurple/protocols/telepathy/telepathy.h
libpurple/protocols/telepathy/telepathy_account.h
libpurple/protocols/telepathy/telepathy_channel_list.h
libpurple/protocols/telepathy/telepathy_channel_text.h
libpurple/protocols/telepathy/telepathy_connection.h
libpurple/protocols/telepathy/telepathy_contact.h
libpurple/protocols/telepathy/telepathy_utils.h
ChangeLog:
Documented all PrplTp* structs.
-------------- next part --------------
============================================================
--- libpurple/protocols/telepathy/telepathy.h 73f0807ac43ec278788bf46933d603a0a4641dd1
+++ libpurple/protocols/telepathy/telepathy.h a8a95410b3c6d2a3df994154f57926e3c868537e
@@ -40,6 +40,10 @@ GHashTable *accounts_Hash_Table;
/* This maps account object path to account_data struct */
GHashTable *accounts_Hash_Table;
+/**
+ * Holds information that binds the purple-land specific plugin data with
+ * telepathy-glib proxy objects.
+ */
typedef struct
{
TpConnectionManager *cm;
============================================================
--- libpurple/protocols/telepathy/telepathy_account.h 96f1e14bbef395f552356f5575727f1873b4ed62
+++ libpurple/protocols/telepathy/telepathy_account.h 00f9f1af053564a1cd436a732ca811beaae0832a
@@ -27,6 +27,9 @@
#include "telepathy_connection.h"
+/**
+ * Holds information about a Telepathy account
+ */
typedef struct
{
TpAccount *tp_account;
@@ -34,10 +37,11 @@ typedef struct
PrplTpConnection *connection_data;
- gchar *obj_Path;
- gchar *cm, *protocol;
+ gchar *obj_Path; /**< The DBus object path of the account */
+ gchar *cm; /**< The name of the account's connection manager */
+ gchar *protocol; /**< The name of the account's protocol */
- GHashTable *properties;
+ GHashTable *properties; /**< A hashtable of the account's DBus properties */
} PrplTpAccount;
============================================================
--- libpurple/protocols/telepathy/telepathy_channel_list.h 34185c1c4052cc2fbc5b6afeec2b5154a194432b
+++ libpurple/protocols/telepathy/telepathy_channel_list.h 52429be1529077b9d5b8929f29966acca76b296f
@@ -25,15 +25,22 @@
#include "telepathy_connection.h"
+/**
+ * Holds information related to an authorization request made by a contact.
+ */
typedef struct
{
PrplTpConnection *connection_data;
- TpChannel *channel;
- TpHandle handle;
- const gchar *message;
+ TpChannel *channel; /**< The channel proxy containing the contact to be
+ added. */
+ TpHandle handle; /**< The handle of the contact to be added. */
+ const gchar *message; /**< An optional message sent by the contact. */
} PrplTpAuthorizationRequest;
+/**
+ * Holds purple and telepathy-glib references for a channel/group.
+ */
typedef struct
{
PrplTpConnection *connection_data;
============================================================
--- libpurple/protocols/telepathy/telepathy_channel_text.h d3baeb47caff0931e828cce74e0769b0f7a3de13
+++ libpurple/protocols/telepathy/telepathy_channel_text.h a0221a2a2a704309afc4ac529780c678bfb8fd5e
@@ -27,75 +27,106 @@
#include "telepathy_connection.h"
+/**
+ * Represents a Telepathy property.
+ *
+ * A Telepathy property is implemented using the
+ * org.freedesktop.Telepathy.Properties interface.
+ */
typedef struct
{
- guint id;
- gchar *name;
- gchar *signature;
- guint flags;
+ guint id; /**< The id of the property. */
+ gchar *name; /**< The name of the property. */
+ gchar *signature; /**< The DBus signature of the property. */
+ guint flags; /**< The property flags (read/write). */
- GValue *value;
+ GValue *value; /**< A GValue containing the property contents. */
} PrplTpProperty;
void
destroy_property(PrplTpProperty *tp_property);
+/**
+ * Holds information related to a Telepathy room channel.
+ */
typedef struct
{
TpChannel *channel;
PrplTpConnection *connection_data;
- GHashTable *contacts;
-
- TpHandle self_handle;
-
- /* This will map property IDs to PrplTpProperty structs */
- GHashTable *properties;
-
- /* This will map property names to PrplTpProperty structs */
- GHashTable *properties_by_name;
-
-
+ GHashTable *contacts; /**< Maps contact handles to TpContact proxy objects. */
+ TpHandle self_handle; /**< Holds the Telepathy self handle. */
+ GHashTable *properties; /**< Maps property IDs to PrplTpProperty strycts. */
+ GHashTable *properties_by_name; /**< Maps property names to PrplTpProperty structs. */
} PrplTpRoomChannel;
void
destroy_room_channel(PrplTpRoomChannel *tp_channel);
+/**
+ * Represents a Telepathy message.
+ */
typedef struct
{
- guint msg_id;
- guint timestamp;
- guint sender;
- guint type;
- guint flags;
- gchar *msg;
-
+ guint msg_id; /**< A numeric identifier for acknowledging the message. */
+ guint timestamp; /**< A Unix timestamp indicating when the message was received. */
+ guint sender; /**< The handle of the contact who sent the message. */
+ guint type; /**< The type of the message (normal, action, notice, etc.). */
+ guint flags; /**< A bitwise OR of the message flags. */
+ gchar *msg; /**< The text of the message. */
} PrplTpMessage;
+/**
+ * Holds information related to scrollback messages that were sent by other
+ * users before joining the channel.
+ */
typedef struct
{
- GArray *messages;
+ GArray *messages; /**< An array containing a PrplTpMessage for each message. */
+
+ /**
+ * An array of contact handles NOT currently in the channel, which must be
+ * explicitly requested before knowing the identity of the sender. These
+ * are contact handles that have sent messages and left the channel before
+ * us joining it.
+ */
GArray *handles;
- PrplTpRoomChannel *channel_data;
-
+ /**
+ * Information of the channel containing the scrollback messages.
+ */
+ PrplTpRoomChannel *channel_data;
} PrplTpScrollbackMessages;
+/**
+ * Represents an invitation sent to another contact.
+ */
typedef struct
{
- PrplTpRoomChannel *tp_channel;
- gchar *msg;
+ PrplTpRoomChannel *tp_channel; /**< The channel to invite the contact to. */
+ gchar *msg; /**< An optional message sent to the contact. */
} PrplTpChatInvitation;
+/**
+ * Holds information related to a Telepathy text channel.
+ */
typedef struct
{
+ /**
+ * A list of (gchar*) message texts that have been sent by the UI before
+ * actually joining the channel.
+ */
GList *pending_Messages;
- TpChannel *channel;
- /* This flag avoids having a message processed twice via both Received signal and ListPendingMessages */
+ TpChannel *channel; /**< The telepathy-glib channel proxy object */
+
+ /**
+ * This flag avoids having a pending message processed twice via both
+ * Received signal and ListPendingMessages.
+ */
gboolean received_Pending_Messages;
} PrplTpTextChannel;
============================================================
--- libpurple/protocols/telepathy/telepathy_connection.h ddfede10f813f9f86150b7950bfb0c41d2650d68
+++ libpurple/protocols/telepathy/telepathy_connection.h aebefef2e1bdcdc46f2485763d7ceba2e0da4866
@@ -30,36 +30,65 @@
#include "connection.h"
+/**
+ * Contains information that binds purple-land structs to telepathy-glib
+ * objects regarding a Telepathy connection.
+ */
typedef struct
{
TpConnection *connection;
- PurpleConnection *gc;
+ PurpleConnection *gc;
PurpleAccount *acct;
- gpointer account_data;
+ /**
+ * A pointer to the PrplTpAccount struct of the account connected using
+ * this Telepathy connection.
+ */
+ gpointer account_data;
+ /**
+ * The Telepathy contact handle representing the local user.
+ */
TpHandle self_handle;
- /* This flag avoids having a channel processed twice via both NewChannels and quering the Channels property */
+ /**
+ * This flag avoids having a channel processed twice via both NewChannels
+ * and quering the Channels property.
+ */
gboolean listing_channels;
- /* This will hold pointers to PrplTpTextChannel for buddies that have an active conversation */
+ /**
+ * Holds pointers to PrplTpTextChannel for buddies that have an active
+ * conversation.
+ *
+ * Maps a buddy name to a PrplTpTextChannel struct.
+ */
GHashTable *text_Channels;
- /* This will map room handles to PrplTpRoomChannel for active chat rooms */
+ /**
+ * Maps room handles to PrplTpRoomChannel for active chat rooms.
+ */
GHashTable *room_Channels;
- /* This will map contact handles to PrplTpContact */
+ /**
+ * Maps contact handles to PrplTpContact structs.
+ */
GHashTable *contacts;
- /* This will map group name to PrplTpGroup structs */
+ /**
+ * Maps group names to PrplTpGroup structs.
+ */
GHashTable *groups;
- /* This will map list name to PrplTpGroup structs */
+ /**
+ * Maps list names to PrplTpGroup structs.
+ */
GHashTable *lists;
- /* This will map a group name to a buddy to be added to that group.
- * It's needed when a new group needs to be created as a request to add a buddy.
+ /* Maps a group name to a buddy name to be added to that group.
+ *
+ * It's needed when a new group needs to be created as a request to add a
+ * buddy.
*/
GHashTable *buddy_to_be_added;
============================================================
--- libpurple/protocols/telepathy/telepathy_contact.h 876bb8db6bd4b7dae7418fe1b780bee4db7c18d8
+++ libpurple/protocols/telepathy/telepathy_contact.h 43a2187950aad6a3c676b6714a69c4c24edb0978
@@ -25,6 +25,9 @@
#include "telepathy_connection.h"
+/**
+ * Holds information about a Telepathy contact.
+ */
typedef struct
{
TpContact *contact;
============================================================
--- libpurple/protocols/telepathy/telepathy_utils.h b5564919740a7b9cdd51cc22b8593e579bf71668
+++ libpurple/protocols/telepathy/telepathy_utils.h ed085d486bee3e27a16c926d8bb7db5c06a3893a
@@ -29,6 +29,9 @@
#include "status.h"
+/**
+ * A mapping of a Telepathy protocol option to a human-readable name.
+ */
typedef struct
{
const gchar *telepathy_name;
@@ -36,6 +39,9 @@ typedef struct
const gchar *human_name;
} OptionMapping;
+/**
+ * A list of standard option mappings.
+ */
static const OptionMapping options[] = {
{ "server", "s", N_("Server")},
{ "port", "q", N_("Port")},
@@ -47,6 +53,9 @@ static const OptionMapping options[] = {
{ NULL, NULL, NULL}
};
+/**
+ * A mapping of a Telepathy status to a human-readable id and description.
+ */
typedef struct
{
const guint status_primitive;
@@ -54,6 +63,9 @@ typedef struct
const gchar* description;
} StatusMapping;
+/**
+ * A list of standard status mappings.
+ */
static const StatusMapping statuses[] =
{
{ PURPLE_STATUS_AVAILABLE, "available", N_("Available") },
More information about the Commits
mailing list