/soc/2013/ankitkv/gobjectification: b78048ba0fbb: Convert protoc...
Ankit Vani
a at nevitus.org
Fri Feb 7 07:45:14 EST 2014
Changeset: b78048ba0fbbc6d9f3bf4b65b82d6e6e79cdacb1
Author: Ankit Vani <a at nevitus.org>
Date: 2014-02-07 16:46 +0530
Branch: soc.2013.gobjectification.plugins
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/b78048ba0fbb
Description:
Convert protocol interfaces doc to gtk-doc format
diffstat:
libpurple/protocol.h | 533 +++++++++++++++++++++++---------------------------
1 files changed, 242 insertions(+), 291 deletions(-)
diffs (truncated from 777 to 300 lines):
diff --git a/libpurple/protocol.h b/libpurple/protocol.h
--- a/libpurple/protocol.h
+++ b/libpurple/protocol.h
@@ -107,37 +107,32 @@ struct _PurpleProtocol
/**
* PurpleProtocolClass:
+ * @login: Log in to the server.
+ * @close: Close connection with the server.
+ * @status_types: Returns a list of #PurpleStatusType which exist for this
+ * account; and must add at least the offline and online states.
+ * @list_icon: 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.
*
* The base class for all protocols.
*
* All protocol types must implement the methods in this class.
*/
+/* If adding new methods to this class, ensure you add checks for them in
+ purple_protocols_add().
+*/
struct _PurpleProtocolClass
{
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);
/*< private >*/
@@ -156,6 +151,61 @@ typedef struct _PurpleProtocolClientIfac
/**
* PurpleProtocolClientIface:
+ * @get_actions: Returns the actions the protocol can perform. These will
+ * show up in the Accounts menu, under a submenu with the name
+ * of the account.
+ * @list_emblem: Fills the four <type>char**</type>'s with string
+ * identifiers for "emblems" that the UI will interpret and
+ * display as relevant
+ * @status_text: Gets a short string representing this buddy's status. This
+ * will be shown on the buddy list.
+ * @tooltip_text: Allows the protocol to add text to a buddy's tooltip.
+ * @blist_node_menu: Returns a list of #PurpleMenuAction structs, which
+ * represent extra actions to be shown in (for example) the
+ * right-click menu for @node.
+ * @normalize: Convert the username @who to its canonical form. Also checks for
+ * validity.
+ * <sbr/>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.
+ * <sbr/>@account: The account the username is related to. Can be
+ * %NULL.
+ * <sbr/>@who: The username to convert.
+ * <sbr/>Returns: Normalized username, or %NULL, if it's invalid.
+ * @offline_message: Checks whether offline messages to @buddy are supported.
+ * <sbr/>Returns: %TRUE if @buddy can be sent messages while
+ * they are offline, or %FALSE if not.
+ * @get_account_text_table: 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
+ * <emphasis>MUST</emphasis> be unrefed by the caller.
+ * <sbr/>@account: The account to specify. This can be
+ * %NULL.
+ * <sbr/>Returns: The protocol's string hash table.
+ * The hash table should be destroyed
+ * by the caller when it's no longer
+ * needed.
+ * @get_moods: Returns an array of #PurpleMood's, with the last one having
+ * "mood" set to %NULL.
+ * @get_max_message_size: Gets the maximum message size in bytes for the
+ * conversation.
+ * <sbr/>It may depend on connection-specific or
+ * conversation-specific variables, like channel or
+ * buddy's name length.
+ * <sbr/>This value is intended for plaintext message,
+ * the exact value may be lower because of:
+ * <sbr/> - used newlines (some protocols count them as
+ * more than one byte),
+ * <sbr/> - formatting,
+ * <sbr/> - used special characters.
+ * <sbr/>@conv: The conversation to query, or NULL to
+ * get safe minimum for the protocol.
+ * <sbr/>Returns: Maximum message size, 0 if unspecified,
+ * -1 for infinite.
*
* The protocol client interface.
*
@@ -167,98 +217,31 @@ struct _PurpleProtocolClientIface
GTypeInterface parent_iface;
/*< public >*/
- /**
- * Returns the actions the protocol can perform. These will show up in the
- * Accounts menu, under a submenu with the name of the account.
- */
GList *(*get_actions)(PurpleConnection *);
- /**
- * Fills the four char**'s with string identifiers for "emblems"
- * that the UI will interpret and display as relevant
- */
const char *(*list_emblem)(PurpleBuddy *buddy);
- /**
- * Gets a short string representing this buddy's status. This will
- * be shown on the buddy list.
- */
char *(*status_text)(PurpleBuddy *buddy);
- /**
- * Allows the protocol to add text to a buddy's tooltip.
- */
void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info,
gboolean full);
- /**
- * Returns a list of #PurpleMenuAction structs, which represent extra
- * actions to be shown in (for example) the right-click menu for @node.
- */
GList *(*blist_node_menu)(PurpleBlistNode *node);
void (*buddy_free)(PurpleBuddy *);
void (*convo_closed)(PurpleConnection *, const char *who);
- /**
- * Convert the username @who to its canonical form. Also checks for
- * validity.
- *
- * 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.
- *
- * @account: The account the username is related to. Can
- * be NULL.
- * @who: The username to convert.
- * Returns: Normalized username, or NULL, if it's invalid.
- */
const char *(*normalize)(const PurpleAccount *account, const char *who);
PurpleChat *(*find_blist_chat)(PurpleAccount *account, const char *name);
- /** Checks whether offline messages to @buddy are supported.
- * Returns: %TRUE if @buddy can be sent messages while they are
- * offline, or %FALSE if not.
- */
gboolean (*offline_message)(const PurpleBuddy *buddy);
- /** 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.
- *
- * @account: The account to specify. This can be NULL.
- * Returns: 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);
- /**
- * Returns an array of "PurpleMood"s, with the last one having
- * "mood" set to %NULL.
- */
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.
- *
- * @conv: The conversation to query, or NULL to get safe minimum
- * for the protocol.
- *
- * Returns: Maximum message size, 0 if unspecified, -1 for infinite.
- */
gssize (*get_max_message_size)(PurpleConversation *conv);
};
@@ -271,6 +254,65 @@ typedef struct _PurpleProtocolServerIfac
/**
* PurpleProtocolServerIface:
+ * @register_user: New user registration
+ * @unregister_user: 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!
+ * @get_info: Should arrange for purple_notify_userinfo() to be called
+ * with @who's user info.
+ * @add_buddy: Add a buddy to a group on the server.
+ * <sbr/>This protocol function may be called in situations in
+ * which the buddy is already in the specified group. If the
+ * protocol supports authorization and the user is not already
+ * authorized to see the status of @buddy, @add_buddy should
+ * request authorization.
+ * <sbr/>If authorization is required, then use the supplied
+ * invite message.
+ * @keepalive: 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 #KEEPALIVE_INTERVAL in
+ * <filename>libpurple/connection.c</filename>.)
+ * @alias_buddy: Save/store buddy's alias on server list/roster
+ * @group_buddy: Change a buddy's group on a server list/roster
+ * @rename_group: Rename a group on a server list/roster
+ * @set_buddy_icon: Set the buddy icon for the given connection to @img. The
+ * protocol does <emphasis>NOT</emphasis> own a reference to
+ * @img; if it needs one, it must #purple_imgstore_ref(@img)
+ * itself.
+ * @send_raw: For use in plugins that may understand the underlying
+ * protocol
+ * @set_public_alias: Set the user's "friendly name" (or alias or nickname or
+ * whatever term you want to call it) on the server. The
+ * protocol should call @success_cb or @failure_cb
+ * <emphasis>asynchronously</emphasis> (if it knows
+ * immediately that the set will fail, call one of the
+ * callbacks from an idle/0-second timeout) depending on if
+ * the nickname is set successfully. See
+ * purple_account_set_public_alias().
+ * <sbr/>@gc: The connection for which to set an alias
+ * <sbr/>@alias: The new server-side alias/nickname for this
+ * account, or %NULL to unset the
+ * alias/nickname (or return it to a
+ * protocol-specific "default").
+ * <sbr/>@success_cb: Callback to be called if the public
+ * alias is set
+ * <sbr/>@failure_cb: Callback to be called if setting the
+ * public alias fails
+ * @get_public_alias: Retrieve the user's "friendly name" as set on the server.
+ * The protocol should call @success_cb or @failure_cb
+ * <emphasis>asynchronously</emphasis> (even if it knows
+ * immediately that the get will fail, call one of the
+ * callbacks from an idle/0-second timeout) depending on if
+ * the nickname is retrieved. See
+ * purple_account_get_public_alias().
+ * <sbr/>@gc: The connection for which to retireve
+ * the alias
+ * <sbr/>@success_cb: Callback to be called with the
+ * retrieved alias
+ * <sbr/>@failure_cb: Callback to be called if the protocol
+ * is unable to retrieve the alias
*
* The protocol server interface.
*
@@ -282,114 +324,54 @@ struct _PurpleProtocolServerIface
GTypeInterface parent_iface;
/*< public >*/
- /** 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);
- /**
- * Should arrange for purple_notify_userinfo() to be called with
- * @who 's user info.
- */
void (*get_info)(PurpleConnection *, const char *who);
More information about the Commits
mailing list