doc/reference/libpurple/signals_conversation.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-conversation">
   6 <title>Conversation signals</title>
   7
   8 <refsect1 id="conversations.signals" role="signal_proto">
   9 <title role="signal_proto.title">List of signals</title>
  10 <synopsis>
  11   &quot;<link linkend="conversations-writing-im-msg">writing-im-msg</link>&quot;
  12   &quot;<link linkend="conversations-wrote-im-msg">wrote-im-msg</link>&quot;
  13   &quot;<link linkend="conversations-sending-im-msg">sending-im-msg</link>&quot;
  14   &quot;<link linkend="conversations-sent-im-msg">sent-im-msg</link>&quot;
  15   &quot;<link linkend="conversations-receiving-im-msg">receiving-im-msg</link>&quot;
  16   &quot;<link linkend="conversations-received-im-msg">received-im-msg</link>&quot;
  17   &quot;<link linkend="conversations-blocked-im-msg">blocked-im-msg</link>&quot;
  18   &quot;<link linkend="conversations-writing-chat-msg">writing-chat-msg</link>&quot;
  19   &quot;<link linkend="conversations-wrote-chat-msg">wrote-chat-msg</link>&quot;
  20   &quot;<link linkend="conversations-sending-chat-msg">sending-chat-msg</link>&quot;
  21   &quot;<link linkend="conversations-sent-chat-msg">sent-chat-msg</link>&quot;
  22   &quot;<link linkend="conversations-receiving-chat-msg">receiving-chat-msg</link>&quot;
  23   &quot;<link linkend="conversations-received-chat-msg">received-chat-msg</link>&quot;
  24   &quot;<link linkend="conversations-conversation-created">conversation-created</link>&quot;
  25   &quot;<link linkend="conversations-conversation-updated">conversation-updated</link>&quot;
  26   &quot;<link linkend="conversations-deleting-conversation">deleting-conversation</link>&quot;
  27   &quot;<link linkend="conversations-buddy-typing">buddy-typing</link>&quot;
  28   &quot;<link linkend="conversations-buddy-typing-stopped">buddy-typing-stopped</link>&quot;
  29   &quot;<link linkend="conversations-chat-user-joining">chat-user-joining</link>&quot;
  30   &quot;<link linkend="conversations-chat-user-joined">chat-user-joined</link>&quot;
  31   &quot;<link linkend="conversations-chat-user-flags">chat-user-flags</link>&quot;
  32   &quot;<link linkend="conversations-chat-user-leaving">chat-user-leaving</link>&quot;
  33   &quot;<link linkend="conversations-chat-user-left">chat-user-left</link>&quot;
  34   &quot;<link linkend="conversations-chat-inviting-user">chat-inviting-user</link>&quot;
  35   &quot;<link linkend="conversations-chat-invited-user">chat-invited-user</link>&quot;
  36   &quot;<link linkend="conversations-chat-invited">chat-invited</link>&quot;
  37   &quot;<link linkend="conversations-chat-invite-blocked">chat-invite-blocked</link>&quot;
  38   &quot;<link linkend="conversations-chat-joined">chat-joined</link>&quot;
  39   &quot;<link linkend="conversations-chat-join-failed">chat-join-failed</link>&quot;
  40   &quot;<link linkend="conversations-chat-left">chat-left</link>&quot;
  41   &quot;<link linkend="conversations-chat-topic-changed">chat-topic-changed</link>&quot;
  42   &quot;<link linkend="conversations-cleared-message-history">cleared-message-history</link>&quot;
  43   &quot;<link linkend="conversations-conversation-extended-menu">conversation-extended-menu</link>&quot;
  44   &quot;<link linkend="conversations-sent-attention">sent-attention</link>&quot;
  45   &quot;<link linkend="conversations-got-attention">got-attention</link>&quot;
  46 </synopsis>
  47 </refsect1>
  48
  49 <refsect1 id="conversations.signal-details" role="signals">
  50 <title role="signals.title">Signal details</title>
  51
  52 <refsect2 id="conversations-writing-im-msg" role="signal">
  53  <title>The <literal>&quot;writing-im-msg&quot;</literal> signal</title>
  54 <programlisting>
  55 gboolean            user_function                      (PurpleAccount *account,
  56                                                         const char *who,
  57                                                         char **message,
  58                                                         PurpleIMConversation *im,
  59                                                         PurpleMessageFlags flags,
  60                                                         gpointer user_data)
  61 </programlisting>
  62   <para>
  63 Emitted before a message is written in an IM conversation. If the message is changed, then the changed message is displayed and logged instead of the original message.
  64   </para>
  65   <note><para>
  66 Make sure to free <literal>*message</literal> before you replace it!
  67   </para></note>
  68   <variablelist role="params">
  69   <varlistentry>
  70     <term><parameter>account</parameter>&#160;:</term>
  71     <listitem><simpara>The account.</simpara></listitem>
  72   </varlistentry>
  73   <varlistentry>
  74     <term><parameter>who</parameter>&#160;:</term>
  75     <listitem><simpara>The name of the user.</simpara></listitem>
  76   </varlistentry>
  77   <varlistentry>
  78     <term><parameter>message</parameter>&#160;:</term>
  79     <listitem><simpara>A pointer to the message.</simpara></listitem>
  80   </varlistentry>
  81   <varlistentry>
  82     <term><parameter>im</parameter>&#160;:</term>
  83     <listitem><simpara>The IM conversation.</simpara></listitem>
  84   </varlistentry>
  85   <varlistentry>
  86     <term><parameter>flags</parameter>&#160;:</term>
  87     <listitem><simpara>Flags for this message.</simpara></listitem>
  88   </varlistentry>
  89   <varlistentry>
  90     <term><parameter>user_data</parameter>&#160;:</term>
  91     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  92   </varlistentry>
  93   <varlistentry>
  94     <term><emphasis>Returns</emphasis>&#160;:</term>
  95     <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem>
  96   </varlistentry>
  97   </variablelist>
  98 </refsect2>
  99
 100 <refsect2 id="conversations-wrote-im-msg" role="signal">
 101  <title>The <literal>&quot;wrote-im-msg&quot;</literal> signal</title>
 102 <programlisting>
 103 void                user_function                      (PurpleAccount *account,
 104                                                         const char *who,
 105                                                         char *message,
 106                                                         PurpleIMConversation *im,
 107                                                         PurpleMessageFlags flags,
 108                                                         gpointer user_data)
 109 </programlisting>
 110   <para>
 111 Emitted after a message is written and possibly displayed in a conversation.
 112   </para>
 113   <variablelist role="params">
 114   <varlistentry>
 115     <term><parameter>account</parameter>&#160;:</term>
 116     <listitem><simpara>The account.</simpara></listitem>
 117   </varlistentry>
 118   <varlistentry>
 119     <term><parameter>who</parameter>&#160;:</term>
 120     <listitem><simpara>The name of the user.</simpara></listitem>
 121   </varlistentry>
 122   <varlistentry>
 123     <term><parameter>message</parameter>&#160;:</term>
 124     <listitem><simpara>The message.</simpara></listitem>
 125   </varlistentry>
 126   <varlistentry>
 127     <term><parameter>im</parameter>&#160;:</term>
 128     <listitem><simpara>The IM conversation.</simpara></listitem>
 129   </varlistentry>
 130   <varlistentry>
 131     <term><parameter>flags</parameter>&#160;:</term>
 132     <listitem><simpara>Flags for this message.</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="conversations-sending-im-msg" role="signal">
 142  <title>The <literal>&quot;sending-im-msg&quot;</literal> signal</title>
 143 <programlisting>
 144 void                user_function                      (PurpleAccount *account,
 145                                                         const char *receiver,
 146                                                         char **message,
 147                                                         gpointer user_data)
 148 </programlisting>
 149   <para>
 150 Emitted before sending an IM to a user. <literal>message</literal> is a pointer to the message string, so the plugin can replace the message before being sent.
 151   </para>
 152   <note><para>
 153 Make sure to free <literal>*message</literal> before you replace it!
 154   </para></note>
 155   <variablelist role="params">
 156   <varlistentry>
 157     <term><parameter>account</parameter>&#160;:</term>
 158     <listitem><simpara>The account the message is being sent on.</simpara></listitem>
 159   </varlistentry>
 160   <varlistentry>
 161     <term><parameter>receiver</parameter>&#160;:</term>
 162     <listitem><simpara>The username of the receiver.</simpara></listitem>
 163   </varlistentry>
 164   <varlistentry>
 165     <term><parameter>message</parameter>&#160;:</term>
 166     <listitem><simpara>A pointer to the outgoing message. This can be modified.</simpara></listitem>
 167   </varlistentry>
 168   <varlistentry>
 169     <term><parameter>user_data</parameter>&#160;:</term>
 170     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 171   </varlistentry>
 172   </variablelist>
 173 </refsect2>
 174
 175 <refsect2 id="conversations-sent-im-msg" role="signal">
 176  <title>The <literal>&quot;sent-im-msg&quot;</literal> signal</title>
 177 <programlisting>
 178 void                user_function                      (PurpleAccount *account,
 179                                                         const char *receiver,
 180                                                         const char *message,
 181                                                         gpointer user_data)
 182 </programlisting>
 183   <para>
 184 Emitted after sending an IM to a user.
 185   </para>
 186   <variablelist role="params">
 187   <varlistentry>
 188     <term><parameter>account</parameter>&#160;:</term>
 189     <listitem><simpara>The account the message was sent on.</simpara></listitem>
 190   </varlistentry>
 191   <varlistentry>
 192     <term><parameter>receiver</parameter>&#160;:</term>
 193     <listitem><simpara>The username of the receiver.</simpara></listitem>
 194   </varlistentry>
 195   <varlistentry>
 196     <term><parameter>message</parameter>&#160;:</term>
 197     <listitem><simpara>The message that was sent.</simpara></listitem>
 198   </varlistentry>
 199   <varlistentry>
 200     <term><parameter>user_data</parameter>&#160;:</term>
 201     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 202   </varlistentry>
 203   </variablelist>
 204 </refsect2>
 205
 206 <refsect2 id="conversations-receiving-im-msg" role="signal">
 207  <title>The <literal>&quot;receiving-im-msg&quot;</literal> signal</title>
 208 <programlisting>
 209 gboolean            user_function                      (PurpleAccount *account,
 210                                                         char **sender,
 211                                                         char **message,
 212                                                         PurpleIMConversation *im,
 213                                                         PurpleMessageFlags *flags,
 214                                                         gpointer user_data)
 215 </programlisting>
 216   <para>
 217 Emitted when an IM is received. The callback can replace the name of the sender, the message, or the flags by modifying the pointer to the strings and integer. This can also be used to cancel a message by returning <literal>TRUE</literal>.
 218   </para>
 219   <note><para>
 220 Make sure to free <literal>*sender</literal> and <literal>*message</literal> before you replace them!
 221   </para></note>
 222   <variablelist role="params">
 223   <varlistentry>
 224     <term><parameter>account</parameter>&#160;:</term>
 225     <listitem><simpara>The account the message was received on.</simpara></listitem>
 226   </varlistentry>
 227   <varlistentry>
 228     <term><parameter>sender</parameter>&#160;:</term>
 229     <listitem><simpara>A pointer to the username of the sender.</simpara></listitem>
 230   </varlistentry>
 231   <varlistentry>
 232     <term><parameter>message</parameter>&#160;:</term>
 233     <listitem><simpara>A pointer to the message that was sent.</simpara></listitem>
 234   </varlistentry>
 235   <varlistentry>
 236     <term><parameter>im</parameter>&#160;:</term>
 237     <listitem><simpara>The IM conversation.</simpara></listitem>
 238   </varlistentry>
 239   <varlistentry>
 240     <term><parameter>flags</parameter>&#160;:</term>
 241     <listitem><simpara>A pointer to the IM message flags.</simpara></listitem>
 242   </varlistentry>
 243   <varlistentry>
 244     <term><parameter>user_data</parameter>&#160;:</term>
 245     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 246   </varlistentry>
 247   <varlistentry>
 248     <term><emphasis>Returns</emphasis>&#160;:</term>
 249     <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem>
 250   </varlistentry>
 251   </variablelist>
 252 </refsect2>
 253
 254 <refsect2 id="conversations-received-im-msg" role="signal">
 255  <title>The <literal>&quot;received-im-msg&quot;</literal> signal</title>
 256 <programlisting>
 257 void                user_function                      (PurpleAccount *account,
 258                                                         char *sender,
 259                                                         char *message,
 260                                                         PurpleIMConversation *im,
 261                                                         PurpleMessageFlags flags,
 262                                                         gpointer user_data)
 263 </programlisting>
 264   <para>
 265 Emitted after an IM is received.
 266   </para>
 267   <variablelist role="params">
 268   <varlistentry>
 269     <term><parameter>account</parameter>&#160;:</term>
 270     <listitem><simpara>The account the message was received on.</simpara></listitem>
 271   </varlistentry>
 272   <varlistentry>
 273     <term><parameter>sender</parameter>&#160;:</term>
 274     <listitem><simpara>The username of the sender.</simpara></listitem>
 275   </varlistentry>
 276   <varlistentry>
 277     <term><parameter>message</parameter>&#160;:</term>
 278     <listitem><simpara>The message that was sent.</simpara></listitem>
 279   </varlistentry>
 280   <varlistentry>
 281     <term><parameter>im</parameter>&#160;:</term>
 282     <listitem><simpara>The IM conversation.</simpara></listitem>
 283   </varlistentry>
 284   <varlistentry>
 285     <term><parameter>flags</parameter>&#160;:</term>
 286     <listitem><simpara>The IM message flags.</simpara></listitem>
 287   </varlistentry>
 288   <varlistentry>
 289     <term><parameter>user_data</parameter>&#160;:</term>
 290     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 291   </varlistentry>
 292   </variablelist>
 293 </refsect2>
 294
 295 <refsect2 id="conversations-blocked-im-msg" role="signal">
 296  <title>The <literal>&quot;blocked-im-msg&quot;</literal> signal</title>
 297 <programlisting>
 298 void                user_function                      (PurpleAccount *account,
 299                                                         const char *sender,
 300                                                         const char *message,
 301                                                         PurpleMessageFlags flags,
 302                                                         time_t when,
 303                                                         gpointer user_data)
 304 </programlisting>
 305   <para>
 306 Emitted after an IM is blocked due to privacy settings.
 307   </para>
 308   <variablelist role="params">
 309   <varlistentry>
 310     <term><parameter>account</parameter>&#160;:</term>
 311     <listitem><simpara>The account the message was received on.</simpara></listitem>
 312   </varlistentry>
 313   <varlistentry>
 314     <term><parameter>sender</parameter>&#160;:</term>
 315     <listitem><simpara>The username of the sender.</simpara></listitem>
 316   </varlistentry>
 317   <varlistentry>
 318     <term><parameter>message</parameter>&#160;:</term>
 319     <listitem><simpara>The message that was blocked.</simpara></listitem>
 320   </varlistentry>
 321   <varlistentry>
 322     <term><parameter>flags</parameter>&#160;:</term>
 323     <listitem><simpara>The IM message flags.</simpara></listitem>
 324   </varlistentry>
 325   <varlistentry>
 326     <term><parameter>when</parameter>&#160;:</term>
 327     <listitem><simpara>The time the message was sent.</simpara></listitem>
 328   </varlistentry>
 329   <varlistentry>
 330     <term><parameter>user_data</parameter>&#160;:</term>
 331     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 332   </varlistentry>
 333   </variablelist>
 334 </refsect2>
 335
 336 <refsect2 id="conversations-writing-chat-msg" role="signal">
 337  <title>The <literal>&quot;writing-chat-msg&quot;</literal> signal</title>
 338 <programlisting>
 339 gboolean            user_function                      (PurpleAccount *account,
 340                                                         const char *who,
 341                                                         char **message,
 342                                                         PurpleChatConversation *chat,
 343                                                         PurpleMessageFlags flags,
 344                                                         gpointer user_data)
 345 </programlisting>
 346   <para>
 347 Emitted before a message is written in a chat conversation. If the message is changed, then the changed message is displayed and logged instead of the original message.
 348   </para>
 349   <note><para>
 350 Make sure to free <literal>*message</literal> before you replace it!
 351   </para></note>
 352   <variablelist role="params">
 353   <varlistentry>
 354     <term><parameter>account</parameter>&#160;:</term>
 355     <listitem><simpara>The account.</simpara></listitem>
 356   </varlistentry>
 357   <varlistentry>
 358     <term><parameter>who</parameter>&#160;:</term>
 359     <listitem><simpara>The name of the user.</simpara></listitem>
 360   </varlistentry>
 361   <varlistentry>
 362     <term><parameter>message</parameter>&#160;:</term>
 363     <listitem><simpara>A pointer to the message.</simpara></listitem>
 364   </varlistentry>
 365   <varlistentry>
 366     <term><parameter>chat</parameter>&#160;:</term>
 367     <listitem><simpara>The chat conversation.</simpara></listitem>
 368   </varlistentry>
 369   <varlistentry>
 370     <term><parameter>flags</parameter>&#160;:</term>
 371     <listitem><simpara>Flags for this message.</simpara></listitem>
 372   </varlistentry>
 373   <varlistentry>
 374     <term><parameter>user_data</parameter>&#160;:</term>
 375     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 376   </varlistentry>
 377   <varlistentry>
 378     <term><emphasis>Returns</emphasis>&#160;:</term>
 379     <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem>
 380   </varlistentry>
 381   </variablelist>
 382 </refsect2>
 383
 384 <refsect2 id="conversations-wrote-chat-msg" role="signal">
 385  <title>The <literal>&quot;wrote-chat-msg&quot;</literal> signal</title>
 386 <programlisting>
 387 void                user_function                      (PurpleAccount *account,
 388                                                         const char *who,
 389                                                         char *message,
 390                                                         PurpleChatConversation *chat,
 391                                                         PurpleMessageFlags flags,
 392                                                         gpointer user_data)
 393 </programlisting>
 394   <para>
 395 Emitted after a message is written and possibly displayed in a chat.
 396   </para>
 397   <variablelist role="params">
 398   <varlistentry>
 399     <term><parameter>account</parameter>&#160;:</term>
 400     <listitem><simpara>The account.</simpara></listitem>
 401   </varlistentry>
 402   <varlistentry>
 403     <term><parameter>who</parameter>&#160;:</term>
 404     <listitem><simpara>The name of the user.</simpara></listitem>
 405   </varlistentry>
 406   <varlistentry>
 407     <term><parameter>message</parameter>&#160;:</term>
 408     <listitem><simpara>The message.</simpara></listitem>
 409   </varlistentry>
 410   <varlistentry>
 411     <term><parameter>chat</parameter>&#160;:</term>
 412     <listitem><simpara>The chat conversation.</simpara></listitem>
 413   </varlistentry>
 414   <varlistentry>
 415     <term><parameter>flags</parameter>&#160;:</term>
 416     <listitem><simpara>Flags for this message.</simpara></listitem>
 417   </varlistentry>
 418   <varlistentry>
 419     <term><parameter>user_data</parameter>&#160;:</term>
 420     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 421   </varlistentry>
 422   </variablelist>
 423 </refsect2>
 424
 425 <refsect2 id="conversations-sending-chat-msg" role="signal">
 426  <title>The <literal>&quot;sending-chat-msg&quot;</literal> signal</title>
 427 <programlisting>
 428 void                user_function                      (PurpleAccount *account,
 429                                                         char **message,
 430                                                         int id,
 431                                                         gpointer user_data)
 432 </programlisting>
 433   <para>
 434 Emitted before sending a message to a chat. <literal>message</literal> is a pointer to the message string, so the plugin can replace the message before being sent.
 435   </para>
 436   <note><para>
 437 Make sure to free <literal>*message</literal> before you replace it!
 438   </para></note>
 439   <variablelist role="params">
 440   <varlistentry>
 441     <term><parameter>account</parameter>&#160;:</term>
 442     <listitem><simpara>The account the message is being sent on.</simpara></listitem>
 443   </varlistentry>
 444   <varlistentry>
 445     <term><parameter>message</parameter>&#160;:</term>
 446     <listitem><simpara>A pointer to the message that will be sent.</simpara></listitem>
 447   </varlistentry>
 448   <varlistentry>
 449     <term><parameter>id</parameter>&#160;:</term>
 450     <listitem><simpara>The ID of the chat.</simpara></listitem>
 451   </varlistentry>
 452   <varlistentry>
 453     <term><parameter>user_data</parameter>&#160;:</term>
 454     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 455   </varlistentry>
 456   </variablelist>
 457 </refsect2>
 458
 459 <refsect2 id="conversations-sent-chat-msg" role="signal">
 460  <title>The <literal>&quot;sent-chat-msg&quot;</literal> signal</title>
 461 <programlisting>
 462 void                user_function                      (PurpleAccount *account,
 463                                                         const char *message,
 464                                                         int id,
 465                                                         gpointer user_data)
 466 </programlisting>
 467   <para>
 468 Emitted after sending a message to a chat.
 469   </para>
 470   <variablelist role="params">
 471   <varlistentry>
 472     <term><parameter>account</parameter>&#160;:</term>
 473     <listitem><simpara>The account the message was sent on.</simpara></listitem>
 474   </varlistentry>
 475   <varlistentry>
 476     <term><parameter>message</parameter>&#160;:</term>
 477     <listitem><simpara>The message that was sent.</simpara></listitem>
 478   </varlistentry>
 479   <varlistentry>
 480     <term><parameter>id</parameter>&#160;:</term>
 481     <listitem><simpara>The ID of the chat.</simpara></listitem>
 482   </varlistentry>
 483   <varlistentry>
 484     <term><parameter>user_data</parameter>&#160;:</term>
 485     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 486   </varlistentry>
 487   </variablelist>
 488 </refsect2>
 489
 490 <refsect2 id="conversations-receiving-chat-msg" role="signal">
 491  <title>The <literal>&quot;receiving-chat-msg&quot;</literal> signal</title>
 492 <programlisting>
 493 gboolean            user_function                      (PurpleAccount *account,
 494                                                         char **sender,
 495                                                         char **message,
 496                                                         PurpleChatConversation *chat,
 497                                                         int *flags,
 498                                                         gpointer user_data)
 499 </programlisting>
 500   <para>
 501 Emitted when a chat message is received. The callback can replace the name of the sender, the message, or the flags by modifying the pointer to the strings. This can also be used to cancel displaying a message by returning <literal>TRUE</literal>.
 502   </para>
 503   <note><para>
 504 Make sure to free <literal>*sender</literal> and <literal>*message</literal> before you replace them!
 505   </para></note>
 506   <variablelist role="params">
 507   <varlistentry>
 508     <term><parameter>account</parameter>&#160;:</term>
 509     <listitem><simpara>The account the message was received on.</simpara></listitem>
 510   </varlistentry>
 511   <varlistentry>
 512     <term><parameter>sender</parameter>&#160;:</term>
 513     <listitem><simpara>A pointer to the username of the sender.</simpara></listitem>
 514   </varlistentry>
 515   <varlistentry>
 516     <term><parameter>message</parameter>&#160;:</term>
 517     <listitem><simpara>A pointer to the message that was sent.</simpara></listitem>
 518   </varlistentry>
 519   <varlistentry>
 520     <term><parameter>chat</parameter>&#160;:</term>
 521     <listitem><simpara>The chat conversation.</simpara></listitem>
 522   </varlistentry>
 523   <varlistentry>
 524     <term><parameter>flags</parameter>&#160;:</term>
 525     <listitem><simpara>A pointer to the chat message flags.</simpara></listitem>
 526   </varlistentry>
 527   <varlistentry>
 528     <term><parameter>user_data</parameter>&#160;:</term>
 529     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 530   </varlistentry>
 531   <varlistentry>
 532     <term><emphasis>Returns</emphasis>&#160;:</term>
 533     <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem>
 534   </varlistentry>
 535   </variablelist>
 536 </refsect2>
 537
 538 <refsect2 id="conversations-received-chat-msg" role="signal">
 539  <title>The <literal>&quot;received-chat-msg&quot;</literal> signal</title>
 540 <programlisting>
 541 void                user_function                      (PurpleAccount *account,
 542                                                         char *sender,
 543                                                         char *message,
 544                                                         PurpleChatConversation *chat,
 545                                                         PurpleMessageFlags flags,
 546                                                         gpointer user_data)
 547 </programlisting>
 548   <para>
 549 Emitted after a chat message is received.
 550   </para>
 551   <variablelist role="params">
 552   <varlistentry>
 553     <term><parameter>account</parameter>&#160;:</term>
 554     <listitem><simpara>The account the message was received on.</simpara></listitem>
 555   </varlistentry>
 556   <varlistentry>
 557     <term><parameter>sender</parameter>&#160;:</term>
 558     <listitem><simpara>The username of the sender.</simpara></listitem>
 559   </varlistentry>
 560   <varlistentry>
 561     <term><parameter>message</parameter>&#160;:</term>
 562     <listitem><simpara>The message that was sent.</simpara></listitem>
 563   </varlistentry>
 564   <varlistentry>
 565     <term><parameter>chat</parameter>&#160;:</term>
 566     <listitem><simpara>The chat conversation.</simpara></listitem>
 567   </varlistentry>
 568   <varlistentry>
 569     <term><parameter>flags</parameter>&#160;:</term>
 570     <listitem><simpara>The chat message flags.</simpara></listitem>
 571   </varlistentry>
 572   <varlistentry>
 573     <term><parameter>user_data</parameter>&#160;:</term>
 574     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 575   </varlistentry>
 576   </variablelist>
 577 </refsect2>
 578
 579 <refsect2 id="conversations-conversation-created" role="signal">
 580  <title>The <literal>&quot;conversation-created&quot;</literal> signal</title>
 581 <programlisting>
 582 void                user_function                      (PurpleConversation *conv,
 583                                                         gpointer user_data)
 584 </programlisting>
 585   <para>
 586 Emitted when a new conversation is created.
 587   </para>
 588   <variablelist role="params">
 589   <varlistentry>
 590     <term><parameter>conv</parameter>&#160;:</term>
 591     <listitem><simpara>The new conversation.</simpara></listitem>
 592   </varlistentry>
 593   <varlistentry>
 594     <term><parameter>user_data</parameter>&#160;:</term>
 595     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 596   </varlistentry>
 597   </variablelist>
 598 </refsect2>
 599
 600 <refsect2 id="conversations-conversation-updated" role="signal">
 601  <title>The <literal>&quot;conversation-updated&quot;</literal> signal</title>
 602 <programlisting>
 603 void                user_function                      (PurpleConversation *conv,
 604                                                         PurpleConvUpdateType type,
 605                                                         gpointer user_data)
 606 </programlisting>
 607   <para>
 608 Emitted when a conversation is updated.
 609   </para>
 610   <variablelist role="params">
 611   <varlistentry>
 612     <term><parameter>conv</parameter>&#160;:</term>
 613     <listitem><simpara>The conversation that was updated.</simpara></listitem>
 614   </varlistentry>
 615   <varlistentry>
 616     <term><parameter>type</parameter>&#160;:</term>
 617     <listitem><simpara>The type of update that was made.</simpara></listitem>
 618   </varlistentry>
 619   <varlistentry>
 620     <term><parameter>user_data</parameter>&#160;:</term>
 621     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 622   </varlistentry>
 623   </variablelist>
 624 </refsect2>
 625
 626 <refsect2 id="conversations-deleting-conversation" role="signal">
 627  <title>The <literal>&quot;deleting-conversation&quot;</literal> signal</title>
 628 <programlisting>
 629 void                user_function                      (PurpleConversation *conv,
 630                                                         gpointer user_data)
 631 </programlisting>
 632   <para>
 633 Emitted just before a conversation is to be destroyed.
 634   </para>
 635   <variablelist role="params">
 636   <varlistentry>
 637     <term><parameter>conv</parameter>&#160;:</term>
 638     <listitem><simpara>The conversation that's about to be destroyed.</simpara></listitem>
 639   </varlistentry>
 640   <varlistentry>
 641     <term><parameter>user_data</parameter>&#160;:</term>
 642     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 643   </varlistentry>
 644   </variablelist>
 645 </refsect2>
 646
 647 <refsect2 id="conversations-buddy-typing" role="signal">
 648  <title>The <literal>&quot;buddy-typing&quot;</literal> signal</title>
 649 <programlisting>
 650 void                user_function                      (PurpleAccount *account,
 651                                                         const char *name,
 652                                                         gpointer user_data)
 653 </programlisting>
 654   <para>
 655 Emitted when a buddy starts typing in a conversation window.
 656   </para>
 657   <variablelist role="params">
 658   <varlistentry>
 659     <term><parameter>account</parameter>&#160;:</term>
 660     <listitem><simpara>The account of the user which is typing.</simpara></listitem>
 661   </varlistentry>
 662   <varlistentry>
 663     <term><parameter>name</parameter>&#160;:</term>
 664     <listitem><simpara>The name of the user which is typing.</simpara></listitem>
 665   </varlistentry>
 666   <varlistentry>
 667     <term><parameter>user_data</parameter>&#160;:</term>
 668     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 669   </varlistentry>
 670   </variablelist>
 671 </refsect2>
 672
 673 <refsect2 id="conversations-buddy-typing-stopped" role="signal">
 674  <title>The <literal>&quot;buddy-typing-stopped&quot;</literal> signal</title>
 675 <programlisting>
 676 void                user_function                      (PurpleAccount *account,
 677                                                         const char *name,
 678                                                         gpointer user_data)
 679 </programlisting>
 680   <para>
 681 Emitted when a buddy stops typing in a conversation window.
 682   </para>
 683   <variablelist role="params">
 684   <varlistentry>
 685     <term><parameter>account</parameter>&#160;:</term>
 686     <listitem><simpara>The account of the user which stopped typing.</simpara></listitem>
 687   </varlistentry>
 688   <varlistentry>
 689     <term><parameter>name</parameter>&#160;:</term>
 690     <listitem><simpara>The name of the user which stopped typing.</simpara></listitem>
 691   </varlistentry>
 692   <varlistentry>
 693     <term><parameter>user_data</parameter>&#160;:</term>
 694     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 695   </varlistentry>
 696   </variablelist>
 697 </refsect2>
 698
 699 <refsect2 id="conversations-chat-user-joining" role="signal">
 700  <title>The <literal>&quot;chat-user-joining&quot;</literal> signal</title>
 701 <programlisting>
 702 gboolean            user_function                      (PurpleChatConversation *chat,
 703                                                         const char *name,
 704                                                         PurpleChatUserFlags flags,
 705                                                         gpointer user_data)
 706 </programlisting>
 707   <para>
 708 Emitted when a buddy is joining a chat, before the list of users in the chat updates to include the new user.
 709   </para>
 710   <variablelist role="params">
 711   <varlistentry>
 712     <term><parameter>chat</parameter>&#160;:</term>
 713     <listitem><simpara>The chat conversation.</simpara></listitem>
 714   </varlistentry>
 715   <varlistentry>
 716     <term><parameter>name</parameter>&#160;:</term>
 717     <listitem><simpara>The name of the user that is joining the conversation.</simpara></listitem>
 718   </varlistentry>
 719   <varlistentry>
 720     <term><parameter>flags</parameter>&#160;:</term>
 721     <listitem><simpara>The flags of the user that is joining the conversation.</simpara></listitem>
 722   </varlistentry>
 723   <varlistentry>
 724     <term><parameter>user_data</parameter>&#160;:</term>
 725     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 726   </varlistentry>
 727   <varlistentry>
 728     <term><emphasis>Returns</emphasis>&#160;:</term>
 729     <listitem><simpara><literal>TRUE</literal> if the join should be hidden, or <literal>FALSE</literal> otherwise.</simpara></listitem>
 730   </varlistentry>
 731   </variablelist>
 732 </refsect2>
 733
 734 <refsect2 id="conversations-chat-user-joined" role="signal">
 735  <title>The <literal>&quot;chat-user-joined&quot;</literal> signal</title>
 736 <programlisting>
 737 void                user_function                      (PurpleChatConversation *chat,
 738                                                         const char *name,
 739                                                         PurpleChatUserFlags flags,
 740                                                         gboolean new_arrival,
 741                                                         gpointer user_data)
 742 </programlisting>
 743   <para>
 744 Emitted when a buddy joined a chat, after the users list is updated.
 745   </para>
 746   <variablelist role="params">
 747   <varlistentry>
 748     <term><parameter>chat</parameter>&#160;:</term>
 749     <listitem><simpara>The chat conversation.</simpara></listitem>
 750   </varlistentry>
 751   <varlistentry>
 752     <term><parameter>name</parameter>&#160;:</term>
 753     <listitem><simpara>The name of the user that has joined the conversation.</simpara></listitem>
 754   </varlistentry>
 755   <varlistentry>
 756     <term><parameter>flags</parameter>&#160;:</term>
 757     <listitem><simpara>The flags of the user that has joined the conversation.</simpara></listitem>
 758   </varlistentry>
 759   <varlistentry>
 760     <term><parameter>new_arrival</parameter>&#160;:</term>
 761     <listitem><simpara>If the buddy is a new arrival.</simpara></listitem>
 762   </varlistentry>
 763   <varlistentry>
 764     <term><parameter>user_data</parameter>&#160;:</term>
 765     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 766   </varlistentry>
 767   </variablelist>
 768 </refsect2>
 769
 770 <refsect2 id="conversations-chat-join-failed" role="signal">
 771  <title>The <literal>&quot;chat-join-failed&quot;</literal> signal</title>
 772 <programlisting>
 773 void                user_function                      (PurpleConnection *gc,
 774                                                         GHashTable *components,
 775                                                         gpointer user_data)
 776 </programlisting>
 777   <para>
 778 Emitted when an account fails to join a chat room.
 779   </para>
 780   <variablelist role="params">
 781   <varlistentry>
 782     <term><parameter>gc</parameter>&#160;:</term>
 783     <listitem><simpara>The PurpleConnection of the account which failed to join the chat.</simpara></listitem>
 784   </varlistentry>
 785   <varlistentry>
 786     <term><parameter>data</parameter>&#160;:</term>
 787     <listitem><simpara>The components passed to purple_serv_join_chat() originally. The hash function should be g_str_hash() and the equal function should be g_str_equal().</simpara></listitem>
 788   </varlistentry>
 789   <varlistentry>
 790     <term><parameter>user_data</parameter>&#160;:</term>
 791     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 792   </varlistentry>
 793   </variablelist>
 794 </refsect2>
 795
 796 <refsect2 id="conversations-chat-user-flags" role="signal">
 797  <title>The <literal>&quot;chat-user-flags&quot;</literal> signal</title>
 798 <programlisting>
 799 void                user_function                      (PurpleChatUser *chatuser,
 800                                                         PurpleChatUserFlags oldflags,
 801                                                         PurpleChatUserFlags newflags,
 802                                                         gpointer user_data)
 803 </programlisting>
 804   <para>
 805 Emitted when a user in a chat changes flags.
 806   </para>
 807   <variablelist role="params">
 808   <varlistentry>
 809     <term><parameter>chatuser</parameter>&#160;:</term>
 810     <listitem><simpara>The chat user whose flags changed.</simpara></listitem>
 811   </varlistentry>
 812   <varlistentry>
 813     <term><parameter>oldflags</parameter>&#160;:</term>
 814     <listitem><simpara>The old flags.</simpara></listitem>
 815   </varlistentry>
 816   <varlistentry>
 817     <term><parameter>newflags</parameter>&#160;:</term>
 818     <listitem><simpara>The new flags.</simpara></listitem>
 819   </varlistentry>
 820   <varlistentry>
 821     <term><parameter>user_data</parameter>&#160;:</term>
 822     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 823   </varlistentry>
 824   </variablelist>
 825 </refsect2>
 826
 827 <refsect2 id="conversations-chat-user-leaving" role="signal">
 828  <title>The <literal>&quot;chat-user-leaving&quot;</literal> signal</title>
 829 <programlisting>
 830 gboolean            user_function                      (PurpleChatConversation *chat,
 831                                                         const char *name,
 832                                                         const char *reason,
 833                                                         gpointer user_data)
 834 </programlisting>
 835   <para>
 836 Emitted when a user is leaving a chat, before the user list is updated. This may include an optional reason why the user is leaving.
 837   </para>
 838   <variablelist role="params">
 839   <varlistentry>
 840     <term><parameter>chat</parameter>&#160;:</term>
 841     <listitem><simpara>The chat conversation.</simpara></listitem>
 842   </varlistentry>
 843   <varlistentry>
 844     <term><parameter>name</parameter>&#160;:</term>
 845     <listitem><simpara>The name of the user that is leaving the chat.</simpara></listitem>
 846   </varlistentry>
 847   <varlistentry>
 848     <term><parameter>reason</parameter>&#160;:</term>
 849     <listitem><simpara>The optional reason why the user is leaving.</simpara></listitem>
 850   </varlistentry>
 851   <varlistentry>
 852     <term><parameter>user_data</parameter>&#160;:</term>
 853     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 854   </varlistentry>
 855   <varlistentry>
 856     <term><emphasis>Returns</emphasis>&#160;:</term>
 857     <listitem><simpara><literal>TRUE</literal> if the leave should be hidden, or <literal>FALSE</literal> otherwise.</simpara></listitem>
 858   </varlistentry>
 859   </variablelist>
 860 </refsect2>
 861
 862 <refsect2 id="conversations-chat-user-left" role="signal">
 863  <title>The <literal>&quot;chat-user-left&quot;</literal> signal</title>
 864 <programlisting>
 865 void                user_function                      (PurpleChatConversation *chat,
 866                                                         const char *name,
 867                                                         const char *reason,
 868                                                         gpointer user_data)
 869 </programlisting>
 870   <para>
 871 Emitted when a user leaves a chat, after the user list is updated. This may include an optional reason why the user is leaving.
 872   </para>
 873   <variablelist role="params">
 874   <varlistentry>
 875     <term><parameter>chat</parameter>&#160;:</term>
 876     <listitem><simpara>The chat conversation.</simpara></listitem>
 877   </varlistentry>
 878   <varlistentry>
 879     <term><parameter>name</parameter>&#160;:</term>
 880     <listitem><simpara>The name of the user that left the chat.</simpara></listitem>
 881   </varlistentry>
 882   <varlistentry>
 883     <term><parameter>reason</parameter>&#160;:</term>
 884     <listitem><simpara>The optional reason why the user left the chat.</simpara></listitem>
 885   </varlistentry>
 886   <varlistentry>
 887     <term><parameter>user_data</parameter>&#160;:</term>
 888     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 889   </varlistentry>
 890   </variablelist>
 891 </refsect2>
 892
 893 <refsect2 id="conversations-chat-inviting-user" role="signal">
 894  <title>The <literal>&quot;chat-inviting-user&quot;</literal> signal</title>
 895 <programlisting>
 896 void                user_function                      (PurpleChatConversation *chat,
 897                                                         const char *name,
 898                                                         char **invite_message,
 899                                                         gpointer user_data)
 900 </programlisting>
 901   <para>
 902 Emitted when a user is being invited to the chat. The callback can replace the invite message to the invitee by modifying the pointer to the invite message.
 903   </para>
 904   <note><para>
 905 Make sure to free <literal>*invite_message</literal> before you replace it!
 906   </para></note>
 907   <variablelist role="params">
 908   <varlistentry>
 909     <term><parameter>chat</parameter>&#160;:</term>
 910     <listitem><simpara>The chat conversation.</simpara></listitem>
 911   </varlistentry>
 912   <varlistentry>
 913     <term><parameter>name</parameter>&#160;:</term>
 914     <listitem><simpara>The name of the user being invited.</simpara></listitem>
 915   </varlistentry>
 916   <varlistentry>
 917     <term><parameter>invite_message</parameter>&#160;:</term>
 918     <listitem><simpara>A pointer to the reason why a user is being invited.</simpara></listitem>
 919   </varlistentry>
 920   <varlistentry>
 921     <term><parameter>user_data</parameter>&#160;:</term>
 922     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 923   </varlistentry>
 924   </variablelist>
 925 </refsect2>
 926
 927 <refsect2 id="conversations-chat-invited-user" role="signal">
 928  <title>The <literal>&quot;chat-invited-user&quot;</literal> signal</title>
 929 <programlisting>
 930 void                user_function                      (PurpleChatConversation *conv,
 931                                                         const char *name,
 932                                                         const char *invite_message,
 933                                                         gpointer user_data)
 934 </programlisting>
 935   <para>
 936 Emitted when a user invited another user to a chat.
 937   </para>
 938   <variablelist role="params">
 939   <varlistentry>
 940     <term><parameter>chat</parameter>&#160;:</term>
 941     <listitem><simpara>The chat conversation.</simpara></listitem>
 942   </varlistentry>
 943   <varlistentry>
 944     <term><parameter>name</parameter>&#160;:</term>
 945     <listitem><simpara>The name of the user that was invited.</simpara></listitem>
 946   </varlistentry>
 947   <varlistentry>
 948     <term><parameter>invite_message</parameter>&#160;:</term>
 949     <listitem><simpara>The message to be sent to the user when invited.</simpara></listitem>
 950   </varlistentry>
 951   <varlistentry>
 952     <term><parameter>user_data</parameter>&#160;:</term>
 953     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 954   </varlistentry>
 955   </variablelist>
 956 </refsect2>
 957
 958 <refsect2 id="conversations-chat-invited" role="signal">
 959  <title>The <literal>&quot;chat-invited&quot;</literal> signal</title>
 960 <programlisting>
 961 gint                user_function                      (PurpleAccount *account,
 962                                                         const char *inviter,
 963                                                         const char *chat,
 964                                                         const char *invite_messageconst GHashTable *components,
 965                                                         gpointer user_data)
 966 </programlisting>
 967   <para>
 968 Emitted when an account was invited to a chat.
 969   </para>
 970   <variablelist role="params">
 971   <varlistentry>
 972     <term><parameter>account</parameter>&#160;:</term>
 973     <listitem><simpara>The account being invited.</simpara></listitem>
 974   </varlistentry>
 975   <varlistentry>
 976     <term><parameter>inviter</parameter>&#160;:</term>
 977     <listitem><simpara>The username of the person inviting the account.</simpara></listitem>
 978   </varlistentry>
 979   <varlistentry>
 980     <term><parameter>chat</parameter>&#160;:</term>
 981     <listitem><simpara>The name of the chat you're being invited to.</simpara></listitem>
 982   </varlistentry>
 983   <varlistentry>
 984     <term><parameter>invite_message</parameter>&#160;:</term>
 985     <listitem><simpara>The optional invite message.</simpara></listitem>
 986   </varlistentry>
 987   <varlistentry>
 988     <term><parameter>components</parameter>&#160;:</term>
 989     <listitem><simpara>The components necessary if you want to call  purple_serv_join_chat().</simpara></listitem>
 990   </varlistentry>
 991   <varlistentry>
 992     <term><parameter>user_data</parameter>&#160;:</term>
 993     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 994   </varlistentry>
 995   <varlistentry>
 996     <term><emphasis>Returns</emphasis>&#160;:</term>
 997     <listitem><simpara>Less than zero if the invitation should be rejected, greater than zero if the invitation should be accepted. If zero is returned, the default behavior will be maintained: the user will be prompted.</simpara></listitem>
 998   </varlistentry>
 999   </variablelist>
