doc/reference/libpurple/signals_account.xml

   1 <?xml version='1.0' encoding="ISO-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
   4 ]>
   5 <chapter id="chapter-signals-account">
   6 <title>Account signals</title>
   7
   8 <refsect1 id="accounts.signals" role="signal_proto">
   9 <title role="signal_proto.title">List of signals</title>
  10 <synopsis>
  11   &quot;<link linkend="accounts-account-created">account-created</link>&quot;
  12   &quot;<link linkend="accounts-account-destroying">account-destroying</link>&quot;
  13   &quot;<link linkend="accounts-account-added">account-added</link>&quot;
  14   &quot;<link linkend="accounts-account-connecting">account-connecting</link>&quot;
  15   &quot;<link linkend="accounts-account-removed">account-removed</link>&quot;
  16   &quot;<link linkend="accounts-account-disabled">account-disabled</link>&quot;
  17   &quot;<link linkend="accounts-account-enabled">account-enabled</link>&quot;
  18   &quot;<link linkend="accounts-account-setting-info">account-setting-info</link>&quot;
  19   &quot;<link linkend="accounts-account-set-info">account-set-info</link>&quot;
  20   &quot;<link linkend="accounts-account-status-changed">account-status-changed</link>&quot;
  21   &quot;<link linkend="accounts-account-actions-changed">account-actions-changed</link>&quot;
  22   &quot;<link linkend="accounts-account-alias-changed">account-alias-changed</link>&quot;
  23   &quot;<link linkend="accounts-account-authorization-requested">account-authorization-requested</link>&quot;
  24   &quot;<link linkend="accounts-account-authorization-denied">account-authorization-denied</link>&quot;
  25   &quot;<link linkend="accounts-account-authorization-granted">account-authorization-granted</link>&quot;
  26   &quot;<link linkend="accounts-account-error-changed">account-error-changed</link>&quot;
  27   &quot;<link linkend="accounts-account-signed-on">account-signed-on</link>&quot;
  28   &quot;<link linkend="accounts-account-signed-off">account-signed-off</link>&quot;
  29   &quot;<link linkend="accounts-account-connection-error">account-connection-error</link>&quot;
  30 </synopsis>
  31 </refsect1>
  32
  33 <refsect1 id="accounts.signal-details" role="signals">
  34 <title role="signals.title">Signal details</title>
  35
  36 <refsect2 id="accounts-account-created" role="signal">
  37  <title>The <literal>&quot;account-created&quot;</literal> signal</title>
  38 <programlisting>
  39 void                user_function                      (PurpleAccount *account,
  40                                                         gpointer user_data)
  41 </programlisting>
  42   <para>
  43 Emitted when an account is created by calling purple_account_new.
  44   </para>
  45   <variablelist role="params">
  46   <varlistentry>
  47     <term><parameter>account</parameter>&#160;:</term>
  48     <listitem><simpara>The account.</simpara></listitem>
  49   </varlistentry>
  50   <varlistentry>
  51     <term><parameter>user_data</parameter>&#160;:</term>
  52     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  53   </varlistentry>
  54   </variablelist>
  55 </refsect2>
  56
  57 <refsect2 id="accounts-account-destroying" role="signal">
  58  <title>The <literal>&quot;account-destroying&quot;</literal> signal</title>
  59 <programlisting>
  60 void                user_function                      (PurpleAccount *account,
  61                                                         gpointer user_data)
  62 </programlisting>
  63   <para>
  64 Emitted when an account is about to be destroyed.
  65   </para>
  66   <variablelist role="params">
  67   <varlistentry>
  68     <term><parameter>account</parameter>&#160;:</term>
  69     <listitem><simpara>The account.</simpara></listitem>
  70   </varlistentry>
  71   <varlistentry>
  72     <term><parameter>user_data</parameter>&#160;:</term>
  73     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  74   </varlistentry>
  75   </variablelist>
  76 </refsect2>
  77
  78 <refsect2 id="accounts-account-added" role="signal">
  79  <title>The <literal>&quot;account-added&quot;</literal> signal</title>
  80 <programlisting>
  81 void                user_function                      (PurpleAccount *account,
  82                                                         gpointer user_data)
  83 </programlisting>
  84   <para>
  85 Emitted when an account is added.
  86   </para>
  87   <variablelist role="params">
  88   <varlistentry>
  89     <term><parameter>account</parameter>&#160;:</term>
  90     <listitem><simpara>The account that was added. See <literal>purple_accounts_add</literal>.</simpara></listitem>
  91   </varlistentry>
  92   <varlistentry>
  93     <term><parameter>user_data</parameter>&#160;:</term>
  94     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  95   </varlistentry>
  96   </variablelist>
  97 </refsect2>
  98
  99 <refsect2 id="accounts-account-connecting" role="signal">
 100  <title>The <literal>&quot;account-connecting&quot;</literal> signal</title>
 101 <programlisting>
 102 void                user_function                      (PurpleAccount *account,
 103                                                         gpointer user_data)
 104 </programlisting>
 105   <para>
 106 This is called when an account is in the process of connecting.
 107   </para>
 108   <variablelist role="params">
 109   <varlistentry>
 110     <term><parameter>account</parameter>&#160;:</term>
 111     <listitem><simpara>The account in the process of connecting.</simpara></listitem>
 112   </varlistentry>
 113   <varlistentry>
 114     <term><parameter>user_data</parameter>&#160;:</term>
 115     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 116   </varlistentry>
 117   </variablelist>
 118 </refsect2>
 119
 120 <refsect2 id="accounts-account-removed" role="signal">
 121  <title>The <literal>&quot;account-removed&quot;</literal> signal</title>
 122 <programlisting>
 123 void                user_function                      (PurpleAccount *account,
 124                                                         gpointer user_data)
 125 </programlisting>
 126   <para>
 127 Emitted when an account is removed.
 128   </para>
 129   <variablelist role="params">
 130   <varlistentry>
 131     <term><parameter>account</parameter>&#160;:</term>
 132     <listitem><simpara>The account that was removed. See <literal>purple_accounts_remove</literal>.</simpara></listitem>
 133   </varlistentry>
 134   <varlistentry>
 135     <term><parameter>user_data</parameter>&#160;:</term>
 136     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 137   </varlistentry>
 138   </variablelist>
 139 </refsect2>
 140
 141 <refsect2 id="accounts-account-disabled" role="signal">
 142  <title>The <literal>&quot;account-disabled&quot;</literal> signal</title>
 143 <programlisting>
 144 void                user_function                      (PurpleAccount *account,
 145                                                         gpointer user_data)
 146 </programlisting>
 147   <para>
 148 Emitted when an account is disabled.
 149   </para>
 150   <variablelist role="params">
 151   <varlistentry>
 152     <term><parameter>account</parameter>&#160;:</term>
 153     <listitem><simpara>The account that was disabled.</simpara></listitem>
 154   </varlistentry>
 155   <varlistentry>
 156     <term><parameter>user_data</parameter>&#160;:</term>
 157     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 158   </varlistentry>
 159   </variablelist>
 160 </refsect2>
 161
 162 <refsect2 id="accounts-account-enabled" role="signal">
 163  <title>The <literal>&quot;account-enabled&quot;</literal> signal</title>
 164 <programlisting>
 165 void                user_function                      (PurpleAccount *account,
 166                                                         gpointer user_data)
 167 </programlisting>
 168   <para>
 169 Emitted when an account is enabled.
 170   </para>
 171   <variablelist role="params">
 172   <varlistentry>
 173     <term><parameter>account</parameter>&#160;:</term>
 174     <listitem><simpara>The account that was enabled.</simpara></listitem>
 175   </varlistentry>
 176   <varlistentry>
 177     <term><parameter>user_data</parameter>&#160;:</term>
 178     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 179   </varlistentry>
 180   </variablelist>
 181 </refsect2>
 182
 183 <refsect2 id="accounts-account-setting-info" role="signal">
 184  <title>The <literal>&quot;account-setting-info&quot;</literal> signal</title>
 185 <programlisting>
 186 void                user_function                      (PurpleAccount *account,
 187                                                         const char *new_info,
 188                                                         gpointer user_data)
 189 </programlisting>
 190   <para>
 191 Emitted when a user is about to send his new user info, or profile, to the server.
 192   </para>
 193   <variablelist role="params">
 194   <varlistentry>
 195     <term><parameter>account</parameter>&#160;:</term>
 196     <listitem><simpara>The account that the info will be set on.</simpara></listitem>
 197   </varlistentry>
 198   <varlistentry>
 199     <term><parameter>new_info</parameter>&#160;:</term>
 200     <listitem><simpara>The new information to set.</simpara></listitem>
 201   </varlistentry>
 202   <varlistentry>
 203     <term><parameter>user_data</parameter>&#160;:</term>
 204     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 205   </varlistentry>
 206   </variablelist>
 207 </refsect2>
 208
 209 <refsect2 id="accounts-account-set-info" role="signal">
 210  <title>The <literal>&quot;account-set-info&quot;</literal> signal</title>
 211 <programlisting>
 212 void                user_function                      (PurpleAccount *account,
 213                                                         const char *new_info,
 214                                                         gpointer user_data)
 215 </programlisting>
 216   <para>
 217 Emitted when a user sent his new user info, or profile, to the server.
 218   </para>
 219   <variablelist role="params">
 220   <varlistentry>
 221     <term><parameter>account</parameter>&#160;:</term>
 222     <listitem><simpara>The account that the info was set on.</simpara></listitem>
 223   </varlistentry>
 224   <varlistentry>
 225     <term><parameter>new_info</parameter>&#160;:</term>
 226     <listitem><simpara>The new information set.</simpara></listitem>
 227   </varlistentry>
 228   <varlistentry>
 229     <term><parameter>user_data</parameter>&#160;:</term>
 230     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 231   </varlistentry>
 232   </variablelist>
 233 </refsect2>
 234
 235 <refsect2 id="accounts-account-status-changed" role="signal">
 236  <title>The <literal>&quot;account-status-changed&quot;</literal> signal</title>
 237 <programlisting>
 238 void                user_function                      (PurpleAccount *account,
 239                                                         PurpleStatus *old,
 240                                                         PurpleStatus *new,
 241                                                         gpointer user_data)
 242 </programlisting>
 243   <para>
 244 Emitted when the status of an account changes (after the change).
 245   </para>
 246   <variablelist role="params">
 247   <varlistentry>
 248     <term><parameter>account</parameter>&#160;:</term>
 249     <listitem><simpara>The account that changed status.</simpara></listitem>
 250   </varlistentry>
 251   <varlistentry>
 252     <term><parameter>old</parameter>&#160;:</term>
 253     <listitem><simpara>The status before change.</simpara></listitem>
 254   </varlistentry>
 255   <varlistentry>
 256     <term><parameter>new</parameter>&#160;:</term>
 257     <listitem><simpara>The status after change.</simpara></listitem>
 258   </varlistentry>
 259   <varlistentry>
 260     <term><parameter>user_data</parameter>&#160;:</term>
 261     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 262   </varlistentry>
 263   </variablelist>
 264 </refsect2>
 265
 266 <refsect2 id="accounts-account-actions-changed" role="signal">
 267  <title>The <literal>&quot;account-actions-changed&quot;</literal> signal</title>
 268 <programlisting>
 269 void                user_function                      (PurpleAccount *account,
 270                                                         gpointer user_data)
 271 </programlisting>
 272   <para>
 273 Emitted when the account actions are changed after initial connection.
 274   </para>
 275   <variablelist role="params">
 276   <varlistentry>
 277     <term><parameter>account</parameter>&#160;:</term>
 278     <listitem><simpara>The account whose actions changed.</simpara></listitem>
 279   </varlistentry>
 280   <varlistentry>
 281     <term><parameter>user_data</parameter>&#160;:</term>
 282     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 283   </varlistentry>
 284   </variablelist>
 285 </refsect2>
 286
 287 <refsect2 id="accounts-account-alias-changed" role="signal">
 288  <title>The <literal>&quot;account-alias-changed&quot;</literal> signal</title>
 289 <programlisting>
 290 void                user_function                      (PurpleAccount *account,
 291                                                         const char *old,
 292                                                         gpointer user_data)
 293 </programlisting>
 294   <para>
 295 Emitted when the alias of an account changes (after the change).
 296   </para>
 297   <variablelist role="params">
 298   <varlistentry>
 299     <term><parameter>account</parameter>&#160;:</term>
 300     <listitem><simpara>The account for which the alias was changed.</simpara></listitem>
 301   </varlistentry>
 302   <varlistentry>
 303     <term><parameter>old</parameter>&#160;:</term>
 304     <listitem><simpara>The alias before change.</simpara></listitem>
 305   </varlistentry>
 306   <varlistentry>
 307     <term><parameter>user_data</parameter>&#160;:</term>
 308     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 309   </varlistentry>
 310   </variablelist>
 311 </refsect2>
 312
 313 <refsect2 id="accounts-account-authorization-requested" role="signal">
 314  <title>The <literal>&quot;account-authorization-requested&quot;</literal> signal</title>
 315 <programlisting>
 316 int                 user_function                      (PurpleAccount *account,
 317                                                         const char *user,
 318                                                         const char *message,
 319                                                         char **response,
 320                                                         gpointer user_data)
 321 </programlisting>
 322   <para>
 323 Emitted when a user requests authorization.
 324   </para>
 325   <variablelist role="params">
 326   <varlistentry>
 327     <term><parameter>account</parameter>&#160;:</term>
 328     <listitem><simpara>The account.</simpara></listitem>
 329   </varlistentry>
 330   <varlistentry>
 331     <term><parameter>user</parameter>&#160;:</term>
 332     <listitem><simpara>The name of the user requesting authorization.</simpara></listitem>
 333   </varlistentry>
 334   <varlistentry>
 335     <term><parameter>message</parameter>&#160;:</term>
 336     <listitem><simpara>The authorization request message.</simpara></listitem>
 337   </varlistentry>
 338   <varlistentry>
 339     <term><parameter>response</parameter>&#160;:</term>
 340     <listitem><simpara>The message to send in the response.</simpara></listitem>
 341   </varlistentry>
 342   <varlistentry>
 343     <term><parameter>user_data</parameter>&#160;:</term>
 344     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 345   </varlistentry>
 346   <varlistentry>
 347     <term><emphasis>Returns</emphasis>&#160;:</term>
 348     <listitem><simpara>PURPLE_ACCOUNT_RESPONSE_IGNORE to silently ignore the request, PURPLE_ACCOUNT_RESPONSE_DENY to block the request (the sender might get informed), PURPLE_ACCOUNT_RESPONSE_ACCEPT if the request should be granted. If PURPLE_ACCOUNT_RESPONSE_PASS is returned, then the user will be prompted with the request.</simpara></listitem>
 349   </varlistentry>
 350   </variablelist>
 351 </refsect2>
 352
 353 <refsect2 id="accounts-account-authorization-denied" role="signal">
 354  <title>The <literal>&quot;account-authorization-denied&quot;</literal> signal</title>
 355 <programlisting>
 356 void                user_function                      (PurpleAccount *account,
 357                                                         const char *user,
 358                                                         const char *message,
 359                                                         gpointer user_data)
 360 </programlisting>
 361   <para>
 362 Emitted when the authorization request for a buddy is denied.
 363   </para>
 364   <variablelist role="params">
 365   <varlistentry>
 366     <term><parameter>account</parameter>&#160;:</term>
 367     <listitem><simpara>The account.</simpara></listitem>
 368   </varlistentry>
 369   <varlistentry>
 370     <term><parameter>user</parameter>&#160;:</term>
 371     <listitem><simpara>The name of the user requesting authorization.</simpara></listitem>
 372   </varlistentry>
 373   <varlistentry>
 374     <term><parameter>message</parameter>&#160;:</term>
 375     <listitem><simpara>The message to tell the buddy who was denied.</simpara></listitem>
 376   </varlistentry>
 377   <varlistentry>
 378     <term><parameter>user_data</parameter>&#160;:</term>
 379     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 380   </varlistentry>
 381   </variablelist>
 382 </refsect2>
 383
 384 <refsect2 id="accounts-account-authorization-granted" role="signal">
 385  <title>The <literal>&quot;account-authorization-granted&quot;</literal> signal</title>
 386 <programlisting>
 387 void                user_function                      (PurpleAccount *account,
 388                                                         const char *user,
 389                                                         const char *message,
 390                                                         gpointer user_data)
 391 </programlisting>
 392   <para>
 393 Emitted when the authorization request for a buddy is granted.
 394   </para>
 395   <variablelist role="params">
 396   <varlistentry>
 397     <term><parameter>account</parameter>&#160;:</term>
 398     <listitem><simpara>The account.</simpara></listitem>
 399   </varlistentry>
 400   <varlistentry>
 401     <term><parameter>user</parameter>&#160;:</term>
 402     <listitem><simpara>The name of the user requesting authorization.</simpara></listitem>
 403   </varlistentry>
 404   <varlistentry>
 405     <term><parameter>message</parameter>&#160;:</term>
 406     <listitem><simpara>The message to tell the buddy who was granted authorization.</simpara></listitem>
 407   </varlistentry>
 408   <varlistentry>
 409     <term><parameter>user_data</parameter>&#160;:</term>
 410     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 411   </varlistentry>
 412   </variablelist>
 413 </refsect2>
 414
 415 <refsect2 id="accounts-account-error-changed" role="signal">
 416  <title>The <literal>&quot;account-error-changed&quot;</literal> signal</title>
 417 <programlisting>
 418 void                user_function                      (PurpleAccount *account,
 419                                                         const PurpleConnectionErrorInfo *old_error,
 420                                                         const PurpleConnectionErrorInfo *current_error,
 421                                                         gpointer user_data)
 422 </programlisting>
 423   <para>
 424 Emitted when <literal>account</literal>'s error changes.  You should not call purple_account_clear_current_error() while this signal is being emitted.
 425   </para>
 426   <variablelist role="params">
 427   <varlistentry>
 428     <term><parameter>account</parameter>&#160;:</term>
 429     <listitem><simpara>The account whose error has changed.</simpara></listitem>
 430   </varlistentry>
 431   <varlistentry>
 432     <term><parameter>old_error</parameter>&#160;:</term>
 433     <listitem><simpara>The account's previous error, or <literal>NULL</literal> if it had no error.  After this signal is emitted, <literal>old_error</literal> is not guaranteed to be a valid pointer.</simpara></listitem>
 434   </varlistentry>
 435   <varlistentry>
 436     <term><parameter>new_error</parameter>&#160;:</term>
 437     <listitem><simpara>The account's new error, or <literal>NULL</literal> if it has no error. If not <literal>NULL</literal>, <literal>new_error</literal> will remain a valid until pointer just after the next time this signal is emitted for this <literal>account</literal>. See <literal>purple_account_get_current_error</literal>().</simpara></listitem>
 438   </varlistentry>
 439   <varlistentry>
 440     <term><parameter>user_data</parameter>&#160;:</term>
 441     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 442   </varlistentry>
 443   </variablelist>
 444 </refsect2>
 445
 446 <refsect2 id="accounts-account-signed-on" role="signal">
 447  <title>The <literal>&quot;account-signed-on&quot;</literal> signal</title>
 448 <programlisting>
 449 void                user_function                      (PurpleAccount *account,
 450                                                         gpointer user_data)
 451 </programlisting>
 452   <para>
 453 Emitted when an account has signed on.
 454   </para>
 455   <variablelist role="params">
 456   <varlistentry>
 457     <term><parameter>account</parameter>&#160;:</term>
 458     <listitem><simpara>The account that has signed on.</simpara></listitem>
 459   </varlistentry>
 460   <varlistentry>
 461     <term><parameter>user_data</parameter>&#160;:</term>
 462     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 463   </varlistentry>
 464   </variablelist>
 465 </refsect2>
 466
 467 <refsect2 id="accounts-account-signed-off" role="signal">
 468  <title>The <literal>&quot;account-signed-off&quot;</literal> signal</title>
 469 <programlisting>
 470 void                user_function                      (PurpleAccount *account,
 471                                                         gpointer user_data)
 472 </programlisting>
 473   <para>
 474 Emitted when an account has signed off.
 475   </para>
 476   <variablelist role="params">
 477   <varlistentry>
 478     <term><parameter>account</parameter>&#160;:</term>
 479     <listitem><simpara>The account that has signed off.</simpara></listitem>
 480   </varlistentry>
 481   <varlistentry>
 482     <term><parameter>user_data</parameter>&#160;:</term>
 483     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 484   </varlistentry>
 485   </variablelist>
 486 </refsect2>
 487
 488 <refsect2 id="accounts-account-connection-error" role="signal">
 489  <title>The <literal>&quot;account-connection-error&quot;</literal> signal</title>
 490 <programlisting>
 491 void                user_function                      (PurpleAccount *gc,
 492                                                         PurpleConnectionError err,
 493                                                         const gchar *desc,
 494                                                         gpointer user_data)
 495 </programlisting>
 496   <para>
 497 Emitted when a connection error occurs, before <literal>"signed"</literal>-off.
 498   </para>
 499   <variablelist role="params">
 500   <varlistentry>
 501     <term><parameter>account</parameter>&#160;:</term>
 502     <listitem><simpara>The account on which the error has occurred.</simpara></listitem>
 503   </varlistentry>
 504   <varlistentry>
 505     <term><parameter>err</parameter>&#160;:</term>
 506     <listitem><simpara>The error that occurred.</simpara></listitem>
 507   </varlistentry>
 508   <varlistentry>
 509     <term><parameter>desc</parameter>&#160;:</term>
 510     <listitem><simpara>A description of the error, giving more information.</simpara></listitem>
 511   </varlistentry>
 512   <varlistentry>
 513     <term><parameter>user_data</parameter>&#160;:</term>
 514     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 515   </varlistentry>
 516   </variablelist>
 517 </refsect2>
 518
 519 </refsect1>
 520
 521 </chapter>