doc/reference/libpurple/signals_connection.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-connection">
   6 <title>Connection signals</title>
   7
   8 <refsect1 id="connections.signals" role="signal_proto">
   9 <title role="signal_proto.title">List of signals</title>
  10 <synopsis>
  11   &quot;<link linkend="connections-signing-on">signing-on</link>&quot;
  12   &quot;<link linkend="connections-signed-on">signed-on</link>&quot;
  13   &quot;<link linkend="connections-autojoin">autojoin</link>&quot;
  14   &quot;<link linkend="connections-signing-off">signing-off</link>&quot;
  15   &quot;<link linkend="connections-signed-off">signed-off</link>&quot;
  16   &quot;<link linkend="connections-connection-error">connection-error</link>&quot;
  17 </synopsis>
  18 </refsect1>
  19
  20 <refsect1 id="connections.signal-details" role="signals">
  21 <title role="signals.title">Signal details</title>
  22
  23 <refsect2 id="connections-signing-on" role="signal">
  24  <title>The <literal>&quot;signing-on&quot;</literal> signal</title>
  25 <programlisting>
  26 void                user_function                      (PurpleConnection *gc,
  27                                                         gpointer user_data)
  28 </programlisting>
  29   <para>
  30 Emitted when a connection is about to sign on.
  31   </para>
  32   <variablelist role="params">
  33   <varlistentry>
  34     <term><parameter>gc</parameter>&#160;:</term>
  35     <listitem><simpara>The connection that is about to sign on.</simpara></listitem>
  36   </varlistentry>
  37   <varlistentry>
  38     <term><parameter>user_data</parameter>&#160;:</term>
  39     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  40   </varlistentry>
  41   </variablelist>
  42 </refsect2>
  43
  44 <refsect2 id="connections-signed-on" role="signal">
  45  <title>The <literal>&quot;signed-on&quot;</literal> signal</title>
  46 <programlisting>
  47 void                user_function                      (PurpleConnection *gc,
  48                                                         gpointer user_data)
  49 </programlisting>
  50   <para>
  51 Emitted when a connection has signed on.
  52   </para>
  53   <variablelist role="params">
  54   <varlistentry>
  55     <term><parameter>gc</parameter>&#160;:</term>
  56     <listitem><simpara>The connection that has signed on.</simpara></listitem>
  57   </varlistentry>
  58   <varlistentry>
  59     <term><parameter>user_data</parameter>&#160;:</term>
  60     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  61   </varlistentry>
  62   </variablelist>
  63 </refsect2>
  64
  65 <refsect2 id="connections-autojoin" role="signal">
  66  <title>The <literal>&quot;autojoin&quot;</literal> signal</title>
  67 <programlisting>
  68 gboolean            user_function                      (PurpleConnection *gc,
  69                                                         gpointer user_data)
  70 </programlisting>
  71   <para>
  72 Emitted when a connection has signed on, after the signed-on signal, to signal UIs to autojoin chats if they wish.  UIs should connect to this with <literal>PURPLE_SIGNAL_PRIORITY_HIGHEST</literal> to allow plugins to block this signal before the UI sees it and then re-emit it later.
  73   </para>
  74   <variablelist role="params">
  75   <varlistentry>
  76     <term><parameter>gc</parameter>&#160;:</term>
  77     <listitem><simpara>The connection that has signed on.</simpara></listitem>
  78   </varlistentry>
  79   <varlistentry>
  80     <term><parameter>user_data</parameter>&#160;:</term>
  81     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
  82   </varlistentry>
  83   <varlistentry>
  84     <term><emphasis>Returns</emphasis>&#160;:</term>
  85     <listitem><simpara><literal>TRUE</literal> if the signal was handled or <literal>FALSE</literal> otherwise.  In practice, the return value is irrelevant, as it really only exists so plugins can block the UI's autojoin.</simpara></listitem>
  86   </varlistentry>
  87   </variablelist>
  88 </refsect2>
  89
  90 <refsect2 id="connections-signing-off" role="signal">
  91  <title>The <literal>&quot;signing-off&quot;</literal> signal</title>
  92 <programlisting>
  93 void                user_function                      (PurpleConnection *gc,
  94                                                         gpointer user_data)
  95 </programlisting>
  96   <para>
  97 Emitted when a connection is about to sign off.
  98   </para>
  99   <variablelist role="params">
 100   <varlistentry>
 101     <term><parameter>gc</parameter>&#160;:</term>
 102     <listitem><simpara>The connection that is about to sign off.</simpara></listitem>
 103   </varlistentry>
 104   <varlistentry>
 105     <term><parameter>user_data</parameter>&#160;:</term>
 106     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 107   </varlistentry>
 108   </variablelist>
 109 </refsect2>
 110
 111 <refsect2 id="connections-signed-off" role="signal">
 112  <title>The <literal>&quot;signed-off&quot;</literal> signal</title>
 113 <programlisting>
 114 void                user_function                      (PurpleConnection *gc,
 115                                                         gpointer user_data)
 116 </programlisting>
 117   <para>
 118 Emitted when a connection has signed off.
 119   </para>
 120   <variablelist role="params">
 121   <varlistentry>
 122     <term><parameter>gc</parameter>&#160;:</term>
 123     <listitem><simpara>The connection that has signed off.</simpara></listitem>
 124   </varlistentry>
 125   <varlistentry>
 126     <term><parameter>user_data</parameter>&#160;:</term>
 127     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 128   </varlistentry>
 129   </variablelist>
 130 </refsect2>
 131
 132 <refsect2 id="connections-connection-error" role="signal">
 133  <title>The <literal>&quot;connection-error&quot;</literal> signal</title>
 134 <programlisting>
 135 void                user_function                      (PurpleConnection *gc,
 136                                                         PurpleConnectionError err,
 137                                                         const gchar *desc,
 138                                                         gpointer user_data)
 139 </programlisting>
 140   <para>
 141 Emitted when a connection error occurs, before <literal>"signed"</literal>-off.
 142   </para>
 143   <variablelist role="params">
 144   <varlistentry>
 145     <term><parameter>gc</parameter>&#160;:</term>
 146     <listitem><simpara>The connection on which the error has occurred.</simpara></listitem>
 147   </varlistentry>
 148   <varlistentry>
 149     <term><parameter>err</parameter>&#160;:</term>
 150     <listitem><simpara>The error that occurred.</simpara></listitem>
 151   </varlistentry>
 152   <varlistentry>
 153     <term><parameter>desc</parameter>&#160;:</term>
 154     <listitem><simpara>A description of the error, giving more information.</simpara></listitem>
 155   </varlistentry>
 156   <varlistentry>
 157     <term><parameter>user_data</parameter>&#160;:</term>
 158     <listitem><simpara>user data set when the signal handler was connected.</simpara></listitem>
 159   </varlistentry>
 160   </variablelist>
 161 </refsect2>
 162
 163 </refsect1>
 164
 165 </chapter>