soc.2008.masterpassword: 57d2d227: Clean up comments.
qulogic at pidgin.im
qulogic at pidgin.im
Mon Nov 7 02:37:36 EST 2011
----------------------------------------------------------------------
Revision: 57d2d2278d44504089b042c2d9ec475854c0f24c
Parent: 12d8bc2b8e6870fab75ea22ee80cab75c57835a7
Author: qulogic at pidgin.im
Date: 11/05/11 22:50:16
Branch: im.pidgin.soc.2008.masterpassword
URL: http://d.pidgin.im/viewmtn/revision/info/57d2d2278d44504089b042c2d9ec475854c0f24c
Changelog:
Clean up comments.
Changes against parent 12d8bc2b8e6870fab75ea22ee80cab75c57835a7
patched libpurple/account.h
patched libpurple/connection.h
patched libpurple/keyring.h
-------------- next part --------------
============================================================
--- libpurple/account.h 866ee720dab2f4575e3a7588f3f5556d0bd87f23
+++ libpurple/account.h 13659374a3de100d3bd35d9961f605d415d55c72
@@ -346,14 +346,15 @@ void purple_account_set_username(PurpleA
void purple_account_set_username(PurpleAccount *account, const char *username);
/**
- * Set the account's password, and call the callback
+ * Sets the account's password.
*
- * The password in the keyring might not be immediatly updated, but the cache
+ * The password in the keyring might not be immediately updated, but the cached
* 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.
+ * the callback has been triggered. One can also set a NULL callback if
+ * notification of saving to the keyring is not required.
*
- * @param account The account for which the password is to be saved.
- * @param password The password to save.
+ * @param account The account.
+ * @param password The password.
* @param cb A callback for once the password is saved.
* @param data A pointer to be passed to the callback.
*/
@@ -668,8 +669,13 @@ const char *purple_account_get_username(
const char *purple_account_get_username(const PurpleAccount *account);
/**
- * Reads the password for the account and passes it to the callback
+ * Reads the password for the account.
*
+ * This is an asynchronous call, that will return the password in a callback
+ * once it has been read from the keyring. If the account is connected, and you
+ * require the password immediately, then consider using @ref
+ * purple_connection_get_password instead.
+ *
* @param account The account.
* @param cb The callback to give the password.
* @param data A pointer passed to the callback.
============================================================
--- libpurple/connection.h a5d28a20fb04250d6ce77de108424eece92e9c77
+++ libpurple/connection.h c1fc8b80f6744ce5cc1eb69dd29390a9b544704e
@@ -357,8 +357,7 @@ PurplePlugin * purple_connection_get_prp
PurplePlugin * purple_connection_get_prpl(const PurpleConnection *gc);
/**
- * Returns the connection's password. Deprecated, use
- * purple_connection_get_password_async() instead.
+ * Returns the connection's password.
*
* @param gc The connection.
*
============================================================
--- libpurple/keyring.h 118af85374128992a7aeb4cce45ee484fc574d27
+++ libpurple/keyring.h ea1a6f8bf75478a8371b2029a73bcc3c9fd80a98
@@ -23,7 +23,7 @@
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
- * along with this program ; if not, write to the Free Software
+ * along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
@@ -59,12 +59,13 @@ typedef struct _PurpleKeyring PurpleKeyr
/*@{*/
/**
- * Callback for once a password is read. If there was a problem, the password
- * should be NULL, and the error set.
+ * Callback for once a password is read.
*
- * @param account The account of which the password was asked.
- * @param password The password that was read.
- * @param error Error that could have occured.
+ * If there was a problem, the password will be NULL, and the error set.
+ *
+ * @param account The account.
+ * @param password The password.
+ * @param error Error that may have occurred.
* @param data Data passed to the callback.
*/
typedef void (*PurpleKeyringReadCallback)(PurpleAccount *account,
@@ -73,11 +74,12 @@ typedef void (*PurpleKeyringReadCallback
gpointer data);
/**
- * Callback for once a password has been stored. If there was a problem, the
- * error will be set.
+ * Callback for once a password has been stored.
*
- * @param error Error that could have occured.
- * @param account The account for which the password was saved.
+ * If there was a problem, the error will be set.
+ *
+ * @param account The account.
+ * @param error Error that may have occurred.
* @param data Data passed to the callback.
*/
typedef void (*PurpleKeyringSaveCallback)(PurpleAccount *account,
@@ -87,8 +89,8 @@ typedef void (*PurpleKeyringSaveCallback
/**
* Callback for once the master password for a keyring has been changed.
*
- * @param result Will be TRUE if the password has been changed, false otherwise.
- * @param error Error that has occured. Must be freed if non NULL.
+ * @param result TRUE if the password has been changed, FALSE otherwise.
+ * @param error Error that has occurred.
* @param data Data passed to the callback.
*/
typedef void (*PurpleKeyringChangeMasterCallback)(gboolean result,
@@ -100,7 +102,7 @@ typedef void (*PurpleKeyringChangeMaster
*
* @param keyring The keyring that is in use.
* @param result TRUE if the keyring was changed, FALSE otherwise.
- * @param error An error that might have occured.
+ * @param error An error that might have occurred.
* @param data A pointer to user supplied data.
*/
typedef void (*PurpleKeyringSetInUseCallback)(const PurpleKeyring *keyring,
@@ -118,8 +120,8 @@ typedef void (*PurpleKeyringSetInUseCall
/**
* Read the password for an account
*
- * @param account The account which's password we want.
- * @param cb A callback to be used once the password is found.
+ * @param account The account.
+ * @param cb A callback for once the password is found.
* @param data Data to be passed to the callback.
*/
typedef void (*PurpleKeyringRead)(PurpleAccount *account,
@@ -129,11 +131,11 @@ typedef void (*PurpleKeyringRead)(Purple
/**
* Store a password in the keyring.
*
- * @param account The account for which the password is to be stored.
+ * @param account The account.
* @param password The password to be stored. If the password is NULL, this
* means that the keyring should forget about that password.
- * @param cb A callback to be called once the password is saved.
- * @param data A pointer to be passed to the callback
+ * @param cb A callback for once the password is saved.
+ * @param data Data to be passed to the callback.
*/
typedef void (*PurpleKeyringSave)(PurpleAccount *account,
const gchar *password,
@@ -142,6 +144,7 @@ typedef void (*PurpleKeyringSave)(Purple
/**
* Close the keyring.
+ *
* This will be called so the keyring can do any cleanup it wants.
*
* @param error An error that may occur.
@@ -149,18 +152,17 @@ typedef void (*PurpleKeyringClose)(GErro
typedef void (*PurpleKeyringClose)(GError **error);
/**
- * Change the master password for the keyring. If NULL, it means the Keyring
- * has no master password capabilities.
+ * Change the master password for the keyring.
*
- * @param error An error that may occur.
- * @param cb A callback to call once the master password has been changed.
- * @param data A pointer to pass to the callback.
+ * @param cb A callback for once the master password has been changed.
+ * @param data Data to be passed to the callback.
*/
typedef void (*PurpleKeyringChangeMaster)(PurpleKeyringChangeMasterCallback cb,
gpointer data);
/**
* Import info on an XML node.
+ *
* This is not async because it is not meant to prompt for a master password and
* decrypt passwords.
*
@@ -177,10 +179,11 @@ typedef gboolean (*PurpleKeyringImportPa
/**
* Export information that will be stored in an XML node.
+ *
* This is not async because it is not meant to prompt for a master password or
* encrypt passwords.
*
- * @param account The account for which we want the info.
+ * @param account The account.
* @param mode An option field that can be used by the plugin. This is
* expected to be a static string.
* @param data The data to be stored in the XML node. This string will be
@@ -196,7 +199,6 @@ typedef gboolean (*PurpleKeyringExportPa
GError **error,
GDestroyNotify *destroy);
-
/*@}*/
#ifdef __cplusplus
@@ -253,11 +255,10 @@ purple_keyring_get_inuse(void);
* remove all passwords from the old safe and close that safe.
*
* @param newkeyring The new keyring to use.
- * @param error Error that may occur.
- * @param cb The callback to call once the change is done.
- * @param data A pointer that will be passed to the callback.
* @param force FALSE if the change can be cancelled. If this is TRUE and
* an error occurs, data might be lost.
+ * @param cb A callback for once the change is complete.
+ * @param data Data to be passed to the callback.
*/
void
purple_keyring_set_inuse(const PurpleKeyring *newkeyring,
@@ -274,10 +275,11 @@ purple_keyring_register(PurpleKeyring *k
purple_keyring_register(PurpleKeyring *keyring);
/**
- * Unregister a keyring plugin. In case the keyring is in use,
- * passwords will be moved to a fallback safe, and the keyring
- * to unregister will be properly closed.
+ * Unregister a keyring plugin.
*
+ * In case the keyring is in use, passwords will be moved to a fallback safe,
+ * and the keyring to unregister will be properly closed.
+ *
* @param keyring The keyring to unregister.
*/
void
@@ -285,7 +287,6 @@ purple_keyring_unregister(PurpleKeyring
/*@}*/
-
/***************************************/
/** @name Keyring plugin wrappers */
/***************************************/
@@ -334,9 +335,9 @@ purple_keyring_export_password(PurpleAcc
/**
* Read a password from the active safe.
*
- * @param account The account for which we want the password.
- * @param cb The callback to be called.
- * @param data A pointer passed to the callback.
+ * @param account The account.
+ * @param cb A callback for once the password is read.
+ * @param data Data passed to the callback.
*/
void
purple_keyring_get_password(PurpleAccount *account,
@@ -346,10 +347,10 @@ purple_keyring_get_password(PurpleAccoun
/**
* Set a password to be remembered.
*
- * @param account The account for which the password is to be saved.
+ * @param account The account.
* @param password The password to save.
* @param cb A callback for once the password is saved.
- * @param data A pointer to be passed to the callback.
+ * @param data Data to be passed to the callback.
*/
void
purple_keyring_set_password(PurpleAccount *account,
@@ -369,8 +370,8 @@ purple_keyring_close(PurpleKeyring *keyr
/**
* Change the master password for a safe (if the safe supports it).
*
- * @param cb A callback to notify once we're done.
- * @param data A pointer to be passed to the callback.
+ * @param cb A callback for once the master password has been changed.
+ * @param data Data to be passed to the callback.
*/
void
purple_keyring_change_master(PurpleKeyringChangeMasterCallback cb,
@@ -422,21 +423,23 @@ enum PurpleKeyringError
/** error codes for keyrings. */
enum PurpleKeyringError
{
- ERR_OK = 0, /**< no error. */
- ERR_NOPASSWD = 1, /**< no stored password. */
- ERR_NOACCOUNT, /**< account not found. */
- ERR_WRONGPASS, /**< user submitted wrong password when prompted. */
- ERR_WRONGFORMAT, /**< data passed is not in suitable format. */
- ERR_NOKEYRING, /**< no keyring configured. */
- ERR_NOCHANNEL, /**< failed to communicate with the backend */
- ERR_INVALID, /**< invalid input */
- ERR_NOCAP, /**< keyring doesn't support this */
- ERR_UNKNOWN /**< unknown error */
+ ERR_OK = 0, /**< No error. */
+ ERR_NOPASSWD = 1, /**< No stored password. */
+ ERR_NOACCOUNT, /**< Account not found. */
+ ERR_WRONGPASS, /**< User submitted wrong password when prompted. */
+ ERR_WRONGFORMAT, /**< Data passed is not in suitable format. */
+ ERR_NOKEYRING, /**< No keyring configured. */
+ ERR_NOCHANNEL, /**< Failed to communicate with the backend */
+ ERR_INVALID, /**< Invalid input */
+ ERR_NOCAP, /**< Keyring doesn't support this */
+ ERR_UNKNOWN /**< Unknown error */
};
+/*}@*/
+
#ifdef __cplusplus
}
#endif
-/*}@*/
+
#endif /* _PURPLE_KEYRING_H_ */
More information about the Commits
mailing list