1000 </refsect2>
1001
1002 <refsect2 id="conversations-chat-invite-blocked" role="signal">
1003  <title>The <literal>&quot;chat-invite-blocked&quot;</literal> signal</title>
1004 <programlisting>
1005 void                user_function                      (PurpleAccount *account,
1006                                                         const char *inviter,
1007                                                         const char *name,
1008                                                         const char *message,
1009                                                         GHashTable *data)
1010 </programlisting>
1011   <para>
1012 Emitted when an invitation to join a chat is blocked.
1013   </para>
1014   <variablelist role="params">
1015   <varlistentry>
1016     <term><parameter>account</parameter>&#160;:</term>
1017     <listitem><simpara>The account the invitation was sent to.</simpara></listitem>
1018   </varlistentry>
1019   <varlistentry>
1020     <term><parameter>inviter</parameter>&#160;:</term>
1021     <listitem><simpara>The name of the person sending the invitation.</simpara></listitem>
1022   </varlistentry>
1023   <varlistentry>
1024     <term><parameter>name</parameter>&#160;:</term>
1025     <listitem><simpara>The name of the chat invited to.</simpara></listitem>
1026   </varlistentry>
1027   <varlistentry>
1028     <term><parameter>message</parameter>&#160;:</term>
1029     <listitem><simpara>The invitation message sent.</simpara></listitem>
1030   </varlistentry>
1031   <varlistentry>
1032     <term><parameter>data</parameter>&#160;:</term>
1033     <listitem><simpara>Hashtable containing data about the invited chat.</simpara></listitem>
1034   </varlistentry>
1035   </variablelist>
1036 </refsect2>
1037
1038 <refsect2 id="conversations-chat-joined" role="signal">
1039  <title>The <literal>&quot;chat-joined&quot;</literal> signal</title>
1040 <programlisting>
1041 void                user_function                      (PurpleChatConversation *chat,
1042                                                         gpointer user_data)
1043 </programlisting>
1044   <para>
1045 Emitted when an account joins a chat room.
1046   </para>
1047   <variablelist role="params">
1048   <varlistentry>
1049     <term><parameter>chat</parameter>&#160;:</term>
1050     <listitem><simpara>The conversation that joined the chat room.</simpara></listitem>
1051   </varlistentry>
1052   <varlistentry>
1053     <term><parameter>user_data</parameter>&#160;:</term>
1054     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
1055   </varlistentry>
1056   </variablelist>
1057 </refsect2>
1058
1059 <refsect2 id="conversations-chat-left" role="signal">
1060  <title>The <literal>&quot;chat-left&quot;</literal> signal</title>
1061 <programlisting>
1062 void                user_function                      (PurpleChatConversation *chat,
1063                                                         gpointer user_data)
1064 </programlisting>
1065   <para>
1066 Emitted when an account leaves a chat room.
1067   </para>
1068   <variablelist role="params">
1069   <varlistentry>
1070     <term><parameter>chat</parameter>&#160;:</term>
1071     <listitem><simpara>The conversation that left the chat room.</simpara></listitem>
1072   </varlistentry>
1073   <varlistentry>
1074     <term><parameter>user_data</parameter>&#160;:</term>
1075     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
1076   </varlistentry>
1077   </variablelist>
1078 </refsect2>
1079
1080 <refsect2 id="conversations-chat-topic-changed" role="signal">
1081  <title>The <literal>&quot;chat-topic-changed&quot;</literal> signal</title>
1082 <programlisting>
1083 void                user_function                      (PurpleChatConversation *chat,
1084                                                         const char *who,
1085                                                         const char *topic,
1086                                                         gpointer user_data)
1087 </programlisting>
1088   <para>
1089 Emitted when the topic is changed in a chat.
1090   </para>
1091   <variablelist role="params">
1092   <varlistentry>
1093     <term><parameter>chat</parameter>&#160;:</term>
1094     <listitem><simpara>The chat conversation whose topic changed.</simpara></listitem>
1095   </varlistentry>
1096   <varlistentry>
1097     <term><parameter>who</parameter>&#160;:</term>
1098     <listitem><simpara>The name of the person that changed the topic.</simpara></listitem>
1099   </varlistentry>
1100   <varlistentry>
1101     <term><parameter>topic</parameter>&#160;:</term>
1102     <listitem><simpara>The new topic.</simpara></listitem>
1103   </varlistentry>
1104   <varlistentry>
1105     <term><parameter>user_data</parameter>&#160;:</term>
1106     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
1107   </varlistentry>
1108   </variablelist>
1109 </refsect2>
1110
1111 <refsect2 id="conversations-conversation-extended-menu" role="signal">
1112  <title>The <literal>&quot;conversation-extended-menu&quot;</literal> signal</title>
1113 <programlisting>
1114 void                user_function                      (PurpleConversation *conv,
1115                                                         GList **list,
1116                                                         gpointer user_data)
1117 </programlisting>
1118   <para>
1119 Emitted when the UI requests a list of plugin actions for a conversation.
1120   </para>
1121   <variablelist role="params">
1122   <varlistentry>
1123     <term><parameter>conv</parameter>&#160;:</term>
1124     <listitem><simpara>The conversation.</simpara></listitem>
1125   </varlistentry>
1126   <varlistentry>
1127     <term><parameter>list</parameter>&#160;:</term>
1128     <listitem><simpara>A pointer to the list of actions.</simpara></listitem>
1129   </varlistentry>
1130   <varlistentry>
1131     <term><parameter>user_data</parameter>&#160;:</term>
1132     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
1133   </varlistentry>
1134   </variablelist>
1135 </refsect2>
1136
1137 <refsect2 id="conversations-cleared-message-history" role="signal">
1138  <title>The <literal>&quot;cleared-message-history&quot;</literal> signal</title>
1139 <programlisting>
1140 void                user_function                      (PurpleConversation *conv,
1141                                                         gpointer user_data)
1142 </programlisting>
1143   <para>
1144 Emitted when the conversation history is cleared.
1145   </para>
1146   <variablelist role="params">
1147   <varlistentry>
1148     <term><parameter>conv</parameter>&#160;:</term>
1149     <listitem><simpara>The conversation.</simpara></listitem>
1150   </varlistentry>
1151   <varlistentry>
1152     <term><parameter>user_data</parameter>&#160;:</term>
1153     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
1154   </varlistentry>
1155   </variablelist>
1156 </refsect2>
1157
1158 <refsect2 id="conversations-sent-attention" role="signal">
1159  <title>The <literal>&quot;sent-attention&quot;</literal> signal</title>
1160 <programlisting>
1161 void                user_function                      (PurpleAccount *account,
1162                                                         const char *who,
1163                                                         PurpleConversation *conv,
1164                                                         guint type,
1165                                                         gpointer user_data)
1166 </programlisting>
1167   <para>
1168 Emitted when receiving an attention message (buzz, nudge, etc.).
1169   </para>
1170   <variablelist role="params">
1171   <varlistentry>
1172     <term><parameter>account</parameter>&#160;:</term>
1173     <listitem><simpara>The account.</simpara></listitem>
1174   </varlistentry>
1175   <varlistentry>
1176     <term><parameter>who</parameter>&#160;:</term>
1177     <listitem><simpara>The name of the person receiving the attention.</simpara></listitem>
1178   </varlistentry>
1179   <varlistentry>
1180     <term><parameter>conv</parameter>&#160;:</term>
1181     <listitem><simpara>The conversation.</simpara></listitem>
1182   </varlistentry>
1183   <varlistentry>
1184     <term><parameter>type</parameter>&#160;:</term>
1185     <listitem><simpara>The attention type (an index starting at 0).</simpara></listitem>
1186   </varlistentry>
1187   <varlistentry>
1188     <term><parameter>user_data</parameter>&#160;:</term>
1189     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
1190   </varlistentry>
1191   </variablelist>
1192 </refsect2>
1193
1194 <refsect2 id="conversations-got-attention" role="signal">
1195  <title>The <literal>&quot;got-attention&quot;</literal> signal</title>
1196 <programlisting>
1197 void                user_function                      (PurpleAccount *account,
1198                                                         const char *who,
1199                                                         PurpleConversation *conv,
1200                                                         guint type,
1201                                                         gpointer user_data)
1202 </programlisting>
1203   <para>
1204 Emitted when receiving an attention message (buzz, nudge, etc.).
1205   </para>
1206   <variablelist role="params">
1207   <varlistentry>
1208     <term><parameter>account</parameter>&#160;:</term>
1209     <listitem><simpara>The account.</simpara></listitem>
1210   </varlistentry>
1211   <varlistentry>
1212     <term><parameter>who</parameter>&#160;:</term>
1213     <listitem><simpara>The name of the person sending the attention.</simpara></listitem>
1214   </varlistentry>
1215   <varlistentry>
1216     <term><parameter>conv</parameter>&#160;:</term>
1217     <listitem><simpara>The conversation.</simpara></listitem>
1218   </varlistentry>
1219   <varlistentry>
1220     <term><parameter>type</parameter>&#160;:</term>
1221     <listitem><simpara>The attention type (an index starting at 0).</simpara></listitem>
1222   </varlistentry>
1223   <varlistentry>
1224     <term><parameter>user_data</parameter>&#160;:</term>
1225     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
1226   </varlistentry>
1227   </variablelist>
1228 </refsect2>
1229
1230 </refsect1>
1231
1232 </chapter>