soc.2008.masterpassword: d1d356b9: Cleaned up documentation and macros arou...

[scrouaf at soc.pidgin.im]

-----------------------------------------------------------------
Revision: d1d356b9ae2e2051fc912337a2568eeed3838ccb
Ancestor: 4f5f37402a9358500575dd8080da5d79ef96c717
Author: scrouaf at soc.pidgin.im
Date: 2008-08-27T13:10:59
Branch: im.pidgin.soc.2008.masterpassword
URL: http://d.pidgin.im/viewmtn/revision/info/d1d356b9ae2e2051fc912337a2568eeed3838ccb

Modified files:
        libpurple/account.c libpurple/account.h libpurple/keyring.h

ChangeLog: 

Cleaned up documentation and macros around deprecated password access.

-------------- next part --------------
============================================================
--- libpurple/account.c	613456ae776686bda9ba757e49850f946349fd1a
+++ libpurple/account.c	1e71f8f85528e23395d1ba51ba519638c3b6b21d
@@ -1619,7 +1619,7 @@ purple_account_set_password(PurpleAccoun
 	account->password = g_strdup(password);
 
 	if (purple_account_get_remember_password(account) == TRUE)
-		purple_keyring_set_password_async(account, account->password, NULL, NULL, NULL);
+		purple_keyring_set_password_async(account, g_strdup(password), g_free, NULL, NULL);
 }
 
 void 
============================================================
--- libpurple/account.h	89d76a25fe92a1a716bf952595f388517c2dfe40
+++ libpurple/account.h	eb196c874f99bfd1fc08e4bceeb1d6381bd7743e
@@ -322,18 +322,28 @@ void purple_account_set_username(PurpleA
  */
 void purple_account_set_username(PurpleAccount *account, const char *username);
 
+#ifndef PURPLE_DISABLE_DEPRECATED
 /**
  * Sets the account's password.
  *
  * @param account  The account.
  * @param password The password.
+ *
+ * @deprecated You should use either purple_account_set_password_async() instead.
+ * This functions is just a wrapper for the async code anyway.
  */
 void purple_account_set_password(PurpleAccount *account, const char *password);
+#endif
 
 /**
- * Set a password to be remembered.
+ * Set the account's password, and call the callback
  * This should be renamed purple_account_set_password() when getting
  * to 3.0. This calls the keyring function and syncs the accounts.xml
+ *
+ * The password in the keyring might not be immediatly updated, but the cache
+ * version will be, and it is therefore safe to read the password back before
+ * the callback has been triggered. One can also set a NULL calback.
+ *
  * @param account The account for which the password is to be saved.
  * @param password The password to save.
  * @param destroypassword A function called to free the password. Can be NULL.
@@ -565,14 +575,22 @@ const char *purple_account_get_username(
  */
 const char *purple_account_get_username(const PurpleAccount *account);
 
+#ifndef PURPLE_DISABLE_DEPRECATED
 /**
- * Returns the account's password (deprecated, use async code instead).
+ * Returns the account's password.
  *
  * @param account The account.
  *
  * @return The password.
+ *
+ * @deprecated This might return NULL if the password has not been cached yet,
+ * and the keyring doesn't support sync access. It might also hang libpurple
+ * while the keyring is prompting for a password. Use purple_account_get_password_async()
+ * or purple_connection_get_password() instead (depending on the part of the code you are
+ * calling from.
  */
 const char *purple_account_get_password(PurpleAccount *account);
+#endif
 
 /**
  * Reads the password for the account and passes it to the callback
============================================================
--- libpurple/keyring.h	bd4ac45266995435c030e76f86452344a916e979
+++ libpurple/keyring.h	c0dc87c27bfe6f83494358c90e0c7493d3b0db7b
@@ -357,29 +357,37 @@ purple_keyring_set_password_async(Purple
 				  GDestroyNotify destroypassword,
 				  PurpleKeyringSaveCallback cb,
 				  gpointer data);
-
+#ifndef PURPLE_DISABLE_DEPRECATED
 /**
  * Read a password in a synchronous way.
- * This is here only for compatibility reasons. Keyrings are not
- * expected to support this (and shouldn't), and new code should
- * use purple_keyring_get_password_async() instead.
+ *
  * @param account The account for which we want the password.
- * @return A pointer to the the password.
+ *
+ * @return A pointer to the the password
+ *
+ * @deprecated This is here only for compatibility reasons. Keyrings
+ * are not expected to support this, and you should use 
+ * purple_keyring_get_password_async() instead.
  */
 const char * 
 purple_keyring_get_password_sync(const PurpleAccount * account);
+#endif
 
+#ifndef PURPLE_DISABLE_DEPRECATED
 /**
  * Save a password in a synchronous way.
- * This is here only for compatibility reasons. Keyrings are not
- * expected to support this (and shouldn't), and new code should
- * use purple_keyring_set_password_async() instead.
+ *
  * @param account The account for which we want the password.
  * @param password The password to save.
+ *
+ * @deprecated This is here only for compatibility reasons. Keyrings are not
+ * expected to support this, and you should use
+ * purple_keyring_set_password_async() instead.
  */
 void 
 purple_keyring_set_password_sync(PurpleAccount * account,
 				 const char *password);
+#endif
 
 /**
  * Close a safe.