doc/reference/libpurple/signals_conversation.xml

<?xml version='1.0' encoding="ISO-8859-1"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<chapter id="chapter-signals-conversation">
<title>Conversation signals</title>

<refsect1 id="conversations.signals" role="signal_proto">
<title role="signal_proto.title">List of signals</title>
<synopsis>
  &quot;<link linkend="conversations-writing-im-msg">writing-im-msg</link>&quot;
  &quot;<link linkend="conversations-wrote-im-msg">wrote-im-msg</link>&quot;
  &quot;<link linkend="conversations-sending-im-msg">sending-im-msg</link>&quot;
  &quot;<link linkend="conversations-sent-im-msg">sent-im-msg</link>&quot;
  &quot;<link linkend="conversations-receiving-im-msg">receiving-im-msg</link>&quot;
  &quot;<link linkend="conversations-received-im-msg">received-im-msg</link>&quot;
  &quot;<link linkend="conversations-blocked-im-msg">blocked-im-msg</link>&quot;
  &quot;<link linkend="conversations-writing-chat-msg">writing-chat-msg</link>&quot;
  &quot;<link linkend="conversations-wrote-chat-msg">wrote-chat-msg</link>&quot;
  &quot;<link linkend="conversations-sending-chat-msg">sending-chat-msg</link>&quot;
  &quot;<link linkend="conversations-sent-chat-msg">sent-chat-msg</link>&quot;
  &quot;<link linkend="conversations-receiving-chat-msg">receiving-chat-msg</link>&quot;
  &quot;<link linkend="conversations-received-chat-msg">received-chat-msg</link>&quot;
  &quot;<link linkend="conversations-conversation-created">conversation-created</link>&quot;
  &quot;<link linkend="conversations-conversation-updated">conversation-updated</link>&quot;
  &quot;<link linkend="conversations-deleting-conversation">deleting-conversation</link>&quot;
  &quot;<link linkend="conversations-buddy-typing">buddy-typing</link>&quot;
  &quot;<link linkend="conversations-buddy-typing-stopped">buddy-typing-stopped</link>&quot;
  &quot;<link linkend="conversations-chat-user-joining">chat-user-joining</link>&quot;
  &quot;<link linkend="conversations-chat-user-joined">chat-user-joined</link>&quot;
  &quot;<link linkend="conversations-chat-user-flags">chat-user-flags</link>&quot;
  &quot;<link linkend="conversations-chat-user-leaving">chat-user-leaving</link>&quot;
  &quot;<link linkend="conversations-chat-user-left">chat-user-left</link>&quot;
  &quot;<link linkend="conversations-chat-inviting-user">chat-inviting-user</link>&quot;
  &quot;<link linkend="conversations-chat-invited-user">chat-invited-user</link>&quot;
  &quot;<link linkend="conversations-chat-invited">chat-invited</link>&quot;
  &quot;<link linkend="conversations-chat-invite-blocked">chat-invite-blocked</link>&quot;
  &quot;<link linkend="conversations-chat-joined">chat-joined</link>&quot;
  &quot;<link linkend="conversations-chat-join-failed">chat-join-failed</link>&quot;
  &quot;<link linkend="conversations-chat-left">chat-left</link>&quot;
  &quot;<link linkend="conversations-chat-topic-changed">chat-topic-changed</link>&quot;
  &quot;<link linkend="conversations-cleared-message-history">cleared-message-history</link>&quot;
  &quot;<link linkend="conversations-conversation-extended-menu">conversation-extended-menu</link>&quot;
  &quot;<link linkend="conversations-sent-attention">sent-attention</link>&quot;
  &quot;<link linkend="conversations-got-attention">got-attention</link>&quot;
</synopsis>
</refsect1>

<refsect1 id="conversations.signal-details" role="signals">
<title role="signals.title">Signal details</title>

<refsect2 id="conversations-writing-im-msg" role="signal">
 <title>The <literal>&quot;writing-im-msg&quot;</literal> signal</title>
<programlisting>
gboolean            user_function                      (PurpleAccount *account,
                                                        const char *who,
                                                        char **message,
                                                        PurpleIMConversation *im,
                                                        PurpleMessageFlags flags,
                                                        gpointer user_data)
