/soc/2013/ankitkv/gobjectification: 6c4736862534: Split up Purpl...
Ankit Vani
a at nevitus.org
Sat Sep 14 05:49:39 EDT 2013
Changeset: 6c4736862534dd14647db88c167e35995b53323a
Author: Ankit Vani <a at nevitus.org>
Date: 2013-09-14 12:01 +0530
Branch: soc.2013.gobjectification.plugins
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/6c4736862534
Description:
Split up PurpleProtocolInterface into 10 smaller interfaces
diffstat:
libpurple/protocol.h | 583 +++++++++++++++++++++++++++++++-------------------
1 files changed, 364 insertions(+), 219 deletions(-)
diffs (truncated from 703 to 300 lines):
diff --git a/libpurple/protocol.h b/libpurple/protocol.h
--- a/libpurple/protocol.h
+++ b/libpurple/protocol.h
@@ -43,8 +43,26 @@ typedef struct _PurpleProtocol PurplePro
/** @copydoc _PurpleProtocolClass */
typedef struct _PurpleProtocolClass PurpleProtocolClass;
-/** @copydoc _PurpleProtocolInterface */
-typedef struct _PurpleProtocolInterface PurpleProtocolInterface;
+/** @copydoc _PurpleProtocolClientInterface */
+typedef struct _PurpleProtocolClientInterface PurpleProtocolClientInterface;
+/** @copydoc _PurpleProtocolServerInterface */
+typedef struct _PurpleProtocolServerInterface PurpleProtocolServerInterface;
+/** @copydoc _PurpleProtocolIMInterface */
+typedef struct _PurpleProtocolIMInterface PurpleProtocolIMInterface;
+/** @copydoc _PurpleProtocolChatInterface */
+typedef struct _PurpleProtocolChatInterface PurpleProtocolChatInterface;
+/** @copydoc _PurpleProtocolPrivacyInterface */
+typedef struct _PurpleProtocolPrivacyInterface PurpleProtocolPrivacyInterface;
+/** @copydoc _PurpleProtocolXferInterface */
+typedef struct _PurpleProtocolXferInterface PurpleProtocolXferInterface;
+/** @copydoc _PurpleProtocolRoomlistInterface */
+typedef struct _PurpleProtocolRoomlistInterface PurpleProtocolRoomlistInterface;
+/** @copydoc _PurpleProtocolAttentionInterface */
+typedef struct _PurpleProtocolAttentionInterface PurpleProtocolAttentionInterface;
+/** @copydoc _PurpleProtocolMediaInterface */
+typedef struct _PurpleProtocolMediaInterface PurpleProtocolMediaInterface;
+/** @copydoc _PurpleProtocolFactoryInterface */
+typedef struct _PurpleProtocolFactoryInterface PurpleProtocolFactoryInterface;
#include "account.h"
#include "accountopt.h"
@@ -104,25 +122,50 @@ struct _PurpleProtocol
/**
* The base class for all protocols.
+ *
+ * All protocol types must implement the methods in this class.
*/
struct _PurpleProtocolClass
{
/*< private >*/
GObjectClass parent_class;
+
+ /**
+ * Log in to the server.
+ */
+ void (*login)(PurpleAccount *);
+
+ /**
+ * Close connection with the server.
+ */
+ void (*close)(PurpleConnection *);
+
+ /**
+ * Returns a list of #PurpleStatusType which exist for this account;
+ * and must add at least the offline and online states.
+ */
+ GList *(*status_types)(PurpleAccount *account);
+
+ /**
+ * Returns the base icon name for the given buddy and account.
+ * If buddy is NULL and the account is non-NULL, it will return the
+ * name to use for the account's icon. If both are NULL, it will
+ * return the name to use for the protocol's icon.
+ */
+ const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
+
+ void (*_purple_reserved1)(void);
+ void (*_purple_reserved2)(void);
+ void (*_purple_reserved3)(void);
+ void (*_purple_reserved4)(void);
};
/**
- * The protocol interface.
+ * The protocol client interface.
*
- * Every protocol implements this interface. It is the gateway between purple
- * and the protocol's functions. Many of these callbacks can be NULL. However,
- * these callbacks must be implemented:
- *
- * PurpleProtocolInterface::list_icon \n
- * PurpleProtocolInterface::login \n
- * PurpleProtocolInterface::close
+ * This interface provides a gateway between purple and the protocol.
*/
-struct _PurpleProtocolInterface
+struct _PurpleProtocolClientInterface
{
/*< private >*/
GTypeInterface parent_iface;
@@ -134,16 +177,6 @@ struct _PurpleProtocolInterface
GList *(*get_actions)(PurpleConnection *);
/**
- * Returns the base icon name for the given buddy and account.
- * If buddy is NULL and the account is non-NULL, it will return the
- * name to use for the account's icon. If both are NULL, it will
- * return the name to use for the protocol's icon.
- *
- * This must be implemented.
- */
- const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
-
- /**
* Fills the four char**'s with string identifiers for "emblems"
* that the UI will interpret and display as relevant
*/
@@ -162,76 +195,100 @@ struct _PurpleProtocolInterface
gboolean full);
/**
- * Returns a list of #PurpleStatusType which exist for this account;
- * this must be implemented, and must add at least the offline and
- * online states.
- */
- GList *(*status_types)(PurpleAccount *account);
-
- /**
* Returns a list of #PurpleMenuAction structs, which represent extra
* actions to be shown in (for example) the right-click menu for @a
* node.
*/
GList *(*blist_node_menu)(PurpleBlistNode *node);
- /**
- * Returns a list of #PurpleProtocolChatEntry structs, which represent
- * information required by the protocol to join a chat. libpurple will
- * call join_chat along with the information filled by the user.
- *
- * @return A list of #PurpleProtocolChatEntry structs
- */
- GList *(*chat_info)(PurpleConnection *);
+ void (*buddy_free)(PurpleBuddy *);
+
+ void (*convo_closed)(PurpleConnection *, const char *who);
/**
- * Returns a hashtable which maps #PurpleProtocolChatEntry struct
- * identifiers to default options as strings based on chat_name. The
- * resulting hashtable should be created with
- * g_hash_table_new_full(g_str_hash, g_str_equal, NULL, g_free);. Use
- * #get_chat_name if you instead need to extract a chat name from a
- * hashtable.
+ * Convert the username @a who to its canonical form. Also checks for
+ * validity.
*
- * @param chat_name The chat name to be turned into components
- * @return Hashtable containing the information extracted from chat_name
+ * For example, AIM treats "fOo BaR" and "foobar" as the same user; this
+ * function should return the same normalized string for both of those.
+ * On the other hand, both of these are invalid for protocols with
+ * number-based usernames, so function should return NULL in such case.
+ *
+ * @param account The account the username is related to. Can
+ * be NULL.
+ * @param who The username to convert.
+ * @return Normalized username, or NULL, if it's invalid.
*/
- GHashTable *(*chat_info_defaults)(PurpleConnection *,
- const char *chat_name);
+ const char *(*normalize)(const PurpleAccount *account, const char *who);
- /* All the server-related functions */
+ PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
- /** This must be implemented. */
- void (*login)(PurpleAccount *);
+ /** Checks whether offline messages to @a buddy are supported.
+ * @return @c TRUE if @a buddy can be sent messages while they are
+ * offline, or @c FALSE if not.
+ */
+ gboolean (*offline_message)(const PurpleBuddy *buddy);
- /** This must be implemented. */
- void (*close)(PurpleConnection *);
+ /** This allows protocols to specify additional strings to be used for
+ * various purposes. The idea is to stuff a bunch of strings in this hash
+ * table instead of expanding the struct for every addition. This hash
+ * table is allocated every call and MUST be unrefed by the caller.
+ *
+ * @param account The account to specify. This can be NULL.
+ * @return The protocol's string hash table. The hash table should be
+ * destroyed by the caller when it's no longer needed.
+ */
+ GHashTable *(*get_account_text_table)(PurpleAccount *account);
/**
- * This protocol function should return a positive value on success.
- * If the message is too big to be sent, return -E2BIG. If
- * the account is not connected, return -ENOTCONN. If the
- * protocol is unable to send the message for another reason, return
- * some other negative value. You can use one of the valid
- * errno values, or just big something. If the message should
- * not be echoed to the conversation window, return 0.
+ * Returns an array of "PurpleMood"s, with the last one having
+ * "mood" set to @c NULL.
*/
- int (*send_im)(PurpleConnection *, const char *who,
- const char *message,
- PurpleMessageFlags flags);
+ PurpleMood *(*get_moods)(PurpleAccount *account);
+
+ /**
+ * Gets the maximum message size in bytes for the conversation.
+ *
+ * It may depend on connection-specific or conversation-specific
+ * variables, like channel or buddy's name length.
+ *
+ * This value is intended for plaintext message, the exact value may be
+ * lower because of:
+ * - used newlines (some protocols count them as more than one byte),
+ * - formatting,
+ * - used special characters.
+ *
+ * @param conv The conversation to query, or NULL to get safe minimum
+ * for the protocol.
+ *
+ * @return Maximum message size, 0 if unspecified, -1 for infinite.
+ */
+ gssize (*get_max_message_size)(PurpleConversation *conv);
+};
+
+/**
+ * The protocol server interface.
+ *
+ * This interface provides a gateway between purple and the protocol's server.
+ */
+struct _PurpleProtocolServerInterface
+{
+ /*< private >*/
+ GTypeInterface parent_iface;
+
+ /** new user registration */
+ void (*register_user)(PurpleAccount *);
+
+ /** Remove the user from the server. The account can either be
+ * connected or disconnected. After the removal is finished, the
+ * connection will stay open and has to be closed!
+ */
+ void (*unregister_user)(PurpleAccount *, PurpleAccountUnregistrationCb cb,
+ void *user_data);
void (*set_info)(PurpleConnection *, const char *info);
/**
- * @return If this protocol requires the PURPLE_IM_TYPING message to
- * be sent repeatedly to signify that the user is still
- * typing, then the protocol should return the number of
- * seconds to wait before sending a subsequent notification.
- * Otherwise the protocol should return 0.
- */
- unsigned int (*send_typing)(PurpleConnection *, const char *name,
- PurpleIMTypingState state);
-
- /**
* Should arrange for purple_notify_userinfo() to be called with
* @a who's user info.
*/
@@ -259,11 +316,144 @@ struct _PurpleProtocolInterface
void (*remove_buddy)(PurpleConnection *, PurpleBuddy *buddy,
PurpleGroup *group);
void (*remove_buddies)(PurpleConnection *, GList *buddies, GList *groups);
- void (*add_permit)(PurpleConnection *, const char *name);
- void (*add_deny)(PurpleConnection *, const char *name);
- void (*rem_permit)(PurpleConnection *, const char *name);
- void (*rem_deny)(PurpleConnection *, const char *name);
- void (*set_permit_deny)(PurpleConnection *);
+
+ /** If implemented, this will be called regularly for this protocol's
+ * active connections. You'd want to do this if you need to repeatedly
+ * send some kind of keepalive packet to the server to avoid being
+ * disconnected. ("Regularly" is defined by
+ * <code>KEEPALIVE_INTERVAL</code> in <tt>libpurple/connection.c</tt>.)
+ */
+ void (*keepalive)(PurpleConnection *);
+
+ /** save/store buddy's alias on server list/roster */
+ void (*alias_buddy)(PurpleConnection *, const char *who,
+ const char *alias);
+
+ /** change a buddy's group on a server list/roster */
+ void (*group_buddy)(PurpleConnection *, const char *who,
+ const char *old_group, const char *new_group);
+
+ /** rename a group on a server list/roster */
+ void (*rename_group)(PurpleConnection *, const char *old_name,
+ PurpleGroup *group, GList *moved_buddies);
+
+ /**
+ * Set the buddy icon for the given connection to @a img. The protocol
+ * does NOT own a reference to @a img; if it needs one, it must
+ * #purple_imgstore_ref(@a img) itself.
+ */
+ void (*set_buddy_icon)(PurpleConnection *, PurpleStoredImage *img);
+
+ void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
+
+ /** For use in plugins that may understand the underlying protocol */
More information about the Commits
mailing list