annotate doc/account-signals.dox @ 10789:0caa9827edf5

[gaim-migrate @ 12431] " The following log snippets should explain it: " --rlaager (20:24:00) rlaager: Regarding the signal handling conversation the other day... I've written a patch to stop calling signal handlers and return as soon as we find one signal handler that returns TRUE to indicate that it's handled the signal. Is this the right approach? (20:24:22) Ethan Blanton (Paco-Paco): the trouble is that it's documented to behave exactly the way it does (20:24:31) Ethan Blanton (Paco-Paco): so changing it is notbackwards compatible (20:24:31) rlaager: I'm talking for HEAD. (20:24:41) Ethan Blanton (Paco-Paco): oh, I think that's a good approach, yes (20:24:53) rlaager: The way I've described is how I *expected* it to work, having not read the documentation. (20:25:09) Ethan Blanton (Paco-Paco): I'm convinced (20:27:04) Stu Tomlinson (nosnilmot): rlaager: this, I assume, breaks the generic-ness of signals, by assuming that any that return values return booleans? (20:27:26) Ethan Blanton (Paco-Paco): please break it (20:27:33) Ethan Blanton (Paco-Paco): we already have out-parameters (20:27:42) rlaager: nosnilmot: from what I can see, the return type is handled as a (void *)... so I'm checking that ret_value != NULL (20:27:57) rlaager: nosnilmot: that's the correct way to do it, right? ... (20:29:01) Ethan Blanton (Paco-Paco): allowing a meaningful return value is an over-engineering (20:30:07) rlaager: even after this patch, you should be able to return meaningful return values (20:30:15) rlaager: it'll just short-circuit on the first handler that does committer: Tailor Script <[e-mail]>

/** @page account-signals Account Signals

 @signals
  @signal account-away
  @signal account-connecting
  @signal account-setting-info
  @signal account-set-info
  @signal account-warned
 @endsignals

 <hr>

 @signaldef account-away
  @signalproto
void (*account_away)(GaimAccount *account, const char *state, const char *message);
  @endsignalproto
  @signaldesc
   Emitted when an account goes away.
  @param account The account that went away.
  @param state   The away state.
  @param message The away message.
 @endsignaldef

 @signaldef account-connecting
  @signalproto
void (*account_connecting)(GaimAccount *account);
  @endsignalproto
  @signaldesc
   This is called when an account is in the process of connecting.
  @param account The account in the process of connecting.
 @endsignaldef

 @signaldef account-setting-info
  @signalproto
void (*account_setting_info)(GaimAccount *account, const char *new_info);
  @endsignalproto
  @signaldesc
   Emitted when a user is about to send his new user info, or
   profile, to the server.
  @param account  The account that the info will be set on.
  @param new_info The new information to set.
 @endsignaldef

 @signaldef account-set-info
  @signalproto
void (*account_set_info)(GaimAccount *account, const char *new_info);
  @endsignalproto
  @signaldesc
   Emitted when a user sent his new user info, or profile, to the server.
  @param account  The account that the info was set on.
  @param new_info The new information set.
 @endsignaldef

 @signaldef account-warned
  @signalproto
void (*account_warned)(GaimAccount *account, const char *warner, int level);
  @endsignalproto
  @signaldesc
   Emitted when an account got warned.
  @param account The account that was warned.
  @param warner  The screenname of the user that warned the account.
  @param level   The new warning level.
 @endsignaldef

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