</programlisting>
  <para>
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.
  </para>
  <note><para>
Make sure to free <literal>*message</literal> before you replace it!
  </para></note>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>who</parameter>&#160;:</term>
    <listitem><simpara>The name of the user.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the message.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>im</parameter>&#160;:</term>
    <listitem><simpara>The IM conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>Flags for this message.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>Returns</emphasis>&#160;:</term>
    <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-wrote-im-msg" role="signal">
 <title>The <literal>&quot;wrote-im-msg&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *who,
                                                        char *message,
                                                        PurpleIMConversation *im,
                                                        PurpleMessageFlags flags,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted after a message is written and possibly displayed in a conversation.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>who</parameter>&#160;:</term>
    <listitem><simpara>The name of the user.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>The message.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>im</parameter>&#160;:</term>
    <listitem><simpara>The IM conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>Flags for this message.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-sending-im-msg" role="signal">
 <title>The <literal>&quot;sending-im-msg&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *receiver,
                                                        char **message,
                                                        gpointer user_data)
</programlisting>
  <para>
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.
  </para>
  <note><para>
Make sure to free <literal>*message</literal> before you replace it!
  </para></note>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the message is being sent on.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>receiver</parameter>&#160;:</term>
    <listitem><simpara>The username of the receiver.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the outgoing message. This can be modified.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-sent-im-msg" role="signal">
 <title>The <literal>&quot;sent-im-msg&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *receiver,
                                                        const char *message,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted after sending an IM to a user.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the message was sent on.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>receiver</parameter>&#160;:</term>
    <listitem><simpara>The username of the receiver.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>The message that was sent.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-receiving-im-msg" role="signal">
 <title>The <literal>&quot;receiving-im-msg&quot;</literal> signal</title>
<programlisting>
gboolean            user_function                      (PurpleAccount *account,
                                                        char **sender,
                                                        char **message,
                                                        PurpleIMConversation *im,
                                                        PurpleMessageFlags *flags,
                                                        gpointer user_data)
</programlisting>
  <para>
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>.
  </para>
  <note><para>
Make sure to free <literal>*sender</literal> and <literal>*message</literal> before you replace them!
  </para></note>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the message was received on.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>sender</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the username of the sender.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the message that was sent.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>im</parameter>&#160;:</term>
    <listitem><simpara>The IM conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the IM message flags.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>Returns</emphasis>&#160;:</term>
    <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-received-im-msg" role="signal">
 <title>The <literal>&quot;received-im-msg&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        char *sender,
                                                        char *message,
                                                        PurpleIMConversation *im,
                                                        PurpleMessageFlags flags,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted after an IM is received.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the message was received on.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>sender</parameter>&#160;:</term>
    <listitem><simpara>The username of the sender.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>The message that was sent.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>im</parameter>&#160;:</term>
    <listitem><simpara>The IM conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>The IM message flags.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-blocked-im-msg" role="signal">
 <title>The <literal>&quot;blocked-im-msg&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *sender,
                                                        const char *message,
                                                        PurpleMessageFlags flags,
                                                        time_t when,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted after an IM is blocked due to privacy settings.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the message was received on.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>sender</parameter>&#160;:</term>
    <listitem><simpara>The username of the sender.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>The message that was blocked.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>The IM message flags.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>when</parameter>&#160;:</term>
    <listitem><simpara>The time the message was sent.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-writing-chat-msg" role="signal">
 <title>The <literal>&quot;writing-chat-msg&quot;</literal> signal</title>
<programlisting>
gboolean            user_function                      (PurpleAccount *account,
                                                        const char *who,
                                                        char **message,
                                                        PurpleChatConversation *chat,
                                                        PurpleMessageFlags flags,
                                                        gpointer user_data)
</programlisting>
  <para>
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.
  </para>
  <note><para>
