annotate doc/cipher-signals.dox @ 30288:a81d44a11d99

If SASL authentication fails, we generally shouldn't be setting an error message, as the actual error was communicated via the "urn:ietf:params:xml:ns:xmpp-sasl" failure stanza. Setting an error means that jabber_auth_handle_failure() won't ever call jabber_parse_error() to extract the actual error message and interpretation. For example, if authentication fails, previously we would show "SASL authentication failed" and think it was a PURPLE_CONNECTION_ERROR_NETWORK_ERROR which is incorrect. Now, jabber_parse_error() gets a chance to return "Not Authorized", clear the saved password, and return PURPLE_CONNECTION_ERROR_AUTHENTICATION_FAILED. We should still set this error message if there is an internal SASL failure leading to SASL_BADPARAM or SASL_NOMEM.

/** @page cipher-signals Cipher Signals

 @signals
  @signal cipher-added
  @signal cipher-removed
 @endsignals

 @see cipher.h

 <hr>

 @signaldef cipher-added
  @signalproto
void (*cipher_added)(PurpleCipher *cipher);
  @endsignalproto
  @signaldesc
   Emitted when a cipher is added.
  @param cipher The cipher that was added.
 @endsignaldef

 @signaldef cipher-removed
  @signalproto
void (*cipher_removed)(PurpleCipher *cipher);
  @endsignalproto
  @signaldesc
   Emitted when a cipher is removed.
  @param cipher The cipher that was removed.
 @endsignaldef

 */
// vim: syntax=c.doxygen tw=75 et