Mercurial > pidgin
changeset 23483:63cfd4ea15ab
propagate from branch 'im.pidgin.pidgin' (head 5209711a57354bb80c0bca86b13e1e819530ac58)
to branch 'im.pidgin.cpw.qulogic.msn' (head 305bb636a4102d934e1a82e845a5b438e2372731)
| author | Elliott Sales de Andrade <qulogic@pidgin.im> |
|---|---|
| date | Mon, 16 Jun 2008 01:44:28 +0000 |
| parents | 314fcd0879ec (current diff) 53db7393829e (diff) |
| children | 46d8edad1647 |
| files | |
| diffstat | 9 files changed, 101 insertions(+), 17 deletions(-) [+] |
line wrap: on
line diff
--- a/libpurple/blist.h Mon Jun 16 01:43:10 2008 +0000 +++ b/libpurple/blist.h Mon Jun 16 01:44:28 2008 +0000 @@ -31,13 +31,20 @@ #include <glib.h> +/** @copydoc _PurpleBuddyList */ typedef struct _PurpleBuddyList PurpleBuddyList; +/** @copydoc _PurpleBlistUiOps */ typedef struct _PurpleBlistUiOps PurpleBlistUiOps; +/** @copydoc _PurpleBlistNode */ typedef struct _PurpleBlistNode PurpleBlistNode; +/** @copydoc _PurpleChat */ typedef struct _PurpleChat PurpleChat; +/** @copydoc _PurpleGroup */ typedef struct _PurpleGroup PurpleGroup; +/** @copydoc _PurpleContact */ typedef struct _PurpleContact PurpleContact; +/** @copydoc _PurpleBuddy */ typedef struct _PurpleBuddy PurpleBuddy; /**************************************************************************/
--- a/libpurple/cmds.h Mon Jun 16 01:43:10 2008 +0000 +++ b/libpurple/cmds.h Mon Jun 16 01:44:28 2008 +0000 @@ -30,6 +30,7 @@ /**************************************************************************/ /*@{*/ +/** The possible results of running a command with purple_cmd_do_command(). */ typedef enum _PurpleCmdStatus { PURPLE_CMD_STATUS_OK, PURPLE_CMD_STATUS_FAILED, @@ -39,16 +40,31 @@ PURPLE_CMD_STATUS_WRONG_TYPE, } PurpleCmdStatus; +/** Commands registered with the core return one of these values when run. + * Normally, a command will want to return one of the first two; in some + * unusual cases, you might want to have several functions called for a + * particular command; in this case, they should return + * #PURPLE_CMD_RET_CONTINUE to cause the core to fall through to other + * commands with the same name. + */ typedef enum _PurpleCmdRet { - PURPLE_CMD_RET_OK, /**< Everything's okay. Don't look for another command to call. */ + PURPLE_CMD_RET_OK, /**< Everything's okay; Don't look for another command to call. */ PURPLE_CMD_RET_FAILED, /**< The command failed, but stop looking.*/ PURPLE_CMD_RET_CONTINUE, /**< Continue, looking for other commands with the same name to call. */ } PurpleCmdRet; #define PURPLE_CMD_FUNC(func) ((PurpleCmdFunc)func) +/** A function implementing a command, as passed to purple_cmd_register(). + * + * @todo document the arguments to these functions. + * */ typedef PurpleCmdRet (*PurpleCmdFunc)(PurpleConversation *, const gchar *cmd, gchar **args, gchar **error, void *data); +/** A unique integer representing a command registered with + * purple_cmd_register(), which can subsequently be passed to + * purple_cmd_unregister() to unregister that command. + */ typedef guint PurpleCmdId; typedef enum _PurpleCmdPriority {
--- a/libpurple/connection.h Mon Jun 16 01:43:10 2008 +0000 +++ b/libpurple/connection.h Mon Jun 16 01:44:28 2008 +0000 @@ -27,6 +27,7 @@ #ifndef _PURPLE_CONNECTION_H_ #define _PURPLE_CONNECTION_H_ +/** @copydoc _PurpleConnection */ typedef struct _PurpleConnection PurpleConnection; /** @@ -223,6 +224,8 @@ void (*_purple_reserved3)(void); } PurpleConnectionUiOps; + +/* Represents an active connection on an account. */ struct _PurpleConnection { PurplePlugin *prpl; /**< The protocol plugin. */
--- a/libpurple/conversation.h Mon Jun 16 01:43:10 2008 +0000 +++ b/libpurple/conversation.h Mon Jun 16 01:44:28 2008 +0000 @@ -32,11 +32,17 @@ /**************************************************************************/ +/** @copydoc _PurpleConversationUiOps */ typedef struct _PurpleConversationUiOps PurpleConversationUiOps; +/** @copydoc _PurpleConversation */ typedef struct _PurpleConversation PurpleConversation; +/** @copydoc _PurpleConvIm */ typedef struct _PurpleConvIm PurpleConvIm; +/** @copydoc _PurpleConvChat */ typedef struct _PurpleConvChat PurpleConvChat; +/** @copydoc _PurpleConvChatBuddy */ typedef struct _PurpleConvChatBuddy PurpleConvChatBuddy; +/** @copydoc _PurpleConvMessage */ typedef struct _PurpleConvMessage PurpleConvMessage; /**
--- a/libpurple/core.h Mon Jun 16 01:43:10 2008 +0000 +++ b/libpurple/core.h Mon Jun 16 01:44:28 2008 +0000 @@ -1,4 +1,5 @@ /** + * @file core.h Startup and shutdown of libpurple * @defgroup core libpurple * @see @ref core-signals */ @@ -28,12 +29,36 @@ typedef struct PurpleCore PurpleCore; +/** Callbacks that fire at different points of the initialization and teardown + * of libpurple, along with a hook to return descriptive information about the + * UI. + */ typedef struct { + /** Called just after the preferences subsystem is initialized; the UI + * could use this callback to add some preferences it needs to be in + * place when other subsystems are initialized. + */ void (*ui_prefs_init)(void); - void (*debug_ui_init)(void); /* Unfortunate necessity. */ + /** Called just after the debug subsystem is initialized, but before + * just about every other component's initialization. The UI should + * use this hook to call purple_debug_set_ui_ops() so that debugging + * information for other components can be logged during their + * initialization. + */ + void (*debug_ui_init)(void); + /** Called after all of libpurple has been initialized. The UI should + * use this hook to set all other necessary UiOps structures. + * + * @see @ref ui-ops + */ void (*ui_init)(void); + /** Called after most of libpurple has been uninitialized. */ void (*quit)(void); + + /** Called by purple_core_get_ui_info(); should return the information + * documented there. + */ GHashTable* (*get_ui_info)(void); void (*_purple_reserved1)(void); @@ -64,17 +89,23 @@ void purple_core_quit(void); /** + * <p> * Calls purple_core_quit(). This can be used as the function * passed to purple_timeout_add() when you want to shutdown Purple * in a specified amount of time. When shutting down Purple * from a plugin, you must use this instead of purple_core_quit(); * for an immediate exit, use a timeout value of 0: - * purple_timeout_add(0, purple_core_quitcb, NULL); + * </p> + * + * <code>purple_timeout_add(0, purple_core_quitcb, NULL);</code> + * + * <p> * This is ensures that code from your plugin is not being * executed when purple_core_quit() is called. If the plugin * called purple_core_quit() directly, you would get a core dump * after purple_core_quit() executes and control returns to your * plugin because purple_core_quit() frees all plugins. + * </p> */ gboolean purple_core_quit_cb(gpointer unused); @@ -86,7 +117,8 @@ const char *purple_core_get_version(void); /** - * Returns the ID of the UI that is using the core. + * Returns the ID of the UI that is using the core, as passed to + * purple_core_init(). * * @return The ID of the UI that is currently using the core. */ @@ -95,7 +127,7 @@ /** * Returns a handle to the purple core. * - * This is used for such things as signals. + * This is used to connect to @ref core-signals "core signals". */ PurpleCore *purple_get_core(void); @@ -114,10 +146,10 @@ PurpleCoreUiOps *purple_core_get_ui_ops(void); /** - * Migrates from .gaim to .purple. + * Migrates from <tt>.gaim</tt> to <tt>.purple</tt>. * - * UIs MUST NOT call this if they have been told to use a custom - * user directory. + * UIs <strong>must not</strong> call this if they have been told to use a + * custom user directory. * * @return A boolean indicating success or migration failure. On failure, * the application must display an error to the user and then exit. @@ -125,20 +157,33 @@ gboolean purple_core_migrate(void); /** - * Ensures that only one instance is running. + * Ensures that only one instance is running. If libpurple is built with D-Bus + * support, this checks if another process owns the libpurple bus name and if + * so whether that process is using the same configuration directory as this + * process. * - * @return A boolean such that @c TRUE indicates that this is the first instance, - * whereas @c FALSE indicates that there is another instance running. + * @return @c TRUE if this is the first instance of libpurple running; + * @c FALSE if there is another instance running. * * @since 2.1.0 */ gboolean purple_core_ensure_single_instance(void); /** - * Returns a hashtable containing various information about the UI + * Returns a hash table containing various information about the UI. The + * following well-known entries may be in the table (along with any others the + * UI might choose to include): + * + * <dl> + * <dt><tt>name</tt></dt> + * <dd>the user-readable name for the UI.</dd> + * + * <dt><tt>version</tt></dt> + * <dd>a user-readable description of the current version of the UI.</dd> + * </dl> * * @return A GHashTable with strings for keys and values. This - * hash table must not be freed. + * hash table must not be freed and should not be modified. * * @since 2.1.0 *
--- a/libpurple/protocols/simple/simple.c Mon Jun 16 01:43:10 2008 +0000 +++ b/libpurple/protocols/simple/simple.c Mon Jun 16 01:44:28 2008 +0000 @@ -1898,7 +1898,7 @@ PurpleConnection *gc; struct simple_account_data *sip; gchar **userserver; - gchar *hosttoconnect; + const gchar *hosttoconnect; const char *username = purple_account_get_username(account); gc = purple_account_get_connection(account); @@ -1934,14 +1934,13 @@ sip->status = g_strdup("available"); if(!purple_account_get_bool(account, "useproxy", FALSE)) { - hosttoconnect = g_strdup(sip->servername); + hosttoconnect = sip->servername; } else { - hosttoconnect = g_strdup(purple_account_get_string(account, "proxy", sip->servername)); + hosttoconnect = purple_account_get_string(account, "proxy", sip->servername); } sip->srv_query_data = purple_srv_resolve("sip", sip->udp ? "udp" : "tcp", hosttoconnect, srvresolved, sip); - g_free(hosttoconnect); } static void simple_close(PurpleConnection *gc)
--- a/libpurple/prpl.h Mon Jun 16 01:43:10 2008 +0000 +++ b/libpurple/prpl.h Mon Jun 16 01:44:28 2008 +0000 @@ -31,6 +31,7 @@ #define _PURPLE_PRPL_H_ typedef struct _PurplePluginProtocolInfo PurplePluginProtocolInfo; +/** @copydoc _PurpleAttentionType */ typedef struct _PurpleAttentionType PurpleAttentionType; /**************************************************************************/ @@ -99,6 +100,9 @@ gboolean secret; }; +/** Represents "nudges" and "buzzes" that you may send to a buddy to attract + * their attention (or vice-versa). + */ struct _PurpleAttentionType { const char *name; /**< Shown in GUI elements */
--- a/libpurple/roomlist.h Mon Jun 16 01:43:10 2008 +0000 +++ b/libpurple/roomlist.h Mon Jun 16 01:44:28 2008 +0000 @@ -30,6 +30,7 @@ typedef struct _PurpleRoomlist PurpleRoomlist; typedef struct _PurpleRoomlistRoom PurpleRoomlistRoom; typedef struct _PurpleRoomlistField PurpleRoomlistField; +/** @copydoc _PurpleRoomlistUiOps */ typedef struct _PurpleRoomlistUiOps PurpleRoomlistUiOps; /**
--- a/libpurple/sound.h Mon Jun 16 01:43:10 2008 +0000 +++ b/libpurple/sound.h Mon Jun 16 01:44:28 2008 +0000 @@ -55,6 +55,9 @@ } PurpleSoundEventID; +/** Operations used by the core to request that particular sound files, or the + * sound associated with a particular event, should be played. + */ typedef struct _PurpleSoundUiOps { void (*init)(void);