Make sure to free <literal>*message</literal> before you replace it!
  </para></note>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>who</parameter>&#160;:</term>
    <listitem><simpara>The name of the user.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the message.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>Flags for this message.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>Returns</emphasis>&#160;:</term>
    <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-wrote-chat-msg" role="signal">
 <title>The <literal>&quot;wrote-chat-msg&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *who,
                                                        char *message,
                                                        PurpleChatConversation *chat,
                                                        PurpleMessageFlags flags,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted after a message is written and possibly displayed in a chat.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>who</parameter>&#160;:</term>
    <listitem><simpara>The name of the user.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>The message.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>Flags for this message.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-sending-chat-msg" role="signal">
 <title>The <literal>&quot;sending-chat-msg&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        char **message,
                                                        int id,
                                                        gpointer user_data)
</programlisting>
  <para>
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.
  </para>
  <note><para>
Make sure to free <literal>*message</literal> before you replace it!
  </para></note>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the message is being sent on.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the message that will be sent.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>id</parameter>&#160;:</term>
    <listitem><simpara>The ID of the chat.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-sent-chat-msg" role="signal">
 <title>The <literal>&quot;sent-chat-msg&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *message,
                                                        int id,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted after sending a message to a chat.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the message was sent on.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>The message that was sent.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>id</parameter>&#160;:</term>
    <listitem><simpara>The ID of the chat.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-receiving-chat-msg" role="signal">
 <title>The <literal>&quot;receiving-chat-msg&quot;</literal> signal</title>
<programlisting>
gboolean            user_function                      (PurpleAccount *account,
                                                        char **sender,
                                                        char **message,
                                                        PurpleChatConversation *chat,
                                                        int *flags,
                                                        gpointer user_data)
</programlisting>
  <para>
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>.
  </para>
  <note><para>
Make sure to free <literal>*sender</literal> and <literal>*message</literal> before you replace them!
  </para></note>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the message was received on.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>sender</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the username of the sender.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the message that was sent.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the chat message flags.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>Returns</emphasis>&#160;:</term>
    <listitem><simpara><literal>TRUE</literal> if the message should be canceled, or <literal>FALSE</literal> otherwise.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-received-chat-msg" role="signal">
 <title>The <literal>&quot;received-chat-msg&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        char *sender,
                                                        char *message,
                                                        PurpleChatConversation *chat,
                                                        PurpleMessageFlags flags,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted after a chat message is received.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the message was received on.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>sender</parameter>&#160;:</term>
    <listitem><simpara>The username of the sender.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>The message that was sent.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>The chat message flags.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-conversation-created" role="signal">
 <title>The <literal>&quot;conversation-created&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleConversation *conv,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when a new conversation is created.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>conv</parameter>&#160;:</term>
    <listitem><simpara>The new conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-conversation-updated" role="signal">
 <title>The <literal>&quot;conversation-updated&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleConversation *conv,
                                                        PurpleConvUpdateType type,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when a conversation is updated.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>conv</parameter>&#160;:</term>
    <listitem><simpara>The conversation that was updated.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>type</parameter>&#160;:</term>
    <listitem><simpara>The type of update that was made.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-deleting-conversation" role="signal">
 <title>The <literal>&quot;deleting-conversation&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleConversation *conv,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted just before a conversation is to be destroyed.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>conv</parameter>&#160;:</term>
    <listitem><simpara>The conversation that's about to be destroyed.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-buddy-typing" role="signal">
 <title>The <literal>&quot;buddy-typing&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *name,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when a buddy starts typing in a conversation window.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account of the user which is typing.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter>&#160;:</term>
    <listitem><simpara>The name of the user which is typing.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-buddy-typing-stopped" role="signal">
 <title>The <literal>&quot;buddy-typing-stopped&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *name,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when a buddy stops typing in a conversation window.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account of the user which stopped typing.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter>&#160;:</term>
    <listitem><simpara>The name of the user which stopped typing.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-user-joining" role="signal">
 <title>The <literal>&quot;chat-user-joining&quot;</literal> signal</title>
