# HG changeset patch
# User Will Thompson <will.thompson@collabora.co.uk>
# Date 1193780294 0
# Node ID 30a532b14003e85ba855c920b8110f790101f96a
# Parent  c1033e943d2a3b4c07ce13bc886b0c1a1ff3f1d1
Document exactly how long the PurpleConnectionErrorInfo pointers given out by
account-error-changed and purple_account_get_current_error() are valid.

diff -r c1033e943d2a -r 30a532b14003 doc/account-signals.dox
--- a/doc/account-signals.dox	Sun Oct 28 23:18:09 2007 +0000
+++ b/doc/account-signals.dox	Tue Oct 30 21:38:14 2007 +0000
@@ -150,8 +150,12 @@
    Emitted when @a account's error changes.
   @param account   The account whose error has changed.
   @param old_error The account's previous error, or @c NULL if it had no
-                   error.
+                   error.  After this signal is emitted, @a old_error is
+                   not guaranteed to be a valid pointer.
   @param new_error The account's new error, or @c NULL if it has no error.
+                   If not @c NULL, @a new_error will remain a valid until
+                   pointer just after the next time this signal is emitted
+                   for this @a account.
   @see purple_account_get_current_error()
   @since 2.3.0
  @endsignaldef
diff -r c1033e943d2a -r 30a532b14003 libpurple/account.c
--- a/libpurple/account.c	Sun Oct 28 23:18:09 2007 +0000
+++ b/libpurple/account.c	Tue Oct 30 21:38:14 2007 +0000
@@ -2309,6 +2309,10 @@
 
 	schedule_accounts_save();
 
+	/* Clearing the error ensures that account-error-changed is emitted,
+	 * which is the end of the guarantee that the the error's pointer is
+	 * valid.
+	 */
 	clear_current_error(account);
 	purple_signal_emit(purple_accounts_get_handle(), "account-removed", account);
 }
diff -r c1033e943d2a -r 30a532b14003 libpurple/account.h
--- a/libpurple/account.h	Sun Oct 28 23:18:09 2007 +0000
+++ b/libpurple/account.h	Tue Oct 30 21:38:14 2007 +0000
@@ -901,7 +901,9 @@
  *
  * @param account The account whose error should be retrieved.
  * @constreturn   The type of error and a human-readable description of the
- *                current error, or @c NULL if there is no current error.
+ *                current error, or @c NULL if there is no current error.  This
+ *                pointer is guaranteed to remain valid until the @ref
+ *                account-error-changed signal is emitted for @a account.
  */
 const PurpleConnectionErrorInfo *purple_account_get_current_error(PurpleAccount *account);