<programlisting>
gboolean            user_function                      (PurpleChatConversation *chat,
                                                        const char *name,
                                                        PurpleChatUserFlags flags,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when a buddy is joining a chat, before the list of users in the chat updates to include the new user.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter>&#160;:</term>
    <listitem><simpara>The name of the user that is joining the conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>The flags of the user that is joining the conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>Returns</emphasis>&#160;:</term>
    <listitem><simpara><literal>TRUE</literal> if the join should be hidden, or <literal>FALSE</literal> otherwise.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-user-joined" role="signal">
 <title>The <literal>&quot;chat-user-joined&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleChatConversation *chat,
                                                        const char *name,
                                                        PurpleChatUserFlags flags,
                                                        gboolean new_arrival,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when a buddy joined a chat, after the users list is updated.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter>&#160;:</term>
    <listitem><simpara>The name of the user that has joined the conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>flags</parameter>&#160;:</term>
    <listitem><simpara>The flags of the user that has joined the conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>new_arrival</parameter>&#160;:</term>
    <listitem><simpara>If the buddy is a new arrival.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-join-failed" role="signal">
 <title>The <literal>&quot;chat-join-failed&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleConnection *gc,
                                                        GHashTable *components,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when an account fails to join a chat room.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>gc</parameter>&#160;:</term>
    <listitem><simpara>The PurpleConnection of the account which failed to join the chat.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>data</parameter>&#160;:</term>
    <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>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-user-flags" role="signal">
 <title>The <literal>&quot;chat-user-flags&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleChatUser *chatuser,
                                                        PurpleChatUserFlags oldflags,
                                                        PurpleChatUserFlags newflags,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when a user in a chat changes flags.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chatuser</parameter>&#160;:</term>
    <listitem><simpara>The chat user whose flags changed.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>oldflags</parameter>&#160;:</term>
    <listitem><simpara>The old flags.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>newflags</parameter>&#160;:</term>
    <listitem><simpara>The new flags.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-user-leaving" role="signal">
 <title>The <literal>&quot;chat-user-leaving&quot;</literal> signal</title>
<programlisting>
gboolean            user_function                      (PurpleChatConversation *chat,
                                                        const char *name,
                                                        const char *reason,
                                                        gpointer user_data)
</programlisting>
  <para>
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.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter>&#160;:</term>
    <listitem><simpara>The name of the user that is leaving the chat.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>reason</parameter>&#160;:</term>
    <listitem><simpara>The optional reason why the user is leaving.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>Returns</emphasis>&#160;:</term>
    <listitem><simpara><literal>TRUE</literal> if the leave should be hidden, or <literal>FALSE</literal> otherwise.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-user-left" role="signal">
 <title>The <literal>&quot;chat-user-left&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleChatConversation *chat,
                                                        const char *name,
                                                        const char *reason,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when a user leaves a chat, after the user list is updated. This may include an optional reason why the user is leaving.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter>&#160;:</term>
    <listitem><simpara>The name of the user that left the chat.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>reason</parameter>&#160;:</term>
    <listitem><simpara>The optional reason why the user left the chat.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-inviting-user" role="signal">
 <title>The <literal>&quot;chat-inviting-user&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleChatConversation *chat,
                                                        const char *name,
                                                        char **invite_message,
                                                        gpointer user_data)
</programlisting>
  <para>
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.
  </para>
  <note><para>
Make sure to free <literal>*invite_message</literal> before you replace it!
  </para></note>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter>&#160;:</term>
    <listitem><simpara>The name of the user being invited.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>invite_message</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the reason why a user is being invited.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-invited-user" role="signal">
 <title>The <literal>&quot;chat-invited-user&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleChatConversation *conv,
                                                        const char *name,
                                                        const char *invite_message,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when a user invited another user to a chat.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter>&#160;:</term>
    <listitem><simpara>The name of the user that was invited.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>invite_message</parameter>&#160;:</term>
    <listitem><simpara>The message to be sent to the user when invited.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-invited" role="signal">
 <title>The <literal>&quot;chat-invited&quot;</literal> signal</title>
<programlisting>
gint                user_function                      (PurpleAccount *account,
                                                        const char *inviter,
                                                        const char *chat,
                                                        const char *invite_messageconst GHashTable *components,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when an account was invited to a chat.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account being invited.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>inviter</parameter>&#160;:</term>
    <listitem><simpara>The username of the person inviting the account.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The name of the chat you're being invited to.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>invite_message</parameter>&#160;:</term>
    <listitem><simpara>The optional invite message.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>components</parameter>&#160;:</term>
    <listitem><simpara>The components necessary if you want to call  purple_serv_join_chat().</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><emphasis>Returns</emphasis>&#160;:</term>
    <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>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-invite-blocked" role="signal">
 <title>The <literal>&quot;chat-invite-blocked&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *inviter,
                                                        const char *name,
                                                        const char *message,
                                                        GHashTable *data)
</programlisting>
  <para>
Emitted when an invitation to join a chat is blocked.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account the invitation was sent to.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>inviter</parameter>&#160;:</term>
    <listitem><simpara>The name of the person sending the invitation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>name</parameter>&#160;:</term>
    <listitem><simpara>The name of the chat invited to.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>message</parameter>&#160;:</term>
    <listitem><simpara>The invitation message sent.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>data</parameter>&#160;:</term>
    <listitem><simpara>Hashtable containing data about the invited chat.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-joined" role="signal">
 <title>The <literal>&quot;chat-joined&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleChatConversation *chat,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when an account joins a chat room.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The conversation that joined the chat room.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-left" role="signal">
 <title>The <literal>&quot;chat-left&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleChatConversation *chat,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when an account leaves a chat room.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The conversation that left the chat room.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-chat-topic-changed" role="signal">
 <title>The <literal>&quot;chat-topic-changed&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleChatConversation *chat,
                                                        const char *who,
                                                        const char *topic,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when the topic is changed in a chat.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>chat</parameter>&#160;:</term>
    <listitem><simpara>The chat conversation whose topic changed.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>who</parameter>&#160;:</term>
    <listitem><simpara>The name of the person that changed the topic.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>topic</parameter>&#160;:</term>
    <listitem><simpara>The new topic.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-conversation-extended-menu" role="signal">
 <title>The <literal>&quot;conversation-extended-menu&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleConversation *conv,
                                                        GList **list,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when the UI requests a list of plugin actions for a conversation.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>conv</parameter>&#160;:</term>
    <listitem><simpara>The conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>list</parameter>&#160;:</term>
    <listitem><simpara>A pointer to the list of actions.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-cleared-message-history" role="signal">
 <title>The <literal>&quot;cleared-message-history&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleConversation *conv,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when the conversation history is cleared.
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>conv</parameter>&#160;:</term>
    <listitem><simpara>The conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-sent-attention" role="signal">
 <title>The <literal>&quot;sent-attention&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *who,
                                                        PurpleConversation *conv,
                                                        guint type,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when receiving an attention message (buzz, nudge, etc.).
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>who</parameter>&#160;:</term>
    <listitem><simpara>The name of the person receiving the attention.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>conv</parameter>&#160;:</term>
    <listitem><simpara>The conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>type</parameter>&#160;:</term>
    <listitem><simpara>The attention type (an index starting at 0).</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

<refsect2 id="conversations-got-attention" role="signal">
 <title>The <literal>&quot;got-attention&quot;</literal> signal</title>
<programlisting>
void                user_function                      (PurpleAccount *account,
                                                        const char *who,
                                                        PurpleConversation *conv,
                                                        guint type,
                                                        gpointer user_data)
</programlisting>
  <para>
Emitted when receiving an attention message (buzz, nudge, etc.).
  </para>
  <variablelist role="params">
  <varlistentry>
    <term><parameter>account</parameter>&#160;:</term>
    <listitem><simpara>The account.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>who</parameter>&#160;:</term>
    <listitem><simpara>The name of the person sending the attention.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>conv</parameter>&#160;:</term>
    <listitem><simpara>The conversation.</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>type</parameter>&#160;:</term>
    <listitem><simpara>The attention type (an index starting at 0).</simpara></listitem>
  </varlistentry>
  <varlistentry>
    <term><parameter>user_data</parameter>&#160;:</term>
    <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  </varlistentry>
  </variablelist>
</refsect2>

</refsect1>

</chapter>